1sys_arch interface for lwIP 0.6++ 2 3Author: Adam Dunkels 4 5The operating system emulation layer provides a common interface 6between the lwIP code and the underlying operating system kernel. The 7general idea is that porting lwIP to new architectures requires only 8small changes to a few header files and a new sys_arch 9implementation. It is also possible to do a sys_arch implementation 10that does not rely on any underlying operating system. 11 12The sys_arch provides semaphores and mailboxes to lwIP. For the full 13lwIP functionality, multiple threads support can be implemented in the 14sys_arch, but this is not required for the basic lwIP 15functionality. Previous versions of lwIP required the sys_arch to 16implement timer scheduling as well but as of lwIP 0.5 this is 17implemented in a higher layer. 18 19In addition to the source file providing the functionality of sys_arch, 20the OS emulation layer must provide several header files defining 21macros used throughout lwip. The files required and the macros they 22must define are listed below the sys_arch description. 23 24Semaphores can be either counting or binary - lwIP works with both 25kinds. Mailboxes are used for message passing and can be implemented 26either as a queue which allows multiple messages to be posted to a 27mailbox, or as a rendez-vous point where only one message can be 28posted at a time. lwIP works with both kinds, but the former type will 29be more efficient. A message in a mailbox is just a pointer, nothing 30more. 31 32Semaphores are represented by the type "sys_sem_t" which is typedef'd 33in the sys_arch.h file. Mailboxes are equivalently represented by the 34type "sys_mbox_t". lwIP does not place any restrictions on how 35sys_sem_t or sys_mbox_t are represented internally. 36 37Since lwIP 1.4.0, semaphore and mailbox functions are prototyped in a way that 38allows both using pointers or actual OS structures to be used. This way, memory 39required for such types can be either allocated in place (globally or on the 40stack) or on the heap (allocated internally in the "*_new()" functions). 41 42The following functions must be implemented by the sys_arch: 43 44- void sys_init(void) 45 46 Is called to initialize the sys_arch layer. 47 48- err_t sys_sem_new(sys_sem_t *sem, u8_t count) 49 50 Creates a new semaphore. The semaphore is allocated to the memory that 'sem' 51 points to (which can be both a pointer or the actual OS structure). 52 The "count" argument specifies the initial state of the semaphore (which is 53 either 0 or 1). 54 If the semaphore has been created, ERR_OK should be returned. Returning any 55 other error will provide a hint what went wrong, but except for assertions, 56 no real error handling is implemented. 57 58- void sys_sem_free(sys_sem_t *sem) 59 60 Deallocates a semaphore. 61 62- void sys_sem_signal(sys_sem_t *sem) 63 64 Signals a semaphore. 65 66- u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout) 67 68 Blocks the thread while waiting for the semaphore to be 69 signaled. If the "timeout" argument is non-zero, the thread should 70 only be blocked for the specified time (measured in 71 milliseconds). If the "timeout" argument is zero, the thread should be 72 blocked until the semaphore is signalled. 73 74 If the timeout argument is non-zero, the return value is the number of 75 milliseconds spent waiting for the semaphore to be signaled. If the 76 semaphore wasn't signaled within the specified time, the return value is 77 SYS_ARCH_TIMEOUT. If the thread didn't have to wait for the semaphore 78 (i.e., it was already signaled), the function may return zero. 79 80 Notice that lwIP implements a function with a similar name, 81 sys_sem_wait(), that uses the sys_arch_sem_wait() function. 82 83- int sys_sem_valid(sys_sem_t *sem) 84 85 Returns 1 if the semaphore is valid, 0 if it is not valid. 86 When using pointers, a simple way is to check the pointer for != NULL. 87 When directly using OS structures, implementing this may be more complex. 88 This may also be a define, in which case the function is not prototyped. 89 90- void sys_sem_set_invalid(sys_sem_t *sem) 91 92 Invalidate a semaphore so that sys_sem_valid() returns 0. 93 ATTENTION: This does NOT mean that the semaphore shall be deallocated: 94 sys_sem_free() is always called before calling this function! 95 This may also be a define, in which case the function is not prototyped. 96 97- err_t sys_mbox_new(sys_mbox_t *mbox, int size) 98 99 Creates an empty mailbox for maximum "size" elements. Elements stored 100 in mailboxes are pointers. You have to define macros "_MBOX_SIZE" 101 in your lwipopts.h, or ignore this parameter in your implementation 102 and use a default size. 103 If the mailbox has been created, ERR_OK should be returned. Returning any 104 other error will provide a hint what went wrong, but except for assertions, 105 no real error handling is implemented. 106 107- void sys_mbox_free(sys_mbox_t *mbox) 108 109 Deallocates a mailbox. If there are messages still present in the 110 mailbox when the mailbox is deallocated, it is an indication of a 111 programming error in lwIP and the developer should be notified. 112 113- void sys_mbox_post(sys_mbox_t *mbox, void *msg) 114 115 Posts the "msg" to the mailbox. This function have to block until 116 the "msg" is really posted. 117 118- err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg) 119 120 Try to post the "msg" to the mailbox. Returns ERR_MEM if this one 121 is full, else, ERR_OK if the "msg" is posted. 122 123- u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout) 124 125 Blocks the thread until a message arrives in the mailbox, but does 126 not block the thread longer than "timeout" milliseconds (similar to 127 the sys_arch_sem_wait() function). If "timeout" is 0, the thread should 128 be blocked until a message arrives. The "msg" argument is a result 129 parameter that is set by the function (i.e., by doing "*msg = 130 ptr"). The "msg" parameter maybe NULL to indicate that the message 131 should be dropped. 132 133 The return values are the same as for the sys_arch_sem_wait() function: 134 Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a 135 timeout. 136 137 Note that a function with a similar name, sys_mbox_fetch(), is 138 implemented by lwIP. 139 140- u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg) 141 142 This is similar to sys_arch_mbox_fetch, however if a message is not 143 present in the mailbox, it immediately returns with the code 144 SYS_MBOX_EMPTY. On success 0 is returned. 145 146 To allow for efficient implementations, this can be defined as a 147 function-like macro in sys_arch.h instead of a normal function. For 148 example, a naive implementation could be: 149 #define sys_arch_mbox_tryfetch(mbox,msg) \ 150 sys_arch_mbox_fetch(mbox,msg,1) 151 although this would introduce unnecessary delays. 152 153- int sys_mbox_valid(sys_mbox_t *mbox) 154 155 Returns 1 if the mailbox is valid, 0 if it is not valid. 156 When using pointers, a simple way is to check the pointer for != NULL. 157 When directly using OS structures, implementing this may be more complex. 158 This may also be a define, in which case the function is not prototyped. 159 160- void sys_mbox_set_invalid(sys_mbox_t *mbox) 161 162 Invalidate a mailbox so that sys_mbox_valid() returns 0. 163 ATTENTION: This does NOT mean that the mailbox shall be deallocated: 164 sys_mbox_free() is always called before calling this function! 165 This may also be a define, in which case the function is not prototyped. 166 167If threads are supported by the underlying operating system and if 168such functionality is needed in lwIP, the following function will have 169to be implemented as well: 170 171- sys_thread_t sys_thread_new(char *name, void (* thread)(void *arg), void *arg, int stacksize, int prio) 172 173 Starts a new thread named "name" with priority "prio" that will begin its 174 execution in the function "thread()". The "arg" argument will be passed as an 175 argument to the thread() function. The stack size to used for this thread is 176 the "stacksize" parameter. The id of the new thread is returned. Both the id 177 and the priority are system dependent. 178 179- sys_prot_t sys_arch_protect(void) 180 181 This optional function does a "fast" critical region protection and returns 182 the previous protection level. This function is only called during very short 183 critical regions. An embedded system which supports ISR-based drivers might 184 want to implement this function by disabling interrupts. Task-based systems 185 might want to implement this by using a mutex or disabling tasking. This 186 function should support recursive calls from the same task or interrupt. In 187 other words, sys_arch_protect() could be called while already protected. In 188 that case the return value indicates that it is already protected. 189 190 sys_arch_protect() is only required if your port is supporting an operating 191 system. 192 193- void sys_arch_unprotect(sys_prot_t pval) 194 195 This optional function does a "fast" set of critical region protection to the 196 value specified by pval. See the documentation for sys_arch_protect() for 197 more information. This function is only required if your port is supporting 198 an operating system. 199 200For some configurations, you also need: 201 202- u32_t sys_now(void) 203 204 This optional function returns the current time in milliseconds (don't care 205 for wraparound, this is only used for time diffs). 206 Not implementing this function means you cannot use some modules (e.g. TCP 207 timestamps, internal timeouts for NO_SYS==1). 208 209 210Note: 211 212Be carefull with using mem_malloc() in sys_arch. When malloc() refers to 213mem_malloc() you can run into a circular function call problem. In mem.c 214mem_init() tries to allcate a semaphore using mem_malloc, which of course 215can't be performed when sys_arch uses mem_malloc. 216 217------------------------------------------------------------------------------- 218Additional files required for the "OS support" emulation layer: 219------------------------------------------------------------------------------- 220 221cc.h - Architecture environment, some compiler specific, some 222 environment specific (probably should move env stuff 223 to sys_arch.h.) 224 225 Typedefs for the types used by lwip - 226 u8_t, s8_t, u16_t, s16_t, u32_t, s32_t, mem_ptr_t 227 228 Compiler hints for packing lwip's structures - 229 PACK_STRUCT_FIELD(x) 230 PACK_STRUCT_STRUCT 231 PACK_STRUCT_BEGIN 232 PACK_STRUCT_END 233 234 Platform specific diagnostic output - 235 LWIP_PLATFORM_DIAG(x) - non-fatal, print a message. 236 LWIP_PLATFORM_ASSERT(x) - fatal, print message and abandon execution. 237 Portability defines for printf formatters: 238 U16_F, S16_F, X16_F, U32_F, S32_F, X32_F, SZT_F 239 240 "lightweight" synchronization mechanisms - 241 SYS_ARCH_DECL_PROTECT(x) - declare a protection state variable. 242 SYS_ARCH_PROTECT(x) - enter protection mode. 243 SYS_ARCH_UNPROTECT(x) - leave protection mode. 244 245 If the compiler does not provide memset() this file must include a 246 definition of it, or include a file which defines it. 247 248 This file must either include a system-local <errno.h> which defines 249 the standard *nix error codes, or it should #define LWIP_PROVIDE_ERRNO 250 to make lwip/arch.h define the codes which are used throughout. 251 252 253perf.h - Architecture specific performance measurement. 254 Measurement calls made throughout lwip, these can be defined to nothing. 255 PERF_START - start measuring something. 256 PERF_STOP(x) - stop measuring something, and record the result. 257 258sys_arch.h - Tied to sys_arch.c 259 260 Arch dependent types for the following objects: 261 sys_sem_t, sys_mbox_t, sys_thread_t, 262 And, optionally: 263 sys_prot_t 264 265 Defines to set vars of sys_mbox_t and sys_sem_t to NULL. 266 SYS_MBOX_NULL NULL 267 SYS_SEM_NULL NULL 268