From 0a2945164cb4ed8f3f4ac7d756eaa15ede17a65b Mon Sep 17 00:00:00 2001 From: "Martine S. Lenders" Date: Wed, 9 Oct 2019 12:45:32 +0200 Subject: [PATCH] lwip: improve and fix documentation --- doc/doxygen/riot.doxyfile | 1 - pkg/lwip/contrib/doc.txt | 3 - pkg/lwip/doc.txt | 5 +- pkg/lwip/include/arch/cc.h | 26 ++++----- pkg/lwip/include/arch/sys_arch.h | 82 ++++++++++++++++++++------- pkg/lwip/include/lwip/sock_internal.h | 3 +- pkg/lwip/include/sock_types.h | 34 ++++++----- 7 files changed, 100 insertions(+), 54 deletions(-) delete mode 100644 pkg/lwip/contrib/doc.txt diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index eed7cfbf81..acbcecca3d 100644 --- a/doc/doxygen/riot.doxyfile +++ b/doc/doxygen/riot.doxyfile @@ -828,7 +828,6 @@ EXCLUDE_PATTERNS = */board/*/tools/* \ */cpu/native/osx-libc-extra \ */cpu/x86/include/* \ */drivers/kw2xrf/include/overwrites.h \ - */pkg/lwip/* \ */pkg/tlsf/patch.txt \ */sys/include/embUnit/* \ */sys/random/fortuna/* \ diff --git a/pkg/lwip/contrib/doc.txt b/pkg/lwip/contrib/doc.txt deleted file mode 100644 index 9ddba3fdb5..0000000000 --- a/pkg/lwip/contrib/doc.txt +++ /dev/null @@ -1,3 +0,0 @@ -/** - * @defgroup pkg_lwip_contrib RIOT lwIP port - */ diff --git a/pkg/lwip/doc.txt b/pkg/lwip/doc.txt index 5cb9fb6a70..a72e2b5062 100644 --- a/pkg/lwip/doc.txt +++ b/pkg/lwip/doc.txt @@ -3,8 +3,9 @@ * @ingroup pkg * @ingroup net * @brief Provides the lwIP network stack - * @see http://savannah.nongnu.org/projects/lwip/ + * @see https://savannah.nongnu.org/projects/lwip/ + * @see https://www.nongnu.org/lwip/2_1_x/ * * lwIP is a lightweight TCP/IP stack primarily for usage with Ethernet. - * It can be used with the @ref sock API. + * It can be used with the @ref net_sock API. */ diff --git a/pkg/lwip/include/arch/cc.h b/pkg/lwip/include/arch/cc.h index fe058e4d60..ebd6cb409f 100644 --- a/pkg/lwip/include/arch/cc.h +++ b/pkg/lwip/include/arch/cc.h @@ -7,13 +7,13 @@ */ /** - * @defgroup pkg_lwip_arch_cc Compiler and processor description - * @ingroup pkg_lwip + * @addtogroup pkg_lwip_sys * @brief Describes compiler and processor to lwIP * @{ * * @file - * @brief Compiler and processor definitions + * @brief Compiler/platform abstraction + * @see http://www.nongnu.org/lwip/2_1_x/group__compiler__abstraction.html * * @author Martine Lenders */ @@ -48,7 +48,7 @@ extern "C" { #endif /** - * @brief (sn)printf formatters for the generic lwIP types + * @name (sn)printf formatters for the generic lwIP types * @{ */ #define X8_F "02" PRIx8 @@ -60,23 +60,22 @@ extern "C" { #define X32_F PRIx32 #define SZT_F "lu" -/** - * @} - */ +/** @} */ /** - * @brief Compiler hints for packing structures + * @name Compiler hints for packing structures * @{ */ #define PACK_STRUCT_FIELD(x) x #define PACK_STRUCT_STRUCT __attribute__((packed)) #define PACK_STRUCT_BEGIN #define PACK_STRUCT_END +/** @} */ + /** - * @} + * @name Platform specific diagnostic output + * @{ */ - - #ifdef MODULE_LOG # define LWIP_PLATFORM_DIAG(x) LOG_INFO x # ifdef NDEBUG @@ -102,10 +101,7 @@ extern "C" { } while (0) # endif #endif - -#define SYS_ARCH_PROTECT(x) mutex_lock(&x) -#define SYS_ARCH_UNPROTECT(x) mutex_unlock(&x) -#define SYS_ARCH_DECL_PROTECT(x) mutex_t x = MUTEX_INIT +/** @} */ #ifdef __cplusplus } diff --git a/pkg/lwip/include/arch/sys_arch.h b/pkg/lwip/include/arch/sys_arch.h index da9281882e..7ac430a30b 100644 --- a/pkg/lwip/include/arch/sys_arch.h +++ b/pkg/lwip/include/arch/sys_arch.h @@ -7,13 +7,14 @@ */ /** - * @defgroup pkg_lwip_arch_sys_arch Architecture depentent definitions + * @defgroup pkg_lwip_sys Porting layer * @ingroup pkg_lwip - * @brief Semaphores and mailboxes. + * @brief System abstraction layer * @{ * * @file - * @brief Semaphore and mailboxes definitions. + * @brief OS abstraction layer + * @see https://www.nongnu.org/lwip/2_1_x/group__sys__os.html * * @author Martine Lenders */ @@ -34,27 +35,68 @@ extern "C" { #endif +/** + * @brief System configuration + */ +/* prefer mutexes rather than binary semaphores */ #define LWIP_COMPAT_MUTEX (0) -#define SYS_MBOX_SIZE (8) +/** @} */ -typedef struct { - mbox_t mbox; - msg_t msgs[SYS_MBOX_SIZE]; -} sys_mbox_t; +/** + * @name Critical sections protection definitions + * @see https://www.nongnu.org/lwip/2_1_x/group__sys__prot.html + * @{ + */ +#define SYS_ARCH_PROTECT(x) mutex_lock(&x) +#define SYS_ARCH_UNPROTECT(x) mutex_unlock(&x) +#define SYS_ARCH_DECL_PROTECT(x) mutex_t x = MUTEX_INIT +/** @} */ -typedef mutex_t sys_mutex_t; -typedef sema_t sys_sem_t; -typedef kernel_pid_t sys_thread_t; +/** + * @name Semaphores definitions + * @see https://www.nongnu.org/lwip/2_1_x/group__sys__sem.html + */ +typedef sema_t sys_sem_t; /**< Platform specific semaphore type */ + +static inline bool sys_sem_valid(sys_sem_t *sem) +{ + return sem != NULL; +} + +#define sys_sem_valid(sem) (sys_sem_valid(sem)) + +#define sys_sem_set_invalid(sem) +/** @} */ + +/** + * @name Mutexes definitions + * @see https://www.nongnu.org/lwip/2_1_x/group__sys__mutex.html + */ +typedef mutex_t sys_mutex_t; /**< Platform specific mutex type */ static inline bool sys_mutex_valid(sys_mutex_t *mutex) { return mutex != NULL; } -static inline bool sys_sem_valid(sys_sem_t *sem) -{ - return sem != NULL; -} +#define sys_mutex_valid(mutex) (sys_mutex_valid(mutex)) +#define sys_mutex_set_invalid(mutex) +/** @} */ + +/** + * @name Mailboxes OS abstraction layer definitions + * @see https://www.nongnu.org/lwip/2_1_x/group__sys__mbox.html + * @{ + */ +#define SYS_MBOX_SIZE (8) + +/** + * @brief Platform specific mailbox type + */ +typedef struct { + mbox_t mbox; /**< RIOT mbox */ + msg_t msgs[SYS_MBOX_SIZE]; /**< queue for the mbox */ +} sys_mbox_t; static inline bool sys_mbox_valid(sys_mbox_t *mbox) { @@ -68,14 +110,16 @@ static inline void sys_mbox_set_invalid(sys_mbox_t *mbox) } } -#define sys_mutex_valid(mutex) (sys_mutex_valid(mutex)) -#define sys_mutex_set_invalid(mutex) -#define sys_sem_valid(sem) (sys_sem_valid(sem)) -#define sys_sem_set_invalid(sem) #define sys_mbox_valid(mbox) (sys_mbox_valid(mbox)) #define sys_mbox_set_invalid(mbox) (sys_mbox_set_invalid(mbox)) +/** @} */ + +typedef kernel_pid_t sys_thread_t; /**< Platform specific thread type */ #ifdef MODULE_RANDOM +/** + * @brief Use `random_uint32()` to generate random numbers, if available + */ #define LWIP_RAND() (random_uint32()) #endif diff --git a/pkg/lwip/include/lwip/sock_internal.h b/pkg/lwip/include/lwip/sock_internal.h index 68eca56794..62e2805d32 100644 --- a/pkg/lwip/include/lwip/sock_internal.h +++ b/pkg/lwip/include/lwip/sock_internal.h @@ -11,10 +11,11 @@ * @ingroup pkg_lwip * @brief Provides an implementation of the @ref net_sock for the * @ref pkg_lwip + * @internal * @{ * * @file - * @brief lwIP-specific function @ref definitions + * @brief lwIP-specific function @ref net_sock definitions * * @author Martine Lenders */ diff --git a/pkg/lwip/include/sock_types.h b/pkg/lwip/include/sock_types.h index 28e3c83026..ea0a033d27 100644 --- a/pkg/lwip/include/sock_types.h +++ b/pkg/lwip/include/sock_types.h @@ -7,7 +7,7 @@ */ /** - * @ingroup pkg_lwip_sock + * @addtogroup pkg_lwip_sock * @{ * * @file @@ -27,41 +27,49 @@ extern "C" { /** * @brief Raw IP sock type + * @warning For network stack internal purposes only. Do not access members + * externally. * @internal */ struct sock_ip { - struct netconn *conn; + struct netconn *conn; /**< lwIP network connection object */ }; /** * @brief TCP sock type + * @warning For network stack internal purposes only. Do not access members + * externally. * @internal */ struct sock_tcp { - struct netconn *conn; - struct sock_tcp_queue *queue; - mutex_t mutex; - struct pbuf *last_buf; - ssize_t last_offset; + struct netconn *conn; /**< lwIP network connection object */ + struct sock_tcp_queue *queue; /**< Queue the sock might have been generated from */ + mutex_t mutex; /**< Mutex to protect the sock */ + struct pbuf *last_buf; /**< Last received data */ + ssize_t last_offset; /**< Offset in struct sock_tcp::last_buf since last read */ }; /** * @brief TCP queue type + * @warning For network stack internal purposes only. Do not access members + * externally. */ struct sock_tcp_queue { - struct netconn *conn; - struct sock_tcp *array; - mutex_t mutex; - unsigned short len; - unsigned short used; + struct netconn *conn; /**< lwIP network connection object */ + struct sock_tcp *array; /**< Allocation array for sock objects to generate */ + mutex_t mutex; /**< Mutex to protect the queue */ + unsigned short len; /**< Length of the struct sock_tcp_queue::array */ + unsigned short used; /**< Used entries in struct sock_tcp_queue::array */ }; /** * @brief UDP sock type + * @warning For network stack internal purposes only. Do not access members + * externally. * @internal */ struct sock_udp { - struct netconn *conn; + struct netconn *conn; /**< lwIP network connection object */ }; #ifdef __cplusplus