Merge pull request #3 in PROCESSOR-SDK/traceframework from CATREQ-2702 to master
[keystone-rtos/traceframework.git] / contract_osal.h
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