bcm68620_release/release/host_driver/transport/bcmtr_interface.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 BCMTR_INTERFACE_H_
#define BCMTR_INTERFACE_H_

#include <bcmos_system.h>
#include <bcmolt_model_types.h>

#ifdef __cplusplus
extern "C" {
#endif

/** Transport statistics */
typedef struct bcmtr_stat
{
    uint32_t msg_sent;                  /**< Messages sent */
    uint32_t msg_resp_received;         /**< Valid responses received */
    uint32_t msg_req_auto_received;     /**< Request or Autonomous message received */
    uint32_t msg_req_timeout;           /**< Number of requests that timed out */
    uint32_t msg_reass_timeout;         /**< Number of messages discarded due to reassemble timeout */
    uint32_t msg_no_req;                /**< Number of responses discarded because there was no matching request */
    uint32_t msg_no_mem;                /**< Number of memory allocation failures */
    uint32_t msg_comm_err;              /**< Messages discarded because of communication error */
    uint32_t msg_ready_timeout;         /**< Responses that have been reported to application but not peaked up */
    uint32_t msg_too_many_req;          /**< Number of requests discarded because there were too many outstanding requests */
    uint32_t msg_too_many_auto;         /**< Number of autonomous messages discarded because there were too many being reassembled */
    uint32_t not_connected;             /**< Number of TX messages discarded because connection was lost */
    uint32_t frag_received;             /**< Valid fragments received */
    uint32_t frag_invalid;              /**< Fragments discarded */
    uint32_t pack_errors;               /**< Message pack errors */
    uint32_t unpack_errors;             /**< Message unpack errors */
    uint32_t no_rx_handler;             /**< Message discarded because there was no rx handler */
} bcmtr_stat;

/** Transport message control block */
typedef struct bcmtr_msg bcmtr_msg;

/** Channel id */
typedef uint8_t bcmtr_channel_id;

/** Send flags */
typedef enum
{
    BCMTR_SEND_FLAGS_NONE               = 0,            /**< None */
    BCMTR_SEND_FLAGS_CALL               = 0x0001,       /**< Request/Response sequence */

    BCMTR_SEND_FLAGS_PRI_NORMAL         = 0,            /**< Normal priority */
    BCMTR_SEND_FLAGS_PRI_HI             = 0x0010,       /**< High priority */

    BCMTR_SEND_FLAGS_LONG_WAIT          = 0x0100,       /**< Enable long wait until there is room in tx queue */
    BCMTR_SEND_FLAGS_SHORT_WAIT         = 0x0200,       /**< Enable short wait until there is room in tx queue */
    BCMTR_SEND_FLAGS_DO_NOT_WAIT        = 0x0400,       /**< Drop packet if TX q is full */

} bcmtr_send_flags;

#define BCMTR_SEND_FLAGS_WAIT_MASK (BCMTR_SEND_FLAGS_LONG_WAIT | BCMTR_SEND_FLAGS_SHORT_WAIT | BCMTR_SEND_FLAGS_DO_NOT_WAIT)

/** Transport handler registration parameters */
typedef struct bcmtr_handler_parm
{
    uint8_t instance;           /**< Instance (i.e, link) */
    bcmolt_mgt_group group;     /**< Message group */
    bcmolt_obj_id object;       /**< Object. Can be BCMOLT_OBJECT_ANY */
    uint16_t subgroup;          /**< Message subgroup. Can be BCMOLT_SUBGROUP_ANY */
    f_bcmolt_msg_handler app_cb;/**< Message handler */
    bcmolt_auto_flags flags;    /**< Flags. app_cb is called in context of transport task
                                     or app module, depending on the flags */
    bcmos_module_id module;     /**< Target module id. Relevant only if flags == BCMOLT_AUTO_FLAGS_DISPATCH.
                                     BCMOS_MODULE_ID_NONE is replaced by the module calling registration function */
} bcmtr_handler_parm;

/** Initialize transport library.
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_init(void);

/** Release resources used by transport library.
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_exit(void);

/** Send message. Do not wait for response
 *
 * Set-up connection if necessary, pack message and send it to the remote side.
 * This function is intended for proxy and autonomous messages.
 *
 * \param[in]   device  OLT device index
 * \param[in]   msg     Application message to be sent
 * \param[in]   flags   flags (request/auto or reply)
 *
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_send(bcmolt_devid device, bcmolt_msg *msg, bcmtr_send_flags flags);

/** Send response message
 *
 * Set-up connection if necessary, pack message and send it to the remote side.
 * This function is intended for proxy and autonomous messages.
 *
 * \param[in]   device  OLT device index
 * \param[in]   msg     Application message to be sent
 * \param[in]   flags   flags (request/auto or reply)
 *
 * \returns BCM_ERR_OK or error code
 */
static inline bcmos_errno bcmtr_send_response(bcmolt_devid device, bcmolt_msg *msg)
{
    msg->dir = BCMOLT_MSG_DIR_RESPONSE;
    return bcmtr_send(device, msg, BCMTR_SEND_FLAGS_CALL | BCMTR_SEND_FLAGS_SHORT_WAIT);
}

/** Send request and wait for reply
 *
 * Set-up connection if necessary, pack message and send it to the remote side.
 * Wait for reply or timeout, unpack the reply and return.
 *
 * \param[in]        device  OLT device index
 * \param[in, out]   msg     Application message
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_call(bcmolt_devid device, bcmolt_msg *msg);

/** Register message handler
 *
 * \param[in]   device          OLT device index
 * \param[in]   parm            Registration parameters
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_msg_handler_register(bcmolt_devid device, const bcmtr_handler_parm *parm);

/** Unregister message handler
 *
 * \param[in]   device          OLT device index
 * \param[in]   parm            Registration parameters
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_msg_handler_unregister(bcmolt_devid device, const bcmtr_handler_parm *parm);

/** Get registration info
 *
 * \param[in]           device          OLT device index
 * \param[in,out]       parm            Registration parameters.
 *                                      instance, group, object, subgroup must be set
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_msg_handler_register_get(bcmolt_devid device, bcmtr_handler_parm *parm);

/** Get transport statistics
 *
 * \param[in]   device          OLT device index
 * \param[out]  stat            Statistics
 * \returns BCM_ERR_OK or error code
 */
bcmos_errno bcmtr_stat_get(bcmolt_devid device, bcmtr_stat *stat);

/* Query whether or not the device is currently connected */
bcmos_errno bcmtr_is_connected(bcmolt_devid device, bcmos_bool *is_connected);

/* Connect device */
bcmos_errno bcmtr_connect(bcmolt_devid device);

/* Disconnect device */
bcmos_errno bcmtr_disconnect(bcmolt_devid device);

/* Low-level disconnect that breaks "physical" connection, but doesn't destroy connection structure and registrations */
bcmos_errno bcmtr_driver_disconnect(bcmolt_devid device);

/* Repair/reconnect the driver-level connection for an already-connected device */
bcmos_errno bcmtr_driver_reconnect(bcmolt_devid device);

/* "dropped because of tx_queue overflow" indication */
typedef void (*F_bcmtr_tx_overflow)(bcmolt_devid device, bcmtr_send_flags send_flags);

/* Register for notification that transmit failed because
 * tx_queue was full
 * \param[in]   device          OLT device index
 * \param[in]   cb              Callback to be called. NULL=unregister
 * \returns 0=OK or error code < 0
 */
bcmos_errno bcmtr_tx_overflow_cb_register(bcmolt_devid device, F_bcmtr_tx_overflow cb);

/*
 * The following functions are useful for proxy daemon.
 * They provide direct interface to transport plugin
 */

/* Connect device in raw mode
 * Receive task is NOT created
 * \param[in]   device          OLT device index
 * \parm[out]   headroom        Headroom that should be reserved in buffer when transmitting
 * \returns 0=OK or error code < 0
 */
bcmos_errno bcmtr_proxy_connect(bcmolt_devid device, uint32_t *headroom);

/* Send data to device
 * \param[in]   device          OLT device index
 * \param[in]   txb             Transmit buffer
 * \returns 0=OK or error code < 0
 */
bcmos_errno bcmtr_proxy_send(bcmolt_devid device, bcmolt_buf *tx_buf);

/* Receive data from device
 * \param[in]   device          OLT device index
 * \param[in]   rxb             Receive buffer
 * \returns 0=OK, BCM_ERR_TIMEOUT-timeout and no message, other errors <0
 */
bcmos_errno bcmtr_proxy_receive(bcmolt_devid device, bcmolt_buf *rx_buf);


#ifdef __cplusplus
}
#endif

#endif /* BCMTR_INTERFACE_H_ */