From 8a46a853d2ab2c470c76962d3f1cbe9362e30fa1 Mon Sep 17 00:00:00 2001 From: Dirk Ziegelmeier Date: Tue, 17 Oct 2017 22:38:18 +0200 Subject: [PATCH] Improve system abstraction layer doxygen docs by moving documentation from sys_arch.txt to sys.c --- doc/sys_arch.txt | 14 ++------------ src/core/sys.c | 11 +++++++++++ 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/doc/sys_arch.txt b/doc/sys_arch.txt index 903b2e9f..39f2ea3c 100644 --- a/doc/sys_arch.txt +++ b/doc/sys_arch.txt @@ -21,24 +21,14 @@ 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. -Semaphores can be either counting or binary - lwIP works with both -kinds. Mailboxes should be implemented as a queue which allows multiple messages -to be posted (implementing as a rendez-vous point where only one message can be -posted at a time can have a highly negative impact on performance). A message -in a mailbox is just a pointer, nothing more. - -Semaphores are represented by the type "sys_sem_t" which is typedef'd -in the sys_arch.h file. Mailboxes are equivalently represented by the -type "sys_mbox_t". Mutexes are represented by the type "sys_mutex_t". -lwIP does not place any restrictions on how these types are represented -internally. - 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 diff --git a/src/core/sys.c b/src/core/sys.c index 7059b4de..62404487 100644 --- a/src/core/sys.c +++ b/src/core/sys.c @@ -47,6 +47,13 @@ * * @defgroup sys_sem Semaphores * @ingroup sys_os + * Semaphores can be either counting or binary - lwIP works with both + * kinds. + * Semaphores are represented by the type "sys_sem_t" which is typedef'd + * in the sys_arch.h file. Mailboxes are equivalently represented by the + * type "sys_mbox_t". Mutexes are represented by the type "sys_mutex_t". + * lwIP does not place any restrictions on how these types are represented + * internally. * * @defgroup sys_mutex Mutexes * @ingroup sys_os @@ -55,6 +62,10 @@ * * @defgroup sys_mbox Mailboxes * @ingroup sys_os + * Mailboxes should be implemented as a queue which allows multiple messages + * to be posted (implementing as a rendez-vous point where only one message can be + * posted at a time can have a highly negative impact on performance). A message + * in a mailbox is just a pointer, nothing more. * * @defgroup sys_time Time * @ingroup sys_layer