bcm68620_release/release/host_driver/api/bcmolt_api.h

/*
<: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_API_H_
#define BCMOLT_API_H_

#include <bcmos_system.h>
#include <bcmolt_msg.h>

/** \defgroup api BCM6862x Host API
 *
 * Data Types, functions and macros that should be used for BCM6862x device management.
 * @{
 */

/** \defgroup api_macros Message Access Macros
 * @{
 */

/*
 * Message Initialization Macros
 */

/* Initialize request. Internal macro
 * \param[in]   _h      Message header
 * \param[in]   _obj    Object type
 * \param[in]   _grp    message type
 * \param[in]   _subgrp message subgroup
 */
#define _BCMOLT_REQ_INIT(_h, _obj, _grp, _subgrp) \
    (_h)->hdr.dir = BCMOLT_MSG_DIR_REQUEST;\
    (_h)->hdr.err = BCM_ERR_OK;\
    (_h)->hdr.presence_mask = 0;\
    (_h)->hdr.obj_type = bcmolt_obj_id_ ## _obj;\
    (_h)->hdr.group = _grp;\
    (_h)->hdr.subgroup = (uint16_t)_subgrp;\
    (_h)->hdr.corr_tag = 0

/** Initialize configuration structure
 * \param[in]   _s      Configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _key    Object key
 */
#define BCMOLT_CFG_INIT(_s, _obj, _key) \
    do {\
        bcmolt_ ## _obj ## _cfg *_x_ = _s;\
        memset(_x_, 0, sizeof(*_x_));\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_CFG, 0);\
        (_x_)->key = _key;\
    } while (0)

/** Initialize statistics structure
 * \param[in]   _s      Statistics structure
 * \param[in]   _obj    Object type
 * \param[in]   _key    Object key
 */
#define BCMOLT_STAT_INIT(_s, _obj, _key) \
    do {\
        bcmolt_ ## _obj ## _stat *_x_ = _s;\
        memset(_x_, 0, sizeof(*_x_));\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_STAT, 0);\
        (_x_)->key = _key;\
    } while (0)

/** Initialize statistic configuration structure
 * \param[in]   _s      Statistics configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _stat   Statistic counter name
 * \param[in]   _key    Object key
 */
#define BCMOLT_STAT_CFG_INIT(_s, _obj, _stat, _key) \
    do {\
        bcmolt_ ## _obj ## _stat_cfg *_x_ = _s;\
        memset(_x_, 0, sizeof(*_x_));\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_STAT_CFG, bcmolt_ ## _obj ## _stat_id_ ## _stat);\
        (_x_)->key = _key;\
    } while (0)

/** Initialize indication configuration structure
 * \param[in]   _s      Indication configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _key    Object key
 */
#define BCMOLT_AUTO_CFG_INIT(_s, _obj, _key) \
    do {\
        bcmolt_ ## _obj ## _auto_cfg *_x_ = _s;\
        memset(_x_, 0, sizeof(*_x_));\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_AUTO_CFG, 0);\
        (_x_)->key = _key;\
    } while (0)

/** Initialize operation structure
 * \param[in]   _s      Operation structure
 * \param[in]   _obj    Object type
 * \param[in]   _op     Operation type
 * \param[in]   _key    Object key
 */
#define BCMOLT_OPER_INIT(_s, _obj, _op, _key) \
    do {\
        bcmolt_ ## _obj ## _ ## _op *_x_ = _s;\
        memset(_x_, 0, sizeof(*_x_));\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_OPER, bcmolt_ ## _obj ## _oper_id_ ## _op);\
        (_x_)->key = _key;\
    } while (0)

/** Initialize proxy message structure
 * \param[in]   _s      Operation structure
 * \param[in]   _obj    Object type
 * \param[in]   _m      Proxy message type
 * \param[in]   _key    Object key
 */
