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  */
  30
  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_map_vatopa
  54  *       env_map_patova
  55  *       env_sleep_msec
  56  *       env_disable_interrupts
  57  *       env_restore_interrupts
  58  *
  59  **************************************************************************/
  60 #ifndef _ENV_H_
  61 #define _ENV_H_
  62
  63 #include <stdio.h>
  64
  65 /**
  66  * -------------------------------------------------------------------------
  67  *
  68  * Dynamic memory management functions. The parameters
  69  * are similar to standard c functions.
  70  *
  71  *-------------------------------------------------------------------------
  72  **/
  73
  74 /**
  75  * env_allocate_memory
  76  *
  77  * Allocates memory with the given size.
  78  *
  79  * @param size - size of memory to allocate
  80  *
  81  * @return - pointer to allocated memory
  82  */
  83 void *env_allocate_memory(unsigned int size);
  84
  85 /**
  86  * env_free_memory
  87  *
  88  * Frees memory pointed by the given parameter.
  89  *
  90  * @param ptr - pointer to memory to free
  91  */
  92 void env_free_memory(void *ptr);
  93
  94 /**
  95  *-----------------------------------------------------------------------------
  96  *
  97  *  Functions to convert physical address to virtual address and vice versa.
  98  *
  99  *-----------------------------------------------------------------------------
 100  */
 101
 102 /**
 103  * env_map_vatopa
 104  *
 105  * Converts logical address to physical address
 106  *
 107  * @param address - pointer to logical address
 108  *
 109  * @return  - physical address
 110  */
 111 unsigned long env_map_vatopa(void *address);
 112
 113 /**
 114  * env_map_patova
 115  *
 116  * Converts physical address to logical address
 117  *
 118  * @param address - pointer to physical address
 119  *
 120  * @return  - logical address
 121  *
 122  */
 123 void *env_map_patova(unsigned long address);
 124
 125 /**
 126  *-----------------------------------------------------------------------------
 127  *
 128  *  Abstractions for OS lock primitives.
 129  *
 130  *-----------------------------------------------------------------------------
 131  */
 132
 133 /**
 134  * env_create_sync_lock
 135  *
 136  * Creates a synchronization lock primitive. It is used
 137  * when signal has to be sent from the interrupt context to main
 138  * thread context.
 139  *
 140  * @param lock  - pointer to created sync lock object
 141  * @param state - initial state , lock or unlocked
 142  *
 143  * @returns - status of function execution
 144  */
 145 #define LOCKED                  0
 146 #define UNLOCKED                1
 147
 148 int env_create_sync_lock(void **lock, int state);
 149
 150 /**
 151  * env_create_sync_lock
 152  *
 153  * Deletes given sync lock object.
 154  *
 155  * @param lock  - sync lock to delete.
 156  *
 157  */
 158
 159 void env_delete_sync_lock(void *lock);
 160
 161 /**
 162  * env_acquire_sync_lock
 163  *
 164  * Tries to acquire the sync lock.
 165  *
 166  * @param lock  - sync lock to acquire.
 167  */
 168 void env_acquire_sync_lock(void *lock);
 169
 170 /**
 171  * env_release_sync_lock
 172  *
 173  * Releases synchronization lock.
 174  *
 175  * @param lock  - sync lock to release.
 176  */
 177 void env_release_sync_lock(void *lock);
 178
 179 /**
 180  * env_sleep_msec
 181  *
 182  * Suspends the calling thread for given time in msecs.
 183  *
 184  * @param num_msec -  delay in msecs
 185  */
 186 void env_sleep_msec(int num_msec);
 187
 188 /**
 189  * env_disable_interrupts
 190  *
 191  * Disables system interrupts
 192  *
 193  */
 194 void env_disable_interrupts();
 195
 196 /**
 197  * env_restore_interrupts
 198  *
 199  * Enables system interrupts
 200  *
 201  */
 202 void env_restore_interrupts();
 203
 204 /**
 205  * env_register_isr
 206  *
 207  * Registers interrupt handler for the given interrupt vector.
 208  *
 209  * @param vector - interrupt vector number
 210  * @param data   - private data
 211  * @param isr    - interrupt handler
 212  */
 213
 214 void env_register_isr(int vector, void *data,
 215                       void (*isr) (int vector, void *data));
 216 /**
 217  * env_register_isr_shared
 218  *
 219  * Registers interrupt handler for the given shared interrupt vector.
 220  *
 221  * @param vector - interrupt vector number
 222  * @param data   - private data
 223  * @param isr    - interrupt handler
 224  * @oaram name   - interrup handler name
 225  * @param shared - if the interrupt is a shared interrupt
 226  */
 227
 228 void env_register_isr_shared(int vector, void *data,
 229                       void (*isr) (int vector, void *data),
 230                       char *name,
 231                       int shared);
 232
 233 void env_update_isr(int vector, void *data,
 234                     void (*isr) (int vector, void *data),
 235                     char *name,
 236                     int shared);
 237
 238 /**
 239  * env_enable_interrupt
 240  *
 241  * Enables the given interrupt.
 242  *
 243  * @param vector   - interrupt vector number
 244  * @param priority - interrupt priority
 245  * @param polarity - interrupt polarity
 246  */
 247
 248 void env_enable_interrupt(unsigned int vector, unsigned int priority,
 249                           unsigned int polarity);
 250
 251 /**
 252  * env_disable_interrupt
 253  *
 254  * Disables the given interrupt.
 255  *
 256  * @param vector   - interrupt vector number
 257  */
 258
 259 void env_disable_interrupt(unsigned int vector);
 260
 261 /**
 262  * env_map_memory
 263  *
 264  * Enables memory mapping for given memory region.
 265  *
 266  * @param pa   - physical address of memory
 267  * @param va   - logical address of memory
 268  * @param size - memory size
 269  * param flags - flags for cache/uncached  and access type
 270  *
 271  * Currently only first byte of flag parameter is used and bits mapping is defined as follow;
 272  *
 273  * Cache bits
 274  * 0x0000_0001 = No cache
 275  * 0x0000_0010 = Write back
 276  * 0x0000_0100 = Write through
 277  * 0x0000_x000 = Not used
 278  *
 279  * Memory types
 280  *
 281  * 0x0001_xxxx = Memory Mapped
 282  * 0x0010_xxxx = IO Mapped
 283  * 0x0100_xxxx = Shared
 284  * 0x1000_xxxx = TLB
 285  */
 286
 287 /* Macros for caching scheme used by the shared memory */
 288 #define UNCACHED                            (1 << 0)
 289 #define WB_CACHE                            (1 << 1)
 290 #define WT_CACHE                            (1 << 2)
 291
 292 /* Memory Types */
 293 #define MEM_MAPPED                          (1 << 4)
 294 #define IO_MAPPED                           (1 << 5)
 295 #define SHARED_MEM                          (1 << 6)
 296 #define TLB_MEM                             (1 << 7)
 297
 298 void env_map_memory(unsigned int pa, unsigned int va, unsigned int size,
 299                     unsigned int flags);
 300
 301 /**
 302  * env_get_timestamp
 303  *
 304  * Returns a 64 bit time stamp.
 305  *
 306  *
 307  */
 308 unsigned long long env_get_timestamp(void);
 309
 310 /**
 311  * env_disable_cache
 312  *
 313  * Disables system caches.
 314  *
 315  */
 316 void env_disable_cache(void);
 317
 318 /**
 319  * env_flush_invalidate_all_caches
 320  *
 321  * Flush and Invalidate all caches.
 322  *
 323  */
 324 void env_flush_invalidate_all_caches(void);
 325
 326 typedef void LOCK;
 327
 328 #endif                          /* _ENV_H_ */