1 /**
2 * @file
3 * lwIP Operating System abstraction
4 *
5 */
6
7 /*
8 * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
9 * All rights reserved.
10 *
11 * Redistribution and use in source and binary forms, with or without modification,
12 * are permitted provided that the following conditions are met:
13 *
14 * 1. Redistributions of source code must retain the above copyright notice,
15 * this list of conditions and the following disclaimer.
16 * 2. Redistributions in binary form must reproduce the above copyright notice,
17 * this list of conditions and the following disclaimer in the documentation
18 * and/or other materials provided with the distribution.
19 * 3. The name of the author may not be used to endorse or promote products
20 * derived from this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
23 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
24 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
25 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
26 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
27 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
30 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
31 * OF SUCH DAMAGE.
32 *
33 * This file is part of the lwIP TCP/IP stack.
34 *
35 * Author: Adam Dunkels <adam@sics.se>
36 *
37 */
38
39 /**
40 * @defgroup sys_layer Porting (system abstraction layer)
41 * @ingroup lwip
42 *
43 * @defgroup sys_os OS abstraction layer
44 * @ingroup sys_layer
45 * No need to implement functions in this section in NO_SYS mode.
46 * The OS-specific code should be implemented in arch/sys_arch.h
47 * and sys_arch.c of your port.
48 *
49 * The operating system emulation layer provides a common interface
50 * between the lwIP code and the underlying operating system kernel. The
51 * general idea is that porting lwIP to new architectures requires only
52 * small changes to a few header files and a new sys_arch
53 * implementation. It is also possible to do a sys_arch implementation
54 * that does not rely on any underlying operating system.
55 *
56 * The sys_arch provides semaphores, mailboxes and mutexes to lwIP. For the full
57 * lwIP functionality, multiple threads support can be implemented in the
58 * sys_arch, but this is not required for the basic lwIP
59 * functionality. Timer scheduling is implemented in lwIP, but can be implemented
60 * by the sys_arch port (LWIP_TIMERS_CUSTOM==1).
61 *
62 * In addition to the source file providing the functionality of sys_arch,
63 * the OS emulation layer must provide several header files defining
64 * macros used throughout lwip. The files required and the macros they
65 * must define are listed below the sys_arch description.
66 *
67 * Since lwIP 1.4.0, semaphore, mutexes and mailbox functions are prototyped in a way that
68 * allows both using pointers or actual OS structures to be used. This way, memory
69 * required for such types can be either allocated in place (globally or on the
70 * stack) or on the heap (allocated internally in the "*_new()" functions).
71 *
72 * Note:
73 * -----
74 * Be careful with using mem_malloc() in sys_arch. When malloc() refers to
75 * mem_malloc() you can run into a circular function call problem. In mem.c
76 * mem_init() tries to allocate a semaphore using mem_malloc, which of course
77 * can't be performed when sys_arch uses mem_malloc.
78 *
79 * @defgroup sys_sem Semaphores
80 * @ingroup sys_os
81 * Semaphores can be either counting or binary - lwIP works with both
82 * kinds.
83 * Semaphores are represented by the type "sys_sem_t" which is typedef'd
84 * in the sys_arch.h file. Mailboxes are equivalently represented by the
85 * type "sys_mbox_t". Mutexes are represented by the type "sys_mutex_t".
86 * lwIP does not place any restrictions on how these types are represented
87 * internally.
88 *
89 * @defgroup sys_mutex Mutexes
90 * @ingroup sys_os
91 * Mutexes are recommended to correctly handle priority inversion,
92 * especially if you use LWIP_CORE_LOCKING .
93 *
94 * @defgroup sys_mbox Mailboxes
95 * @ingroup sys_os
96 * Mailboxes should be implemented as a queue which allows multiple messages
97 * to be posted (implementing as a rendez-vous point where only one message can be
98 * posted at a time can have a highly negative impact on performance). A message
99 * in a mailbox is just a pointer, nothing more.
100 *
101 * @defgroup sys_time Time
102 * @ingroup sys_layer
103 *
104 * @defgroup sys_prot Critical sections
105 * @ingroup sys_layer
106 * Used to protect short regions of code against concurrent access.
107 * - Your system is a bare-metal system (probably with an RTOS)
108 * and interrupts are under your control:
109 * Implement this as LockInterrupts() / UnlockInterrupts()
110 * - Your system uses an RTOS with deferred interrupt handling from a
111 * worker thread: Implement as a global mutex or lock/unlock scheduler
112 * - Your system uses a high-level OS with e.g. POSIX signals:
113 * Implement as a global mutex
114 *
115 * @defgroup sys_misc Misc
116 * @ingroup sys_os
117 */
118
119 #include "lwip/opt.h"
120
121 #include "lwip/sys.h"
122
123 /* Most of the functions defined in sys.h must be implemented in the
124 * architecture-dependent file sys_arch.c */
125
126 #if !NO_SYS
127
128 #ifndef sys_msleep
129 /**
130 * Sleep for some ms. Timeouts are NOT processed while sleeping.
131 *
132 * @param ms number of milliseconds to sleep
133 */
134 void
sys_msleep(u32_t ms)135 sys_msleep(u32_t ms)
136 {
137 if (ms > 0) {
138 sys_sem_t delaysem;
139 err_t err = sys_sem_new(&delaysem, 0);
140 if (err == ERR_OK) {
141 sys_arch_sem_wait(&delaysem, ms);
142 sys_sem_free(&delaysem);
143 }
144 }
145 }
146 #endif /* sys_msleep */
147
148 #endif /* !NO_SYS */
149