mirror/lwip
1
0
Fork 0
mirror of https://github.com/lwip-tcpip/lwip.git synced 2024-07-07 13:29:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document system abstraction layer in doxygen module style

Browse Source
This commit is contained in:
Dirk Ziegelmeier 2016-07-26 20:03:04 +02:00
parent c7e20150f0
commit 7f43fcab71
4 changed files with 163 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/doxygen/lwip.Doxyfile
View File

@ -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

4
doc/doxygen/sys_arch.h
View File

@ -1,4 +0,0 @@
/**
* @page sys Porting (sys abstraction layer)
* @verbinclude "sys_arch.txt"
*/

3
doc/snmp_agent.txt
View File

@ -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

207
src/include/lwip/sys.h
View File

@ -33,8 +33,32 @@
* This file is part of the lwIP TCP/IP stack.
*
* Author: Adam Dunkels <adam@sics.se>
*
*/
/**
* @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