1 /*
2 * Copyright (c) 2014, Mentor Graphics Corporation
3 * All rights reserved.
4 * Copyright (c) 2015 Xilinx, Inc. All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright notice,
10 * this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright notice,
12 * this list of conditions and the following disclaimer in the documentation
13 * and/or other materials provided with the distribution.
14 * 3. Neither the name of Mentor Graphics Corporation nor the names of its
15 * contributors may be used to endorse or promote products derived from this
16 * software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 * POSSIBILITY OF SUCH DAMAGE.
29 */
31 /**************************************************************************
32 * FILE NAME
33 *
34 * env.h
35 *
36 * COMPONENT
37 *
38 * OpenAMP stack.
39 *
40 * DESCRIPTION
41 *
42 * This file defines abstraction layer for OpenAMP stack. The implementor
43 * must provide definition of all the functions.
44 *
45 * DATA STRUCTURES
46 *
47 * none
48 *
49 * FUNCTIONS
50 *
51 * env_allocate_memory
52 * env_free_memory
53 * env_print
54 * env_assert
55 * env_map_vatopa
56 * env_map_patova
57 * env_sleep_msec
58 * env_disable_interrupts
59 * env_restore_interrupts
60 *
61 **************************************************************************/
62 #ifndef _ENV_H_
63 #define _ENV_H_
65 #include <stdio.h>
67 /**
68 * -------------------------------------------------------------------------
69 *
70 * Dynamic memory management functions. The parameters
71 * are similar to standard c functions.
72 *
73 *-------------------------------------------------------------------------
74 **/
76 /**
77 * env_allocate_memory
78 *
79 * Allocates memory with the given size.
80 *
81 * @param size - size of memory to allocate
82 *
83 * @return - pointer to allocated memory
84 */
85 void *env_allocate_memory(unsigned int size);
87 /**
88 * env_free_memory
89 *
90 * Frees memory pointed by the given parameter.
91 *
92 * @param ptr - pointer to memory to free
93 */
94 void env_free_memory(void *ptr);
96 #define env_print(...) printf(__VA_ARGS__)
97 #define env_assert(_exp, _msg) do { \
98 if (!(_exp)) {env_print("%s: %s", __func__, _msg); while(1);} \
99 } while(0)
102 /**
103 *-----------------------------------------------------------------------------
104 *
105 * Functions to convert physical address to virtual address and vice versa.
106 *
107 *-----------------------------------------------------------------------------
108 */
110 /**
111 * env_map_vatopa
112 *
113 * Converts logical address to physical address
114 *
115 * @param address - pointer to logical address
116 *
117 * @return - physical address
118 */
119 unsigned long env_map_vatopa(void *address);
121 /**
122 * env_map_patova
123 *
124 * Converts physical address to logical address
125 *
126 * @param address - pointer to physical address
127 *
128 * @return - logical address
129 *
130 */
131 void *env_map_patova(unsigned long address);
133 /**
134 *-----------------------------------------------------------------------------
135 *
136 * Abstractions for OS lock primitives.
137 *
138 *-----------------------------------------------------------------------------
139 */
141 /**
142 * env_create_sync_lock
143 *
144 * Creates a synchronization lock primitive. It is used
145 * when signal has to be sent from the interrupt context to main
146 * thread context.
147 *
148 * @param lock - pointer to created sync lock object
149 * @param state - initial state , lock or unlocked
150 *
151 * @returns - status of function execution
152 */
153 #define LOCKED 0
154 #define UNLOCKED 1
156 int env_create_sync_lock(void **lock, int state);
158 /**
159 * env_create_sync_lock
160 *
161 * Deletes given sync lock object.
162 *
163 * @param lock - sync lock to delete.
164 *
165 */
167 void env_delete_sync_lock(void *lock);
169 /**
170 * env_acquire_sync_lock
171 *
172 * Tries to acquire the sync lock.
173 *
174 * @param lock - sync lock to acquire.
175 */
176 void env_acquire_sync_lock(void *lock);
178 /**
179 * env_release_sync_lock
180 *
181 * Releases synchronization lock.
182 *
183 * @param lock - sync lock to release.
184 */
185 void env_release_sync_lock(void *lock);
187 /**
188 * env_sleep_msec
189 *
190 * Suspends the calling thread for given time in msecs.
191 *
192 * @param num_msec - delay in msecs
193 */
194 void env_sleep_msec(int num_msec);
196 /**
197 * env_disable_interrupts
198 *
199 * Disables system interrupts
200 *
201 */
202 void env_disable_interrupts();
204 /**
205 * env_restore_interrupts
206 *
207 * Enables system interrupts
208 *
209 */
210 void env_restore_interrupts();
212 /**
213 * env_register_isr
214 *
215 * Registers interrupt handler for the given interrupt vector.
216 *
217 * @param vector - interrupt vector number
218 * @param data - private data
219 * @param isr - interrupt handler
220 */
222 void env_register_isr(int vector, void *data,
223 void (*isr) (int vector, void *data));
224 /**
225 * env_register_isr_shared
226 *
227 * Registers interrupt handler for the given shared interrupt vector.
228 *
229 * @param vector - interrupt vector number
230 * @param data - private data
231 * @param isr - interrupt handler
232 * @oaram name - interrup handler name
233 * @param shared - if the interrupt is a shared interrupt
234 */
236 void env_register_isr_shared(int vector, void *data,
237 void (*isr) (int vector, void *data),
238 char *name,
239 int shared);
241 void env_update_isr(int vector, void *data,
242 void (*isr) (int vector, void *data),
243 char *name,
244 int shared);
246 /**
247 * env_enable_interrupt
248 *
249 * Enables the given interrupt.
250 *
251 * @param vector - interrupt vector number
252 * @param priority - interrupt priority
253 * @param polarity - interrupt polarity
254 */
256 void env_enable_interrupt(unsigned int vector, unsigned int priority,
257 unsigned int polarity);
259 /**
260 * env_disable_interrupt
261 *
262 * Disables the given interrupt.
263 *
264 * @param vector - interrupt vector number
265 */
267 void env_disable_interrupt(unsigned int vector);
269 /**
270 * env_map_memory
271 *
272 * Enables memory mapping for given memory region.
273 *
274 * @param pa - physical address of memory
275 * @param va - logical address of memory
276 * @param size - memory size
277 * param flags - flags for cache/uncached and access type
278 *
279 * Currently only first byte of flag parameter is used and bits mapping is defined as follow;
280 *
281 * Cache bits
282 * 0x0000_0001 = No cache
283 * 0x0000_0010 = Write back
284 * 0x0000_0100 = Write through
285 * 0x0000_x000 = Not used
286 *
287 * Memory types
288 *
289 * 0x0001_xxxx = Memory Mapped
290 * 0x0010_xxxx = IO Mapped
291 * 0x0100_xxxx = Shared
292 * 0x1000_xxxx = TLB
293 */
295 /* Macros for caching scheme used by the shared memory */
296 #define UNCACHED (1 << 0)
297 #define WB_CACHE (1 << 1)
298 #define WT_CACHE (1 << 2)
300 /* Memory Types */
301 #define MEM_MAPPED (1 << 4)
302 #define IO_MAPPED (1 << 5)
303 #define SHARED_MEM (1 << 6)
304 #define TLB_MEM (1 << 7)
306 void env_map_memory(unsigned int pa, unsigned int va, unsigned int size,
307 unsigned int flags);
309 /**
310 * env_get_timestamp
311 *
312 * Returns a 64 bit time stamp.
313 *
314 *
315 */
316 unsigned long long env_get_timestamp(void);
318 /**
319 * env_disable_cache
320 *
321 * Disables system caches.
322 *
323 */
324 void env_disable_cache(void);
326 /**
327 * env_flush_invalidate_all_caches
328 *
329 * Flush and Invalidate all caches.
330 *
331 */
332 void env_flush_invalidate_all_caches(void);
334 typedef void LOCK;
336 #endif /* _ENV_H_ */