a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsys_arch interface for lwIP 0.6++
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncAuthor: Adam Dunkels
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThe operating system emulation layer provides a common interface
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncbetween the lwIP code and the underlying operating system kernel. The
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncgeneral idea is that porting lwIP to new architectures requires only
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsmall changes to a few header files and a new sys_arch
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncimplementation. It is also possible to do a sys_arch implementation
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncthat does not rely on any underlying operating system.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThe sys_arch provides semaphores and mailboxes to lwIP. For the full
a82212bd36e1074408974b466798b9966bbaf49bvboxsynclwIP functionality, multiple threads support can be implemented in the
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsys_arch, but this is not required for the basic lwIP
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncfunctionality. Previous versions of lwIP required the sys_arch to
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncimplement timer scheduling as well but as of lwIP 0.5 this is
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncimplemented in a higher layer.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncIn addition to the source file providing the functionality of sys_arch,
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncthe OS emulation layer must provide several header files defining
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncmacros used throughout lwip. The files required and the macros they
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncmust define are listed below the sys_arch description.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncSemaphores can be either counting or binary - lwIP works with both
a82212bd36e1074408974b466798b9966bbaf49bvboxsynckinds. Mailboxes are used for message passing and can be implemented
a82212bd36e1074408974b466798b9966bbaf49bvboxsynceither as a queue which allows multiple messages to be posted to a
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncmailbox, or as a rendez-vous point where only one message can be
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncposted at a time. lwIP works with both kinds, but the former type will
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncbe more efficient. A message in a mailbox is just a pointer, nothing
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncSemaphores are represented by the type "sys_sem_t" which is typedef'd
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncin the sys_arch.h file. Mailboxes are equivalently represented by the
a82212bd36e1074408974b466798b9966bbaf49bvboxsynctype "sys_mbox_t". lwIP does not place any restrictions on how
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsys_sem_t or sys_mbox_t are represented internally.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncThe following functions must be implemented by the sys_arch:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- void sys_init(void)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Is called to initialize the sys_arch layer.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- sys_sem_t sys_sem_new(u8_t count)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Creates and returns a new semaphore. The "count" argument specifies
a82212bd36e1074408974b466798b9966bbaf49bvboxsync the initial state of the semaphore.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- void sys_sem_free(sys_sem_t sem)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Deallocates a semaphore.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- void sys_sem_signal(sys_sem_t sem)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Signals a semaphore.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- u32_t sys_arch_sem_wait(sys_sem_t sem, u32_t timeout)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Blocks the thread while waiting for the semaphore to be
a82212bd36e1074408974b466798b9966bbaf49bvboxsync signaled. If the "timeout" argument is non-zero, the thread should
a82212bd36e1074408974b466798b9966bbaf49bvboxsync only be blocked for the specified time (measured in
a82212bd36e1074408974b466798b9966bbaf49bvboxsync milliseconds).
a82212bd36e1074408974b466798b9966bbaf49bvboxsync If the timeout argument is non-zero, the return value is the number of
a82212bd36e1074408974b466798b9966bbaf49bvboxsync milliseconds spent waiting for the semaphore to be signaled. If the
a82212bd36e1074408974b466798b9966bbaf49bvboxsync semaphore wasn't signaled within the specified time, the return value is
a82212bd36e1074408974b466798b9966bbaf49bvboxsync SYS_ARCH_TIMEOUT. If the thread didn't have to wait for the semaphore
a82212bd36e1074408974b466798b9966bbaf49bvboxsync (i.e., it was already signaled), the function may return zero.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Notice that lwIP implements a function with a similar name,
a82212bd36e1074408974b466798b9966bbaf49bvboxsync sys_sem_wait(), that uses the sys_arch_sem_wait() function.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- sys_mbox_t sys_mbox_new(void)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Creates an empty mailbox.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- void sys_mbox_free(sys_mbox_t mbox)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Deallocates a mailbox. If there are messages still present in the
a82212bd36e1074408974b466798b9966bbaf49bvboxsync mailbox when the mailbox is deallocated, it is an indication of a
a82212bd36e1074408974b466798b9966bbaf49bvboxsync programming error in lwIP and the developer should be notified.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- void sys_mbox_post(sys_mbox_t mbox, void *msg)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Posts the "msg" to the mailbox.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- u32_t sys_arch_mbox_fetch(sys_mbox_t mbox, void **msg, u32_t timeout)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Blocks the thread until a message arrives in the mailbox, but does
a82212bd36e1074408974b466798b9966bbaf49bvboxsync not block the thread longer than "timeout" milliseconds (similar to
a82212bd36e1074408974b466798b9966bbaf49bvboxsync the sys_arch_sem_wait() function). The "msg" argument is a result
a82212bd36e1074408974b466798b9966bbaf49bvboxsync parameter that is set by the function (i.e., by doing "*msg =
a82212bd36e1074408974b466798b9966bbaf49bvboxsync ptr"). The "msg" parameter maybe NULL to indicate that the message
a82212bd36e1074408974b466798b9966bbaf49bvboxsync should be dropped.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync The return values are the same as for the sys_arch_sem_wait() function:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Note that a function with a similar name, sys_mbox_fetch(), is
a82212bd36e1074408974b466798b9966bbaf49bvboxsync implemented by lwIP.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- struct sys_timeouts *sys_arch_timeouts(void)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Returns a pointer to the per-thread sys_timeouts structure. In lwIP,
a82212bd36e1074408974b466798b9966bbaf49bvboxsync each thread has a list of timeouts which is repressented as a linked
a82212bd36e1074408974b466798b9966bbaf49bvboxsync list of sys_timeout structures. The sys_timeouts structure holds a
a82212bd36e1074408974b466798b9966bbaf49bvboxsync pointer to a linked list of timeouts. This function is called by
a82212bd36e1074408974b466798b9966bbaf49bvboxsync the lwIP timeout scheduler and must not return a NULL value.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync In a single threadd sys_arch implementation, this function will
a82212bd36e1074408974b466798b9966bbaf49bvboxsync simply return a pointer to a global sys_timeouts variable stored in
a82212bd36e1074408974b466798b9966bbaf49bvboxsync the sys_arch module.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncIf threads are supported by the underlying operating system and if
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncsuch functionality is needed in lwIP, the following function will have
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncto be implemented as well:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- sys_thread_t sys_thread_new(void (* thread)(void *arg), void *arg, int prio)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Starts a new thread with priority "prio" that will begin its execution in the
a82212bd36e1074408974b466798b9966bbaf49bvboxsync function "thread()". The "arg" argument will be passed as an argument to the
a82212bd36e1074408974b466798b9966bbaf49bvboxsync thread() function. The id of the new thread is returned. Both the id and
a82212bd36e1074408974b466798b9966bbaf49bvboxsync the priority are system dependent.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- sys_prot_t sys_arch_protect(void)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync This optional function does a "fast" critical region protection and returns
a82212bd36e1074408974b466798b9966bbaf49bvboxsync the previous protection level. This function is only called during very short
a82212bd36e1074408974b466798b9966bbaf49bvboxsync critical regions. An embedded system which supports ISR-based drivers might
a82212bd36e1074408974b466798b9966bbaf49bvboxsync want to implement this function by disabling interrupts. Task-based systems
a82212bd36e1074408974b466798b9966bbaf49bvboxsync might want to implement this by using a mutex or disabling tasking. This
a82212bd36e1074408974b466798b9966bbaf49bvboxsync function should support recursive calls from the same task or interrupt. In
a82212bd36e1074408974b466798b9966bbaf49bvboxsync other words, sys_arch_protect() could be called while already protected. In
a82212bd36e1074408974b466798b9966bbaf49bvboxsync that case the return value indicates that it is already protected.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync sys_arch_protect() is only required if your port is supporting an operating
a82212bd36e1074408974b466798b9966bbaf49bvboxsync- void sys_arch_unprotect(sys_prot_t pval)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync This optional function does a "fast" set of critical region protection to the
a82212bd36e1074408974b466798b9966bbaf49bvboxsync value specified by pval. See the documentation for sys_arch_protect() for
a82212bd36e1074408974b466798b9966bbaf49bvboxsync more information. This function is only required if your port is supporting
a82212bd36e1074408974b466798b9966bbaf49bvboxsync an operating system.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncBe carefull with using mem_malloc() in sys_arch. When malloc() refers to
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncmem_malloc() you can run into a circular function call problem. In mem.c
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncmem_init() tries to allcate a semaphore using mem_malloc, which of course
a82212bd36e1074408974b466798b9966bbaf49bvboxsynccan't be performed when sys_arch uses mem_malloc.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync-------------------------------------------------------------------------------
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncAdditional files required for the "OS support" emulation layer:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync-------------------------------------------------------------------------------
a82212bd36e1074408974b466798b9966bbaf49bvboxsynccc.h - Architecture environment, some compiler specific, some
a82212bd36e1074408974b466798b9966bbaf49bvboxsync environment specific (probably should move env stuff
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Typedefs for the types used by lwip -
a82212bd36e1074408974b466798b9966bbaf49bvboxsync u8_t, s8_t, u16_t, s16_t, u32_t, s32_t, mem_ptr_t
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Compiler hints for packing lwip's structures -
a82212bd36e1074408974b466798b9966bbaf49bvboxsync PACK_STRUCT_FIELD(x)
a82212bd36e1074408974b466798b9966bbaf49bvboxsync PACK_STRUCT_STRUCT
a82212bd36e1074408974b466798b9966bbaf49bvboxsync PACK_STRUCT_BEGIN
a82212bd36e1074408974b466798b9966bbaf49bvboxsync PACK_STRUCT_END
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Platform specific diagnostic output -
a82212bd36e1074408974b466798b9966bbaf49bvboxsync LWIP_PLATFORM_DIAG(x) - non-fatal, print a message.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync LWIP_PLATFORM_ASSERT(x) - fatal, print message and abandon execution.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync "lightweight" synchronization mechanisms -
a82212bd36e1074408974b466798b9966bbaf49bvboxsync SYS_ARCH_DECL_PROTECT(x) - declare a protection state variable.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync SYS_ARCH_PROTECT(x) - enter protection mode.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync SYS_ARCH_UNPROTECT(x) - leave protection mode.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync If the compiler does not provide memset() this file must include a
a82212bd36e1074408974b466798b9966bbaf49bvboxsync definition of it, or include a file which defines it.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync This file must either include a system-local <errno.h> which defines
a82212bd36e1074408974b466798b9966bbaf49bvboxsync the standard *nix error codes, or it should #define LWIP_PROVIDE_ERRNO
a82212bd36e1074408974b466798b9966bbaf49bvboxsync to make lwip/arch.h define the codes which are used throughout.
a82212bd36e1074408974b466798b9966bbaf49bvboxsyncperf.h - Architecture specific performance measurement.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Measurement calls made throughout lwip, these can be defined to nothing.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync PERF_START - start measuring something.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync PERF_STOP(x) - stop measuring something, and record the result.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Arch dependent types for the following objects:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync sys_sem_t, sys_mbox_t, sys_thread_t,
a82212bd36e1074408974b466798b9966bbaf49bvboxsync And, optionally:
a82212bd36e1074408974b466798b9966bbaf49bvboxsync Defines to set vars of sys_mbox_t and sys_sem_t to NULL.
a82212bd36e1074408974b466798b9966bbaf49bvboxsync SYS_MBOX_NULL NULL
a82212bd36e1074408974b466798b9966bbaf49bvboxsync SYS_SEM_NULL NULL