1 /**\r
2 * @file contract_osal.h\r
3 *\r
4 * @brief \r
5 * This is a very slim consumer framework library implementation.\r
6 *\r
7 * ============================================================================\r
8 * @n (C) Copyright 2012, Texas Instruments, Inc.\r
9 * \r
10 * Redistribution and use in source and binary forms, with or without \r
11 * modification, are permitted provided that the following conditions \r
12 * are met:\r
13 *\r
14 * Redistributions of source code must retain the above copyright \r
15 * notice, this list of conditions and the following disclaimer.\r
16 *\r
17 * Redistributions in binary form must reproduce the above copyright\r
18 * notice, this list of conditions and the following disclaimer in the \r
19 * documentation and/or other materials provided with the \r
20 * distribution.\r
21 *\r
22 * Neither the name of Texas Instruments Incorporated nor the names of\r
23 * its contributors may be used to endorse or promote products derived\r
24 * from this software without specific prior written permission.\r
25 *\r
26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \r
27 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT \r
28 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
29 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT \r
30 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, \r
31 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT \r
32 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
33 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
34 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \r
35 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE \r
36 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
37 *\r
38 */\r
39 \r
40 #ifndef __CONTRACTOSAL_H__\r
41 #define __CONTRACTOSAL_H__\r
42 #include <ti/instrumentation/traceframework/tf_types.h>\r
43 \r
44 #ifdef __cplusplus\r
45 extern "C" {\r
46 #endif\r
47 \r
48 /** @addtogroup TRACEFRAMEWORK_OSAL\r
49 @{ \r
50 */\r
51 \r
52 /**********************************************************************\r
53 ************************* Extern Declarations ************************\r
54 **********************************************************************/\r
55 extern void Osal_contract_EndMemAccess (void* addr, uint32_t sizeWords);\r
56 extern void Osal_contract_BeginMemAccess (void* addr, uint32_t sizeWords);\r
57 extern void Osal_contract_Enter (void);\r
58 extern void Osal_contract_Exit (void);\r
59 extern void Osal_contract_MemFree(void* ptr, uint32_t size);\r
60 extern void* Osal_contract_MemAlloc(uint32_t num_bytes, uint32_t alignment);\r
61 extern void* Osal_contract_mmap(void* phy_addr, uint32_t size);\r
62 extern void Osal_contract_unmap(void* virt_addr, uint32_t size);\r
63 \r
64 \r
65 /**\r
66 * @brief The macro is used by the trace framework Library to allocate the memory\r
67 *\r
68 * <b> Prototype: </b>\r
69 * The following is the C prototype for the expected OSAL API.\r
70 *\r
71 * @verbatim\r
72 * void* Osal_contract_MemAlloc (uint32_t num_bytes, uint32_t alignment)\r
73 * @endverbatim\r
74 *\r
75 * <b> Parameter </b>\r
76 * @n num_bytes - number of bytes to be allocated\r
77 * @n alignment - memory alignment\r
78 *\r
79 * <b> Return Value </b>\r
80 * @n memory address allocated\r
81 */\r
82 \r
83 #define TF_CONTRACT_osalMemAlloc Osal_contract_MemAlloc\r
84 \r
85 \r
86 /**\r
87 * @brief The macro is used by the trace framework Library to free the memory\r
88 *\r
89 * <b> Prototype: </b>\r
90 * The following is the C prototype for the expected OSAL API.\r
91 *\r
92 * @verbatim\r
93 * void Osal_contract_MemFree (void* ptr, uint32_t size)\r
94 * @endverbatim\r
95 *\r
96 * <b> Parameter </b>\r
97 * @n ptr - memory base address to be freed\r
98 * @n size - size of the mem block\r
99 *\r
100 * <b> Return Value </b>\r
101 * @n None\r
102 */\r
103 \r
104 #define TF_CONTRACT_osalMemFree Osal_contract_MemFree\r
105 \r
106 \r
107 /**\r
108 * @brief The macro is used by the producer/consumer Library to indicate that memory\r
109 * access has been accessed & updated . If the values are in cached memory the \r
110 * implementation should invalidate the contents of the cache\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_contract_BeginMemAccess (void* addr, uint32_t sizeWords)\r
117 * @endverbatim\r
118 *\r
119 * <b> Parameter </b>\r
120 * @n addr - Pointer to the memory address being accessed.\r
121 * @n size - Size of the packet.\r
122 *\r
123 * <b> Return Value </b>\r
124 * @n None\r
125 */\r
126 \r
127 #define TF_CONTRACT_osalBeginMemAccess Osal_contract_BeginMemAccess\r
128 \r
129 \r
130 /**\r
131 * @brief The macro is used by the producer/consumer Library to indicate that memory\r
132 * access has been completed. If the values are in cached memory the \r
133 * implementation should writeback the contents of the contents\r
134 *\r
135 * <b> Prototype: </b>\r
136 * The following is the C prototype for the expected OSAL API.\r
137 *\r
138 * @verbatim\r
139 * void Osal_contract_EndMemAccess (void* addr, uint32_t sizeWords)\r
140 * @endverbatim\r
141 *\r
142 * <b> Parameter </b>\r
143 * @n addr - Pointer to the memory address being accessed.\r
144 * @n size - Size of the packet.\r
145 *\r
146 * <b> Return Value </b>\r
147 * @n None\r
148 */\r
149 \r
150 #define TF_CONTRACT_osalEndMemAccess Osal_contract_EndMemAccess\r
151 \r
152 \r
153 /**\r
154 * @brief The macro is used by the contract to indicate that memory\r
155 * access needs to be protected\r
156 *\r
157 * <b> Prototype: </b>\r
158 * The following is the C prototype for the expected OSAL API.\r
159 *\r
160 * @verbatim\r
161 * void Osal_contract_Enter (void)\r
162 * @endverbatim\r
163 *\r
164 * <b> Parameter </b>\r
165 * @n None\r
166 *\r
167 * <b> Return Value </b>\r
168 * @n None\r
169 */\r
170 \r
171 #define TF_CONTRACT_osalEnter Osal_contract_Enter\r
172 \r
173 /**\r
174 * @brief The macro is used by the contract to indicate that memory\r
175 * access needs to be protected\r
176 *\r
177 * <b> Prototype: </b>\r
178 * The following is the C prototype for the expected OSAL API.\r
179 *\r
180 * @verbatim\r
181 * void Osal_contract_Exit (void)\r
182 * @endverbatim\r
183 *\r
184 * <b> Parameter </b>\r
185 * @n None\r
186 *\r
187 * <b> Return Value </b>\r
188 * @n None\r
189 */\r
190 \r
191 #define TF_CONTRACT_osalExit Osal_contract_Exit\r
192 \r
193 /**\r
194 * @brief The macro is used by the trace framework Library to get the virtual address\r
195 * from Physical address (Applicable for ARM user mode library only)\r
196 *\r
197 * <b> Prototype: </b>\r
198 * The following is the C prototype for the expected OSAL API.\r
199 *\r
200 * @verbatim\r
201 * void* Osal_contract_mmap (void* phy_addr, uint32_t size)\r
202 * @endverbatim\r
203 *\r
204 * <b> Parameter </b>\r
205 * @n addr - Pointer to the physical memory address.\r
206 *\r
207 * <b> Return Value </b>\r
208 * @n virtual address space\r
209 */\r
210 #define TF_CONTRACT_osalMmap Osal_contract_mmap\r
211 \r
212 /**\r
213 * @brief The macro is used by the trace framework Library to get the physical address\r
214 * from virtual address (Applicable for ARM user mode library only)\r
215 *\r
216 * <b> Prototype: </b>\r
217 * The following is the C prototype for the expected OSAL API.\r
218 *\r
219 * @verbatim\r
220 * void Osal_contract_unmap (void* virt_addr, uint32_t size)\r
221 *\r
222 * @endverbatim\r
223 *\r
224 * <b> Parameter </b>\r
225 * @n addr - Pointer to the virtual memory address.\r
226 * @n size - Size to be un mapped\r
227 *\r
228 * <b> Return Value </b>\r
229 * @n none\r
230 */\r
231 #define TF_CONTRACT_osalUnmap Osal_contract_unmap\r
232 \r
233 /**\r
234 @}\r
235 */\r
236 \r
237 #ifdef __cplusplus\r
238 }\r
239 #endif\r
240 \r
241 #endif /* __CONTRACTOSAL_H__ */\r