Lee Kai Xuan / mbed-os

mbed-os

Fork of mbed-os by erkin yucel

features/unsupported/doc/net/sys_arch.txt@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

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