| /* |
| <:copyright-BRCM:2016:DUAL/GPL:standard |
| |
| Broadcom Proprietary and Confidential.(c) 2016 Broadcom |
| All Rights Reserved |
| |
| Unless you and Broadcom execute a separate written software license |
| agreement governing use of this software, this software is licensed |
| to you under the terms of the GNU General Public License version 2 |
| (the "GPL"), available at http://www.broadcom.com/licenses/GPLv2.php, |
| with the following added to such license: |
| |
| As a special exception, the copyright holders of this software give |
| you permission to link this software with independent modules, and |
| to copy and distribute the resulting executable under terms of your |
| choice, provided that you also meet, for each linked independent |
| module, the terms and conditions of the license of that module. |
| An independent module is a module which is not derived from this |
| software. The special exception does not apply to any modifications |
| of the software. |
| |
| Not withstanding the above, under no circumstances may you combine |
| this software in any way with any other Broadcom software provided |
| under a license other than the GPL, without Broadcom's express prior |
| written consent. |
| |
| :> |
| */ |
| |
| #ifndef _BCMOLT_USER_APPL_PS_H_ |
| #define _BCMOLT_USER_APPL_PS_H_ |
| |
| #include <bcmos_system.h> |
| #include <bcmolt_api.h> |
| #include <bcmolt_model_types.h> |
| |
| /** Conditions that can cause a protection switch to be performed. */ |
| typedef enum |
| { |
| BCMOLT_PS_SWITCH_CONDITION_LOS, /**< Switch when LoS alarm is received for a working PON. */ |
| BCMOLT_PS_SWITCH_CONDITION_MANUAL, /**< Do not switch automatically. */ |
| } bcmolt_ps_switch_condition; |
| |
| /** How provisioning should be mirrored from working to standby. */ |
| typedef enum |
| { |
| BCMOLT_PS_MIRROR_MODE_AUTO, /**< Whenever an indication is received on the working PON, mirror all necessary |
| configuration to standby PON. */ |
| BCMOLT_PS_MIRROR_MODE_NONE, /**< Do not automatically mirror any provisioning from working to standby. */ |
| } bcmolt_ps_mirror_mode; |
| |
| /** What the order of operations should be when performing a switchover. */ |
| typedef enum |
| { |
| BCMOLT_PS_SWITCH_SEQUENCE_STANDARD, /**< "standard" order: |
| 1: Change the working PON state to standby. |
| 2: Disable optical TX channel of working PON. |
| 3: Enable optical TX channel of standby PON. |
| 4: Change the standby PON state to working. */ |
| BCMOLT_PS_SWITCH_SEQUENCE_TRX_FIRST, /**< Perform transceiver enable/disable first: |
| 1: Disable optical TX channel of working PON. |
| 2: Enable optical TX channel of standby PON. |
| 3: Change the standby PON state to working. |
| 4: Change the working PON state to standby. */ |
| } bcmolt_ps_switch_sequence; |
| |
| /** Global configuration for the protection switching application. */ |
| typedef struct |
| { |
| uint16_t max_num_pairs; /**< Maximum number of protected pairs supported. */ |
| bcmolt_ps_switch_condition switch_condition; /**< Condition that should cause a switchover. */ |
| bcmolt_ps_switch_sequence switch_sequence; /**< Order of operations when performing a switchover. */ |
| |
| /* The following properties are only used in GPON mode. */ |
| bcmolt_ps_mirror_mode mirror_mode; /**< How provisioning should be mirrored from working to standby. */ |
| bcmos_bool mirror_mac_entries; /**< If TRUE, mirror all MAC learning entries to the standby PON |
| when learning indications are received from the working PON. |
| This will also cause entries to be automatically deleted when |
| aging indications are received and moved when MAC move |
| indications are received. */ |
| bcmos_bool static_mac_entries; /**< If TRUE, when entries are mirrored to the standby PON, treat |
| them as "static" (not aged). */ |
| uint32_t trx_warming_delay; /**< Delay (in usec) to wait after TRX enable, in order to |
| guarantee that POPUP PLOAMs are correctly seen by ONUs. */ |
| } bcmolt_ps_global_cfg; |
| |
| /** A single PON on an OLT device - half of a protected pair. */ |
| typedef struct |
| { |
| bcmolt_devid device_id; |
| bcmolt_pon_ni pon_id; |
| bcmolt_pon_ni transceiver_id; |
| } bcmolt_ps_pon; |
| |
| /** A protected pair of PONs, on the same OLT device or different devices. */ |
| typedef struct |
| { |
| bcmolt_ps_pon working; |
| bcmolt_ps_pon standby; |
| } bcmolt_ps_pair; |
| |
| /** Possible states for a single PON from a protection switching point-of-view. */ |
| typedef enum |
| { |
| BCMOLT_PS_PON_STATE_UNASSOCIATED, /**< The PON is not part of a protected pair. */ |
| BCMOLT_PS_PON_STATE_WORKING, /**< The PON is designated as working with the TRX enabled while active. */ |
| BCMOLT_PS_PON_STATE_STANDBY, /**< The PON is designated as standby with the TRX disabled while active. */ |
| } bcmolt_ps_pon_state; |
| |
| /** Initialize the protection switching application (this should be called as part of application startup). */ |
| void bcmolt_ps_appl_init(void); |
| |
| /** Start the protection switching application (this is global for the entire system). |
| * |
| * \param[in] cfg Global protection switching configuration. |
| * \return BCM_ERR_OK if the application was started successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_appl_start(const bcmolt_ps_global_cfg *cfg); |
| |
| /** Stop the protection switching application (this is global for the entire system). |
| * |
| * \return BCM_ERR_OK if the application was stopped successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_appl_stop(void); |
| |
| /** Query whether the protection switching application is currently running. |
| * |
| * \return BCMOS_TRUE if the application is running, BCMOS_FALSE otherwise. |
| */ |
| bcmos_bool bcmolt_ps_appl_is_running(void); |
| |
| /** Get the configuration of the running protection switching application (this is global for the entire system). |
| * |
| * \param[out] cfg Global protection switching configuration. |
| * \return BCM_ERR_OK if the configuration was retrieved successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_global_cfg_get(bcmolt_ps_global_cfg *cfg); |
| |
| /** Change the configuration of the running protection switching application (this is global for the entire system). |
| * |
| * \param[in] cfg Global protection switching configuration. |
| * \return BCM_ERR_OK if the configuration was updated successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_global_cfg_update(const bcmolt_ps_global_cfg *cfg); |
| |
| /** Get the list of all protected pairs currently tracked by the protection switching application. |
| * |
| * \param[in] array_len The length of the pairs array. |
| * \param[out] pairs An array of protected pairs to fill. |
| * \param[out] num_written The number of pairs written to the array. |
| * \return BCM_ERR_OK if the array was written successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_pairs_get(uint16_t array_len, bcmolt_ps_pair *pairs, uint16_t *num_written); |
| |
| /** Add a protected pair to the protection switching database. |
| * |
| * After this has been called, provisioning will be mirrored from the working PON to the standby PON according to the |
| * mirror_mode global parameter, and a switch will be performed per the switch_condition global parameter. |
| * |
| * \param[in] pair A pair of PONs to add - they can be on the same OLT device or different devices. |
| * \return BCM_ERR_OK if the pair was added successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_pair_add(const bcmolt_ps_pair *pair); |
| |
| /** Remove the protected pair containing the specified PON from the protection switching database. |
| * |
| * \param[in] pon A PON that is a member of a protection pair. |
| * \return BCM_ERR_OK if the PON was removed successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_pon_remove(const bcmolt_ps_pon *pon); |
| |
| /** Query for the current state of a protected PON. |
| * |
| * \param[in] pon The PON to query. |
| * \param[out] state The protection state of the PON (e.g. working/standby). |
| * \param[out] partner If this PON is protected, the other half of the protected pair. |
| * \return BCM_ERR_OK if the PON was queried successfully, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_pon_state_get(const bcmolt_ps_pon *pon, bcmolt_ps_pon_state *state, bcmolt_ps_pon *partner); |
| |
| /** Process an indication received by the working PON. |
| * |
| * The action taken will depend on the object/indication type and the mirror_mode global parameter. |
| * If the application isn't running, the supplied PON isn't in a protected working state or the indication isn't |
| * relevant for protection switching, the indication will be ignored. |
| * |
| * Note: this function does not free the indication. |
| * The caller must free it using bcmos_msg_free() after calling this function. |
| * |
| * \param[in] pon The PON on which the indication was received. |
| * \param[in] ind The indication that was received. |
| * \return BCM_ERR_OK if the indication was processed successfully or ignored, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_process_ind(const bcmolt_ps_pon *pon, bcmolt_auto *ind); |
| |
| /** Immediately perform a protection switch on the given PON, which must belong to a protected pair. |
| * |
| * This function is primarily intended for use with the BCMOLT_PS_SWITCH_CONDITION_MANUAL switch condition, or for |
| * debugging purposes. |
| * |
| * Note that this doesn't wait for the switch to complete - it merely just configures the transceivers and initiates |
| * the PON state transitions. To wait for completion, the host must wait for the PON NI state change complete or |
| * "protection_switching_traffic_resume" indications to be received. |
| * |
| * \param[in] pair The PON on which to perform the switch (either the working or standby PON of a protected pair). |
| * \return BCM_ERR_OK if the switch was successful, <0 otherwise. |
| */ |
| bcmos_errno bcmolt_ps_switch_perform(const bcmolt_ps_pon *pon); |
| |
| #endif |