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_memcpy
54 * env_strlen
55 * env_strcpy
56 * env_strncpy
57 * env_print
58 * env_assert
59 * env_map_vatopa
60 * env_map_patova
61 * env_mb
62 * env_rmb
63 * env_wmb
64 * env_sleep_msec
65 * env_disable_interrupts
66 * env_restore_interrupts
67 *
68 **************************************************************************/
69 #ifndef _ENV_H_
70 #define _ENV_H_
72 #include <stdio.h>
74 /**
75 * -------------------------------------------------------------------------
76 *
77 * Dynamic memory management functions. The parameters
78 * are similar to standard c functions.
79 *
80 *-------------------------------------------------------------------------
81 **/
83 /**
84 * env_allocate_memory
85 *
86 * Allocates memory with the given size.
87 *
88 * @param size - size of memory to allocate
89 *
90 * @return - pointer to allocated memory
91 */
92 void *env_allocate_memory(unsigned int size);
94 /**
95 * env_free_memory
96 *
97 * Frees memory pointed by the given parameter.
98 *
99 * @param ptr - pointer to memory to free
100 */
101 void env_free_memory(void *ptr);
103 /**
104 * -------------------------------------------------------------------------
105 *
106 * RTL Functions
107 *
108 *-------------------------------------------------------------------------
109 */
111 void env_memcpy(void *, void const *, unsigned long);
112 size_t env_strlen(const char *);
113 void env_strcpy(char *, const char *);
114 int env_strcmp(const char *, const char *);
115 void env_strncpy(char *, const char *, unsigned long);
116 int env_strncmp(char *, const char *, unsigned long);
117 #define env_print(...) printf(__VA_ARGS__)
118 #define env_assert(_exp, _msg) do { \
119 if (!(_exp)) {env_print("%s: %s", __func__, _msg); while(1);} \
120 } while(0)
123 /**
124 *-----------------------------------------------------------------------------
125 *
126 * Functions to convert physical address to virtual address and vice versa.
127 *
128 *-----------------------------------------------------------------------------
129 */
131 /**
132 * env_map_vatopa
133 *
134 * Converts logical address to physical address
135 *
136 * @param address - pointer to logical address
137 *
138 * @return - physical address
139 */
140 unsigned long env_map_vatopa(void *address);
142 /**
143 * env_map_patova
144 *
145 * Converts physical address to logical address
146 *
147 * @param address - pointer to physical address
148 *
149 * @return - logical address
150 *
151 */
152 void *env_map_patova(unsigned long address);
154 /**
155 *-----------------------------------------------------------------------------
156 *
157 * Abstractions for memory barrier instructions.
158 *
159 *-----------------------------------------------------------------------------
160 */
162 /**
163 * env_mb
164 *
165 * Inserts memory barrier.
166 */
168 void env_mb();
170 /**
171 * env_rmb
172 *
173 * Inserts read memory barrier
174 */
176 void env_rmb();
178 /**
179 * env_wmb
180 *
181 * Inserts write memory barrier
182 */
184 void env_wmb();
186 /**
187 *-----------------------------------------------------------------------------
188 *
189 * Abstractions for OS lock primitives.
190 *
191 *-----------------------------------------------------------------------------
192 */
194 /**
195 * env_create_sync_lock
196 *
197 * Creates a synchronization lock primitive. It is used
198 * when signal has to be sent from the interrupt context to main
199 * thread context.
200 *
201 * @param lock - pointer to created sync lock object
202 * @param state - initial state , lock or unlocked
203 *
204 * @returns - status of function execution
205 */
206 #define LOCKED 0
207 #define UNLOCKED 1
209 int env_create_sync_lock(void **lock, int state);
211 /**
212 * env_create_sync_lock
213 *
214 * Deletes given sync lock object.
215 *
216 * @param lock - sync lock to delete.
217 *
218 */
220 void env_delete_sync_lock(void *lock);
222 /**
223 * env_acquire_sync_lock
224 *
225 * Tries to acquire the sync lock.
226 *
227 * @param lock - sync lock to acquire.
228 */
229 void env_acquire_sync_lock(void *lock);
231 /**
232 * env_release_sync_lock
233 *
234 * Releases synchronization lock.
235 *
236 * @param lock - sync lock to release.
237 */
238 void env_release_sync_lock(void *lock);
240 /**
241 * env_sleep_msec
242 *
243 * Suspends the calling thread for given time in msecs.
244 *
245 * @param num_msec - delay in msecs
246 */
247 void env_sleep_msec(int num_msec);
249 /**
250 * env_disable_interrupts
251 *
252 * Disables system interrupts
253 *
254 */
255 void env_disable_interrupts();
257 /**
258 * env_restore_interrupts
259 *
260 * Enables system interrupts
261 *
262 */
263 void env_restore_interrupts();
265 /**
266 * env_register_isr
267 *
268 * Registers interrupt handler for the given interrupt vector.
269 *
270 * @param vector - interrupt vector number
271 * @param data - private data
272 * @param isr - interrupt handler
273 */
275 void env_register_isr(int vector, void *data,
276 void (*isr) (int vector, void *data));
277 /**
278 * env_register_isr_shared
279 *
280 * Registers interrupt handler for the given shared interrupt vector.
281 *
282 * @param vector - interrupt vector number
283 * @param data - private data
284 * @param isr - interrupt handler
285 * @oaram name - interrup handler name
286 * @param shared - if the interrupt is a shared interrupt
287 */
289 void env_register_isr_shared(int vector, void *data,
290 void (*isr) (int vector, void *data),
291 char *name,
292 int shared);
294 void env_update_isr(int vector, void *data,
295 void (*isr) (int vector, void *data),
296 char *name,
297 int shared);
299 /**
300 * env_enable_interrupt
301 *
302 * Enables the given interrupt.
303 *
304 * @param vector - interrupt vector number
305 * @param priority - interrupt priority
306 * @param polarity - interrupt polarity
307 */
309 void env_enable_interrupt(unsigned int vector, unsigned int priority,
310 unsigned int polarity);
312 /**
313 * env_disable_interrupt
314 *
315 * Disables the given interrupt.
316 *
317 * @param vector - interrupt vector number
318 */
320 void env_disable_interrupt(unsigned int vector);
322 /**
323 * env_map_memory
324 *
325 * Enables memory mapping for given memory region.
326 *
327 * @param pa - physical address of memory
328 * @param va - logical address of memory
329 * @param size - memory size
330 * param flags - flags for cache/uncached and access type
331 *
332 * Currently only first byte of flag parameter is used and bits mapping is defined as follow;
333 *
334 * Cache bits
335 * 0x0000_0001 = No cache
336 * 0x0000_0010 = Write back
337 * 0x0000_0100 = Write through
338 * 0x0000_x000 = Not used
339 *
340 * Memory types
341 *
342 * 0x0001_xxxx = Memory Mapped
343 * 0x0010_xxxx = IO Mapped
344 * 0x0100_xxxx = Shared
345 * 0x1000_xxxx = TLB
346 */
348 /* Macros for caching scheme used by the shared memory */
349 #define UNCACHED (1 << 0)
350 #define WB_CACHE (1 << 1)
351 #define WT_CACHE (1 << 2)
353 /* Memory Types */
354 #define MEM_MAPPED (1 << 4)
355 #define IO_MAPPED (1 << 5)
356 #define SHARED_MEM (1 << 6)
357 #define TLB_MEM (1 << 7)
359 void env_map_memory(unsigned int pa, unsigned int va, unsigned int size,
360 unsigned int flags);
362 /**
363 * env_get_timestamp
364 *
365 * Returns a 64 bit time stamp.
366 *
367 *
368 */
369 unsigned long long env_get_timestamp(void);
371 /**
372 * env_disable_cache
373 *
374 * Disables system caches.
375 *
376 */
377 void env_disable_cache(void);
379 /**
380 * env_flush_invalidate_all_caches
381 *
382 * Flush and Invalidate all caches.
383 *
384 */
385 void env_flush_invalidate_all_caches(void);
387 typedef void LOCK;
389 #endif /* _ENV_H_ */