More documentation

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 <netinet/if_ether.h>
 
 #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 <string.h>
 
 
+/** 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 <sys/epoll.h>
 
 
+/** 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