Merge pull request #3 in PROCESSOR-SDK/traceframework from CATREQ-2702 to master
[keystone-rtos/traceframework.git] / consumer_osal.h
1 /**\r
2  *   @file  consumer_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 CONSUMER  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  *              - CONSUMER  LLD Libraries need to be rebuilt by the customer.\r
33  *\r
34  *  NOTE:\r
35  *      (C) Copyright 2012 Texas Instruments, Inc.\r
36  * \r
37  *  Redistribution and use in source and binary forms, with or without \r
38  *  modification, are permitted provided that the following conditions \r
39  *  are met:\r
40  *\r
41  *    Redistributions of source code must retain the above copyright \r
42  *    notice, this list of conditions and the following disclaimer.\r
43  *\r
44  *    Redistributions in binary form must reproduce the above copyright\r
45  *    notice, this list of conditions and the following disclaimer in the \r
46  *    documentation and/or other materials provided with the   \r
47  *    distribution.\r
48  *\r
49  *    Neither the name of Texas Instruments Incorporated nor the names of\r
50  *    its contributors may be used to endorse or promote products derived\r
51  *    from this software without specific prior written permission.\r
52  *\r
53  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \r
54  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT \r
55  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
56  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT \r
57  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, \r
58  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT \r
59  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
60  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
61  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \r
62  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE \r
63  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
64  *\r
65 */\r
66 #ifndef _CONSUMER_OSAL_H\r
67 #define _CONSUMER_OSAL_H\r
68 \r
69 #ifdef __cplusplus\r
70 extern "C" {\r
71 #endif\r
72 \r
73 #include "tf_types.h"\r
74 \r
75 /** @addtogroup TRACEFRAMEWORK_OSAL\r
76 @{ \r
77 */\r
78  \r
79 /**********************************************************************\r
80  ************************* Extern Declarations ************************\r
81  **********************************************************************/\r
82 extern void  Osal_consumer_EndMemAccess (void* addr, uint32_t size);\r
83 extern void  Osal_consumer_BeginMemAccess(void* addr, uint32_t size);\r
84 extern void  Osal_consumer_MemFree(void* ptr, uint32_t size);\r
85 extern void* Osal_consumer_MemAlloc(uint32_t num_bytes, uint32_t alignment);\r
86 extern void  Osal_consumer_Exception (uint32_t id, int32_t exception);\r
87 \r
88 /**\r
89  * @brief   The macro is used by the consumer Library to allocate the memory\r
90  *\r
91  * <b> Prototype: </b>\r
92  *  The following is the C prototype for the expected OSAL API.\r
93  *\r
94  *  @verbatim\r
95  *       void* Osal_consumer_MemAlloc (uint32_t num_bytes, uint32_t alignment)\r
96  *  @endverbatim\r
97  *\r
98  *  <b> Parameter </b>\r
99  *  @n num_bytes      - number of bytes to be allocated\r
100  *  @n alignment      - memory alignment\r
101  *\r
102  *  <b> Return Value </b>\r
103  *  @n  memory address allocated\r
104  */\r
105 \r
106 #define TF_CONSUMER_osalMemAlloc   Osal_consumer_MemAlloc\r
107 \r
108 \r
109 /**\r
110  * @brief   The macro is used by the consumer Library to free the memory\r
111  *\r
112  * <b> Prototype: </b>\r
113  *  The following is the C prototype for the expected OSAL API.\r
114  *\r
115  *  @verbatim\r
116  *       void  Osal_consumer_MemFree (void* ptr, uint32_t size)\r
117  *  @endverbatim\r
118  *\r
119  *  <b> Parameter </b>\r
120  *  @n ptr      - memory base address to be freed\r
121  *  @n size     - size of the mem block\r
122  *\r
123  *  <b> Return Value </b>\r
124  *  @n  None\r
125  */\r
126 \r
127 #define TF_CONSUMER_osalMemFree   Osal_consumer_MemFree\r
128 \r
129 /**\r
130  * @brief   The macro is used by the consumer Library to indicate that packet\r
131  * access has been accessed & updated . If the packet is in cached memory the \r
132  * implementation should writeback the contents of the packet\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_consumer_BeginMemAccess (void* addr, uint32_t sizeWords)\r
139  *  @endverbatim\r
140  *\r
141  *  <b> Parameter </b>\r
142  *  @n addr      - The address of the table to be accessed\r
143  *  @n sizeWords - The number of bytes in the table\r
144  *\r
145  *  <b> Return Value </b>\r
146  *  @n  None\r
147  */\r
148 \r
149 #define TF_CONSUMER_osalBeginMemAccess   Osal_consumer_BeginMemAccess\r
150 \r
151 \r
152 \r
153 /**\r
154  * @brief  This macro is used to alert the application that the CONSUMER \r
155  *         has completed access to table memory. This call will always\r
156  *         be made following a call to Osal_CONSUMER BeginMemAccess and have\r
157  *         the same parameters\r
158  *\r
159  * <b> Prototype: </b>\r
160  *  The following is the C prototype for the expected OSAL API.\r
161  *\r
162  *  @verbatim\r
163  *      void Osal_consumer_EndMemAccess (void* addr, uint32_t sizeWords)\r
164  *  @endverbatim\r
165  *\r
166  *  <b> Parameters </b>\r
167  *  @n addr      - The address of the table to be accessed\r
168  *  @n sizeWords - The number of bytes in the table\r
169  *\r
170  *  @note CONSUMER  will make nested calls to this function for memory access\r
171  *        protection of different memory tables. The multicore semaphore\r
172  *        should be freed when all previous memory access has completed,\r
173  *        in other words, when the nested call level reaches 0.\r
174  */\r
175  \r
176 #define TF_CONSUMER_osalEndMemAccess   Osal_consumer_EndMemAccess\r
177 \r
178 \r
179 /**\r
180  * @brief  This macro is used to alert the application that the CONSUMER \r
181  *         has encountered an exception\r
182  *\r
183  * <b> Prototype: </b>\r
184  *  The following is the C prototype for the expected OSAL API.\r
185  *\r
186  *  @verbatim\r
187  *      void Osal_consumer_Exception (uint32_t moduleId, uint32_t exception)\r
188  *  @endverbatim\r
189  *\r
190  *  <b> Parameters </b>\r
191  *  @n addr      - The address of the table to be accessed\r
192  *  @n sizeWords - The number of bytes in the table\r
193  *\r
194  *  @note CONSUMER  will make nested calls to this function for memory access\r
195  *        protection of different memory tables. The multicore semaphore\r
196  *        should be freed when all previous memory access has completed,\r
197  *        in other words, when the nested call level reaches 0.\r
198  */\r
199  \r
200 #define TF_CONSUMER_osalException   Osal_consumer_Exception\r
201 \r
202 /**\r
203 @}\r
204 */\r
205 \r
206 #ifdef __cplusplus\r
207 }\r
208 #endif\r
209 \r
210 #endif /* _CONSUMER_OSAL_H */\r
211 \r