MessageQ.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2015 Texas Instruments Incorporated - https://www.ti.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef ti_ipc_MessageQ__include
#define ti_ipc_MessageQ__include

#include <ti/ipc/MultiProc.h>

#if defined (__cplusplus)
extern "C" {
#endif

/* =============================================================================
 *  All success and failure codes for the module
 * =============================================================================
 */

#define MessageQ_S_BUSY                  (2)

#define MessageQ_S_ALREADYSETUP          (1)

#define MessageQ_S_SUCCESS               (0)

#define MessageQ_E_FAIL                 (-1)

#define MessageQ_E_INVALIDARG           (-2)

#define MessageQ_E_MEMORY               (-3)

#define MessageQ_E_ALREADYEXISTS        (-4)

#define MessageQ_E_NOTFOUND             (-5)

#define MessageQ_E_TIMEOUT              (-6)

#define MessageQ_E_INVALIDSTATE         (-7)

#define MessageQ_E_OSFAILURE            (-8)

#define MessageQ_E_RESOURCE             (-9)

#define MessageQ_E_RESTART              (-10)

#define MessageQ_E_INVALIDMSG           (-11)

#define MessageQ_E_NOTOWNER             (-12)

#define MessageQ_E_REMOTEACTIVE         (-13)

#define MessageQ_E_INVALIDHEAPID        (-14)

#define MessageQ_E_INVALIDPROCID        (-15)

#define MessageQ_E_MAXREACHED           (-16)

#define MessageQ_E_UNREGISTEREDHEAPID   (-17)

#define MessageQ_E_CANNOTFREESTATICMSG  (-18)

#define MessageQ_E_UNBLOCKED            (-19)

#define MessageQ_E_SHUTDOWN             (-20)

/* =============================================================================
 *  Macros
 * =============================================================================
 */

#define MessageQ_FOREVER                (~(0))

#define MessageQ_INVALIDMSGID           (0xffff)

#define MessageQ_INVALIDMESSAGEQ        (0xffff)

#define MessageQ_PRIORITYMASK           (0x3)

#define MessageQ_PORTOFFSET             (0x80)

#define MessageQ_getDstQueue(msg) \
        (((MessageQ_Msg)(msg))->dstId == \
        (MessageQ_QueueIndex)MessageQ_INVALIDMESSAGEQ) ? \
        (MessageQ_QueueId)MessageQ_INVALIDMESSAGEQ : \
        (((MessageQ_QueueId)((MessageQ_Msg)(msg))->dstProc << 16u) \
        | (((MessageQ_Msg)(msg))->dstId))


#define MessageQ_getMsgId(msg) (((MessageQ_Msg) (msg))->msgId)

#define MessageQ_getMsgSize(msg) (((MessageQ_Msg) (msg))->msgSize)

#define MessageQ_getMsgPri(msg)        \
                 ((((MessageQ_Msg) (msg))->flags & MessageQ_PRIORITYMASK))

#define MessageQ_getProcId(queueId)     \
                 ((UInt16)((queueId) >> 16))

#define MessageQ_getQueueIndex(queueId) \
        (((MessageQ_QueueIndex)((MessageQ_QueueId)0xFFFF & (queueId))) \
        - MessageQ_PORTOFFSET)

#define MessageQ_getReplyQueue(msg)           \
                (MessageQ_QueueId)((((MessageQ_Msg) (msg))->replyProc << 16u) \
                | ((MessageQ_Msg)(msg))->replyId)

#define MessageQ_getTransportId(msg) \
        ((((MessageQ_Msg)(msg))->flags & (0x7 << 2)) >> 2)

#define MessageQ_setMsgId(msg, id) ((MessageQ_Msg) (msg))->msgId = (id)

#define MessageQ_setMsgPri(msg, priority) \
        ((MessageQ_Msg)(msg))->flags = \
        (((MessageQ_Msg)(msg))->flags & ~(MessageQ_PRIORITYMASK)) \
        | ((priority) & MessageQ_PRIORITYMASK)

#define MessageQ_setTransportId(msg, tid) \
        ((MessageQ_Msg)(msg))->flags = \
        ((((MessageQ_Msg)(msg))->flags & ~(0x7 << 2)) | ((tid) << 2))

/* =============================================================================
 *  Structures & Enums
 * =============================================================================
 */

typedef UInt32 MessageQ_QueueId;

typedef UInt16 MessageQ_QueueIndex;

typedef struct MessageQ_Object *MessageQ_Handle;

typedef struct {
    Int __version;
    /*  Used internally for tracking implementation evolution.
     *  For internal use only.
     */
    Void *synchronizer;
     MessageQ_QueueIndex queueIndex;
} MessageQ_Params;

/*  Date: 02 Dec 2014
 *
 *  Initial implementation of params structure which contains
 *  a version field. This allows for binary compatibility as
 *  the params structure is modified in the future.
 */
#define MessageQ_Params_VERSION_2       2

#define MessageQ_Params_VERSION         MessageQ_Params_VERSION_2

typedef struct {
    Void *synchronizer;
     MessageQ_QueueIndex queueIndex;
} MessageQ_Params2;

typedef struct {
    Bits32       reserved0;         
    Bits32       reserved1;         
    Bits32       msgSize;           
    Bits16       flags;             
    Bits16       msgId;             
    Bits16       dstId;             
    Bits16       dstProc;           
    Bits16       replyId;           
    Bits16       replyProc;         
    Bits16       srcProc;           
    Bits16       heapId;            
    Bits16       seqNum;            
    Bits16       reserved;          
} MessageQ_MsgHeader;

typedef MessageQ_MsgHeader *MessageQ_Msg;

typedef enum {
    MessageQ_NORMALPRI      = 0,    
    MessageQ_HIGHPRI        = 1,    
    MessageQ_RESERVEDPRI    = 2,    
    MessageQ_URGENTPRI      = 3     
} MessageQ_Priority;

#define MessageQ_ANY (Bits16)~(0)

typedef Void (*MessageQ_FreeHookFxn)(Bits16 heapId, Bits16 msgId);

typedef Void (*MessageQ_PutHookFxn)(MessageQ_QueueId queueId, MessageQ_Msg msg);

#ifdef STD_H
#include <ti/ipc/interfaces/ITransport.h>
#include <ti/ipc/interfaces/IMessageQTransport.h>
#else
#include <ti/sdo/ipc/interfaces/ITransport.h>
#include <ti/sdo/ipc/interfaces/IMessageQTransport.h>
#endif

Bool MessageQ_registerTransport(IMessageQTransport_Handle handle,
                                UInt16 rprocId, UInt priority);
Void MessageQ_unregisterTransport(UInt16 rprocId, UInt priority);


/* =============================================================================
 *  MessageQ Module-wide Functions
 * =============================================================================
 */

/* Returns the local handle associated with queueId. */
MessageQ_Handle MessageQ_getLocalHandle(MessageQ_QueueId queueId);
Void MessageQ_Params_init__S(MessageQ_Params *params, Int version);
#ifndef MessageQ_internal
static inline Void MessageQ_Params_init(MessageQ_Params *params)
{
    if (params != NULL) {
        MessageQ_Params_init__S(params, MessageQ_Params_VERSION);
    }
}
#endif

Void MessageQ_Params2_init(MessageQ_Params2 *params);

MessageQ_Handle MessageQ_create(String name, const MessageQ_Params *params);

MessageQ_Handle MessageQ_create2(String name, const MessageQ_Params2 *params);

Int MessageQ_delete(MessageQ_Handle *handlePtr);

Int MessageQ_open(String name, MessageQ_QueueId *queueId);

MessageQ_QueueId MessageQ_openQueueId(UInt16 queueIndex, UInt16 procId);

Int MessageQ_close(MessageQ_QueueId *queueId);

MessageQ_Msg MessageQ_alloc(UInt16 heapId, UInt32 size);

Int MessageQ_free(MessageQ_Msg msg);

Int MessageQ_registerHeap(Ptr heap, UInt16 heapId);

Bool MessageQ_registerTransportId(UInt tid, ITransport_Handle inst);

Int MessageQ_unregisterHeap(UInt16 heapId);

Void MessageQ_unregisterTransportId(UInt tid);

Void MessageQ_setMsgTrace(MessageQ_Msg msg, Bool traceFlag);

Void MessageQ_staticMsgInit(MessageQ_Msg msg, UInt32 size);

Void MessageQ_setFreeHookFxn(MessageQ_FreeHookFxn freeHookFxn);

Void MessageQ_setPutHookFxn(MessageQ_PutHookFxn putHookFxn);

/* =============================================================================
 *  MessageQ Per-instance Functions
 * =============================================================================
 */

Int MessageQ_get(MessageQ_Handle handle, MessageQ_Msg *msg, UInt timeout);

Int MessageQ_put(MessageQ_QueueId queueId, MessageQ_Msg msg);

Int MessageQ_count(MessageQ_Handle handle);

UInt32 MessageQ_getQueueId(MessageQ_Handle handle);

Void MessageQ_setReplyQueue(MessageQ_Handle handle, MessageQ_Msg msg);

Void MessageQ_unblock(MessageQ_Handle handle);

Void MessageQ_shutdown(MessageQ_Handle handle);

#if defined (__cplusplus)
}
#endif /* defined (__cplusplus) */
#endif /* ti_ipc_MessageQ__include */