/*
<: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