Improve system abstraction layer doxygen docs by moving documentation from sys_arch.txt to sys.c

This commit is contained in:
Dirk Ziegelmeier 2017-10-17 22:38:18 +02:00
parent 26b2628f01
commit 8a46a853d2
2 changed files with 13 additions and 12 deletions

View File

@ -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 macros used throughout lwip. The files required and the macros they
must define are listed below the sys_arch description. 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 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 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 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). stack) or on the heap (allocated internally in the "*_new()" functions).
-------------------------------------------------------------------------------
Note: Note:
-------------------------------------------------------------------------------
Be careful with using mem_malloc() in sys_arch. When malloc() refers to 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_malloc() you can run into a circular function call problem. In mem.c

View File

@ -47,6 +47,13 @@
* *
* @defgroup sys_sem Semaphores * @defgroup sys_sem Semaphores
* @ingroup sys_os * @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 * @defgroup sys_mutex Mutexes
* @ingroup sys_os * @ingroup sys_os
@ -55,6 +62,10 @@
* *
* @defgroup sys_mbox Mailboxes * @defgroup sys_mbox Mailboxes
* @ingroup sys_os * @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 * @defgroup sys_time Time
* @ingroup sys_layer * @ingroup sys_layer