sdk/lib/drivers/lwip/doc/sys_arch.txt

   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 Since lwIP 1.4.0, semaphore and mailbox functions are prototyped in a way that
  38 allows both using pointers or actual OS structures to be used. This way, memory
  39 required for such types can be either allocated in place (globally or on the
  40 stack) or on the heap (allocated internally in the "*_new()" functions).
  41
  42 The 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
 167 If threads are supported by the underlying operating system and if
 168 such functionality is needed in lwIP, the following function will have
 169 to 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
 200 For 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
 210 Note:
 211
 212 Be carefull with using mem_malloc() in sys_arch. When malloc() refers to
 213 mem_malloc() you can run into a circular function call problem. In mem.c
 214 mem_init() tries to allcate a semaphore using mem_malloc, which of course
 215 can't be performed when sys_arch uses mem_malloc.
 216
 217 -------------------------------------------------------------------------------
 218 Additional files required for the "OS support" emulation layer:
 219 -------------------------------------------------------------------------------
 220
 221 cc.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
 253 perf.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
 258 sys_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