From a0e0e9898a7c1abeb4dbf6ba188a9bcaf523e003 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Tue, 27 May 2014 04:44:01 +0200 Subject: More documentation --- Doxyfile.in | 2 +- src/buffer.h | 30 ++++++++++++++++++++++++++---- src/compat.h | 24 ++++++++++++++++-------- src/log.h | 41 ++++++++++++++++++++++++++++++++--------- src/poll.c | 8 ++++++++ src/poll.h | 6 ++++++ 6 files changed, 89 insertions(+), 22 deletions(-) diff --git a/Doxyfile.in b/Doxyfile.in index f813573..2603770 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -1943,7 +1943,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = __attribute__(x)= VECTOR(x):=VECTOR WITH_CAPABILITIES WITH_VERIFY __linux__ +PREDEFINED = __attribute__(x)= VECTOR(x):=VECTOR WITH_CAPABILITIES WITH_VERIFY USE_FREEBIND __linux__ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/src/buffer.h b/src/buffer.h index 489e509..ac1df3d 100644 --- a/src/buffer.h +++ b/src/buffer.h @@ -23,21 +23,36 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file buffer.h + + Buffer management +*/ + #pragma once #include "log.h" +/** A buffer descriptor */ struct fastd_buffer { - void *base; - size_t base_len; + void *base; /**< The beginning of the allocated memory area */ + size_t base_len; /**< The size of the allocated memory area */ - void *data; - size_t len; + void *data; /**< The beginning of the actual data in the buffer */ + size_t len; /**< The data length */ }; +/** + Allocate a new buffer + + A buffer can have head and tail space which allows changing with data size without moving the data. + + The buffer is always allocated aligned to 16 bytes to allow efficient access for SIMD instructions + etc. in crypto implementations +*/ static inline fastd_buffer_t fastd_buffer_alloc(const size_t len, size_t head_space, size_t tail_space) { size_t base_len = head_space+len+tail_space; void *ptr; @@ -48,17 +63,20 @@ static inline fastd_buffer_t fastd_buffer_alloc(const size_t len, size_t head_sp return (fastd_buffer_t){ .base = ptr, .base_len = base_len, .data = ptr+head_space, .len = len }; } +/** Duplicates a buffer */ static inline fastd_buffer_t fastd_buffer_dup(const fastd_buffer_t buffer, size_t head_space, size_t tail_space) { fastd_buffer_t new_buffer = fastd_buffer_alloc(buffer.len, head_space, tail_space); memcpy(new_buffer.data, buffer.data, buffer.len); return new_buffer; } +/** Frees a buffer */ static inline void fastd_buffer_free(fastd_buffer_t buffer) { free(buffer.base); } +/** Pulls the data head (decreases the head space) */ static inline void fastd_buffer_pull_head(fastd_buffer_t *buffer, size_t len) { if (len > (size_t)(buffer->data - buffer->base)) exit_bug("tried to pull buffer across base"); @@ -67,17 +85,20 @@ static inline void fastd_buffer_pull_head(fastd_buffer_t *buffer, size_t len) { buffer->len += len; } +/** Pulls the data head and fills with zeroes */ static inline void fastd_buffer_pull_head_zero(fastd_buffer_t *buffer, size_t len) { fastd_buffer_pull_head(buffer, len); memset(buffer->data, 0, len); } +/** Pulls the data head and copies data into the new space */ static inline void fastd_buffer_pull_head_from(fastd_buffer_t *buffer, const void *data, size_t len) { fastd_buffer_pull_head(buffer, len); memcpy(buffer->data, data, len); } +/** Pushes the buffer head (increases the head space) */ static inline void fastd_buffer_push_head(fastd_buffer_t *buffer, size_t len) { if (buffer->len < len) exit_bug("tried to push buffer across tail"); @@ -86,6 +107,7 @@ static inline void fastd_buffer_push_head(fastd_buffer_t *buffer, size_t len) { buffer->len -= len; } +/** Pushes the buffer head, copying the removed buffer data somewhere else */ static inline void fastd_buffer_push_head_to(fastd_buffer_t *buffer, void *data, size_t len) { memcpy(data, buffer->data, len); fastd_buffer_push_head(buffer, len); diff --git a/src/compat.h b/src/compat.h index e3d9e49..1ab8452 100644 --- a/src/compat.h +++ b/src/compat.h @@ -23,6 +23,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file compat.h + + Portablity definitions +*/ + #pragma once @@ -41,35 +47,37 @@ #include #ifndef ETH_ALEN -#define ETH_ALEN 6 +#define ETH_ALEN 6 /**< The length of a MAC address */ #endif #ifndef ETH_HLEN -#define ETH_HLEN 14 +#define ETH_HLEN 14 /**< The length of the standard ethernet header */ #endif #ifndef HAVE_ETHHDR +/** An ethernet header */ struct ethhdr { - uint8_t h_dest[ETH_ALEN]; - uint8_t h_source[ETH_ALEN]; - uint16_t h_proto; + uint8_t h_dest[ETH_ALEN]; /**< The destination MAC address field */ + uint8_t h_source[ETH_ALEN]; /**< The source MAC address field */ + uint16_t h_proto; /**< The EtherType/length field */ } __attribute__((packed)); #endif #if defined(USE_FREEBIND) && !defined(IP_FREEBIND) -#define IP_FREEBIND 15 +#define IP_FREEBIND 15 /**< Compatiblity define for systems supporting, but not defining IP_FREEBIND */ #endif #ifndef SOCK_NONBLOCK -#define NO_HAVE_SOCK_NONBLOCK -#define SOCK_NONBLOCK 0 +#define NO_HAVE_SOCK_NONBLOCK /**< Defined if SOCK_NONBLOCK doesn't have an effect */ +#define SOCK_NONBLOCK 0 /**< Compatiblity define for systems not supporting SOCK_NONBLOCK */ #endif #ifndef HAVE_GET_CURRENT_DIR_NAME #if defined(__FreeBSD__) || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) +/**< Replacement function for *BSD systems not supporting get_current_dir_name() */ static inline char *get_current_dir_name(void) { return getcwd(NULL, 0); } diff --git a/src/log.h b/src/log.h index b64971e..8cfee16 100644 --- a/src/log.h +++ b/src/log.h @@ -23,6 +23,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file log.h + + Logging functions and macros +*/ + #pragma once @@ -32,35 +38,52 @@ #include +/** A log level specification */ typedef enum fastd_loglevel { - LL_UNSPEC = 0, - LL_FATAL, - LL_ERROR, - LL_WARN, - LL_INFO, - LL_VERBOSE, - LL_DEBUG, - LL_DEBUG2, - LL_DEFAULT = LL_VERBOSE, + LL_UNSPEC = 0, /**< Nothing is logged */ + LL_FATAL, /**< Only fatal errors are logged */ + LL_ERROR, /**< Only errors are logged */ + LL_WARN, /**< Only warning and errors are logged */ + LL_INFO, /**< General informational messages are logged */ + LL_VERBOSE, /**< More verbose logging */ + LL_DEBUG, /**< Debug messages are logged, excluding messages potentially occuring very often */ + LL_DEBUG2, /**< All debug messages a logged */ + LL_DEFAULT = LL_VERBOSE, /**< The default log level */ } fastd_loglevel_t; +/** Logs a formatted string with the specified log level */ void fastd_logf(const fastd_loglevel_t level, const char *format, ...); +/** Logs a formatted fatal error message */ #define pr_fatal(args...) fastd_logf(LL_FATAL, args) +/** Logs a formatted error message */ #define pr_error(args...) fastd_logf(LL_ERROR, args) +/** Logs a formatted warning message */ #define pr_warn(args...) fastd_logf(LL_WARN, args) +/** Logs a formatted informational message */ #define pr_info(args...) fastd_logf(LL_INFO, args) +/** Logs a formatted verbose message */ #define pr_verbose(args...) fastd_logf(LL_VERBOSE, args) +/** Logs a formatted debug message */ #define pr_debug(args...) fastd_logf(LL_DEBUG, args) +/** Logs a formatted debug2 message */ #define pr_debug2(args...) fastd_logf(LL_DEBUG2, args) +/** Logs a simple error message adding the error found in \e errno */ #define pr_error_errno(message) pr_error("%s: %s", message, strerror(errno)) +/** Logs a simple warning message adding the error found in \e errno */ #define pr_warn_errno(message) pr_warn("%s: %s", message, strerror(errno)) +/** Logs a simple debug message adding the error found in \e errno */ #define pr_debug_errno(message) pr_debug("%s: %s", message, strerror(errno)) +/** Logs a simple debug2 message adding the error found in \e errno */ #define pr_debug2_errno(message) pr_debug2("%s: %s", message, strerror(errno)) +/** Logs a formatted fatal error message and aborts the program */ #define exit_fatal(args...) do { pr_fatal(args); abort(); } while(0) +/** Logs a simple fatal error message after a bug was found and aborts the program */ #define exit_bug(message) exit_fatal("BUG: %s", message) +/** Logs a formatted error message and exits with an error status */ #define exit_error(args...) do { pr_error(args); exit(1); } while(0) +/** Logs a simple error message adding the error found in \e errno and exits with an error status */ #define exit_errno(message) exit_error("%s: %s", message, strerror(errno)) diff --git a/src/poll.c b/src/poll.c index ce1a7f4..0a2e11a 100644 --- a/src/poll.c +++ b/src/poll.c @@ -23,6 +23,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file poll.h + + Portable polling API implementations +*/ + #include "poll.h" #include "async.h" @@ -90,6 +96,7 @@ static inline int handshake_timeout(void) { #include +/** Initializes the poll interface */ void fastd_poll_init(void) { ctx.epoll_fd = epoll_create1(0); if (ctx.epoll_fd < 0) @@ -103,6 +110,7 @@ void fastd_poll_init(void) { exit_errno("epoll_ctl"); } +/** Frees the poll interface */ void fastd_poll_free(void) { if (close(ctx.epoll_fd)) pr_warn_errno("closing EPOLL: close"); diff --git a/src/poll.h b/src/poll.h index dcf5d6c..08baa8a 100644 --- a/src/poll.h +++ b/src/poll.h @@ -23,6 +23,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ +/** + \file poll.h + + Portable polling API +*/ + #pragma once -- cgit v1.2.3