Daiki Kato / mbed-os-lychee

Dependents:   mbed-os-example-blinky-gr-lychee GR-Boads_Camera_sample GR-Boards_Audio_Recoder GR-Boads_Camera_DisplayApp ... more

Committer:
dkato
Date:
Fri Feb 02 05:42:23 2018 +0000
Revision:
0:f782d9c66c49
mbed-os for GR-LYCHEE

Who changed what in which revision?

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