Travis Geiselbrecht | 1d0df69 | 2008-09-01 02:26:09 -0700 | [diff] [blame^] | 1 | sys_arch interface for lwIP 0.6++ |
| 2 | |
| 3 | Author: Adam Dunkels |
| 4 | |
| 5 | The operating system emulation layer provides a common interface |
| 6 | between the lwIP code and the underlying operating system kernel. The |
| 7 | general idea is that porting lwIP to new architectures requires only |
| 8 | small changes to a few header files and a new sys_arch |
| 9 | implementation. It is also possible to do a sys_arch implementation |
| 10 | that does not rely on any underlying operating system. |
| 11 | |
| 12 | The sys_arch provides semaphores and mailboxes to lwIP. For the full |
| 13 | lwIP functionality, multiple threads support can be implemented in the |
| 14 | sys_arch, but this is not required for the basic lwIP |
| 15 | functionality. Previous versions of lwIP required the sys_arch to |
| 16 | implement timer scheduling as well but as of lwIP 0.5 this is |
| 17 | implemented in a higher layer. |
| 18 | |
| 19 | In addition to the source file providing the functionality of sys_arch, |
| 20 | the OS emulation layer must provide several header files defining |
| 21 | macros used throughout lwip. The files required and the macros they |
| 22 | must define are listed below the sys_arch description. |
| 23 | |
| 24 | Semaphores can be either counting or binary - lwIP works with both |
| 25 | kinds. Mailboxes are used for message passing and can be implemented |
| 26 | either as a queue which allows multiple messages to be posted to a |
| 27 | mailbox, or as a rendez-vous point where only one message can be |
| 28 | posted at a time. lwIP works with both kinds, but the former type will |
| 29 | be more efficient. A message in a mailbox is just a pointer, nothing |
| 30 | more. |
| 31 | |
| 32 | Semaphores are represented by the type "sys_sem_t" which is typedef'd |
| 33 | in the sys_arch.h file. Mailboxes are equivalently represented by the |
| 34 | type "sys_mbox_t". lwIP does not place any restrictions on how |
| 35 | sys_sem_t or sys_mbox_t are represented internally. |
| 36 | |
| 37 | The following functions must be implemented by the sys_arch: |
| 38 | |
| 39 | - void sys_init(void) |
| 40 | |
| 41 | Is called to initialize the sys_arch layer. |
| 42 | |
| 43 | - sys_sem_t sys_sem_new(u8_t count) |
| 44 | |
| 45 | Creates and returns a new semaphore. The "count" argument specifies |
| 46 | the initial state of the semaphore. |
| 47 | |
| 48 | - void sys_sem_free(sys_sem_t sem) |
| 49 | |
| 50 | Deallocates a semaphore. |
| 51 | |
| 52 | - void sys_sem_signal(sys_sem_t sem) |
| 53 | |
| 54 | Signals a semaphore. |
| 55 | |
| 56 | - u32_t sys_arch_sem_wait(sys_sem_t sem, u32_t timeout) |
| 57 | |
| 58 | Blocks the thread while waiting for the semaphore to be |
| 59 | signaled. If the "timeout" argument is non-zero, the thread should |
| 60 | only be blocked for the specified time (measured in |
| 61 | milliseconds). |
| 62 | |
| 63 | If the timeout argument is non-zero, the return value is the number of |
| 64 | milliseconds spent waiting for the semaphore to be signaled. If the |
| 65 | semaphore wasn't signaled within the specified time, the return value is |
| 66 | SYS_ARCH_TIMEOUT. If the thread didn't have to wait for the semaphore |
| 67 | (i.e., it was already signaled), the function may return zero. |
| 68 | |
| 69 | Notice that lwIP implements a function with a similar name, |
| 70 | sys_sem_wait(), that uses the sys_arch_sem_wait() function. |
| 71 | |
| 72 | - sys_mbox_t sys_mbox_new(void) |
| 73 | |
| 74 | Creates an empty mailbox. |
| 75 | |
| 76 | - void sys_mbox_free(sys_mbox_t mbox) |
| 77 | |
| 78 | Deallocates a mailbox. If there are messages still present in the |
| 79 | mailbox when the mailbox is deallocated, it is an indication of a |
| 80 | programming error in lwIP and the developer should be notified. |
| 81 | |
| 82 | - void sys_mbox_post(sys_mbox_t mbox, void *msg) |
| 83 | |
| 84 | Posts the "msg" to the mailbox. |
| 85 | |
| 86 | - u32_t sys_arch_mbox_fetch(sys_mbox_t mbox, void **msg, u32_t timeout) |
| 87 | |
| 88 | Blocks the thread until a message arrives in the mailbox, but does |
| 89 | not block the thread longer than "timeout" milliseconds (similar to |
| 90 | the sys_arch_sem_wait() function). The "msg" argument is a result |
| 91 | parameter that is set by the function (i.e., by doing "*msg = |
| 92 | ptr"). The "msg" parameter maybe NULL to indicate that the message |
| 93 | should be dropped. |
| 94 | |
| 95 | The return values are the same as for the sys_arch_sem_wait() function: |
| 96 | Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a |
| 97 | timeout. |
| 98 | |
| 99 | Note that a function with a similar name, sys_mbox_fetch(), is |
| 100 | implemented by lwIP. |
| 101 | |
| 102 | - struct sys_timeouts *sys_arch_timeouts(void) |
| 103 | |
| 104 | Returns a pointer to the per-thread sys_timeouts structure. In lwIP, |
| 105 | each thread has a list of timeouts which is repressented as a linked |
| 106 | list of sys_timeout structures. The sys_timeouts structure holds a |
| 107 | pointer to a linked list of timeouts. This function is called by |
| 108 | the lwIP timeout scheduler and must not return a NULL value. |
| 109 | |
| 110 | In a single threadd sys_arch implementation, this function will |
| 111 | simply return a pointer to a global sys_timeouts variable stored in |
| 112 | the sys_arch module. |
| 113 | |
| 114 | If threads are supported by the underlying operating system and if |
| 115 | such functionality is needed in lwIP, the following function will have |
| 116 | to be implemented as well: |
| 117 | |
| 118 | - sys_thread_t sys_thread_new(void (* thread)(void *arg), void *arg, int prio) |
| 119 | |
| 120 | Starts a new thread with priority "prio" that will begin its execution in the |
| 121 | function "thread()". The "arg" argument will be passed as an argument to the |
| 122 | thread() function. The id of the new thread is returned. Both the id and |
| 123 | the priority are system dependent. |
| 124 | |
| 125 | - sys_prot_t sys_arch_protect(void) |
| 126 | |
| 127 | This optional function does a "fast" critical region protection and returns |
| 128 | the previous protection level. This function is only called during very short |
| 129 | critical regions. An embedded system which supports ISR-based drivers might |
| 130 | want to implement this function by disabling interrupts. Task-based systems |
| 131 | might want to implement this by using a mutex or disabling tasking. This |
| 132 | function should support recursive calls from the same task or interrupt. In |
| 133 | other words, sys_arch_protect() could be called while already protected. In |
| 134 | that case the return value indicates that it is already protected. |
| 135 | |
| 136 | sys_arch_protect() is only required if your port is supporting an operating |
| 137 | system. |
| 138 | |
| 139 | - void sys_arch_unprotect(sys_prot_t pval) |
| 140 | |
| 141 | This optional function does a "fast" set of critical region protection to the |
| 142 | value specified by pval. See the documentation for sys_arch_protect() for |
| 143 | more information. This function is only required if your port is supporting |
| 144 | an operating system. |
| 145 | |
| 146 | ------------------------------------------------------------------------------- |
| 147 | Additional files required for the "OS support" emulation layer: |
| 148 | ------------------------------------------------------------------------------- |
| 149 | |
| 150 | cc.h - Architecture environment, some compiler specific, some |
| 151 | environment specific (probably should move env stuff |
| 152 | to sys_arch.h.) |
| 153 | |
| 154 | Typedefs for the types used by lwip - |
| 155 | u8_t, s8_t, u16_t, s16_t, u32_t, s32_t, mem_ptr_t |
| 156 | |
| 157 | Compiler hints for packing lwip's structures - |
| 158 | PACK_STRUCT_FIELD(x) |
| 159 | PACK_STRUCT_STRUCT |
| 160 | PACK_STRUCT_BEGIN |
| 161 | PACK_STRUCT_END |
| 162 | |
| 163 | Platform specific diagnostic output - |
| 164 | LWIP_PLATFORM_DIAG(x) - non-fatal, print a message. |
| 165 | LWIP_PLATFORM_ASSERT(x) - fatal, print message and abandon execution. |
| 166 | |
| 167 | "lightweight" synchronization mechanisms - |
| 168 | SYS_ARCH_DECL_PROTECT(x) - declare a protection state variable. |
| 169 | SYS_ARCH_PROTECT(x) - enter protection mode. |
| 170 | SYS_ARCH_UNPROTECT(x) - leave protection mode. |
| 171 | |
| 172 | If the compiler does not provide memset() this file must include a |
| 173 | definition of it, or include a file which defines it. |
| 174 | |
| 175 | This file must either include a system-local <errno.h> which defines |
| 176 | the standard *nix error codes, or it should #define LWIP_PROVIDE_ERRNO |
| 177 | to make lwip/arch.h define the codes which are used throughout. |
| 178 | |
| 179 | |
| 180 | perf.h - Architecture specific performance measurement. |
| 181 | Measurement calls made throughout lwip, these can be defined to nothing. |
| 182 | PERF_START - start measuring something. |
| 183 | PERF_STOP(x) - stop measuring something, and record the result. |
| 184 | |
| 185 | sys_arch.h - Tied to sys_arch.c |
| 186 | |
| 187 | Arch dependent types for the following objects: |
| 188 | sys_sem_t, sys_mbox_t, sys_thread_t, |
| 189 | And, optionally: |
| 190 | sys_prot_t |
| 191 | |
| 192 | Defines to set vars of sys_mbox_t and sys_sem_t to NULL. |
| 193 | SYS_MBOX_NULL NULL |
| 194 | SYS_SEM_NULL NULL |