/*
<: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_TR_MUX_H_
#define BCMOLT_TR_MUX_H_

/** \defgroup tr_mux Transport Multiplexer
 * - PCIe channel multiplexer
 * - locally/remotely - terminated message multiplexer
 * - autonomous messages de-multiplexer
 * @{
 */

#include <bcmolt_msg.h>
#ifndef IN_BAND
#include <bcmtr_pcie_sw_queue.h>
#endif


/* Message destination: local or remote */
typedef enum
{
    BCMTRMUX_DEST_LOCAL,
    BCMTRMUX_DEST_REMOTE,
} bcmtrmux_msg_dest;

typedef bcmtrmux_msg_dest (*bcmtrmux_msg_filter_cb_t)(bcmolt_devid, bcmolt_obj_id obj, bcmolt_mgt_group group, uint16_t subgroup);

/** Initialize mux service
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_init(bcmtrmux_msg_filter_cb_t msg_filter_cb);

/** Notify mux driver that low-level transport connection is ready
 * \returns: 0 in case of success or error code < 0
 */
#ifdef IN_BAND 
bcmos_errno bcmtrmux_connect(bcmolt_devid device,  bcmos_ipv4_address ip_address, uint16_t udp_port);
#else
bcmos_errno bcmtrmux_connect(bcmolt_devid device, uint32_t txq_size, uint32_t rxq_size);
#endif

/** Notify mux driver that low-level transport connection is disconnected
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_disconnect(bcmolt_devid device);

/** Cleanup and exit
 */
void bcmtrmux_exit(void);

/*
 * PCIe channel multiplexer
 */

/** Logical channel id */
typedef int bcmtrmux_channel;

/** Mux statistics */
typedef struct bcmtrmux_stat
{
    uint32_t tx_remote;         /**< Attempted transmit to device (incuding discards) */
    uint32_t tx_local;          /**< Attempted "transmit" to device control */
    uint32_t tx_disc_remote;    /**< Discarded when transmitting to remote device (not ready or queue overflow) */
    uint32_t tx_disc_local;     /**< Couldn't deliver to device control. No handler */
    uint32_t rx_remote;         /**< Received from device */
    uint32_t rx_local;          /**< Message from the line intercepted by device control */
    uint32_t rx_auto;           /**< Received autonomous messages */
    uint32_t control_to_host;   /**< Sent by device control to the host */
    uint32_t control_to_line;   /**< Sent by device control to line */
    uint32_t rx_disc_remote;    /**< Discarded packets received from device. Can't demux channel */
    uint32_t rx_disc_auto;      /**< Discarded autonomous messages. Can't demux auto message */
    uint32_t rx_disc_local;     /**< Discarded packets received from device control. Can't demux channel */
    uint32_t rx_disc_inv_ch;    /**< Discarded because channel is invalid */
    uint32_t rx_poll_urgent;    /**< Urgent buffers counted by bcmtr_sw_queue_rx_poll() */
    uint32_t rx_poll_normal;    /**< Normal buffers counted by bcmtr_sw_queue_rx_poll() */
} bcmtrmux_stat;


/** Max number of channels per device */
#define BCMTRMUX_MAX_CHANNELS   32

/** First urgent channel */
#ifndef IN_BAND
#define BCMTRMUX_FIRST_URGENT_CHANNEL BCMTR_SWQ_FIRST_URGENT_CHANNEL
#if BCMTRMUX_FIRST_URGENT_CHANNEL >= BCMTRMUX_MAX_CHANNELS
    #error BCMTRMUX_FIRST_URGENT_CHANNEL and BCMTRMUX_MAX_CHANNELS settings are inconsistent
#endif

#else

#define BCMTRMUX_FIRST_URGENT_CHANNEL (BCMTRMUX_MAX_CHANNELS - 1)        /* Urgent channel is not supported for INBAND. */

#endif


/** Auto-assign channel */
#define BCMTRMUX_CHANNEL_AUTO_ASSIGN   (-1)

/** Channel id reserved for autonomous/proxy messages */
#define BCMTRMUX_CHANNEL_AUTO_PROXY     0

/** Channel id reserved for device control */
#define BCMTRMUX_CHANNEL_DEV_CONTROL    1

/** First channel id that is not reserved */
#define BCMTRMUX_CHANNEL_FIRST_FREE     (BCMTRMUX_CHANNEL_DEV_CONTROL + 1)

