1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, 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
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON 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
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28/*=============================================================================
29VideoCore 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
227