1 /*
2 * Copyright (c) 2008-2013, 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 */
40 #ifndef MESSAGEQ_H_0xded2
41 #define MESSAGEQ_H_0xded2
43 /* Utilities headers */
44 #include <ti/ipc/NameServer.h>
47 #if defined (__cplusplus)
48 extern "C" {
49 #endif
52 /*!
53 * @def MessageQ_MODULEID
54 * @brief Unique module ID.
55 */
56 #define MessageQ_MODULEID (0xded2)
58 /*!
59 * @def MessageQ_ALLOWGROWTH
60 * @brief Allow runtime growth
61 */
62 #define MessageQ_ALLOWGROWTH NameServer_ALLOWGROWTH
64 /*! @brief Number of queues */
65 #define MessageQ_NUM_PRIORITY_QUEUES 2
67 /*
68 * Used to denote a message that was initialized
69 * with the #MessageQ_staticMsgInit function.
70 */
71 #define MessageQ_STATICMSG 0xFFFF
73 /*! Version setting */
74 #define MessageQ_HEADERVERSION (UInt) 0x2000
76 /*! Mask to extract Trace setting */
77 #define MessageQ_TRACEMASK (UInt) 0x1000
79 /*! Shift for Trace setting */
80 #define MessageQ_TRACESHIFT (UInt) 12
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;
98 /* =============================================================================
99 * APIs
100 * =============================================================================
101 */
102 /*!
103 * @brief Function to get the default configuration for the MessageQ
104 * module.
105 *
106 * This function can be called by the application to get their
107 * configuration parameter to MessageQ_setup filled in by the
108 * MessageQ module with the default parameters. If the user does
109 * not wish to make any change in the default parameters, this API
110 * is not required to be called.
111 *
112 * @param cfg Pointer to the MessageQ module configuration structure
113 * in which the default config is to be returned.
114 *
115 * @sa MessageQ_setup
116 */
117 Void MessageQ_getConfig (MessageQ_Config * cfg);
119 /*!
120 * @brief Function to setup the MessageQ module.
121 *
122 * This function sets up the MessageQ module. This function must
123 * be called before any other instance-level APIs can be invoked.
124 * Module-level configuration needs to be provided to this
125 * function. If the user wishes to change some specific config
126 * parameters, then MessageQ_getConfig can be called to get the
127 * configuration filled with the default values. After this, only
128 * the required configuration values can be changed. If the user
129 * does not wish to make any change in the default parameters, the
130 * application can simply call MessageQ with NULL parameters.
131 * The default parameters would get automatically used.
132 *
133 * @param cfg Optional MessageQ module configuration. If provided as
134 * NULL, default configuration is used.
135 *
136 * @sa MessageQ_destroy
137 * NameServer_create
138 * GateSpinlock_create
139 * Memory_alloc
140 */
141 Int MessageQ_setup (const MessageQ_Config * cfg);
143 /* Function to destroy the MessageQ module. */
144 Int MessageQ_destroy (void);
146 /* Returns the amount of shared memory used by one transport instance.
147 *
148 * The MessageQ module itself does not use any shared memory but the
149 * underlying transport may use some shared memory.
150 */
151 SizeT MessageQ_sharedMemReq (Ptr sharedAddr);
153 /* Calls the SetupProxy function to setup the MessageQ transports. */
154 Int MessageQ_attach (UInt16 remoteProcId, Ptr sharedAddr);
156 /* Calls the SetupProxy function to detach the MessageQ transports. */
157 Int MessageQ_detach (UInt16 remoteProcId);
159 NameServer_Handle MessageQ_getNameServerHandle(void);
161 Void MessageQ_setQueueOwner(MessageQ_Handle handle, Int pid);
163 Void MessageQ_cleanupOwner(Int pid);
165 Void MessageQ_msgInit(MessageQ_Msg msg);
167 #if defined (__cplusplus)
168 }
169 #endif /* defined (__cplusplus) */
172 #endif /* MESSAGEQ_H_0xded2 */