api: document common headers

Add comments to utility headers for bit operations, error codes, macros,
network types and string helpers.

Signed-off-by: Robin Jarry <[email protected]>
Reviewed-by: Christophe Fontaine <[email protected]>

Author: rjarry

api/gr_bitops.h

@@ -5,6 +5,7 @@
 
 #include <stdint.h>
 
+// Bit manipulation utilities for flags and bitmasks.
 #define GR_BIT8(n) (UINT8_C(1) << (n))
 #define GR_BIT16(n) (UINT16_C(1) << (n))
 #define GR_BIT32(n) (UINT32_C(1) << (n))

api/gr_clock.h

@@ -6,14 +6,14 @@
 #include <stdint.h>
 #include <time.h>
 
-//! Get the elapsed time since last boot (using a common clock across all processes).
+// Get the elapsed time since last boot (using a common clock across all processes).
 static inline struct timespec gr_clock_raw(void) {
 	struct timespec tp = {0};
 	clock_gettime(CLOCK_MONOTONIC_RAW, &tp);
 	return tp;
 }
 
-//! Get elapsed time since last boot in microseconds.
+// Get elapsed time since last boot in microseconds.
 static inline clock_t gr_clock_us(void) {
 	struct timespec tp = gr_clock_raw();
 	return (tp.tv_sec * CLOCKS_PER_SEC) + (tp.tv_nsec / 1000);

api/gr_errno.h

@@ -6,11 +6,13 @@
 #include <errno.h>
 #include <stddef.h>
 
+// Set errno and return negative error code.
 static inline int errno_set(int errnum) {
 	errno = errnum;
 	return -errnum;
 }
 
+// Set errno and return NULL pointer.
 static inline void *errno_set_null(int errnum) {
 	errno = errnum;
 	return NULL;

api/gr_macro.h

@@ -6,9 +6,16 @@
 #include <errno.h>
 #include <limits.h>
 
+// Get number of elements in a static array.
 #define ARRAY_DIM(array) (sizeof(array) / sizeof(array[0]))
+
+// Get size of a specific member in a struct type.
 #define MEMBER_SIZE(type, member) (sizeof(((type *)0)->member))
+
+// Get pointer to payload data immediately following a header.
 #define PAYLOAD(header) ((void *)(header + 1))
+
+// Get maximum number of values for an unsigned integer type.
 #define UINT_NUM_VALUES(type) (1ULL << (sizeof(type) * CHAR_BIT))
 
 // Define a structure as a base for another one using anonymous tagged structure extension.

api/gr_net_types.h

@@ -22,12 +22,14 @@
 #include <gr_net_compat.h>
 #endif
 
+// Address family enumeration.
 typedef enum : uint8_t {
 	GR_AF_UNSPEC = AF_UNSPEC,
 	GR_AF_IP4 = AF_INET,
 	GR_AF_IP6 = AF_INET6,
 } addr_family_t;
 
+// Convert address family enum to string representation.
 static inline const char *gr_af_name(addr_family_t af) {
 	switch (af) {
 	case GR_AF_UNSPEC:
@@ -40,7 +42,7 @@ static inline const char *gr_af_name(addr_family_t af) {
 	return "?";
 }
 
-// Custom printf specifiers
+// Custom printf specifiers for network addresses.
 
 // struct rte_ether_addr *
 #define ETH_F "%2p"
@@ -61,20 +63,24 @@ static inline const char *gr_af_name(addr_family_t af) {
 #define IPV4_RE "^" __IPV4_RE "$"
 #define IPV4_NET_RE "^" __IPV4_RE __IPV4_PREFIX_RE "$"
 
+// IPv4 address type (network byte order).
 typedef uint32_t ip4_addr_t;
 
+// IPv4 network with prefix length.
 struct ip4_net {
 	ip4_addr_t ip;
 	uint8_t prefixlen;
 };
 
+// Check if two IPv4 addresses are in the same subnet.
 static inline bool ip4_addr_same_subnet(ip4_addr_t a, ip4_addr_t b, uint8_t prefixlen) {
 	ip4_addr_t mask = htonl(~(UINT32_MAX >> prefixlen));
 	return ((a ^ b) & mask) == 0;
 }
 
 #define IPV4_ADDR_BCAST RTE_BE32(0xffffffff)
 
+// Check if the provided IPv4 address is multicast.
 static inline bool ip4_addr_is_mcast(const ip4_addr_t ip) {
 	const union {
 		ip4_addr_t ip;
@@ -83,6 +89,7 @@ static inline bool ip4_addr_is_mcast(const ip4_addr_t ip) {
 	return addr.u8[0] >= 224 && addr.u8[0] <= 239;
 }
 
+// Parse IPv4 network string (e.g. "192.168.1.0/24") into ip4_net structure.
 static inline int ip4_net_parse(const char *s, struct ip4_net *net, bool zero_mask) {
 	char *addr = NULL;
 	int ret = -1;
@@ -115,11 +122,13 @@ static inline int ip4_net_parse(const char *s, struct ip4_net *net, bool zero_ma
 #define IPV6_RE "^" __IPV6_RE "$"
 #define IPV6_NET_RE "^" __IPV6_RE __IPV6_PREFIX_RE "$"
 
+// IPv6 network with prefix length.
 struct ip6_net {
 	struct rte_ipv6_addr ip;
 	uint8_t prefixlen;
 };
 
+// Parse IPv6 network string (e.g. "2001:db8::/32") into ip6_net structure.
 static inline int ip6_net_parse(const char *s, struct ip6_net *net, bool zero_mask) {
 	char *addr = NULL;
 	int ret = -1;

api/gr_string.h

@@ -6,13 +6,17 @@
 #include <sched.h>
 #include <stddef.h>
 
+// Concatenate formatted string to existing buffer (realloc as needed).
 char *astrcat(char *buf, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
+
+// Join array of strings with separator.
 char *strjoin(char **array, size_t len, const char *sep);
+
+// Check if buffer contains only printable characters up to maxlen.
 int charset_check(const char *buf, size_t maxlen);
 
-// Return human readable representation of a cpuset. The output format is
-// a list of CPUs with ranges (for example, "0,1,3-9").
+// Format CPU set as human readable string with ranges (e.g. "0,1,3-9").
 int cpuset_format(char *buf, size_t len, const cpu_set_t *set);
 
-// Parse a list of CPUs (e.g. "0,1,3-9") to a cpu_set_t object.
+// Parse CPU list string (e.g. "0,1,3-9") into a cpu_set_t object.
 int cpuset_parse(cpu_set_t *set, const char *buf);

main/gr_config.h

@@ -22,8 +22,8 @@ struct gr_config {
 	bool log_syslog;
 	bool log_packets;
 	gr_vec char **eal_extra_args;
-	cpu_set_t control_cpus; //!< control plane threads allowed CPUs
-	cpu_set_t datapath_cpus; //!< datapath threads allowed CPUs
+	cpu_set_t control_cpus; // control plane threads allowed CPUs
+	cpu_set_t datapath_cpus; // datapath threads allowed CPUs
 };
 
 extern struct gr_config gr_config;