diff --git a/CHANGELOG b/CHANGELOG index f46974a3..4876c42a 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -27,6 +27,9 @@ HISTORY ++ Bugfixes: + 2011-07-04: Simon Goldschmidt + * sys_arch.txt: Fixed documentation after changing sys arch prototypes for 1.4.0. + 2011-06-26: Simon Goldschmidt * tcp.c: fixed bug #31723 (tcp_kill_prio() kills pcbs with the same prio) by updating its documentation only. diff --git a/doc/sys_arch.txt b/doc/sys_arch.txt index 38377b66..847cd777 100644 --- a/doc/sys_arch.txt +++ b/doc/sys_arch.txt @@ -34,26 +34,36 @@ in the sys_arch.h file. Mailboxes are equivalently represented by the type "sys_mbox_t". lwIP does not place any restrictions on how sys_sem_t or sys_mbox_t are represented internally. +Since lwIP 1.4.0, semaphore 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). + The following functions must be implemented by the sys_arch: - void sys_init(void) Is called to initialize the sys_arch layer. -- sys_sem_t sys_sem_new(u8_t count) +- err_t sys_sem_new(sys_sem_t *sem, u8_t count) - Creates and returns a new semaphore. The "count" argument specifies - the initial state of the semaphore. + Creates a new semaphore. The semaphore is allocated to the memory that 'sem' + points to (which can be both a pointer or the actual OS structure). + The "count" argument specifies the initial state of the semaphore (which is + either 0 or 1). + If the semaphore has been created, ERR_OK should be returned. Returning any + other error will provide a hint what went wrong, but except for assertions, + no real error handling is implemented. -- void sys_sem_free(sys_sem_t sem) +- void sys_sem_free(sys_sem_t *sem) Deallocates a semaphore. -- void sys_sem_signal(sys_sem_t sem) +- void sys_sem_signal(sys_sem_t *sem) Signals a semaphore. -- u32_t sys_arch_sem_wait(sys_sem_t sem, u32_t timeout) +- u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout) Blocks the thread while waiting for the semaphore to be signaled. If the "timeout" argument is non-zero, the thread should @@ -70,30 +80,47 @@ The following functions must be implemented by the sys_arch: Notice that lwIP implements a function with a similar name, sys_sem_wait(), that uses the sys_arch_sem_wait() function. -- sys_mbox_t sys_mbox_new(int size) +- int sys_sem_valid(sys_sem_t *sem) + + Returns 1 if the semaphore is valid, 0 if it is not valid. + When using pointers, a simple way is to check the pointer for != NULL. + When directly using OS structures, implementing this may be more complex. + This may also be a define, in which case the function is not prototyped. + +- void sys_sem_set_invalid(sys_sem_t *sem) + + Invalidate a semaphore so that sys_sem_valid() returns 0. + ATTENTION: This does NOT mean that the semaphore shall be deallocated: + sys_sem_free() is always called before calling this function! + This may also be a define, in which case the function is not prototyped. + +- err_t sys_mbox_new(sys_mbox_t *mbox, int size) Creates an empty mailbox for maximum "size" elements. Elements stored in mailboxes are pointers. You have to define macros "_MBOX_SIZE" in your lwipopts.h, or ignore this parameter in your implementation and use a default size. + If the mailbox has been created, ERR_OK should be returned. Returning any + other error will provide a hint what went wrong, but except for assertions, + no real error handling is implemented. -- void sys_mbox_free(sys_mbox_t mbox) +- void sys_mbox_free(sys_mbox_t *mbox) Deallocates a mailbox. If there are messages still present in the mailbox when the mailbox is deallocated, it is an indication of a programming error in lwIP and the developer should be notified. -- void sys_mbox_post(sys_mbox_t mbox, void *msg) +- void sys_mbox_post(sys_mbox_t *mbox, void *msg) Posts the "msg" to the mailbox. This function have to block until the "msg" is really posted. -- err_t sys_mbox_trypost(sys_mbox_t mbox, void *msg) +- err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg) Try to post the "msg" to the mailbox. Returns ERR_MEM if this one is full, else, ERR_OK if the "msg" is posted. -- u32_t sys_arch_mbox_fetch(sys_mbox_t mbox, void **msg, u32_t timeout) +- u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout) Blocks the thread until a message arrives in the mailbox, but does not block the thread longer than "timeout" milliseconds (similar to @@ -110,7 +137,7 @@ The following functions must be implemented by the sys_arch: Note that a function with a similar name, sys_mbox_fetch(), is implemented by lwIP. -- u32_t sys_arch_mbox_tryfetch(sys_mbox_t mbox, void **msg) +- u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg) This is similar to sys_arch_mbox_fetch, however if a message is not present in the mailbox, it immediately returns with the code @@ -122,7 +149,21 @@ The following functions must be implemented by the sys_arch: #define sys_arch_mbox_tryfetch(mbox,msg) \ sys_arch_mbox_fetch(mbox,msg,1) although this would introduce unnecessary delays. - + +- int sys_mbox_valid(sys_mbox_t *mbox) + + Returns 1 if the mailbox is valid, 0 if it is not valid. + When using pointers, a simple way is to check the pointer for != NULL. + When directly using OS structures, implementing this may be more complex. + This may also be a define, in which case the function is not prototyped. + +- void sys_mbox_set_invalid(sys_mbox_t *mbox) + + Invalidate a mailbox so that sys_mbox_valid() returns 0. + ATTENTION: This does NOT mean that the mailbox shall be deallocated: + sys_mbox_free() is always called before calling this function! + This may also be a define, in which case the function is not prototyped. + If threads are supported by the underlying operating system and if such functionality is needed in lwIP, the following function will have to be implemented as well: @@ -156,6 +197,16 @@ to be implemented as well: more information. This function is only required if your port is supporting an operating system. +For some configurations, you also need: + +- u32_t sys_now(void) + + This optional function returns the current time in milliseconds (don't care + for wraparound, this is only used for time diffs). + Not implementing this function means you cannot use some modules (e.g. TCP + timestamps, internal timeouts for NO_SYS==1). + + Note: Be carefull with using mem_malloc() in sys_arch. When malloc() refers to