bal_release/src/common/include/bal_msg.h

/******************************************************************************
 *
 *  <:copyright-BRCM:2016:DUAL/GPL:standard
 *  
 *     Copyright (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.
 *  
 *  :>
 *
 *****************************************************************************/
 
/* Define the top level Doxygen groups. */

/**
 * @defgroup core  BAL Core Engine
 *
 * @defgroup apps  BAL Utils
 *
 * @defgroup lib   BAL Libraries
 *
 */

/**
 * @file bal_msg.h
 *
 * @brief Include files and miscellaneous macros for the BAL messaging
 *
 */

#ifndef	BALMSG_H
#define	BALMSG_H

#include <bal_objs.h>
#include <bal_msg_type.h>


/*******************************************************************
 **
 ** BAL message header helpers
 **
 *******************************************************************
 */

/*
 * Underlying msg_send timeout units in uS (micro seconds)
 */
#define BCMBAL_MSG_TIMEOUT_1_SEC  (1000000)

/*
 * Get a pointer to the message payload given the bcmos_msg pointer
 */
static inline void *bcmbal_payload_ptr_get(bal_comm_msg_hdr *_m)
{
    /* payload starts from BAL communication header */
    return (void *)_m;
}

/*
 * Get a pointer to the BAL header given the message payload pointer
 */
static inline bal_comm_msg_hdr *bcmbal_bal_hdr_get(void *_msg_payload_ptr)
{
    /* payload starts from BAL communication header */
    return (bal_comm_msg_hdr *)_msg_payload_ptr;
}

/*
 * Get a pointer to the BAL header given the bcmos header pointer
 */
static inline bal_comm_msg_hdr *bcmbal_bal_hdr_get_by_bcmos_hdr(bcmos_msg *m)
{
    return container_of(m, bal_comm_msg_hdr, m);
}

/*
 * Get a pointer to the BCMOS header given the message payload pointer
 */
static inline bcmos_msg *bcmbal_bcmos_hdr_get(void *_msg_payload_ptr)
{
    return &(bcmbal_bal_hdr_get(_msg_payload_ptr)->m);
}

/*
 * Set the BAL header parameters given the message payload pointer
 */
static inline void bcmbal_msg_hdr_set(void *_msg_payload_ptr,
                                      bcmos_msg_id _type_major,
                                      bcmbal_msg_type  _type_minor,
                                      bal_subsystem _sender_subsys,
                                      bcmbal_obj_id _msg_id_obj,
                                      uint16_t _msg_id_oper,
                                      uint32_t _ex_id)
{
    bcmos_msg *os_msg = bcmbal_bcmos_hdr_get(_msg_payload_ptr);
    bal_comm_msg_hdr *bal_hdr = bcmbal_bal_hdr_get(_msg_payload_ptr);

    /*
     * set up the bcmos_msg header fields
     */
    os_msg->data = (void *)((char *)(bcmbal_bcmos_hdr_get(_msg_payload_ptr)) + sizeof(bcmos_msg));
    os_msg->start = os_msg->data;
    os_msg->type = _type_major;
    os_msg->instance = 0;
    os_msg->sender = BCMOS_MODULE_ID_NONE; /* doesn't matter */

    /*
     * set up the bal msg header fields
     */
    bal_hdr->version_major = BAL_HDR_VERSION_MAJOR;
    bal_hdr->version_minor = BAL_HDR_VERSION_MINOR;
    bal_hdr->msg_type = _type_minor;
    bal_hdr->msg_id = ((bal_hdr->msg_id & 0x0000FFFF) |  ((_msg_id_oper & 0x0000FFFF) << 16));
    bal_hdr->msg_id = ((bal_hdr->msg_id & 0xFFFF0000) |  (_msg_id_obj & 0x0000FFFF));
    bal_hdr->ex_id = _ex_id;
    bal_hdr->sender = _sender_subsys;
    bal_hdr->timestamp = bcmos_timestamp();
}

/*
 * Get the sender field in the BAL header given the message pointer
 */
static inline bal_subsystem bcmbal_sender_get(void *_msg_payload_ptr)
{
    return bcmbal_bal_hdr_get(_msg_payload_ptr)->sender;
}

/*
 * Set the sender field in the BAL header given the message pointer
 */
static inline void bcmbal_sender_set(void *_msg_payload_ptr, bal_subsystem _sender_subsys)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->sender = _sender_subsys;
}

/*
 * Get the top level type field in the BAL header given the message pointer
 */
static inline bcmos_msg_id bcmbal_type_major_get(void *_msg_payload_ptr)
{
    return bcmbal_bcmos_hdr_get(_msg_payload_ptr)->type;
}

/*
 * Set the top level type field in the BAL header given the message pointer
 */
static inline void bcmbal_type_major_set(void *_msg_payload_ptr, bcmos_msg_id _type_major)
{
    bcmbal_bcmos_hdr_get(_msg_payload_ptr)->type = _type_major;
}

/*
 * Get the inner type field in the BAL header given the message pointer
 */
static inline bcmbal_msg_type bcmbal_type_minor_get(void *_msg_payload_ptr)
{
    return bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_type;
}

/*
 * Set the inner type field in the BAL header given the message pointer
 */
static inline void bcmbal_type_minor_set(void *_msg_payload_ptr, bcmbal_msg_type _type_minor)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_type = _type_minor;
}


