Shad Ansari | 2f7f9be | 2017-06-07 13:34:53 -0700 | [diff] [blame] | 1 | /* |
| 2 | <:copyright-BRCM:2016:DUAL/GPL:standard |
| 3 | |
| 4 | Broadcom Proprietary and Confidential.(c) 2016 Broadcom |
| 5 | All Rights Reserved |
| 6 | |
| 7 | Unless you and Broadcom execute a separate written software license |
| 8 | agreement governing use of this software, this software is licensed |
| 9 | to you under the terms of the GNU General Public License version 2 |
| 10 | (the "GPL"), available at http://www.broadcom.com/licenses/GPLv2.php, |
| 11 | with the following added to such license: |
| 12 | |
| 13 | As a special exception, the copyright holders of this software give |
| 14 | you permission to link this software with independent modules, and |
| 15 | to copy and distribute the resulting executable under terms of your |
| 16 | choice, provided that you also meet, for each linked independent |
| 17 | module, the terms and conditions of the license of that module. |
| 18 | An independent module is a module which is not derived from this |
| 19 | software. The special exception does not apply to any modifications |
| 20 | of the software. |
| 21 | |
| 22 | Not withstanding the above, under no circumstances may you combine |
| 23 | this software in any way with any other Broadcom software provided |
| 24 | under a license other than the GPL, without Broadcom's express prior |
| 25 | written consent. |
| 26 | |
| 27 | :> |
| 28 | */ |
| 29 | |
| 30 | #ifndef _BCMOLT_USER_APPL_PS_H_ |
| 31 | #define _BCMOLT_USER_APPL_PS_H_ |
| 32 | |
| 33 | #include <bcmos_system.h> |
| 34 | #include <bcmolt_api.h> |
| 35 | #include <bcmolt_model_types.h> |
| 36 | |
| 37 | /** Conditions that can cause a protection switch to be performed. */ |
| 38 | typedef enum |
| 39 | { |
| 40 | BCMOLT_PS_SWITCH_CONDITION_LOS, /**< Switch when LoS alarm is received for a working PON. */ |
| 41 | BCMOLT_PS_SWITCH_CONDITION_MANUAL, /**< Do not switch automatically. */ |
| 42 | } bcmolt_ps_switch_condition; |
| 43 | |
| 44 | /** How provisioning should be mirrored from working to standby. */ |
| 45 | typedef enum |
| 46 | { |
| 47 | BCMOLT_PS_MIRROR_MODE_AUTO, /**< Whenever an indication is received on the working PON, mirror all necessary |
| 48 | configuration to standby PON. */ |
| 49 | BCMOLT_PS_MIRROR_MODE_NONE, /**< Do not automatically mirror any provisioning from working to standby. */ |
| 50 | } bcmolt_ps_mirror_mode; |
| 51 | |
| 52 | /** What the order of operations should be when performing a switchover. */ |
| 53 | typedef enum |
| 54 | { |
| 55 | BCMOLT_PS_SWITCH_SEQUENCE_STANDARD, /**< "standard" order: |
| 56 | 1: Change the working PON state to standby. |
| 57 | 2: Disable optical TX channel of working PON. |
| 58 | 3: Enable optical TX channel of standby PON. |
| 59 | 4: Change the standby PON state to working. */ |
| 60 | BCMOLT_PS_SWITCH_SEQUENCE_TRX_FIRST, /**< Perform transceiver enable/disable first: |
| 61 | 1: Disable optical TX channel of working PON. |
| 62 | 2: Enable optical TX channel of standby PON. |
| 63 | 3: Change the standby PON state to working. |
| 64 | 4: Change the working PON state to standby. */ |
| 65 | } bcmolt_ps_switch_sequence; |
| 66 | |
| 67 | /** Global configuration for the protection switching application. */ |
| 68 | typedef struct |
| 69 | { |
| 70 | uint16_t max_num_pairs; /**< Maximum number of protected pairs supported. */ |
| 71 | bcmolt_ps_switch_condition switch_condition; /**< Condition that should cause a switchover. */ |
| 72 | bcmolt_ps_switch_sequence switch_sequence; /**< Order of operations when performing a switchover. */ |
| 73 | |
| 74 | /* The following properties are only used in GPON mode. */ |
| 75 | bcmolt_ps_mirror_mode mirror_mode; /**< How provisioning should be mirrored from working to standby. */ |
| 76 | bcmos_bool mirror_mac_entries; /**< If TRUE, mirror all MAC learning entries to the standby PON |
| 77 | when learning indications are received from the working PON. |
| 78 | This will also cause entries to be automatically deleted when |
| 79 | aging indications are received and moved when MAC move |
| 80 | indications are received. */ |
| 81 | bcmos_bool static_mac_entries; /**< If TRUE, when entries are mirrored to the standby PON, treat |
| 82 | them as "static" (not aged). */ |
| 83 | uint32_t trx_warming_delay; /**< Delay (in usec) to wait after TRX enable, in order to |
| 84 | guarantee that POPUP PLOAMs are correctly seen by ONUs. */ |
| 85 | } bcmolt_ps_global_cfg; |
| 86 | |
| 87 | /** A single PON on an OLT device - half of a protected pair. */ |
| 88 | typedef struct |
| 89 | { |
| 90 | bcmolt_devid device_id; |
| 91 | bcmolt_pon_ni pon_id; |
| 92 | bcmolt_pon_ni transceiver_id; |
| 93 | } bcmolt_ps_pon; |
| 94 | |
| 95 | /** A protected pair of PONs, on the same OLT device or different devices. */ |
| 96 | typedef struct |
| 97 | { |
| 98 | bcmolt_ps_pon working; |
| 99 | bcmolt_ps_pon standby; |
| 100 | } bcmolt_ps_pair; |
| 101 | |
| 102 | /** Possible states for a single PON from a protection switching point-of-view. */ |
| 103 | typedef enum |
| 104 | { |
| 105 | BCMOLT_PS_PON_STATE_UNASSOCIATED, /**< The PON is not part of a protected pair. */ |
| 106 | BCMOLT_PS_PON_STATE_WORKING, /**< The PON is designated as working with the TRX enabled while active. */ |
| 107 | BCMOLT_PS_PON_STATE_STANDBY, /**< The PON is designated as standby with the TRX disabled while active. */ |
| 108 | } bcmolt_ps_pon_state; |
| 109 | |
| 110 | /** Initialize the protection switching application (this should be called as part of application startup). */ |
| 111 | void bcmolt_ps_appl_init(void); |
| 112 | |
| 113 | /** Start the protection switching application (this is global for the entire system). |
| 114 | * |
| 115 | * \param[in] cfg Global protection switching configuration. |
| 116 | * \return BCM_ERR_OK if the application was started successfully, <0 otherwise. |
| 117 | */ |
| 118 | bcmos_errno bcmolt_ps_appl_start(const bcmolt_ps_global_cfg *cfg); |
| 119 | |
| 120 | /** Stop the protection switching application (this is global for the entire system). |
| 121 | * |
| 122 | * \return BCM_ERR_OK if the application was stopped successfully, <0 otherwise. |
| 123 | */ |
| 124 | bcmos_errno bcmolt_ps_appl_stop(void); |
| 125 | |
| 126 | /** Query whether the protection switching application is currently running. |
| 127 | * |
| 128 | * \return BCMOS_TRUE if the application is running, BCMOS_FALSE otherwise. |
| 129 | */ |
| 130 | bcmos_bool bcmolt_ps_appl_is_running(void); |
| 131 | |
| 132 | /** Get the configuration of the running protection switching application (this is global for the entire system). |
| 133 | * |
| 134 | * \param[out] cfg Global protection switching configuration. |
| 135 | * \return BCM_ERR_OK if the configuration was retrieved successfully, <0 otherwise. |
| 136 | */ |
| 137 | bcmos_errno bcmolt_ps_global_cfg_get(bcmolt_ps_global_cfg *cfg); |
| 138 | |
| 139 | /** Change the configuration of the running protection switching application (this is global for the entire system). |
| 140 | * |
| 141 | * \param[in] cfg Global protection switching configuration. |
| 142 | * \return BCM_ERR_OK if the configuration was updated successfully, <0 otherwise. |
| 143 | */ |
| 144 | bcmos_errno bcmolt_ps_global_cfg_update(const bcmolt_ps_global_cfg *cfg); |
| 145 | |
| 146 | /** Get the list of all protected pairs currently tracked by the protection switching application. |
| 147 | * |
| 148 | * \param[in] array_len The length of the pairs array. |
| 149 | * \param[out] pairs An array of protected pairs to fill. |
| 150 | * \param[out] num_written The number of pairs written to the array. |
| 151 | * \return BCM_ERR_OK if the array was written successfully, <0 otherwise. |
| 152 | */ |
| 153 | bcmos_errno bcmolt_ps_pairs_get(uint16_t array_len, bcmolt_ps_pair *pairs, uint16_t *num_written); |
| 154 | |
| 155 | /** Add a protected pair to the protection switching database. |
| 156 | * |
| 157 | * After this has been called, provisioning will be mirrored from the working PON to the standby PON according to the |
| 158 | * mirror_mode global parameter, and a switch will be performed per the switch_condition global parameter. |
| 159 | * |
| 160 | * \param[in] pair A pair of PONs to add - they can be on the same OLT device or different devices. |
| 161 | * \return BCM_ERR_OK if the pair was added successfully, <0 otherwise. |
| 162 | */ |
| 163 | bcmos_errno bcmolt_ps_pair_add(const bcmolt_ps_pair *pair); |
| 164 | |
| 165 | /** Remove the protected pair containing the specified PON from the protection switching database. |
| 166 | * |
| 167 | * \param[in] pon A PON that is a member of a protection pair. |
| 168 | * \return BCM_ERR_OK if the PON was removed successfully, <0 otherwise. |
| 169 | */ |
| 170 | bcmos_errno bcmolt_ps_pon_remove(const bcmolt_ps_pon *pon); |
| 171 | |
| 172 | /** Query for the current state of a protected PON. |
| 173 | * |
| 174 | * \param[in] pon The PON to query. |
| 175 | * \param[out] state The protection state of the PON (e.g. working/standby). |
| 176 | * \param[out] partner If this PON is protected, the other half of the protected pair. |
| 177 | * \return BCM_ERR_OK if the PON was queried successfully, <0 otherwise. |
| 178 | */ |
| 179 | bcmos_errno bcmolt_ps_pon_state_get(const bcmolt_ps_pon *pon, bcmolt_ps_pon_state *state, bcmolt_ps_pon *partner); |
| 180 | |
| 181 | /** Process an indication received by the working PON. |
| 182 | * |
| 183 | * The action taken will depend on the object/indication type and the mirror_mode global parameter. |
| 184 | * If the application isn't running, the supplied PON isn't in a protected working state or the indication isn't |
| 185 | * relevant for protection switching, the indication will be ignored. |
| 186 | * |
| 187 | * Note: this function does not free the indication. |
| 188 | * The caller must free it using bcmos_msg_free() after calling this function. |
| 189 | * |
| 190 | * \param[in] pon The PON on which the indication was received. |
| 191 | * \param[in] ind The indication that was received. |
| 192 | * \return BCM_ERR_OK if the indication was processed successfully or ignored, <0 otherwise. |
| 193 | */ |
| 194 | bcmos_errno bcmolt_ps_process_ind(const bcmolt_ps_pon *pon, bcmolt_auto *ind); |
| 195 | |
| 196 | /** Immediately perform a protection switch on the given PON, which must belong to a protected pair. |
| 197 | * |
| 198 | * This function is primarily intended for use with the BCMOLT_PS_SWITCH_CONDITION_MANUAL switch condition, or for |
| 199 | * debugging purposes. |
| 200 | * |
| 201 | * Note that this doesn't wait for the switch to complete - it merely just configures the transceivers and initiates |
| 202 | * the PON state transitions. To wait for completion, the host must wait for the PON NI state change complete or |
| 203 | * "protection_switching_traffic_resume" indications to be received. |
| 204 | * |
| 205 | * \param[in] pair The PON on which to perform the switch (either the working or standby PON of a protected pair). |
| 206 | * \return BCM_ERR_OK if the switch was successful, <0 otherwise. |
| 207 | */ |
| 208 | bcmos_errno bcmolt_ps_switch_perform(const bcmolt_ps_pon *pon); |
| 209 | |
| 210 | #endif |