Merge pull request #3 in PROCESSOR-SDK/traceframework from CATREQ-2702 to master
[keystone-rtos/traceframework.git] / producer_osal.h
1 /**\r
2  *   @file  producer_osal.h\r
3  *\r
4  *   @brief   \r
5  *      This is the sample OS Adaptation layer which is used by the TF Producer low level\r
6  *      driver. \r
7  *    \r
8  *   @details The OSAL layer can be ported in either of the following manners to a native OS:\r
9  *\r
10  *      <b> Approach 1: </b>\r
11  *      @n  Use Prebuilt Libraries\r
12  *           - Ensure that the LLD users provide an implementation of all \r
13  *             Osal_XXX API for their native OS.\r
14  *           - Link the prebuilt libraries with their application.\r
15  *           - Refer to the "test" directory for an example of this\r
16  *       @n <b> Pros: </b>\r
17  *              - Customers can reuse prebuilt TI provided libraries\r
18  *       @n <b> Cons: </b>\r
19  *              - Level of indirection in the API to get to the actual OS call\r
20  *              \r
21  *      <b> Approach 2: </b>\r
22  *      @n  Rebuilt Library \r
23  *           - Create a copy of this file and modify it to directly \r
24  *             inline the native OS calls\r
25  *           - Rebuild the PRODUCER  low level driver library; ensure that the Include \r
26  *             path points to the directory where the copy of this file \r
27  *             has been provided.\r
28  *           - Please refer to the "test" directory for an example of this \r
29  *       @n <b> Pros: </b>\r
30  *              - Optimizations can be done to remove the level of indirection\r
31  *       @n <b> Cons: </b>\r
32  *              - PRODUCER  LLD Libraries need to be rebuilt by the customer.\r
33  *\r
34  *  \par\r
35  *  NOTE:\r
36  *      (C) Copyright 2012 Texas Instruments, Inc.\r
37  * \r
38  *  Redistribution and use in source and binary forms, with or without \r
39  *  modification, are permitted provided that the following conditions \r
40  *  are met:\r
41  *\r
42  *    Redistributions of source code must retain the above copyright \r
43  *    notice, this list of conditions and the following disclaimer.\r
44  *\r
45  *    Redistributions in binary form must reproduce the above copyright\r
46  *    notice, this list of conditions and the following disclaimer in the \r
47  *    documentation and/or other materials provided with the   \r
48  *    distribution.\r
49  *\r
50  *    Neither the name of Texas Instruments Incorporated nor the names of\r
51  *    its contributors may be used to endorse or promote products derived\r
52  *    from this software without specific prior written permission.\r
53  *\r
54  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \r
55  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT \r
56  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
57  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT \r
58  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, \r
59  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT \r
60  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
61  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
62  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \r
63  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE \r
64  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
65  *\r
66 */\r
67 #ifndef _PRODUCER_OSAL_H\r
68 #define _PRODUCER_OSAL_H\r
69 #ifdef __cplusplus\r
70 extern "C" {\r
71 #endif\r
72 \r
73 /** @addtogroup TRACEFRAMEWORK_OSAL\r
74 @{ \r
75 */\r
76 \r
77 #include <ti/instrumentation/traceframework/producer.h>\r
78  \r
79 /**********************************************************************\r
80  ************************* Extern Declarations ************************\r
81  **********************************************************************/\r
82 extern void     Osal_producer_EndMemAccess (void* addr, uint32_t size);\r
83 extern void     Osal_producer_BeginMemAccess(void* addr, uint32_t size);\r
84 extern void     Osal_producer_MemFree(void* ptr, uint32_t size);\r
85 extern void*    Osal_producer_MemAlloc(uint32_t num_bytes, uint32_t alignment);\r
86 extern void     Osal_producer_Exception (uint32_t id, int32_t exception);\r
87 extern uint32_t Osal_producer_GetProcId(void);\r
88 \r
89 /**\r
90  * @brief   The macro is used by the trace framework Library to get the process ID\r
91  *\r
92  * <b> Prototype: </b>\r
93  *  The following is the C prototype for the expected OSAL API.\r
94  *\r
95  *  @verbatim\r
96  *       uint32_t Osal_producer_GetProcId (void)\r
97  *  @endverbatim\r
98  *\r
99  *  <b> Parameter </b>\r
100  *  @n num_bytes      - number of bytes to be allocated\r
101  *  @n alignment      - memory alignment\r
102  *\r
103  *  <b> Return Value </b>\r
104  *  @n  memory address allocated\r
105  */\r
106 \r
107 #define TF_PRODUCER_osalGetProcId   Osal_producer_GetProcId\r
108 \r
109 \r
110 /**\r
111  * @brief   The macro is used by the producer Library to allocate the memory\r
112  *\r
113  * <b> Prototype: </b>\r
114  *  The following is the C prototype for the expected OSAL API.\r
115  *\r
116  *  @verbatim\r
117  *       void* Osal_producer_MemAlloc (uint32_t num_bytes, uint32_t alignment)\r
118  *  @endverbatim\r
119  *\r
120  *  <b> Parameter </b>\r
121  *  @n num_bytes      - number of bytes to be allocated\r
122  *  @n alignment      - memory alignment\r
123  *\r
124  *  <b> Return Value </b>\r
125  *  @n  memory address allocated\r
126  */\r
127 \r
128 #define TF_PRODUCER_osalMemAlloc   Osal_producer_MemAlloc\r
129 \r
130 \r
131 /**\r
132  * @brief   The macro is used by the producer Library to free the memory\r
133  *\r
134  * <b> Prototype: </b>\r
135  *  The following is the C prototype for the expected OSAL API.\r
136  *\r
137  *  @verbatim\r
138  *       void  Osal_producer_MemFree (void* ptr, uint32_t size)\r
139  *  @endverbatim\r
140  *\r
141  *  <b> Parameter </b>\r
142  *  @n ptr      - memory base address to be freed\r
143  *  @n size     - size of the mem block\r
144  *\r
145  *  <b> Return Value </b>\r
146  *  @n  None\r
147  */\r
148 \r
149 #define TF_PRODUCER_osalMemFree   Osal_producer_MemFree\r
150 \r
151 /**\r
152  * @brief   The macro is used by the producer Library to indicate that packet\r
153  * access has been accessed & updated . If the packet is in cached memory the \r
154  * implementation should writeback the contents of the packet\r
155  *\r
156  * <b> Prototype: </b>\r
157  *  The following is the C prototype for the expected OSAL API.\r
158  *\r
159  *  @verbatim\r
160  *       void Osal_producer_BeginMemAccess (void* addr, uint32_t sizeWords)\r
161  *  @endverbatim\r
162  *\r
163  *  <b> Parameter </b>\r
164  *  @n addr      - The address of the table to be accessed\r
165  *  @n sizeWords - The number of bytes in the table\r
166  *\r
167  *  <b> Return Value </b>\r
168  *  @n  None\r
169  */\r
170 \r
171 #define TF_PRODUCER_osalBeginMemAccess   Osal_producer_BeginMemAccess\r
172 \r
173 \r
174 \r
175 /**\r
176  * @brief  This macro is used to alert the application that the PRODUCER \r
177  *         has completed access to table memory. This call will always\r
178  *         be made following a call to Osal_PRODUCER BeginMemAccess and have\r
179  *         the same parameters\r
180  *\r
181  * <b> Prototype: </b>\r
182  *  The following is the C prototype for the expected OSAL API.\r
183  *\r
184  *  @verbatim\r
185  *      void Osal_producer_EndMemAccess (void* addr, uint32_t sizeWords)\r
186  *  @endverbatim\r
187  *\r
188  *  <b> Parameters </b>\r
189  *  @n addr      - The address of the table to be accessed\r
190  *  @n sizeWords - The number of bytes in the table\r
191  *\r
192  *  @note PRODUCER  will make nested calls to this function for memory access\r
193  *        protection of different memory tables. The multicore semaphore\r
194  *        should be freed when all previous memory access has completed,\r
195  *        in other words, when the nested call level reaches 0.\r
196  */\r
197  \r
198 #define TF_PRODUCER_osalEndMemAccess   Osal_producer_EndMemAccess\r
199 \r
200 \r
201 /**\r
202  * @brief  This macro is used to alert the application that the PRODUCER \r
203  *         has encountered an exception\r
204  *\r
205  * <b> Prototype: </b>\r
206  *  The following is the C prototype for the expected OSAL API.\r
207  *\r
208  *  @verbatim\r
209  *      void Osal_producer_Exception (uint32_t moduleId, int32_t exception)\r
210  *  @endverbatim\r
211  *\r
212  *  <b> Parameters </b>\r
213  *  @n addr      - The address of the table to be accessed\r
214  *  @n sizeWords - The number of bytes in the table\r
215  *\r
216  *  @note PRODUCER  will make nested calls to this function for memory access\r
217  *        protection of different memory tables. The multicore semaphore\r
218  *        should be freed when all previous memory access has completed,\r
219  *        in other words, when the nested call level reaches 0.\r
220  */\r
221  \r
222 #define TF_PRODUCER_osalException   Osal_producer_Exception\r
223 \r
224 /**\r
225 @}\r
226 */\r
227 #ifdef __cplusplus\r
228 }\r
229 #endif\r
230 \r
231 #endif /* _PRODUCER_OSAL_H */\r
232 \r