1 /*
2 * Copyright (c) 2008-2015 Texas Instruments Incorporated - http://www.ti.com
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/MessageQ.h>
45 #include <ti/ipc/NameServer.h>
48 #if defined (__cplusplus)
49 extern "C" {
50 #endif
53 /*!
54 * @def MessageQ_MODULEID
55 * @brief Unique module ID.
56 */
57 #define MessageQ_MODULEID (0xded2)
59 /*!
60 * @def MessageQ_ALLOWGROWTH
61 * @brief Allow runtime growth
62 */
63 #define MessageQ_ALLOWGROWTH NameServer_ALLOWGROWTH
65 /*! @brief Number of queues */
66 #define MessageQ_NUM_PRIORITY_QUEUES 2
68 /*
69 * Used to denote a message that was initialized
70 * with the #MessageQ_staticMsgInit function.
71 */
72 #define MessageQ_STATICMSG 0xFFFF
74 /*! Version setting */
75 #define MessageQ_HEADERVERSION (UInt) 0x2000
77 /*! Mask to extract Trace setting */
78 #define MessageQ_TRACEMASK (UInt) 0x1000
80 /*! Shift for Trace setting */
81 #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 UInt numReservedEntries;
97 /*!< Number of reserved message queue indexes */
98 } MessageQ_Config;
100 /* =============================================================================
101 * APIs
102 * =============================================================================
103 */
105 /* Internal variable to enable/disable tracing throughout MessageQ */
106 extern Bool _MessageQ_verbose;
108 /*!
109 * @brief Function to get the default configuration for the MessageQ
110 * module.
111 *
112 * This function can be called by the application to get their
113 * configuration parameter to MessageQ_setup filled in by the
114 * MessageQ module with the default parameters. If the user does
115 * not wish to make any change in the default parameters, this API
116 * is not required to be called.
117 *
118 * @param cfg Pointer to the MessageQ module configuration structure
119 * in which the default config is to be returned.
120 *
121 * @sa MessageQ_setup
122 */
123 Void MessageQ_getConfig (MessageQ_Config * cfg);
125 /*!
126 * @brief Function to setup the MessageQ module.
127 *
128 * This function sets up the MessageQ module. This function must
129 * be called before any other instance-level APIs can be invoked.
130 * Module-level configuration needs to be provided to this
131 * function. If the user wishes to change some specific config
132 * parameters, then MessageQ_getConfig can be called to get the
133 * configuration filled with the default values. After this, only
134 * the required configuration values can be changed. If the user
135 * does not wish to make any change in the default parameters, the
136 * application can simply call MessageQ with NULL parameters.
137 * The default parameters would get automatically used.
138 *
139 * @param cfg Optional MessageQ module configuration. If provided as
140 * NULL, default configuration is used.
141 *
142 * @sa MessageQ_destroy
143 * NameServer_create
144 * GateSpinlock_create
145 * Memory_alloc
146 */
147 Int MessageQ_setup (const MessageQ_Config * cfg);
149 /* Function to destroy the MessageQ module. */
150 Int MessageQ_destroy (void);
152 /* Returns the amount of shared memory used by one transport instance.
153 *
154 * The MessageQ module itself does not use any shared memory but the
155 * underlying transport may use some shared memory.
156 */
157 SizeT MessageQ_sharedMemReq (Ptr sharedAddr);
159 /* Calls the SetupProxy function to setup the MessageQ transports. */
160 Int MessageQ_attach (UInt16 remoteProcId, Ptr sharedAddr);
162 /* Calls the SetupProxy function to detach the MessageQ transports. */
163 Int MessageQ_detach (UInt16 remoteProcId);
165 NameServer_Handle MessageQ_getNameServerHandle(void);
167 Void MessageQ_setQueueOwner(MessageQ_Handle handle, Int pid);
169 Void MessageQ_cleanupOwner(Int pid);
171 Void MessageQ_msgInit(MessageQ_Msg msg);
173 #if defined (__cplusplus)
174 }
175 #endif /* defined (__cplusplus) */
178 #endif /* MESSAGEQ_H_0xded2 */