/** Receive message handler */
typedef void (*f_bcmtr_rx_handler)(bcmolt_devid device, bcmos_buf *buf, bcmtrmux_channel channel, void *data);

/** Local receive message handler */
typedef void (*f_bcmtr_local_rx_handler)(bcmolt_devid device, bcmolt_msg *msg, void *data);

/** Register PCIe channel owner
 *
 * \param[in]           device  Maple device index
 * \param[in,out]       channel Logical PCIe channel id.
 *                              If BCMTRMUX_CHANNEL_AUTO_ASSIGN, unused channel is allocated internally.
 * \param[in]           rx      Receive callback that should be used for packets received over channel
 * \param[in]           data    Data to be passed to receive callback
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_channel_register(bcmolt_devid device, bcmtrmux_channel *channel,
    f_bcmtr_rx_handler rx, void *data);


/** Release PCIe channel allocated by bcmtrmux_channel_register()
 *
 * \param[in]   device  Maple device index
 * \param[in]   channel
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_channel_unregister(bcmolt_devid device, bcmtrmux_channel channel);


/** Receive message from host application
 *
 * This function is called for messages transmitted from the host.
 * Message can be locally or remotely terminated
 * \param[in]   device  Maple device index
 * \param[in]   channel Logical channel
 * \param[in]   buf     Buffer to be transmitted
 */
void bcmtrmux_rx_from_host(bcmolt_devid device, bcmtrmux_channel channel, bcmos_buf *buf);

/** Receive packet from PCIe interface
 *
 * \param[in]   device  Maple device index
 * \param[in]   channel Logical channel
 * \param[in]   buf     Buffer to be forwarded to application.
 *                      It is de-allocated automatically
 */
void bcmtrmux_rx_from_line(bcmolt_devid device, bcmtrmux_channel channel, bcmos_buf *buf);

/** Send packet from local control process to the host application
 *
 * \param[in]   device  Maple device index
 * \param[in]   msg     Message to be sent to host application.
 *                      Attention! It is responsibility of the caller to release the message
 *                      after return from this function - if necessary.
 *                      The reason for this is that it is expected that often msg will be allocated on stack.
 *                      It is also responsibility of the caller to make sure that msg->subch is set correctly
 *                      - preserved for request/response exchange
 *                      - set = BCMTRMUX_CHANNEL_AUTO_PROXY for autonomous indications
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_control_to_host(bcmolt_devid device, bcmolt_msg *msg);

/** Send packet from local control process to the embedded system
 *
 * \param[in]   device  Maple device index
 * \param[in]   msg     Message to be sent to the embedded system.
 *                      Attention! It is responsibility of the caller to release the message
 *                      after return from this function - if necessary.
 *                      The reason for this is that it is expected that often msg will be allocated on stack.
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_control_to_line(bcmolt_devid device, bcmolt_msg *msg);

/** Register message for intercept by dev_ctrl
 *
 * Matched message receive from the line will be intercepted and
 * delivered to callback registered using bcmtrmux_local_handler_register()
 *
 * \param[in]   device   Maple device index
 * \param[in]   object   Object for which message is to be intercepted
 * \param[in]   subgroup Message subgroup
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_control_auto_intercept_filter(bcmolt_devid device,  bcmolt_obj_id object, uint16_t subgroup);

/*
 * Local termination handler
 */

/** Register local termination handler.
 *
 * This handler is called for messages transmitted by host application
 * that should be terminated locally by device control driver and
 * for messages received from the line that match bcmtrmux_control_auto_intercept_filter()
 *
 * \param[in]   device  Maple device index
 * \param[in]   rx      Receive callback that should be used for locally-terminated packets.
 *                      It must release the buffer when no longer needed
 * \param[in]   data    Data to be passed to receive callback
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_local_handler_register(bcmolt_devid device, f_bcmtr_local_rx_handler rx, void *data);

/** Unregister local termination handler registered by bcmtrmux_local_handler_register()
 *
 * \param[in]   device  Maple device index
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_local_handler_unregister(bcmolt_devid device);

/** Get transport mux statistics.
 *
 * \param[in]   device  Maple device index
 * \param[out]  stat    Statistics
 * \returns: 0 in case of success or error code < 0
 */
bcmos_errno bcmtrmux_stat_get(bcmolt_devid device, bcmtrmux_stat *stat);

#endif