hlos_common/include/_MessageQ.h

   1 /*
   2  *  Copyright (c) 2008-2014, Texas Instruments Incorporated
   3  *  All rights reserved.
   4  *
   5  *  Redistribution and use in source and binary forms, with or without
   6  *  modification, are permitted provided that the following conditions
   7  *  are met:
   8  *
   9  *  *  Redistributions of source code must retain the above copyright
  10  *     notice, this list of conditions and the following disclaimer.
  11  *
  12  *  *  Redistributions in binary form must reproduce the above copyright
  13  *     notice, this list of conditions and the following disclaimer in the
  14  *     documentation and/or other materials provided with the distribution.
  15  *
  16  *  *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *     its contributors may be used to endorse or promote products derived
  18  *     from this software without specific prior written permission.
  19  *
  20  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  *  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  *  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ============================================================================
  33  *  @file   _MessageQ.h
  34  *
  35  *  @brief  Defines MessageQ module.
  36  *  ============================================================================
  37  */
  38
  39
  40 #ifndef MESSAGEQ_H_0xded2
  41 #define MESSAGEQ_H_0xded2
  42
  43 /* Utilities headers */
  44 #include <ti/ipc/NameServer.h>
  45
  46
  47 #if defined (__cplusplus)
  48 extern "C" {
  49 #endif
  50
  51
  52 /*!
  53  *  @def    MessageQ_MODULEID
  54  *  @brief  Unique module ID.
  55  */
  56 #define MessageQ_MODULEID               (0xded2)
  57
  58 /*!
  59  *  @def    MessageQ_ALLOWGROWTH
  60  *  @brief  Allow runtime growth
  61  */
  62 #define MessageQ_ALLOWGROWTH             NameServer_ALLOWGROWTH
  63
  64 /*! @brief Number of queues */
  65 #define MessageQ_NUM_PRIORITY_QUEUES  2
  66
  67 /*
  68  *  Used to denote a message that was initialized
  69  *  with the #MessageQ_staticMsgInit function.
  70  */
  71 #define MessageQ_STATICMSG              0xFFFF
  72
  73 /*! Version setting */
  74 #define MessageQ_HEADERVERSION   (UInt) 0x2000
  75
  76 /*! Mask to extract Trace setting */
  77 #define MessageQ_TRACEMASK       (UInt) 0x1000
  78
  79 /*! Shift for Trace setting */
  80 #define MessageQ_TRACESHIFT      (UInt) 12
  81
  82
  83 /*!
  84  *  @brief  Structure defining config parameters for the MessageQ Buf module.
  85  */
  86 typedef struct MessageQ_Config_tag {
  87     Bool   traceFlag;
  88     /*!< Trace flag
  89      *  This flag allows the configuration of the default module trace
  90      *  settings.
  91      */
  92     UInt maxRuntimeEntries;
  93     /*!< Maximum number of MessageQs that can be dynamically created */
  94     UInt maxNameLen;
  95     /*!< Maximum length for Message queue names */
  96 } MessageQ_Config;
  97
  98 /* =============================================================================
  99  *  APIs
 100  * =============================================================================
 101  */
 102
 103 /* Internal variable to enable/disable tracing throughout MessageQ */
 104 extern Bool _MessageQ_verbose;
 105
 106 /*!
 107  *  @brief      Function to get the default configuration for the MessageQ
 108  *              module.
 109  *
 110  *              This function can be called by the application to get their
 111  *              configuration parameter to MessageQ_setup filled in by the
 112  *              MessageQ module with the default parameters. If the user does
 113  *              not wish to make any change in the default parameters, this API
 114  *              is not required to be called.
 115  *
 116  *  @param      cfg     Pointer to the MessageQ module configuration structure
 117  *                      in which the default config is to be returned.
 118  *
 119  *  @sa         MessageQ_setup
 120  */
 121 Void MessageQ_getConfig (MessageQ_Config * cfg);
 122
 123 /*!
 124  *  @brief      Function to setup the MessageQ module.
 125  *
 126  *              This function sets up the MessageQ module. This function must
 127  *              be called before any other instance-level APIs can be invoked.
 128  *              Module-level configuration needs to be provided to this
 129  *              function. If the user wishes to change some specific config
 130  *              parameters, then MessageQ_getConfig can be called to get the
 131  *              configuration filled with the default values. After this, only
 132  *              the required configuration values can be changed. If the user
 133  *              does not wish to make any change in the default parameters, the
 134  *              application can simply call MessageQ with NULL parameters.
 135  *              The default parameters would get automatically used.
 136  *
 137  *  @param      cfg   Optional MessageQ module configuration. If provided as
 138  *                    NULL, default configuration is used.
 139  *
 140  *  @sa         MessageQ_destroy
 141  *              NameServer_create
 142  *              GateSpinlock_create
 143  *              Memory_alloc
 144  */
 145 Int MessageQ_setup (const MessageQ_Config * cfg);
 146
 147 /* Function to destroy the MessageQ module. */
 148 Int MessageQ_destroy (void);
 149
 150 /* Returns the amount of shared memory used by one transport instance.
 151  *
 152  *  The MessageQ module itself does not use any shared memory but the
 153  *  underlying transport may use some shared memory.
 154  */
 155 SizeT MessageQ_sharedMemReq (Ptr sharedAddr);
 156
 157 /* Calls the SetupProxy function to setup the MessageQ transports. */
 158 Int MessageQ_attach (UInt16 remoteProcId, Ptr sharedAddr);
 159
 160 /* Calls the SetupProxy function to detach the MessageQ transports. */
 161 Int MessageQ_detach (UInt16 remoteProcId);
 162
 163 NameServer_Handle MessageQ_getNameServerHandle(void);
 164
 165 Void MessageQ_setQueueOwner(MessageQ_Handle handle, Int pid);
 166
 167 Void MessageQ_cleanupOwner(Int pid);
 168
 169 Void MessageQ_msgInit(MessageQ_Msg msg);
 170
 171 #if defined (__cplusplus)
 172 }
 173 #endif /* defined (__cplusplus) */
 174
 175
 176 #endif /* MESSAGEQ_H_0xded2 */