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