interface/vcos/vcos.h

   1 /*
   2 Copyright (c) 2012, Broadcom Europe Ltd
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7     * Redistributions of source code must retain the above copyright
   8       notice, this list of conditions and the following disclaimer.
   9     * Redistributions in binary form must reproduce the above copyright
  10       notice, this list of conditions and the following disclaimer in the
  11       documentation and/or other materials provided with the distribution.
  12     * Neither the name of the copyright holder nor the
  13       names of its contributors may be used to endorse or promote products
  14       derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
  20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27
  28 /*=============================================================================
  29 VideoCore OS Abstraction Layer - public header file
  30 =============================================================================*/
  31
  32 /**
  33   * \mainpage OS Abstraction Layer
  34   *
  35   * \section intro Introduction
  36   *
  37   * This abstraction layer is here to allow the underlying OS to be easily changed (e.g. from
  38   * Nucleus to ThreadX) and to aid in porting host applications to new targets.
  39   *
  40   * \subsection error Error handling
  41   *
  42   * Wherever possible, VCOS functions assert internally and return void. The only exceptions
  43   * are creation functions (which might fail due to lack of resources) and functions that
  44   * might timeout or fail due to lack of space. Errors that might be reported by the underlying
  45   * OS API (e.g. invalid mutex) are treated as a programming error, and are merely asserted on.
  46   *
  47   * \section thread_synch Threads and synchronisation
  48   *
  49   * \subsection thread Threads
  50   *
  51   * The thread API is somewhat different to that found in Nucleus. In particular, threads
  52   * cannot just be destroyed at arbitrary times and nor can they merely exit. This is so
  53   * that the same API can be implemented across all interesting platforms without too much
  54   * difficulty. See vcos_thread.h for details. Thread attributes are configured via
  55   * the VCOS_THREAD_ATTR_T structure, found in vcos_thread_attr.h.
  56   *
  57   * \subsection sema Semaphores
  58   *
  59   * Counted semaphores (c.f. Nucleus NU_SEMAPHORE) are created with VCOS_SEMAPHORE_T.
  60   * Under ThreadX on VideoCore, semaphores are implemented using VideoCore spinlocks, and
  61   * so are quite a lot faster than ordinary ThreadX semaphores. See vcos_semaphore.h.
  62   *
  63   * \subsection mtx Mutexes
  64   *
  65   * Mutexes are used for locking. Attempts to take a mutex twice, or to unlock it
  66   * in a different thread to the one in which it was locked should be expected to fail.
  67   * Mutexes are not re-entrant (see vcos_reentrant_mutex.h for a slightly slower
  68   * re-entrant mutex).
  69   *
  70   * \subsection evflags Event flags
  71   *
  72   * Event flags (the ThreadX name - also known as event groups under Nucleus) provide
  73   * 32 flags which can be waited on by multiple clients, and signalled by multiple clients.
  74   * A timeout can be specified. See vcos_event_flags.h. An alternative to this is the
  75   * VCOS_EVENT_T (see vcos_event.h) which is akin to the Win32 auto-reset event, or a
  76   * saturating counted semaphore.
  77   *
  78   * \subsection event Events
  79   *
  80   * A VCOS_EVENT_T is a bit like a saturating semaphore. No matter how many times it
  81   * is signalled, the waiter will only wake up once. See vcos_event.h. You might think this
  82   * is useful if you suspect that the cost of reading the semaphore count (perhaps via a
  83   * system call) is expensive on your platform.
  84   *
  85   * \subsection tls Thread local storage
  86   *
  87   * Thread local storage is supported using vcos_tls.h. This is emulated on Nucleus
  88   * and ThreadX.
  89   *
  90   * \section int Interrupts
  91   *
  92   * The legacy LISR/HISR scheme found in Nucleus is supported via the legacy ISR API,
  93   * which is also supported on ThreadX. New code should avoid this, and old code should
  94   * be migrated away from it, since it is slow. See vcos_legacy_isr.h.
  95   *
  96   * Registering an interrupt handler, and disabling/restoring interrupts, is handled
  97   * using the functions in vcos_isr.h.
  98   *
  99   */
 100
 101 /**
 102   * \file vcos.h
 103   *
 104   * This is the top level header file. Clients include this. It pulls in the platform-specific
 105   * header file (vcos_platform.h) together with header files defining the expected APIs, such
 106   * as vcos_mutex.h, vcos_semaphore.h, etc. It is also possible to include these header files
 107   * directly.
 108   *
 109   */
 110
 111 #ifndef VCOS_H
 112 #define VCOS_H
 113
 114 #include "interface/vcos/vcos_assert.h"
 115 #include "vcos_types.h"
 116
 117 #if defined(__unix__) && !defined(__ANDROID__)
 118 #include "interface/vcos/pthreads/vcos_platform.h"
 119 #else
 120 #include "vcos_platform.h"
 121 #endif
 122
 123 #ifndef VCOS_INIT_H
 124 #include "interface/vcos/vcos_init.h"
 125 #endif
 126
 127 #ifndef VCOS_SEMAPHORE_H
 128 #include "interface/vcos/vcos_semaphore.h"
 129 #endif
 130
 131 #ifndef VCOS_THREAD_H
 132 #include "interface/vcos/vcos_thread.h"
 133 #endif
 134
 135 #ifndef VCOS_MUTEX_H
 136 #include "interface/vcos/vcos_mutex.h"
 137 #endif
 138
 139 #ifndef VCOS_MEM_H
 140 #include "interface/vcos/vcos_mem.h"
 141 #endif
 142
 143 #ifndef VCOS_LOGGING_H
 144 #include "interface/vcos/vcos_logging.h"
 145 #endif
 146
 147 #ifndef VCOS_STRING_H
 148 #include "interface/vcos/vcos_string.h"
 149 #endif
 150
 151 #ifndef VCOS_EVENT_H
 152 #include "interface/vcos/vcos_event.h"
 153 #endif
 154
 155 #ifndef VCOS_THREAD_ATTR_H
 156 #include "interface/vcos/vcos_thread_attr.h"
 157 #endif
 158
 159 #ifndef VCOS_TLS_H
 160 #include "interface/vcos/vcos_tls.h"
 161 #endif
 162
 163 #ifndef VCOS_REENTRANT_MUTEX_H
 164 #include "interface/vcos/vcos_reentrant_mutex.h"
 165 #endif
 166
 167 #ifndef VCOS_NAMED_SEMAPHORE_H
 168 #include "interface/vcos/vcos_named_semaphore.h"
 169 #endif
 170
 171 #ifndef VCOS_QUICKSLOW_MUTEX_H
 172 #include "interface/vcos/vcos_quickslow_mutex.h"
 173 #endif
 174
 175 /* Headers with predicates */
 176
 177 #if VCOS_HAVE_EVENT_FLAGS
 178 #include "interface/vcos/vcos_event_flags.h"
 179 #endif
 180
 181 #if VCOS_HAVE_QUEUE
 182 #include "interface/vcos/vcos_queue.h"
 183 #endif
 184
 185 #if VCOS_HAVE_LEGACY_ISR
 186 #include "interface/vcos/vcos_legacy_isr.h"
 187 #endif
 188
 189 #if VCOS_HAVE_TIMER
 190 #include "interface/vcos/vcos_timer.h"
 191 #endif
 192
 193 #if VCOS_HAVE_MEMPOOL
 194 #include "interface/vcos/vcos_mempool.h"
 195 #endif
 196
 197 #if VCOS_HAVE_ISR
 198 #include "interface/vcos/vcos_isr.h"
 199 #endif
 200
 201 #if VCOS_HAVE_ATOMIC_FLAGS
 202 #include "interface/vcos/vcos_atomic_flags.h"
 203 #endif
 204
 205 #if VCOS_HAVE_ONCE
 206 #include "interface/vcos/vcos_once.h"
 207 #endif
 208
 209 #if VCOS_HAVE_BLOCK_POOL
 210 #include "interface/vcos/vcos_blockpool.h"
 211 #endif
 212
 213 #if VCOS_HAVE_FILE
 214 #include "interface/vcos/vcos_file.h"
 215 #endif
 216
 217 #if VCOS_HAVE_CFG
 218 #include "interface/vcos/vcos_cfg.h"
 219 #endif
 220
 221 #if VCOS_HAVE_CMD
 222 #include "interface/vcos/vcos_cmd.h"
 223 #endif
 224
 225 #endif /* VCOS_H */
 226