/*
 * Get the msg_id_oper field in the BAL header given the message pointer
 */
static inline uint16_t bcmbal_msg_id_oper_get(void *_msg_payload_ptr)
{
    return ((bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_id & 0xFFFF0000) >> 16);
}

/*
 * Set the msg_id_oper field in the BAL header given the message pointer
 */
static inline void bcmbal_msg_id_oper_set(void *_msg_payload_ptr, uint16_t _msg_id_oper)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_id =
        ((bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_id & 0x0000FFFF) |   ((_msg_id_oper & 0x0000FFFF) << 16));
}

/*
 * Get the msg_id_obj field in the BAL header given the message pointer
 */
static inline bcmbal_obj_id bcmbal_msg_id_obj_get(void *_msg_payload_ptr)
{
    return (bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_id & 0x0000FFFF );
}

/*
 * Set the msg_id_obj field in the BAL header given the message pointer
 */
static inline void bcmbal_msg_id_obj_set(void *_msg_payload_ptr, bcmbal_obj_id _msg_id_obj)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_id =
        ((bcmbal_bal_hdr_get(_msg_payload_ptr)->msg_id & 0xFFFF0000) | (_msg_id_obj & 0x0000FFFF));
}

/*
 * Get the ex_id field in the BAL header given the message pointer
 */
static inline uint32_t bcmbal_ex_id_get(void *_msg_payload_ptr)
{
    return bcmbal_bal_hdr_get(_msg_payload_ptr)->ex_id;
}

/*
 * Set the ex_id field in the BAL header given the message pointer
 */
static inline void bcmbal_ex_id_set(void *_msg_payload_ptr, uint32_t _ex_id)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->ex_id = _ex_id;
}

/*
 * Get the major version field in the BAL header given the message pointer
 */
static inline uint16_t bcmbal_major_version_get(void *_msg_payload_ptr)
{
    return bcmbal_bal_hdr_get(_msg_payload_ptr)->version_major;
}

/*
 * Set the major version field in the BAL header given the message pointer
 */
static inline void  bcmbal_major_version_set(void *_msg_payload_ptr, uint16_t _version_major)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->version_major = _version_major;
}

/*
 * Get the minor version field in the BAL header given the message pointer
 */
static inline uint16_t bcmbal_minor_version_get(void *_msg_payload_ptr)
{
    return bcmbal_bal_hdr_get(_msg_payload_ptr)->version_minor;
}

/*
 * Set the minor version field in the BAL header given the message pointer
 */
static inline void bcmbal_minor_version_set(void *_msg_payload_ptr, uint16_t _version_major)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->version_major = _version_major;
}

/*
 * Get the scratchpad field in the BAL header given the message pointer
 */
static inline void *bcmbal_scratchpad_get(void *_msg_payload_ptr)
{
    return bcmbal_bal_hdr_get(_msg_payload_ptr)->scratchpad;
}

/*
 * Set the scratchpad field in the BAL header given the message pointer
 */
static inline void bcmbal_scratchpad_set(void *_msg_payload_ptr, void *_scratchpad)
{
    bcmbal_bal_hdr_get(_msg_payload_ptr)->scratchpad = _scratchpad;
}

/*
 * Allocate a BAL message given the payload pointer
 */
static inline void *bcmbal_msg_calloc(uint32_t _msg_payload_size)
{
    /* Payload includes comm header */
    bal_comm_msg_hdr *m = bcmos_calloc(_msg_payload_size);
    if (NULL == m)
        return NULL;
    return bcmbal_payload_ptr_get(m);
}

/*
 * Free a BAL message given the payload pointer
 */
static inline void bcmbal_msg_free(void *msg)
{
    return bcmos_msg_free(bcmbal_bcmos_hdr_get(msg));
}

/*
 * External functions implemented in bal_msg.c
 */

/*
 * Clone BAL message
 * Returns payload_ptr of the clone
 */
void *bcmbal_msg_clone(void *bal_obj);

/*
 * Send a BAL message given the payload pointer
 */
bcmos_errno bcmbal_msg_send(bcmos_msg_queue *queue, void *msg_payload, bcmos_msg_send_flags flags);

/*
 * Call callback in the context of the target module and pass it the BAL message pointer
 */
bcmos_errno bcmbal_msg_call(void *msg_payload, bcmos_module_id module, F_bcmos_msg_handler cb, bcmos_msg_send_flags flags);

/*
 * Receive a BAL message given the payload pointer
 *
 * NOTE: The timeout argument is in units of uS (micro seconds).  Use the #defined timeout values above.
 *
 */
bcmos_errno bcmbal_msg_recv(bcmos_msg_queue *queue, uint32_t timeout, void **msg_payload);

/** Get packed bal_comm_msg_hdr length */
int32_t bcmbal_bal_msg_hdr_get_packed_length(void);

/** Pack a BAL message header to a byte stream */
bcmos_errno bcmbal_bal_msg_hdr_pack(const bal_comm_msg_hdr *msg, bcmbal_buf *buf);

/** Unpack a BAL message header from a byte stream */
bcmos_errno bcmbal_bal_msg_hdr_unpack(bal_comm_msg_hdr *msg, bcmbal_buf *buf);

/** Peek exchange_id in the received message without unpacking */
bcmos_errno bcmbal_bal_msg_peek_ex_id(bcmos_msg *msg, uint32_t *ex_id);

#endif /* #ifndef BALMSG_H */