dce66650b80dbf5daa246b261bf82314d6b75f14
[processor-sdk/open-amp.git] / lib / include / openamp / env.h
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_memset
54  *       env_memcpy
55  *       env_strlen
56  *       env_strcpy
57  *       env_strncpy
58  *       env_print
59  *       env_map_vatopa
60  *       env_map_patova
61  *       env_mb
62  *       env_rmb
63  *       env_wmb
64  *       env_create_mutex
65  *       env_delete_mutex
66  *       env_lock_mutex
67  *       env_unlock_mutex
68  *       env_sleep_msec
69  *       env_disable_interrupts
70  *       env_restore_interrupts
71  *
72  **************************************************************************/
73 #ifndef _ENV_H_
74 #define _ENV_H_
76 #include <stdio.h>
78 /**
79  * env_init
80  *
81  * Initializes OS/BM environment.
82  *
83  * @returns - execution status
84  */
86 int env_init();
88 /**
89  * env_deinit
90  *
91  * Uninitializes OS/BM environment.
92  *
93  * @returns - execution status
94  */
96 int env_deinit();
97 /**
98  * -------------------------------------------------------------------------
99  *
100  * Dynamic memory management functions. The parameters
101  * are similar to standard c functions.
102  *
103  *-------------------------------------------------------------------------
104  **/
106 /**
107  * env_allocate_memory
108  *
109  * Allocates memory with the given size.
110  *
111  * @param size - size of memory to allocate
112  *
113  * @return - pointer to allocated memory
114  */
115 void *env_allocate_memory(unsigned int size);
117 /**
118  * env_free_memory
119  *
120  * Frees memory pointed by the given parameter.
121  *
122  * @param ptr - pointer to memory to free
123  */
124 void env_free_memory(void *ptr);
126 /**
127  * -------------------------------------------------------------------------
128  *
129  * RTL Functions
130  *
131  *-------------------------------------------------------------------------
132  */
134 void env_memset(void *, int, unsigned long);
135 void env_memcpy(void *, void const *, unsigned long);
136 size_t env_strlen(const char *);
137 void env_strcpy(char *, const char *);
138 int env_strcmp(const char *, const char *);
139 void env_strncpy(char *, const char *, unsigned long);
140 int env_strncmp(char *, const char *, unsigned long);
141 #define env_print(...)  printf(__VA_ARGS__)
143 /**
144  *-----------------------------------------------------------------------------
145  *
146  *  Functions to convert physical address to virtual address and vice versa.
147  *
148  *-----------------------------------------------------------------------------
149  */
151 /**
152  * env_map_vatopa
153  *
154  * Converts logical address to physical address
155  *
156  * @param address - pointer to logical address
157  *
158  * @return  - physical address
159  */
160 unsigned long env_map_vatopa(void *address);
162 /**
163  * env_map_patova
164  *
165  * Converts physical address to logical address
166  *
167  * @param address - pointer to physical address
168  *
169  * @return  - logical address
170  *
171  */
172 void *env_map_patova(unsigned long address);
174 /**
175  *-----------------------------------------------------------------------------
176  *
177  *  Abstractions for memory barrier instructions.
178  *
179  *-----------------------------------------------------------------------------
180  */
182 /**
183  * env_mb
184  *
185  * Inserts memory barrier.
186  */
188 void env_mb();
190 /**
191  * env_rmb
192  *
193  * Inserts read memory barrier
194  */
196 void env_rmb();
198 /**
199  * env_wmb
200  *
201  * Inserts write memory barrier
202  */
204 void env_wmb();
206 /**
207  *-----------------------------------------------------------------------------
208  *
209  *  Abstractions for OS lock primitives.
210  *
211  *-----------------------------------------------------------------------------
212  */
214 /**
215  * env_create_mutex
216  *
217  * Creates a mutex with given initial count.
218  *
219  * @param lock -  pointer to created mutex
220  * @param count - initial count 0 or 1
221  *
222  * @return - status of function execution
223  */
224 int env_create_mutex(void **lock, int count);
226 /**
227  * env_delete_mutex
228  *
229  * Deletes the given lock.
230  *
231  * @param lock - mutex to delete
232  */
234 void env_delete_mutex(void *lock);
236 /**
237  * env_lock_mutex
238  *
239  * Tries to acquire the lock, if lock is not available then call to
240  * this function will suspend.
241  *
242  * @param lock - mutex to lock
243  *
244  */
246 void env_lock_mutex(void *lock);
248 /**
249  * env_unlock_mutex
250  *
251  * Releases the given lock.
252  *
253  * @param lock - mutex to unlock
254  */
256 void env_unlock_mutex(void *lock);
258 /**
259  * env_create_sync_lock
260  *
261  * Creates a synchronization lock primitive. It is used
262  * when signal has to be sent from the interrupt context to main
263  * thread context.
264  *
265  * @param lock  - pointer to created sync lock object
266  * @param state - initial state , lock or unlocked
267  *
268  * @returns - status of function execution
269  */
270 #define LOCKED                  0
271 #define UNLOCKED                1
273 int env_create_sync_lock(void **lock, int state);
275 /**
276  * env_create_sync_lock
277  *
278  * Deletes given sync lock object.
279  *
280  * @param lock  - sync lock to delete.
281  *
282  */
284 void env_delete_sync_lock(void *lock);
286 /**
287  * env_acquire_sync_lock
288  *
289  * Tries to acquire the sync lock.
290  *
291  * @param lock  - sync lock to acquire.
292  */
293 void env_acquire_sync_lock(void *lock);
295 /**
296  * env_release_sync_lock
297  *
298  * Releases synchronization lock.
299  *
300  * @param lock  - sync lock to release.
301  */
302 void env_release_sync_lock(void *lock);
304 /**
305  * env_sleep_msec
306  *
307  * Suspends the calling thread for given time in msecs.
308  *
309  * @param num_msec -  delay in msecs
310  */
311 void env_sleep_msec(int num_msec);
313 /**
314  * env_disable_interrupts
315  *
316  * Disables system interrupts
317  *
318  */
319 void env_disable_interrupts();
321 /**
322  * env_restore_interrupts
323  *
324  * Enables system interrupts
325  *
326  */
327 void env_restore_interrupts();
329 /**
330  * env_register_isr
331  *
332  * Registers interrupt handler for the given interrupt vector.
333  *
334  * @param vector - interrupt vector number
335  * @param data   - private data
336  * @param isr    - interrupt handler
337  */
339 void env_register_isr(int vector, void *data,
340                       void (*isr) (int vector, void *data));
342 void env_update_isr(int vector, void *data,
343                     void (*isr) (int vector, void *data));
345 /**
346  * env_enable_interrupt
347  *
348  * Enables the given interrupt.
349  *
350  * @param vector   - interrupt vector number
351  * @param priority - interrupt priority
352  * @param polarity - interrupt polarity
353  */
355 void env_enable_interrupt(unsigned int vector, unsigned int priority,
356                           unsigned int polarity);
358 /**
359  * env_disable_interrupt
360  *
361  * Disables the given interrupt.
362  *
363  * @param vector   - interrupt vector number
364  */
366 void env_disable_interrupt(unsigned int vector);
368 /**
369  * env_map_memory
370  *
371  * Enables memory mapping for given memory region.
372  *
373  * @param pa   - physical address of memory
374  * @param va   - logical address of memory
375  * @param size - memory size
376  * param flags - flags for cache/uncached  and access type
377  *
378  * Currently only first byte of flag parameter is used and bits mapping is defined as follow;
379  *
380  * Cache bits
381  * 0x0000_0001 = No cache
382  * 0x0000_0010 = Write back
383  * 0x0000_0100 = Write through
384  * 0x0000_x000 = Not used
385  *
386  * Memory types
387  *
388  * 0x0001_xxxx = Memory Mapped
389  * 0x0010_xxxx = IO Mapped
390  * 0x0100_xxxx = Shared
391  * 0x1000_xxxx = TLB
392  */
394 /* Macros for caching scheme used by the shared memory */
395 #define UNCACHED                            (1 << 0)
396 #define WB_CACHE                            (1 << 1)
397 #define WT_CACHE                            (1 << 2)
399 /* Memory Types */
400 #define MEM_MAPPED                          (1 << 4)
401 #define IO_MAPPED                           (1 << 5)
402 #define SHARED_MEM                          (1 << 6)
403 #define TLB_MEM                             (1 << 7)
405 void env_map_memory(unsigned int pa, unsigned int va, unsigned int size,
406                     unsigned int flags);
408 /**
409  * env_get_timestamp
410  *
411  * Returns a 64 bit time stamp.
412  *
413  *
414  */
415 unsigned long long env_get_timestamp(void);
417 /**
418  * env_disable_cache
419  * 
420  * Disables system caches.
421  *
422  */
424 void env_disable_cache();
426 typedef void LOCK;
428 #endif                          /* _ENV_H_ */