#define BCMOLT_PROXY_INIT(_s, _obj, _m, _key) \
    do {\
        bcmolt_ ## _obj ## _ ## _m *_x_ = _s;\
        memset(_x_, 0, sizeof(*_x_));\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_PROXY, bcmolt_ ## _obj ## _proxy_id_ ## _m);\
        (_x_)->key = _key;\
    } while (0)

/** Initialize autonomous indication structure
 * \param[in]   _s      Autonomous indication structure
 * \param[in]   _obj    Object type
 * \param[in]   _au     Autonomous indication type
 */
#define BCMOLT_AUTO_INIT(_s, _obj, _au) \
    do {\
        bcmolt_ ## _obj ## _ ## _au *_x_ = _s;\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_AUTO, bcmolt_ ## _obj ## _auto_id_ ## _au);\
        _x_->hdr.hdr.subch = 0;\
        _x_->hdr.hdr.presence_mask = (1ULL << (uint64_t)bcmolt_ ## _obj ## _ ## _au ## _id_all_properties) - 1;\
    } while (0)

/** Initialize proxy_rx structure
 * \param[in]   _s      Proxy rx message structure
 * \param[in]   _obj    Object type
 * \param[in]   _pr     Proxy message type
 */
#define BCMOLT_PROXY_RX_INIT(_s, _obj, _pr) \
    do {\
        bcmolt_ ## _obj ## _ ## _pr *_x_ = _s;\
        _BCMOLT_REQ_INIT(&((_x_)->hdr), _obj, BCMOLT_MGT_GROUP_PROXY_RX, bcmolt_ ## _obj ## _proxy_rx_id_ ## _pr);\
        _x_->hdr.hdr.subch = 0;\
        _x_->hdr.hdr.presence_mask = (1ULL << (uint64_t)bcmolt_ ## _obj ## _ ## _pr ## _id_all_properties) - 1;\
    } while (0)

/** Set the memory buffer to use for variable-sized lists within a cfg get
* \param[in]   _s      Configuration structure
* \param[in]   _obj    Object type
* \param[in]   _buf    Pointer to a location in memory in which to store the lists
* \param[in]   _len    Length of the buffer pointed to by _buf
*/
#define BCMOLT_CFG_LIST_BUF_SET(_s, _obj, _buf, _len) \
    do {\
        bcmolt_ ## _obj ## _cfg *_x_ = _s;\
        _x_->hdr.hdr.list_buf = _buf;\
        _x_->hdr.hdr.list_buf_size = _len;\
    } while (0)

/* Internal macro: Get a bitmask given a property ID enum */
#define BCMOLT_PROP_MASK_GET(_obj, _grp, _p) \
    (bcmolt_ ## _obj ## _grp ## _id_ ## _p == bcmolt_ ## _obj ## _grp ## _id_all_properties ? \
        ((1ULL << (uint64_t)bcmolt_ ## _obj ## _grp ## _id_ ## _p) - 1) : \
        (1ULL << (uint64_t)bcmolt_ ## _obj ## _grp ## _id_ ## _p))

/* Internal macro: Indicate that configuration property is present */
#define _BCMOLT_PROP_SET_PRESENT(_m, _obj, _grp, _p) \
    do { \
        (_m)->hdr.hdr.presence_mask |= BCMOLT_PROP_MASK_GET(_obj, _grp, _p);\
    } while (0)

/* Internal macro: check if property is present */
#define _BCMOLT_PROP_IS_PRESENT(_m, _obj, _grp, _p) \
    (((_m)->hdr.hdr.presence_mask & BCMOLT_PROP_MASK_GET(_obj, _grp, _p)) ? \
        BCMOS_TRUE : BCMOS_FALSE)

/** Set configuration property in message structure
 * \param[in]   _m      Configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 * \param[in]   _v      Property value
 */
#define BCMOLT_CFG_PROP_SET(_m, _obj, _p, _v) \
    do { \
        _BCMOLT_PROP_SET_PRESENT(_m, _obj, _cfg, _p);\
        (_m)->data._p = (_v);\
    } while (0)

/** Indicate that configuration property should be read
 * \param[in]   _m      Configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_CFG_PROP_GET(_m, _obj, _p) _BCMOLT_PROP_SET_PRESENT(_m, _obj, _cfg, _p)

/** Check if configuration property is set in message structure
 * \param[in]   _m      Configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_CFG_PROP_IS_SET(_m, _obj, _p)    _BCMOLT_PROP_IS_PRESENT(_m, _obj, _cfg, _p)

/** Indicate that statistic property should be read
 * \param[in]   _m      Configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_STAT_PROP_GET(_m, _obj, _p) _BCMOLT_PROP_SET_PRESENT(_m, _obj, _stat, _p)

/** Check if statistic property is set in message structure
 * \param[in]   _m      Statistic structure
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_STAT_PROP_IS_SET(_m, _obj, _p)    _BCMOLT_PROP_IS_PRESENT(_m, _obj, _stat, _p)

/** Set operation property in message structure
 * \param[in]   _m      Operation structure
 * \param[in]   _obj    Object type
 * \param[in]   _op     Operation
 * \param[in]   _p      Property name
 * \param[in]   _v      Property value
 */
#define BCMOLT_OPER_PROP_SET(_m, _obj, _op, _p, _v) \
    do { \
        _BCMOLT_PROP_SET_PRESENT(_m, _obj, _ ## _op, _p);\
        (_m)->data._p = (_v);\
    } while (0)

/** Check if operation property is set in message structure
* \param[in]   _m      Operation structure
* \param[in]   _obj    Object type
* \param[in]   _op     Operation
* \param[in]   _p      Property name
*/
#define BCMOLT_OPER_PROP_IS_SET(_m, _obj, _op, _p)    _BCMOLT_PROP_IS_PRESENT(_m, _obj, _op, _p)

/** Indicate that autonomous message configuration property should be read
 * \param[in]   _m      Configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_AUTO_CFG_PROP_GET(_m, _obj, _p) _BCMOLT_PROP_SET_PRESENT(_m, _obj, _auto_cfg, _p)

/** Set autonomous message configuration property in message structure
 * \param[in]   _m      Operation structure
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 * \param[in]   _v      Property value
 */
#define BCMOLT_AUTO_CFG_PROP_SET(_m, _obj, _p, _v) \
    do { \
        _BCMOLT_PROP_SET_PRESENT(_m, _obj, _auto_cfg, _p);\
        (_m)->data._p = (_v);\
    } while (0)

/** Check if autonomous message configuration property is set in message structure
* \param[in]   _m      Configuration structure
* \param[in]   _obj    Object type
* \param[in]   _p      Property name
*/
#define BCMOLT_AUTO_CFG_PROP_IS_SET(_m, _obj, _p) _BCMOLT_PROP_IS_PRESENT(_m, _obj, _auto_cfg, _p)

/** Set statistic configuration property in message structure
* \param[in]   _m      Configuration structure
* \param[in]   _obj    Object type
* \param[in]   _p      Property name
* \param[in]   _v      Property value
*/
#define BCMOLT_STAT_CFG_PROP_SET(_m, _obj, _p, _v) \
    do { \
        _BCMOLT_PROP_SET_PRESENT(_m, _obj, _stat_cfg, _p);\
        (_m)->data._p = (_v);\
    } while (0)

/** Check if statistic configuration property is set in message structure
* \param[in]   _m      Configuration structure
* \param[in]   _obj    Object type
* \param[in]   _p      Property name
*/
#define BCMOLT_STAT_CFG_PROP_IS_SET(_m, _obj, _p) _BCMOLT_PROP_IS_PRESENT(_m, _obj, _stat_cfg, _p)

/** Set proxy message property in message structure
 * \param[in]   _m      Configuration structure
 * \param[in]   _obj    Object type
 * \param[in]   _grp    Proxy message type
 * \param[in]   _p      Property name
 * \param[in]   _v      Property value
 */
#define BCMOLT_PROXY_PROP_SET(_m, _obj, _grp, _p, _v) \
    do { \
        _BCMOLT_PROP_SET_PRESENT(_m, _obj, _ ## _grp, _p);\
        (_m)->data._p = (_v);\
    } while (0)

/** \defgroup multi_api_func Multi-object property access macros
 * @{
 */

/*
 * Macros for multi-object configuration and statistics retrieval
 */

/* Internal macro: Indicate that configuration property is present */
#define _BCMOLT_MSGSET_PROP_SET_PRESENT(_set, _obj, _grp, _p) \
    do { \
        (_set)->presence_mask |= BCMOLT_PROP_MASK_GET(_obj, _grp, _p);\
    } while (0)

/* Internal macro: check if property is present */
#define _BCMOLT_MSGSET_PROP_IS_PRESENT(_set, _obj, _grp, _p) \
    (((_set)->presence_mask & BCMOLT_PROP_MASK_GET(_obj, _grp, _p)) ? \
        BCMOS_TRUE : BCMOS_FALSE)

/** Indicate that configuration property should be read
 * \param[in]   _set    Message set
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_MSGSET_CFG_PROP_GET(_set, _obj, _p)  _BCMOLT_MSGSET_PROP_SET_PRESENT(_set, _obj, _cfg, _p)

/** Check if configuration property is set in message set
 * \param[in]   _set    Message set
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_MSGSET_CFG_PROP_IS_SET(_set, _obj, _p) _BCMOLT_MSGSET_PROP_IS_PRESENT(_set, _obj, _cfg, _p)

/** Indicate that statistic should be read
 * \param[in]   _set    Message set
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_MSGSET_STAT_PROP_GET(_set, _obj, _p)  _BCMOLT_MSGSET_PROP_SET_PRESENT(_set, _obj, _stat, _p)

/** Check if statistic property is set in message set
 * \param[in]   _set    Message set
 * \param[in]   _obj    Object type
 * \param[in]   _p      Property name
 */
#define BCMOLT_MSGSET_STAT_PROP_IS_SET(_set, _obj, _p) _BCMOLT_MSGSET_PROP_IS_PRESENT(_m, _obj, _stat, _p)

/** @} */

/** @} */

/** \defgroup api_func API Functions
 * @{
 */

/*
 * API
 */

typedef void (*system_mode_change_cb)(bcmolt_devid dev);

extern system_mode_change_cb sm_change_cb;

/** Set Configuration
 *
 * \param[in]   dev     Device id
 * \param[in]   cfg     Configuration
 * \returns error code
 */
bcmos_errno bcmolt_cfg_set(bcmolt_devid dev, bcmolt_cfg *cfg);

/** Get Configuration
 *
 * \param[in]   dev     Device id
 * \param[in]   cfg     Configuration
 * \returns error code
 * The error code can indicate local or remote failure
 */
bcmos_errno bcmolt_cfg_get(bcmolt_devid dev, bcmolt_cfg *cfg);

/** Clear Configuration
 *
 * \param[in]   dev     Device id
 * \param[in]   cfg     Configuration
 * \returns error code
 * The error code can indicate local or remote failure
 */
bcmos_errno bcmolt_cfg_clear(bcmolt_devid dev, bcmolt_cfg *cfg);

/** Get Statistics
 *
 * \param[in]   dev     Device id
 * \param[in]   stat    Configuration
 * \param[in]   flags   Flags
 * \returns error code
 * The error code can indicate local or remote failure
 */
bcmos_errno bcmolt_stat_get(bcmolt_devid dev, bcmolt_stat *stat, bcmolt_stat_flags flags);

/** Get Statistics Configuration
 *
 * \param[in]   dev     Device id
 * \param[in]   cfg     Configuration
 * \returns error code
 * The error code can indicate local or remote failure
 */
bcmos_errno bcmolt_stat_cfg_get(bcmolt_devid dev, bcmolt_stat_cfg *cfg);

/** Set Statistics Configuration
 *
 * \param[in]   dev     Device id
 * \param[in]   cfg     Configuration
 * \returns error code
 * The error code can indicate local or remote failure
 */
bcmos_errno bcmolt_stat_cfg_set(bcmolt_devid dev, bcmolt_stat_cfg *cfg);

/** Get Indication Configuration
 *
 * \param[in]   dev     Device id
 * \param[in]   cfg     Configuration
 * \returns error code
 * The error code can indicate local or remote failure
 */
bcmos_errno bcmolt_auto_cfg_get(bcmolt_devid dev, bcmolt_auto_cfg *cfg);

/** Set Indication Configuration
 *
 * \param[in]   dev     Device id
 * \param[in]   cfg     Configuration
 * \returns error code
 * The error code can indicate local or remote failure
 */
bcmos_errno bcmolt_auto_cfg_set(bcmolt_devid dev, bcmolt_auto_cfg *cfg);

/** Submit Operation
 *
 * \param[in]   dev     Device id
 * \param[in]   oper    Operation
 * \returns error code
 */
bcmos_errno bcmolt_oper_submit(bcmolt_devid dev, bcmolt_oper *oper);

/** Send Message to ONU
 *
 * \param[in]   dev     Device id
 * \param[in]   msg     Message to be sent
 * \returns error code
 */
bcmos_errno bcmolt_proxy_send(bcmolt_devid dev, bcmolt_proxy *msg);

/** Receive callback registration parameters */
typedef struct bcmolt_rx_cfg
{
    bcmolt_obj_id obj_type;     /**< Object type. Can be \ref BCMOLT_OBJECT_ANY */
    f_bcmolt_msg_handler rx_cb; /**< Receive callback. NULL=unregister */
    bcmolt_auto_flags flags;    /**< Dispatch flags. Receive callback function can be called
                                     in the context of rx task or application task,
                                     depending on the flags */
    bcmos_module_id module;     /**< Target module id.
                                     Relevant only if flags == BCMOLT_AUTO_FLAGS_DISPATCH */
    uint32_t pon_ni_mask;       /**< Bitmask of pon_ni interfaces the registration applies to.
                                     0=all interfaces. Each interface is identified by (1 << pon_ni) bit */
} bcmolt_rx_cfg;

/* (Un)Register Autonomous Indication Message Handler
 *
 * \param[in]   dev             Device id
 * \param[in]   rx_cfg          Receive handler configuration
 * \returns error code
 */
bcmos_errno bcmolt_auto_rx_cb_set(bcmolt_devid device, bcmolt_rx_cfg *rx_cfg);

/* (Un)Register Proxy Message Handler
 *
 * \param[in]   dev             Device id
 * \param[in]   rx_cfg          Receive handler configuration
 * \returns error code
 */
bcmos_errno bcmolt_proxy_rx_cb_set(bcmolt_devid device, bcmolt_rx_cfg *rx_cfg);

/** \defgroup multi_api_func Multi-object API Functions
 * @{
 */

/* Get configuration of multiple objects
 * \param[in]           olt             Device id
 * \param[in]           filter          Object filter. Header of generated bcmolt_xx_cfg structure
 * \param[in]           filter_flags    Optional filtering flags
 * \param[in,out]       msg_set         Message set
 */
bcmos_errno bcmolt_cfg_get_multi(bcmolt_devid olt, bcmolt_cfg *filter,
    bcmolt_filter_flags filter_flags, bcmolt_msg_set *msg_set);

/** @} */

/** @} */

/** @} */

#endif /* BCMOLT_API_H_ */