From 7f43fcab71d9105daaff44978ed3b6e7b52bec99 Mon Sep 17 00:00:00 2001 From: Dirk Ziegelmeier Date: Tue, 26 Jul 2016 20:03:04 +0200 Subject: [PATCH] Document system abstraction layer in doxygen module style --- doc/doxygen/lwip.Doxyfile | 2 +- doc/doxygen/sys_arch.h | 4 - doc/snmp_agent.txt | 3 + src/include/lwip/sys.h | 207 +++++++++++++++++++++++++++++--------- 4 files changed, 163 insertions(+), 53 deletions(-) delete mode 100644 doc/doxygen/sys_arch.h diff --git a/doc/doxygen/lwip.Doxyfile b/doc/doxygen/lwip.Doxyfile index 3c510a2d..0b9b8122 100644 --- a/doc/doxygen/lwip.Doxyfile +++ b/doc/doxygen/lwip.Doxyfile @@ -781,7 +781,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../src main_page.h ppp.h contrib.h sys_arch.h +INPUT = ../../src main_page.h ppp.h contrib.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/doc/doxygen/sys_arch.h b/doc/doxygen/sys_arch.h deleted file mode 100644 index 213cec90..00000000 --- a/doc/doxygen/sys_arch.h +++ /dev/null @@ -1,4 +0,0 @@ -/** - * @page sys Porting (sys abstraction layer) - * @verbinclude "sys_arch.txt" - */ diff --git a/doc/snmp_agent.txt b/doc/snmp_agent.txt index 3d514cc3..224a986d 100644 --- a/doc/snmp_agent.txt +++ b/doc/snmp_agent.txt @@ -1,3 +1,6 @@ +* THIS DOCUMENTATION IS OUTDATED * +It was written before the agent was largely rewritten in 2015. + SNMPv1 agent for lwIP Author: Christiaan Simons diff --git a/src/include/lwip/sys.h b/src/include/lwip/sys.h index 380d03b0..cedaf8ef 100644 --- a/src/include/lwip/sys.h +++ b/src/include/lwip/sys.h @@ -33,8 +33,32 @@ * This file is part of the lwIP TCP/IP stack. * * Author: Adam Dunkels - * */ + +/** + * @defgroup sys_layer System abstraction layer + * @ingroup infrastructure + * @verbinclude "sys_arch.txt" + * + * @defgroup sys_sem Semaphores + * @ingroup sys_layer + * + * @defgroup sys_mutex Mutexes + * @ingroup sys_layer + * + * @defgroup sys_mbox Mailboxes + * @ingroup sys_layer + * + * @defgroup sys_time Time + * @ingroup sys_layer + * + * @defgroup sys_prot Critical sections + * @ingroup sys_layer + * + * @defgroup sys_thread Threads + * @ingroup sys_layer + */ + #ifndef LWIP_HDR_SYS_H #define LWIP_HDR_SYS_H @@ -121,130 +145,205 @@ typedef void (*lwip_thread_fn)(void *arg); #else /* LWIP_COMPAT_MUTEX */ -/** Create a new mutex +/** + * @ingroup sys_mutex + * Create a new mutex * @param mutex pointer to the mutex to create - * @return a new mutex */ + * @return a new mutex + */ err_t sys_mutex_new(sys_mutex_t *mutex); -/** Lock a mutex - * @param mutex the mutex to lock */ +/** + * @ingroup sys_mutex + * Lock a mutex + * @param mutex the mutex to lock + */ void sys_mutex_lock(sys_mutex_t *mutex); -/** Unlock a mutex - * @param mutex the mutex to unlock */ +/** + * @ingroup sys_mutex + * Unlock a mutex + * @param mutex the mutex to unlock + */ void sys_mutex_unlock(sys_mutex_t *mutex); -/** Delete a semaphore - * @param mutex the mutex to delete */ +/** + * @ingroup sys_mutex + * Delete a semaphore + * @param mutex the mutex to delete + */ void sys_mutex_free(sys_mutex_t *mutex); #ifndef sys_mutex_valid -/** Check if a mutex is valid/allocated: return 1 for valid, 0 for invalid */ +/** + * @ingroup sys_mutex + * Check if a mutex is valid/allocated: return 1 for valid, 0 for invalid + */ int sys_mutex_valid(sys_mutex_t *mutex); #endif #ifndef sys_mutex_set_invalid -/** Set a mutex invalid so that sys_mutex_valid returns 0 */ +/** + * @ingroup sys_mutex + * Set a mutex invalid so that sys_mutex_valid returns 0 + */ void sys_mutex_set_invalid(sys_mutex_t *mutex); #endif #endif /* LWIP_COMPAT_MUTEX */ /* Semaphore functions: */ -/** Create a new semaphore +/** + * @ingroup sys_sem + * Create a new semaphore * @param sem pointer to the semaphore to create * @param count initial count of the semaphore - * @return ERR_OK if successful, another err_t otherwise */ + * @return ERR_OK if successful, another err_t otherwise + */ err_t sys_sem_new(sys_sem_t *sem, u8_t count); -/** Signals a semaphore - * @param sem the semaphore to signal */ +/** + * @ingroup sys_sem + * Signals a semaphore + * @param sem the semaphore to signal + */ void sys_sem_signal(sys_sem_t *sem); -/** Wait for a semaphore for the specified timeout +/** + * @ingroup sys_sem + * Wait for a semaphore for the specified timeout * @param sem the semaphore to wait for * @param timeout timeout in milliseconds to wait (0 = wait forever) * @return time (in milliseconds) waited for the semaphore - * or SYS_ARCH_TIMEOUT on timeout */ + * or SYS_ARCH_TIMEOUT on timeout + */ u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout); -/** Delete a semaphore - * @param sem semaphore to delete */ +/** + * @ingroup sys_sem + * Delete a semaphore + * @param sem semaphore to delete + */ void sys_sem_free(sys_sem_t *sem); /** Wait for a semaphore - forever/no timeout */ #define sys_sem_wait(sem) sys_arch_sem_wait(sem, 0) #ifndef sys_sem_valid -/** Check if a semaphore is valid/allocated: return 1 for valid, 0 for invalid */ +/** + * @ingroup sys_sem + * Check if a semaphore is valid/allocated: return 1 for valid, 0 for invalid + */ int sys_sem_valid(sys_sem_t *sem); #endif #ifndef sys_sem_set_invalid -/** Set a semaphore invalid so that sys_sem_valid returns 0 */ +/** + * @ingroup sys_sem + * Set a semaphore invalid so that sys_sem_valid returns 0 + */ void sys_sem_set_invalid(sys_sem_t *sem); #endif #ifndef sys_sem_valid_val -/** Same as sys_sem_valid() but taking a value, not a pointer */ +/** + * Same as sys_sem_valid() but taking a value, not a pointer + */ #define sys_sem_valid_val(sem) sys_sem_valid(&(sem)) #endif #ifndef sys_sem_set_invalid_val -/** Same as sys_sem_set_invalid() but taking a value, not a pointer */ +/** + * Same as sys_sem_set_invalid() but taking a value, not a pointer + */ #define sys_sem_set_invalid_val(sem) sys_sem_set_invalid(&(sem)) #endif -/* Time functions. */ #ifndef sys_msleep +/** + * @ingroup sys_time + * Sleep for specified number of ms + */ void sys_msleep(u32_t ms); /* only has a (close to) 1 ms resolution. */ #endif /* Mailbox functions. */ -/** Create a new mbox of specified size +/** + * @ingroup sys_mbox + * Create a new mbox of specified size * @param mbox pointer to the mbox to create * @param size (minimum) number of messages in this mbox - * @return ERR_OK if successful, another err_t otherwise */ + * @return ERR_OK if successful, another err_t otherwise + */ err_t sys_mbox_new(sys_mbox_t *mbox, int size); -/** Post a message to an mbox - may not fail +/** + * @ingroup sys_mbox + * Post a message to an mbox - may not fail * -> blocks if full, only used from tasks not from ISR * @param mbox mbox to posts the message - * @param msg message to post (ATTENTION: can be NULL) */ + * @param msg message to post (ATTENTION: can be NULL) + */ void sys_mbox_post(sys_mbox_t *mbox, void *msg); -/** Try to post a message to an mbox - may fail if full or ISR +/** + * @ingroup sys_mbox + * Try to post a message to an mbox - may fail if full or ISR * @param mbox mbox to posts the message - * @param msg message to post (ATTENTION: can be NULL) */ + * @param msg message to post (ATTENTION: can be NULL) + */ err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg); -/** Wait for a new message to arrive in the mbox +/** + * @ingroup sys_mbox + * Wait for a new message to arrive in the mbox * @param mbox mbox to get a message from * @param msg pointer where the message is stored * @param timeout maximum time (in milliseconds) to wait for a message (0 = wait forever) * @return time (in milliseconds) waited for a message, may be 0 if not waited or SYS_ARCH_TIMEOUT on timeout - * The returned time has to be accurate to prevent timer jitter! */ + * The returned time has to be accurate to prevent timer jitter! + */ u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout); /* Allow port to override with a macro, e.g. special timeout for sys_arch_mbox_fetch() */ #ifndef sys_arch_mbox_tryfetch -/** Wait for a new message to arrive in the mbox +/** + * @ingroup sys_mbox + * Wait for a new message to arrive in the mbox * @param mbox mbox to get a message from * @param msg pointer where the message is stored * @return 0 (milliseconds) if a message has been received - * or SYS_MBOX_EMPTY if the mailbox is empty */ + * or SYS_MBOX_EMPTY if the mailbox is empty + */ u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg); #endif -/** For now, we map straight to sys_arch implementation. */ +/** + * For now, we map straight to sys_arch implementation. + */ #define sys_mbox_tryfetch(mbox, msg) sys_arch_mbox_tryfetch(mbox, msg) -/** Delete an mbox - * @param mbox mbox to delete */ +/** + * @ingroup sys_mbox + * Delete an mbox + * @param mbox mbox to delete + */ void sys_mbox_free(sys_mbox_t *mbox); #define sys_mbox_fetch(mbox, msg) sys_arch_mbox_fetch(mbox, msg, 0) #ifndef sys_mbox_valid -/** Check if an mbox is valid/allocated: return 1 for valid, 0 for invalid */ +/** + * @ingroup sys_mbox + * Check if an mbox is valid/allocated: return 1 for valid, 0 for invalid + */ int sys_mbox_valid(sys_mbox_t *mbox); #endif #ifndef sys_mbox_set_invalid -/** Set an mbox invalid so that sys_mbox_valid returns 0 */ +/** + * @ingroup sys_mbox + * Set an mbox invalid so that sys_mbox_valid returns 0 + */ void sys_mbox_set_invalid(sys_mbox_t *mbox); #endif #ifndef sys_mbox_valid_val -/** Same as sys_mbox_valid() but taking a value, not a pointer */ +/** + * Same as sys_mbox_valid() but taking a value, not a pointer + */ #define sys_mbox_valid_val(mbox) sys_mbox_valid(&(mbox)) #endif #ifndef sys_mbox_set_invalid_val -/** Same as sys_mbox_set_invalid() but taking a value, not a pointer */ +/** + * Same as sys_mbox_set_invalid() but taking a value, not a pointer + */ #define sys_mbox_set_invalid_val(mbox) sys_mbox_set_invalid(&(mbox)) #endif -/** The only thread function: +/** + * @ingroup sys_thread + * The only thread function: * Creates a new thread * ATTENTION: although this function returns a value, it MUST NOT FAIL (ports have to assert this!) * @param name human-readable name for the thread (used for debugging purposes) @@ -260,12 +359,18 @@ sys_thread_t sys_thread_new(const char *name, lwip_thread_fn thread, void *arg, void sys_init(void); #ifndef sys_jiffies -/** Ticks/jiffies since power up. */ +/** + * @ingroup sys_time + * Ticks/jiffies since power up. + */ u32_t sys_jiffies(void); #endif -/** Returns the current time in milliseconds, - * may be the same as sys_jiffies or at least based on it. */ +/** + * @ingroup sys_time + * Returns the current time in milliseconds, + * may be the same as sys_jiffies or at least based on it. + */ u32_t sys_now(void); /* Critical Region Protection */ @@ -281,13 +386,17 @@ u32_t sys_now(void); */ #if SYS_LIGHTWEIGHT_PROT -/** SYS_ARCH_DECL_PROTECT +/** + * @ingroup sys_prot + * SYS_ARCH_DECL_PROTECT * declare a protection variable. This macro will default to defining a variable of * type sys_prot_t. If a particular port needs a different implementation, then * this macro may be defined in sys_arch.h. */ #define SYS_ARCH_DECL_PROTECT(lev) sys_prot_t lev -/** SYS_ARCH_PROTECT +/** + * @ingroup sys_prot + * SYS_ARCH_PROTECT * Perform a "fast" protect. This could be implemented by * disabling interrupts for an embedded system or by using a semaphore or * mutex. The implementation should allow calling SYS_ARCH_PROTECT when @@ -297,7 +406,9 @@ u32_t sys_now(void); * different implementation, then this macro may be defined in sys_arch.h */ #define SYS_ARCH_PROTECT(lev) lev = sys_arch_protect() -/** SYS_ARCH_UNPROTECT +/** + * @ingroup sys_prot + * SYS_ARCH_UNPROTECT * Perform a "fast" set of the protection level to "lev". This could be * implemented by setting the interrupt level to "lev" within the MACRO or by * using a semaphore or mutex. This macro will default to calling the