am65xx: Update Resource type to match sciclient API change
[ipc/ipcdev.git] / hlos_common / include / _MessageQ.h
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 numHeaps;
93     /*!< Number of heapIds in the system */
94     UInt maxRuntimeEntries;
95     /*!< Maximum number of MessageQs that can be dynamically created */
96     UInt maxNameLen;
97     /*!< Maximum length for Message queue names */
98     UInt numReservedEntries;
99     /*!< Number of reserved message queue indexes */
100 } MessageQ_Config;
102 /* =============================================================================
103  *  APIs
104  * =============================================================================
105  */
107 /* Internal variable to enable/disable tracing throughout MessageQ */
108 extern Bool _MessageQ_verbose;
110 /*!
111  *  @brief      Function to get the default configuration for the MessageQ
112  *              module.
113  *
114  *              This function can be called by the application to get their
115  *              configuration parameter to MessageQ_setup filled in by the
116  *              MessageQ module with the default parameters. If the user does
117  *              not wish to make any change in the default parameters, this API
118  *              is not required to be called.
119  *
120  *  @param      cfg     Pointer to the MessageQ module configuration structure
121  *                      in which the default config is to be returned.
122  *
123  *  @sa         MessageQ_setup
124  */
125 Void MessageQ_getConfig (MessageQ_Config * cfg);
127 /*!
128  *  @brief      Function to setup the MessageQ module.
129  *
130  *              This function sets up the MessageQ module. This function must
131  *              be called before any other instance-level APIs can be invoked.
132  *              Module-level configuration needs to be provided to this
133  *              function. If the user wishes to change some specific config
134  *              parameters, then MessageQ_getConfig can be called to get the
135  *              configuration filled with the default values. After this, only
136  *              the required configuration values can be changed. If the user
137  *              does not wish to make any change in the default parameters, the
138  *              application can simply call MessageQ with NULL parameters.
139  *              The default parameters would get automatically used.
140  *
141  *  @param      cfg   Optional MessageQ module configuration. If provided as
142  *                    NULL, default configuration is used.
143  *
144  *  @sa         MessageQ_destroy
145  *              NameServer_create
146  *              GateSpinlock_create
147  *              Memory_alloc
148  */
149 Int MessageQ_setup (const MessageQ_Config * cfg);
151 /* Function to destroy the MessageQ module. */
152 Int MessageQ_destroy (void);
154 /* Returns the amount of shared memory used by one transport instance.
155  *
156  *  The MessageQ module itself does not use any shared memory but the
157  *  underlying transport may use some shared memory.
158  */
159 SizeT MessageQ_sharedMemReq (Ptr sharedAddr);
161 /* Calls the SetupProxy function to setup the MessageQ transports. */
162 Int MessageQ_attach (UInt16 remoteProcId, Ptr sharedAddr);
164 /* Calls the SetupProxy function to detach the MessageQ transports. */
165 Int MessageQ_detach (UInt16 remoteProcId);
167 NameServer_Handle MessageQ_getNameServerHandle(void);
169 Void MessageQ_setQueueOwner(MessageQ_Handle handle, Int pid);
171 Void MessageQ_cleanupOwner(Int pid);
173 Void MessageQ_msgInit(MessageQ_Msg msg);
175 Void _MessageQ_setNumReservedEntries(UInt n);
177 #if defined (__cplusplus)
179 #endif /* defined (__cplusplus) */
182 #endif /* MESSAGEQ_H_0xded2 */