From a8edee82685d0e8d2087d6c2fece8b7e52d49281 Mon Sep 17 00:00:00 2001 From: Dirk Ziegelmeier Date: Fri, 20 Oct 2017 18:20:25 +0200 Subject: [PATCH] Move all text from sys_arch.txt to appropriate doxygen places --- doc/sys_arch.txt | 89 ----------------------------------------- src/core/sys.c | 33 ++++++++++++++- src/include/lwip/arch.h | 2 + src/include/lwip/def.h | 11 +++++ 4 files changed, 45 insertions(+), 90 deletions(-) delete mode 100644 doc/sys_arch.txt diff --git a/doc/sys_arch.txt b/doc/sys_arch.txt deleted file mode 100644 index 39f2ea3c..00000000 --- a/doc/sys_arch.txt +++ /dev/null @@ -1,89 +0,0 @@ -sys_arch interface for lwIP - -Author: Adam Dunkels - Simon Goldschmidt - -The operating system emulation layer provides a common interface -between the lwIP code and the underlying operating system kernel. The -general idea is that porting lwIP to new architectures requires only -small changes to a few header files and a new sys_arch -implementation. It is also possible to do a sys_arch implementation -that does not rely on any underlying operating system. - -The sys_arch provides semaphores, mailboxes and mutexes to lwIP. For the full -lwIP functionality, multiple threads support can be implemented in the -sys_arch, but this is not required for the basic lwIP -functionality. Timer scheduling is implemented in lwIP, but can be implemented -by the sys_arch port (LWIP_TIMERS_CUSTOM==1). - -In addition to the source file providing the functionality of sys_arch, -the OS emulation layer must provide several header files defining -macros used throughout lwip. The files required and the macros they -must define are listed below the sys_arch description. - -Since lwIP 1.4.0, semaphore, mutexes and mailbox functions are prototyped in a way that -allows both using pointers or actual OS structures to be used. This way, memory -required for such types can be either allocated in place (globally or on the -stack) or on the heap (allocated internally in the "*_new()" functions). - -------------------------------------------------------------------------------- -Note: -------------------------------------------------------------------------------- - -Be careful with using mem_malloc() in sys_arch. When malloc() refers to -mem_malloc() you can run into a circular function call problem. In mem.c -mem_init() tries to allcate a semaphore using mem_malloc, which of course -can't be performed when sys_arch uses mem_malloc. - -------------------------------------------------------------------------------- -Additional files required for the "OS support" emulation layer: -------------------------------------------------------------------------------- - -cc.h - Architecture environment, some compiler specific, some - environment specific (probably should move env stuff - to sys_arch.h.) - - Typedefs for the types used by lwip - - u8_t, s8_t, u16_t, s16_t, u32_t, s32_t, mem_ptr_t - - Compiler hints for packing lwip's structures - - PACK_STRUCT_FIELD(x) - PACK_STRUCT_STRUCT - PACK_STRUCT_BEGIN - PACK_STRUCT_END - - Platform specific diagnostic output - - LWIP_PLATFORM_DIAG(x) - non-fatal, print a message. - LWIP_PLATFORM_ASSERT(x) - fatal, print message and abandon execution. - Portability defines for printf formatters: - U16_F, S16_F, X16_F, U32_F, S32_F, X32_F, SZT_F - - "lightweight" synchronization mechanisms - - SYS_ARCH_DECL_PROTECT(x) - declare a protection state variable. - SYS_ARCH_PROTECT(x) - enter protection mode. - SYS_ARCH_UNPROTECT(x) - leave protection mode. - - If the compiler does not provide memset() this file must include a - definition of it, or include a file which defines it. - - This file must either include a system-local which defines - the standard *nix error codes (or define LWIP_ERRNO_INCLUDE to that file name), - or it should #define LWIP_PROVIDE_ERRNO to make lwip/arch.h define the codes - which are used throughout. - - -perf.h - Architecture specific performance measurement. - Measurement calls made throughout lwip, these can be defined to nothing. - PERF_START - start measuring something. - PERF_STOP(x) - stop measuring something, and record the result. - -sys_arch.h - Tied to sys_arch.c - - Arch dependent types for the following objects: - sys_sem_t, sys_mbox_t, sys_thread_t, - And, optionally: - sys_prot_t - - Defines to set vars of sys_mbox_t and sys_sem_t to NULL. - SYS_MBOX_NULL NULL - SYS_SEM_NULL NULL diff --git a/src/core/sys.c b/src/core/sys.c index 62404487..fbf5b6b7 100644 --- a/src/core/sys.c +++ b/src/core/sys.c @@ -39,11 +39,42 @@ /** * @defgroup sys_layer Porting (system abstraction layer) * @ingroup lwip - * @verbinclude "sys_arch.txt" * * @defgroup sys_os OS abstraction layer * @ingroup sys_layer * No need to implement functions in this section in NO_SYS mode. + * The OS-specific code should be implemented in arch/sys_arch.h + * and sys_arch.c of your port. + * + * The operating system emulation layer provides a common interface + * between the lwIP code and the underlying operating system kernel. The + * general idea is that porting lwIP to new architectures requires only + * small changes to a few header files and a new sys_arch + * implementation. It is also possible to do a sys_arch implementation + * that does not rely on any underlying operating system. + * + * The sys_arch provides semaphores, mailboxes and mutexes to lwIP. For the full + * lwIP functionality, multiple threads support can be implemented in the + * sys_arch, but this is not required for the basic lwIP + * functionality. Timer scheduling is implemented in lwIP, but can be implemented + * by the sys_arch port (LWIP_TIMERS_CUSTOM==1). + * + * In addition to the source file providing the functionality of sys_arch, + * the OS emulation layer must provide several header files defining + * macros used throughout lwip. The files required and the macros they + * must define are listed below the sys_arch description. + * + * Since lwIP 1.4.0, semaphore, mutexes and mailbox functions are prototyped in a way that + * allows both using pointers or actual OS structures to be used. This way, memory + * required for such types can be either allocated in place (globally or on the + * stack) or on the heap (allocated internally in the "*_new()" functions). + * + * Note: + * ----- + * Be careful with using mem_malloc() in sys_arch. When malloc() refers to + * mem_malloc() you can run into a circular function call problem. In mem.c + * mem_init() tries to allcate a semaphore using mem_malloc, which of course + * can't be performed when sys_arch uses mem_malloc. * * @defgroup sys_sem Semaphores * @ingroup sys_os diff --git a/src/include/lwip/arch.h b/src/include/lwip/arch.h index 16a6e6c2..488f9972 100644 --- a/src/include/lwip/arch.h +++ b/src/include/lwip/arch.h @@ -52,6 +52,8 @@ * @ingroup sys_layer * All defines related to this section must not be placed in lwipopts.h, * but in arch/cc.h! + * If the compiler does not provide memset() this file must include a + * definition of it, or include a file which defines it. * These options cannot be \#defined in lwipopts.h since they are not options * of lwIP itself, but options of the lwIP port to your system. * @{ diff --git a/src/include/lwip/def.h b/src/include/lwip/def.h index f836ba90..3d6e107e 100644 --- a/src/include/lwip/def.h +++ b/src/include/lwip/def.h @@ -34,6 +34,17 @@ * Author: Adam Dunkels * */ + +/** + * @defgroup perf Performance measurement + * @ingroup sys_layer + * All defines related to this section must not be placed in lwipopts.h, + * but in arch/perf.h! + * Measurement calls made throughout lwip, these can be defined to nothing. + * - PERF_START: start measuring something. + * - PERF_STOP(x): stop measuring something, and record the result. + */ + #ifndef LWIP_HDR_DEF_H #define LWIP_HDR_DEF_H