aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--include/osmocom/core/bits.h11
-rw-r--r--include/osmocom/core/gsmtap.h26
-rw-r--r--include/osmocom/core/gsmtap_util.h4
-rw-r--r--include/osmocom/core/linuxlist.h195
-rw-r--r--include/osmocom/core/logging.h40
-rw-r--r--include/osmocom/core/rate_ctr.h7
-rw-r--r--include/osmocom/core/signal.h6
-rw-r--r--include/osmocom/core/socket.h3
-rw-r--r--include/osmocom/core/utils.h9
-rw-r--r--src/application.c2
-rw-r--r--src/backtrace.c2
-rw-r--r--src/bitcomp.c16
-rw-r--r--src/bits.c1
-rw-r--r--src/bitvec.c51
-rw-r--r--src/crc16.c14
-rw-r--r--src/gsmtap_util.c21
-rw-r--r--src/logging.c57
-rw-r--r--src/macaddr.c27
-rw-r--r--src/msgb.c1
-rw-r--r--src/panic.c25
-rw-r--r--src/prim.c2
-rw-r--r--src/rate_ctr.c23
-rw-r--r--src/select.c6
-rw-r--r--src/signal.c1
-rw-r--r--src/socket.c6
-rw-r--r--src/timer.c2
-rw-r--r--src/write_queue.c2
27 files changed, 374 insertions, 186 deletions
diff --git a/include/osmocom/core/bits.h b/include/osmocom/core/bits.h
index e082313..3218330 100644
--- a/include/osmocom/core/bits.h
+++ b/include/osmocom/core/bits.h
@@ -13,20 +13,19 @@
/*! \file bits.h
* \brief Osmocom bit level support code
+ *
+ * NOTE on the endianess of pbit_t:
+ * Bits in a pbit_t are ordered MSB first, i.e. 0x80 is the first bit.
+ * Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
*/
typedef int8_t sbit_t; /*!< \brief soft bit (-127...127) */
typedef uint8_t ubit_t; /*!< \brief unpacked bit (0 or 1) */
typedef uint8_t pbit_t; /*!< \brief packed bis (8 bits in a byte) */
-/*
- NOTE on the endianess of pbit_t:
- Bits in a pbit_t are ordered MSB first, i.e. 0x80 is the first bit.
- Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
-*/
-
/*! \brief determine how many bytes we would need for \a num_bits packed bits
* \param[in] num_bits Number of packed bits
+ * \returns number of bytes needed for \a num_bits packed bits
*/
static inline unsigned int osmo_pbit_bytesize(unsigned int num_bits)
{
diff --git a/include/osmocom/core/gsmtap.h b/include/osmocom/core/gsmtap.h
index c1ac3ed..c35582e 100644
--- a/include/osmocom/core/gsmtap.h
+++ b/include/osmocom/core/gsmtap.h
@@ -44,6 +44,7 @@
#define GSMTAP_TYPE_UMTS_RRC 0x0c
#define GSMTAP_TYPE_LTE_RRC 0x0d /* LTE interface */
#define GSMTAP_TYPE_LTE_MAC 0x0e /* LTE MAC interface */
+#define GSMTAP_TYPE_LTE_MAC_FRAMED 0x0f /* LTE MAC with context hdr */
/* ====== DO NOT MAKE UNAPPROVED MODIFICATIONS HERE ===== */
@@ -235,21 +236,22 @@ enum {
};
/* ====== DO NOT MAKE UNAPPROVED MODIFICATIONS HERE ===== */
+/*! \brief Structure of the GTMTAP pseudo-header */
struct gsmtap_hdr {
- uint8_t version; /* version, set to 0x01 currently */
- uint8_t hdr_len; /* length in number of 32bit words */
- uint8_t type; /* see GSMTAP_TYPE_* */
- uint8_t timeslot; /* timeslot (0..7 on Um) */
+ uint8_t version; /*!< version, set to 0x01 currently */
+ uint8_t hdr_len; /*!< length in number of 32bit words */
+ uint8_t type; /*!< see GSMTAP_TYPE_* */
+ uint8_t timeslot; /*!< timeslot (0..7 on Um) */
- uint16_t arfcn; /* ARFCN (frequency) */
- int8_t signal_dbm; /* signal level in dBm */
- int8_t snr_db; /* signal/noise ratio in dB */
+ uint16_t arfcn; /*!< ARFCN (frequency) */
+ int8_t signal_dbm; /*!< signal level in dBm */
+ int8_t snr_db; /*!< signal/noise ratio in dB */
- uint32_t frame_number; /* GSM Frame Number (FN) */
+ uint32_t frame_number; /*!< GSM Frame Number (FN) */
- uint8_t sub_type; /* Type of burst/channel, see above */
- uint8_t antenna_nr; /* Antenna Number */
- uint8_t sub_slot; /* sub-slot within timeslot */
- uint8_t res; /* reserved for future use (RFU) */
+ uint8_t sub_type; /*!< Type of burst/channel, see above */
+ uint8_t antenna_nr; /*!< Antenna Number */
+ uint8_t sub_slot; /*!< sub-slot within timeslot */
+ uint8_t res; /*!< reserved for future use (RFU) */
} __attribute__((packed));
diff --git a/include/osmocom/core/gsmtap_util.h b/include/osmocom/core/gsmtap_util.h
index a5c03e7..2e3d068 100644
--- a/include/osmocom/core/gsmtap_util.h
+++ b/include/osmocom/core/gsmtap_util.h
@@ -26,7 +26,9 @@ struct gsmtap_inst {
struct osmo_fd sink_ofd;/*!< \brief file descriptor */
};
-/*! \brief obtain the file descriptor associated with a gsmtap instance */
+/*! \brief obtain the file descriptor associated with a gsmtap instance
+ * \param[in] gti GSMTAP instance
+ * \returns file descriptor of GSMTAP instance */
static inline int gsmtap_inst_fd(struct gsmtap_inst *gti)
{
return gti->wq.bfd.fd;
diff --git a/include/osmocom/core/linuxlist.h b/include/osmocom/core/linuxlist.h
index 01fd261..1c83395 100644
--- a/include/osmocom/core/linuxlist.h
+++ b/include/osmocom/core/linuxlist.h
@@ -1,5 +1,21 @@
#pragma once
+/*! \defgroup linuxlist Simple doubly linked list implementation
+ * @{
+ */
+
+/*!
+ * \file linuxlist.h
+ *
+ * \brief Simple doubly linked list implementation.
+ *
+ * Some of the internal functions ("__xxx") are useful when
+ * manipulating whole llists rather than single entries, as
+ * sometimes we already know the next/prev entries and we can
+ * generate better code by using them directly rather than
+ * using the generic single-entry routines.
+ */
+
#include <stddef.h>
#ifndef inline
@@ -8,20 +24,18 @@
static inline void prefetch(const void *x) {;}
-/**
- * container_of - cast a member of a structure out to the containing structure
- *
- * @ptr: the pointer to the member.
- * @type: the type of the container struct this is embedded in.
- * @member: the name of the member within the struct.
+/*! \brief cast a member of a structure out to the containing structure
*
+ * \param[in] ptr the pointer to the member.
+ * \param[in] type the type of the container struct this is embedded in.
+ * \param[in] member the name of the member within the struct.
*/
#define container_of(ptr, type, member) ({ \
const typeof( ((type *)0)->member ) *__mptr = (ptr); \
(type *)( (char *)__mptr - offsetof(type, member) );})
-/*
+/*!
* These are non-NULL pointers that will result in page faults
* under normal circumstances, used to verify that nobody uses
* non-initialized llist entries.
@@ -29,31 +43,28 @@ static inline void prefetch(const void *x) {;}
#define LLIST_POISON1 ((void *) 0x00100100)
#define LLIST_POISON2 ((void *) 0x00200200)
-/*
- * Simple doubly linked llist implementation.
- *
- * Some of the internal functions ("__xxx") are useful when
- * manipulating whole llists rather than single entries, as
- * sometimes we already know the next/prev entries and we can
- * generate better code by using them directly rather than
- * using the generic single-entry routines.
- */
-
+/*! \brief (double) linked list header structure */
struct llist_head {
+ /*! \brief Pointer to next and previous item */
struct llist_head *next, *prev;
};
#define LLIST_HEAD_INIT(name) { &(name), &(name) }
+/*! \brief define a statically-initialized \ref llist_head
+ * \param[in] name Variable name
+ *
+ * This is a helper macro that will define a named variable of type
+ * \ref llist_head and initialize it */
#define LLIST_HEAD(name) \
struct llist_head name = LLIST_HEAD_INIT(name)
+/*! \brief initialize a \ref llist_head to point back to self */
#define INIT_LLIST_HEAD(ptr) do { \
(ptr)->next = (ptr); (ptr)->prev = (ptr); \
} while (0)
-/*
- * Insert a new entry between two known consecutive entries.
+/*! \brief Insert a new entry between two known consecutive entries.
*
* This is only for internal llist manipulation where we know
* the prev/next entries already!
@@ -68,10 +79,9 @@ static inline void __llist_add(struct llist_head *_new,
prev->next = _new;
}
-/**
- * llist_add - add a new entry
- * @new: new entry to be added
- * @head: llist head to add it after
+/*! \brief add a new entry into a linked list (at head)
+ * \param _new New entry to be added
+ * \param head \ref llist_head to add it after
*
* Insert a new entry after the specified head.
* This is good for implementing stacks.
@@ -81,10 +91,9 @@ static inline void llist_add(struct llist_head *_new, struct llist_head *head)
__llist_add(_new, head, head->next);
}
-/**
- * llist_add_tail - add a new entry
- * @new: new entry to be added
- * @head: llist head to add it before
+/*! \brief add a new entry into a linked list (at tail)
+ * \param _new New entry to be added
+ * \param head Head of linked list to whose tail we shall add \a _new
*
* Insert a new entry before the specified head.
* This is useful for implementing queues.
@@ -107,9 +116,9 @@ static inline void __llist_del(struct llist_head * prev, struct llist_head * nex
prev->next = next;
}
-/**
- * llist_del - deletes entry from llist.
- * @entry: the element to delete from the llist.
+/*! \brief Delete entry from linked list
+ * \param entry The element to delete from the llist
+ *
* Note: llist_empty on entry does not return true after this, the entry is
* in an undefined state.
*/
@@ -120,9 +129,8 @@ static inline void llist_del(struct llist_head *entry)
entry->prev = (struct llist_head *)LLIST_POISON2;
}
-/**
- * llist_del_init - deletes entry from llist and reinitialize it.
- * @entry: the element to delete from the llist.
+/*! \brief Delete entry from linked list and reinitialize it
+ * \param entry The element to delete from the list
*/
static inline void llist_del_init(struct llist_head *entry)
{
@@ -130,10 +138,9 @@ static inline void llist_del_init(struct llist_head *entry)
INIT_LLIST_HEAD(entry);
}
-/**
- * llist_move - delete from one llist and add as another's head
- * @llist: the entry to move
- * @head: the head that will precede our entry
+/*! \brief Delete from one llist and add as another's head
+ * \param llist The entry to move
+ * \param head The head that will precede our entry
*/
static inline void llist_move(struct llist_head *llist, struct llist_head *head)
{
@@ -141,10 +148,9 @@ static inline void llist_move(struct llist_head *llist, struct llist_head *head)
llist_add(llist, head);
}
-/**
- * llist_move_tail - delete from one llist and add as another's tail
- * @llist: the entry to move
- * @head: the head that will follow our entry
+/*! \brief Delete from one llist and add as another's tail
+ * \param llist The entry to move
+ * \param head The head that will follow our entry
*/
static inline void llist_move_tail(struct llist_head *llist,
struct llist_head *head)
@@ -153,9 +159,9 @@ static inline void llist_move_tail(struct llist_head *llist,
llist_add_tail(llist, head);
}
-/**
- * llist_empty - tests whether a llist is empty
- * @head: the llist to test.
+/*! \brief Test whether a linked list is empty
+ * \param[in] head The llist to test.
+ * \returns 1 if the list is empty, 0 otherwise
*/
static inline int llist_empty(const struct llist_head *head)
{
@@ -176,10 +182,9 @@ static inline void __llist_splice(struct llist_head *llist,
at->prev = last;
}
-/**
- * llist_splice - join two llists
- * @llist: the new llist to add.
- * @head: the place to add it in the first llist.
+/*! \brief Join two llists
+ * \param llist The new linked list to add
+ * \param head The place to add \a llist in the other list
*/
static inline void llist_splice(struct llist_head *llist, struct llist_head *head)
{
@@ -187,10 +192,9 @@ static inline void llist_splice(struct llist_head *llist, struct llist_head *hea
__llist_splice(llist, head);
}
-/**
- * llist_splice_init - join two llists and reinitialise the emptied llist.
- * @llist: the new llist to add.
- * @head: the place to add it in the first llist.
+/*! \brief join two llists and reinitialise the emptied llist.
+ * \param llist The new linked list to add.
+ * \param head The place to add it in the first llist.
*
* The llist at @llist is reinitialised
*/
@@ -203,28 +207,25 @@ static inline void llist_splice_init(struct llist_head *llist,
}
}
-/**
- * llist_entry - get the struct for this entry
- * @ptr: the &struct llist_head pointer.
- * @type: the type of the struct this is embedded in.
- * @member: the name of the llist_struct within the struct.
+/*! \brief Get the struct containing this list entry
+ * \param ptr The \ref llist_head pointer
+ * \param type The type of the struct this is embedded in
+ * \param @member The name of the \ref llist_head within the struct
*/
#define llist_entry(ptr, type, member) \
container_of(ptr, type, member)
-/**
- * llist_for_each - iterate over a llist
- * @pos: the &struct llist_head to use as a loop counter.
- * @head: the head for your llist.
+/*! \brief Iterate over a linked list
+ * \param pos The \ref llist_head to use as a loop counter
+ * \param head The head of the list over which to iterate
*/
#define llist_for_each(pos, head) \
for (pos = (head)->next, prefetch(pos->next); pos != (head); \
pos = pos->next, prefetch(pos->next))
-/**
- * __llist_for_each - iterate over a llist
- * @pos: the &struct llist_head to use as a loop counter.
- * @head: the head for your llist.
+/*! \brief Iterate over a llist (no prefetch)
+ * \param pos The \ref llist_head to use as a loop counter
+ * \param head The head of the list over which to iterate
*
* This variant differs from llist_for_each() in that it's the
* simplest possible llist iteration code, no prefetching is done.
@@ -234,30 +235,27 @@ static inline void llist_splice_init(struct llist_head *llist,
#define __llist_for_each(pos, head) \
for (pos = (head)->next; pos != (head); pos = pos->next)
-/**
- * llist_for_each_prev - iterate over a llist backwards
- * @pos: the &struct llist_head to use as a loop counter.
- * @head: the head for your llist.
+/*! \brief Iterate over a llist backwards
+ * \param pos The \ref llist_head to use as a loop counter
+ * \param head The head of the list over which to iterate
*/
#define llist_for_each_prev(pos, head) \
for (pos = (head)->prev, prefetch(pos->prev); pos != (head); \
pos = pos->prev, prefetch(pos->prev))
-
-/**
- * llist_for_each_safe - iterate over a llist safe against removal of llist entry
- * @pos: the &struct llist_head to use as a loop counter.
- * @n: another &struct llist_head to use as temporary storage
- * @head: the head for your llist.
+
+/*! \brief Iterate over a list; safe against removal of llist entry
+ * \param pos The \ref llist_head to use as a loop counter
+ * \param n Another \ref llist_head to use as temporary storage
+ * \param head The head of the list over which to iterate
*/
#define llist_for_each_safe(pos, n, head) \
for (pos = (head)->next, n = pos->next; pos != (head); \
pos = n, n = pos->next)
-/**
- * llist_for_each_entry - iterate over llist of given type
- * @pos: the type * to use as a loop counter.
- * @head: the head for your llist.
- * @member: the name of the llist_struct within the struct.
+/*! \brief Iterate over llist of given type
+ * \param pos The 'type *' to use as a loop counter
+ * \param head The head of the list over which to iterate
+ * \param member The name of the \ref llist_head within struct \a pos
*/
#define llist_for_each_entry(pos, head, member) \
for (pos = llist_entry((head)->next, typeof(*pos), member), \
@@ -266,11 +264,10 @@ static inline void llist_splice_init(struct llist_head *llist,
pos = llist_entry(pos->member.next, typeof(*pos), member), \
prefetch(pos->member.next))
-/**
- * llist_for_each_entry_reverse - iterate backwards over llist of given type.
- * @pos: the type * to use as a loop counter.
- * @head: the head for your llist.
- * @member: the name of the llist_struct within the struct.
+/*! \brief Iterate backwards over llist of given type.
+ * \param pos The 'type *' to use as a loop counter
+ * \param head The head of the list over which to iterate
+ * \param member The name of the \ref llist_head within struct \a pos
*/
#define llist_for_each_entry_reverse(pos, head, member) \
for (pos = llist_entry((head)->prev, typeof(*pos), member), \
@@ -279,12 +276,11 @@ static inline void llist_splice_init(struct llist_head *llist,
pos = llist_entry(pos->member.prev, typeof(*pos), member), \
prefetch(pos->member.prev))
-/**
- * llist_for_each_entry_continue - iterate over llist of given type
- * continuing after existing point
- * @pos: the type * to use as a loop counter.
- * @head: the head for your llist.
- * @member: the name of the llist_struct within the struct.
+/*! \brief iterate over llist of given type continuing after existing
+ * point
+ * \param pos The 'type *' to use as a loop counter
+ * \param head The head of the list over which to iterate
+ * \param member The name of the \ref llist_head within struct \a pos
*/
#define llist_for_each_entry_continue(pos, head, member) \
for (pos = llist_entry(pos->member.next, typeof(*pos), member), \
@@ -293,13 +289,12 @@ static inline void llist_splice_init(struct llist_head *llist,
pos = llist_entry(pos->member.next, typeof(*pos), member), \
prefetch(pos->member.next))
-/**
- * llist_for_each_entry_safe - iterate over llist of given type, safe against
- * removal of non-consecutive(!) llist entries
- * @pos: the type * to use as a loop counter.
- * @n: another type * to use as temporary storage
- * @head: the head for your llist.
- * @member: the name of the llist_struct within the struct.
+/*! \brief iterate over llist of given type, safe against removal of
+ * non-consecutive(!) llist entries
+ * \param pos The 'type *' to use as a loop counter
+ * \param n Another type * to use as temporary storage
+ * \param head The head of the list over which to iterate
+ * \param member The name of the \ref llist_head within struct \a pos
*/
#define llist_for_each_entry_safe(pos, n, head, member) \
for (pos = llist_entry((head)->next, typeof(*pos), member), \
@@ -355,3 +350,7 @@ static inline void llist_splice_init(struct llist_head *llist,
#define llist_for_each_continue_rcu(pos, head) \
for ((pos) = (pos)->next, prefetch((pos)->next); (pos) != (head); \
(pos) = (pos)->next, ({ smp_read_barrier_depends(); 0;}), prefetch((pos)->next))
+
+/*!
+ * }@
+ */
diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h
index 3193411..4b79c05 100644
--- a/include/osmocom/core/logging.h
+++ b/include/osmocom/core/logging.h
@@ -19,6 +19,11 @@
#define DEBUG
#ifdef DEBUG
+/*! \brief Log a debug message through the Osmocom logging framework
+ * \param[in] ss logging subsystem (e.g. \ref DLGLOBAL)
+ * \param[in] fmt format string
+ * \param[in] args variable argument list
+ */
#define DEBUGP(ss, fmt, args...) \
do { \
if (log_check_level(ss, LOGL_DEBUG)) \
@@ -68,7 +73,7 @@ void logp(int subsys, const char *file, int line, int cont, const char *format,
/*! \brief different log levels */
#define LOGL_DEBUG 1 /*!< \brief debugging information */
-#define LOGL_INFO 3
+#define LOGL_INFO 3 /*!< \brief general information */
#define LOGL_NOTICE 5 /*!< \brief abnormal/unexpected condition */
#define LOGL_ERROR 7 /*!< \brief error condition, requires user action */
#define LOGL_FATAL 8 /*!< \brief fatal, program aborted */
@@ -76,21 +81,22 @@ void logp(int subsys, const char *file, int line, int cont, const char *format,
#define LOG_FILTER_ALL 0x0001
/* logging levels defined by the library itself */
-#define DLGLOBAL -1
-#define DLLAPD -2
-#define DLINP -3
-#define DLMUX -4
-#define DLMI -5
-#define DLMIB -6
-#define DLSMS -7
-#define DLCTRL -8
-#define DLGTP -9
-#define DLSTATS -10
-#define OSMO_NUM_DLIB 10
-
+#define DLGLOBAL -1 /*!< global logging */
+#define DLLAPD -2 /*!< LAPD implementation */
+#define DLINP -3 /*!< (A-bis) Input sub-system */
+#define DLMUX -4 /*!< Osmocom Multiplex (Osmux) */
+#define DLMI -5 /*!< ISDN-layer below input sub-system */
+#define DLMIB -6 /*!< ISDN layer B-channel */
+#define DLSMS -7 /*!< SMS sub-system */
+#define DLCTRL -8 /*!< Control Interface */
+#define DLGTP -9 /*!< GTP (GPRS Tunneling Protocol */
+#define DLSTATS -10 /*!< Statistics */
+#define OSMO_NUM_DLIB 10 /*!< Number of logging sub-systems in libraries */
+
+/*! Configuration of singgle log category / sub-system */
struct log_category {
- uint8_t loglevel;
- uint8_t enabled;
+ uint8_t loglevel; /*!< configured log-level */
+ uint8_t enabled; /*!< is logging enabled? */
};
/*! \brief Information regarding one logging category */
@@ -136,9 +142,9 @@ struct log_info {
/*! \brief total number of user categories (not library) */
unsigned int num_cat_user;
- /* \brief filter saving function */
+ /*! \brief filter saving function */
log_save_filters *save_fn;
- /* \brief filter saving function */
+ /*! \brief filter saving function */
log_print_filters *print_fn;
};
diff --git a/include/osmocom/core/rate_ctr.h b/include/osmocom/core/rate_ctr.h
index cdde353..ebaa7a7 100644
--- a/include/osmocom/core/rate_ctr.h
+++ b/include/osmocom/core/rate_ctr.h
@@ -78,10 +78,13 @@ static inline void rate_ctr_group_upd_idx(struct rate_ctr_group *grp, unsigned i
void rate_ctr_group_free(struct rate_ctr_group *grp);
-/*! \brief Increment the counter by \a inc */
+/*! \brief Increment the counter by \a inc
+ * \param ctr \ref rate_ctr to increment
+ * \param inc quantity to increment \a ctr by */
void rate_ctr_add(struct rate_ctr *ctr, int inc);
-/*! \brief Increment the counter by 1 */
+/*! \brief Increment the counter by 1
+ * \param ctr \ref rate_ctr to increment */
static inline void rate_ctr_inc(struct rate_ctr *ctr)
{
rate_ctr_add(ctr, 1);
diff --git a/include/osmocom/core/signal.h b/include/osmocom/core/signal.h
index 6f56496..5ed4e15 100644
--- a/include/osmocom/core/signal.h
+++ b/include/osmocom/core/signal.h
@@ -7,9 +7,9 @@
*/
/*! \file signal.h */
-/* subsystem signaling numbers: we split the numberspace for applications and
- * libraries: from 0 to UINT_MAX/2 for applications, from UINT_MAX/2 to
- * UINT_MAX for libraries. */
+/*! subsystem signaling numbers: we split the numberspace for
+ * applications and libraries: from 0 to UINT_MAX/2 for applications,
+ * from UINT_MAX/2 to UINT_MAX for libraries. */
#define OSMO_SIGNAL_SS_APPS 0
#define OSMO_SIGNAL_SS_RESERVED 2147483648u
diff --git a/include/osmocom/core/socket.h b/include/osmocom/core/socket.h
index 1df28c9..6ef0912 100644
--- a/include/osmocom/core/socket.h
+++ b/include/osmocom/core/socket.h
@@ -14,8 +14,11 @@ struct sockaddr;
struct osmo_fd;
/* flags for osmo_sock_init. */
+/*! connect the socket to a remote peer */
#define OSMO_SOCK_F_CONNECT (1 << 0)
+/*! bind the socket to a local address/port */
#define OSMO_SOCK_F_BIND (1 << 1)
+/*! switch socket to non-blocking mode */
#define OSMO_SOCK_F_NONBLOCK (1 << 2)
int osmo_sock_init(uint16_t family, uint16_t type, uint8_t proto,
diff --git a/include/osmocom/core/utils.h b/include/osmocom/core/utils.h
index 205fa28..27e1e18 100644
--- a/include/osmocom/core/utils.h
+++ b/include/osmocom/core/utils.h
@@ -53,6 +53,11 @@ do { \
rem -= ret; \
} while (0)
+/*! Helper macro to terminate when an assertion failes
+ * \param[in] exp Predicate to verify
+ * This function will generate a backtrace and terminate the program if
+ * the predicate evaluates to false (0).
+ */
#define OSMO_ASSERT(exp) \
if (!(exp)) { \
fprintf(stderr, "Assert failed %s %s:%d\n", #exp, __FILE__, __LINE__); \
@@ -60,6 +65,10 @@ do { \
abort(); \
}
+/*! duplicate a string using talloc and release its prior content (if any)
+ * \param[in] ctx Talloc context to use for allocation
+ * \param[out] dst pointer to string, will be updated with ptr to new string
+ * \param[in] newstr String that will be copieed to newly allocated string */
static inline void osmo_talloc_replace_string(void *ctx, char **dst, char *newstr)
{
if (*dst)
diff --git a/src/application.c b/src/application.c
index 9c3fe52..8a325c8 100644
--- a/src/application.c
+++ b/src/application.c
@@ -40,7 +40,7 @@
* a multi-threaded context, you have to add your own locking.
*
* \section sec_copyright Copyright and License
- * Copyright © 2008-2011 - Harald Welte, Holger Freyther and contributors\n
+ * Copyright © 2008-2016 - Harald Welte, Holger Freyther and contributors\n
* All rights reserved. \n\n
* The source code of libosmocore is licensed under the terms of the GNU
* General Public License as published by the Free Software Foundation;
diff --git a/src/backtrace.c b/src/backtrace.c
index 5b93bec..6cd798c 100644
--- a/src/backtrace.c
+++ b/src/backtrace.c
@@ -70,6 +70,8 @@ void osmo_generate_backtrace(void)
}
/*! \brief Generate and log a call back-trace
+ * \param[in] subsys Logging sub-system
+ * \param[in] level Logging level
*
* This function will generate a function call back-trace of the
* current process and log it to the specified subsystem and
diff --git a/src/bitcomp.c b/src/bitcomp.c
index bf35927..8b3090e 100644
--- a/src/bitcomp.c
+++ b/src/bitcomp.c
@@ -232,9 +232,9 @@ static const unsigned t4_make_up[2][15] = {
/*! \brief Attempt to decode compressed bit vector
*
- * Return length of RLE according to modified ITU-T T.4 from TS 44.060 Table 9.1.10.2
- * or -1 if no applicable RLE found
- * N. B: we need explicit bit length to make decoding unambiguous
+ * \return length of RLE according to modified ITU-T T.4 from TS 44.060
+ * Table 9.1.10.2 or -1 if no applicable RLE found N. B: we need
+ * explicit bit length to make decoding unambiguous
*/
static inline int t4_rle_term(unsigned w, bool b, unsigned bits)
{
@@ -256,8 +256,9 @@ static inline int t4_rle_makeup(unsigned w, bool b, unsigned bits)
/*! \brief Make-up codes for a given length
*
- * Return proper make-up code word for an uninterrupted sequence of b bits
- * of length len according to modified ITU-T T.4 from TS 44.060 Table 9.1.10.2 */
+ * \return Return proper make-up code word for an uninterrupted
+ * sequence of b bits of length len according to modified ITU-T T.4
+ * from TS 44.060 Table 9.1.10.2 */
static inline int t4_rle(struct bitvec *bv, unsigned len, bool b)
{
if (len >= 960) {
@@ -384,7 +385,7 @@ static inline enum dec_state _t4_step(struct bitvec *v, uint16_t w, bool b, unsi
* \param[in] in bit vector with encoded data
* \param[in] cc color code (whether decoding should start with 1 or 0)
* \param[out] out the bit vector to store result into
- * returns 0 on success, negative value otherwise
+ * \return 0 on success, negative value otherwise
*/
int osmo_t4_decode(const struct bitvec *in, bool cc, struct bitvec *out)
{
@@ -437,7 +438,8 @@ int osmo_t4_decode(const struct bitvec *in, bool cc, struct bitvec *out)
/*! \brief encode bit vector in-place using T4 encoding
* Assumes MSB first encoding.
* \param[in] bv bit vector to be encoded
- * returns color code (if the encoding started with 0 or 1) or -1 on failure (encoded is bigger than original)
+ * \return color code (if the encoding started with 0 or 1) or -1 on
+ * failure (encoded is bigger than original)
*/
int osmo_t4_encode(struct bitvec *bv)
{
diff --git a/src/bits.c b/src/bits.c
index 48314af..569a10f 100644
--- a/src/bits.c
+++ b/src/bits.c
@@ -89,6 +89,7 @@ void osmo_sbit2ubit(ubit_t *out, const sbit_t *in, unsigned int num_bits)
* \param[out] out output buffer of unpacked bits
* \param[in] in input buffer of packed bits
* \param[in] num_bits number of bits
+ * \return number of bytes used in \ref out
*/
int osmo_pbit2ubit(ubit_t *out, const pbit_t *in, unsigned int num_bits)
{
diff --git a/src/bitvec.c b/src/bitvec.c
index a92fd71..88343c4 100644
--- a/src/bitvec.c
+++ b/src/bitvec.c
@@ -75,7 +75,7 @@ static uint8_t bitval2mask(enum bit_value bit, uint8_t bitnum)
/*! \brief check if the bit is 0 or 1 for a given position inside a bitvec
* \param[in] bv the bit vector on which to check
* \param[in] bitnr the bit number inside the bit vector to check
- * \returns
+ * \return value of the requested bit
*/
enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr)
{
@@ -97,6 +97,7 @@ enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr)
/*! \brief check if the bit is L or H for a given position inside a bitvec
* \param[in] bv the bit vector on which to check
* \param[in] bitnr the bit number inside the bit vector to check
+ * \return value of the requested bit
*/
enum bit_value bitvec_get_bit_pos_high(const struct bitvec *bv,
unsigned int bitnr)
@@ -179,7 +180,8 @@ int bitvec_set_bit(struct bitvec *bv, enum bit_value bit)
return rc;
}
-/*! \brief get the next bit (low/high) inside a bitvec */
+/*! \brief get the next bit (low/high) inside a bitvec
+ * \return value of th next bit in the vector */
int bitvec_get_bit_high(struct bitvec *bv)
{
int rc;
@@ -195,7 +197,7 @@ int bitvec_get_bit_high(struct bitvec *bv)
* \param[in] bv bit vector
* \param[in] bits array of \ref bit_value
* \param[in] count number of bits to set
- */
+ * \return 0 on success; negative in case of error */
int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, unsigned int count)
{
int i, rc;
@@ -209,7 +211,8 @@ int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, unsigned int count)
return 0;
}
-/*! \brief set multiple bits (based on numeric value) at current pos */
+/*! \brief set multiple bits (based on numeric value) at current pos
+ * \return 0 in case of success; negative in case of error */
int bitvec_set_uint(struct bitvec *bv, unsigned int ui, unsigned int num_bits)
{
int rc;
@@ -226,7 +229,8 @@ int bitvec_set_uint(struct bitvec *bv, unsigned int ui, unsigned int num_bits)
return 0;
}
-/*! \brief get multiple bits (num_bits) from beginning of vector (MSB side) */
+/*! \brief get multiple bits (num_bits) from beginning of vector (MSB side)
+ * \return 16bit signed integer retrieved from bit vector */
int16_t bitvec_get_int16_msb(const struct bitvec *bv, unsigned int num_bits)
{
if (num_bits > 15 || bv->cur_bit < num_bits)
@@ -238,7 +242,8 @@ int16_t bitvec_get_int16_msb(const struct bitvec *bv, unsigned int num_bits)
return osmo_load16be(bv->data) >> (16 - num_bits);
}
-/*! \brief get multiple bits (based on numeric value) from current pos */
+/*! \brief get multiple bits (based on numeric value) from current pos
+ * \return integer value retrieved from bit vector */
int bitvec_get_uint(struct bitvec *bv, unsigned int num_bits)
{
int i;
@@ -257,7 +262,7 @@ int bitvec_get_uint(struct bitvec *bv, unsigned int num_bits)
}
/*! \brief fill num_bits with \fill starting from the current position
- * returns 0 on success, negative otherwise (out of vector boundary)
+ * \return 0 on success; negative otherwise (out of vector boundary)
*/
int bitvec_fill(struct bitvec *bv, unsigned int num_bits, enum bit_value fill)
{
@@ -269,7 +274,8 @@ int bitvec_fill(struct bitvec *bv, unsigned int num_bits, enum bit_value fill)
return 0;
}
-/*! \brief pad all remaining bits up to num_bits */
+/*! \brief pad all remaining bits up to num_bits
+ * \return 0 on success; negative otherwise */
int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit)
{
int n = up_to_bit - bv->cur_bit + 1;
@@ -279,7 +285,8 @@ int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit)
return bitvec_fill(bv, n, L);
}
-/*! \brief find first bit set in bit vector */
+/*! \brief find first bit set in bit vector
+ * \return 0 on success; negative otherwise */
int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n,
enum bit_value val)
{
@@ -298,6 +305,7 @@ int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n,
* \param[in] bv bit vector
* \param[in] bytes array
* \param[in] count number of bytes to copy
+ * \return 0 on success; negative otherwise
*/
int bitvec_get_bytes(struct bitvec *bv, uint8_t *bytes, unsigned int count)
{
@@ -333,6 +341,7 @@ int bitvec_get_bytes(struct bitvec *bv, uint8_t *bytes, unsigned int count)
* \param[in] bv bit vector
* \param[in] bytes array
* \param[in] count number of bytes to copy
+ * \return 0 on success; negative otherwise
*/
int bitvec_set_bytes(struct bitvec *bv, const uint8_t *bytes, unsigned int count)
{
@@ -367,6 +376,10 @@ int bitvec_set_bytes(struct bitvec *bv, const uint8_t *bytes, unsigned int count
return 0;
}
+/*! \brief Allocate a bit vector
+ * \param[in] size Number of bits in the vector
+ * \param[in] ctx Context from which to allocate
+ * \return pointer to allocated vector; NULL in case of error */
struct bitvec *bitvec_alloc(unsigned int size, TALLOC_CTX *ctx)
{
struct bitvec *bv = talloc_zero(ctx, struct bitvec);
@@ -384,12 +397,18 @@ struct bitvec *bitvec_alloc(unsigned int size, TALLOC_CTX *ctx)
return bv;
}
+/*! \brief Free a bit vector (release its memory)
+ * \param[in] bit vector to free */
void bitvec_free(struct bitvec *bv)
{
talloc_free(bv->data);
talloc_free(bv);
}
+/*! \brief Export a bit vector to a buffer
+ * \param[in] bitvec (unpacked bits)
+ * \param[out] buffer for the unpacked bits
+ * \return number of bytes (= bits) copied */
unsigned int bitvec_pack(const struct bitvec *bv, uint8_t *buffer)
{
unsigned int i = 0;
@@ -399,6 +418,10 @@ unsigned int bitvec_pack(const struct bitvec *bv, uint8_t *buffer)
return i;
}
+/*! \brief Copy buffer of unpacked bits into bit vector
+ * \param[in] buffer unpacked input bits
+ * \param[out] bv unpacked bit vector
+ * \return number of bytes (= bits) copied */
unsigned int bitvec_unpack(struct bitvec *bv, const uint8_t *buffer)
{
unsigned int i = 0;
@@ -408,7 +431,11 @@ unsigned int bitvec_unpack(struct bitvec *bv, const uint8_t *buffer)
return i;
}
-
+/*! \brief read hexadecimap string into a bit vector
+ * \param[in] src string containing hex digits
+ * \param[out] bv unpacked bit vector
+ * \return 0 in case of success; 1 in case of error
+ */
int bitvec_unhex(struct bitvec *bv, const char *src)
{
unsigned i;
@@ -472,7 +499,9 @@ int bitvec_write_field(struct bitvec *bv, unsigned int *write_index, uint64_t va
return 0;
}
-/*! \brief convert enum to corresponding character */
+/*! \brief convert enum to corresponding character
+ * \param v input value (bit)
+ * \return single character, either 0, 1, L or H */
char bit_value_to_char(enum bit_value v)
{
switch (v) {
diff --git a/src/crc16.c b/src/crc16.c
index 2741cf5..9dd4672 100644
--- a/src/crc16.c
+++ b/src/crc16.c
@@ -10,7 +10,7 @@
#include <osmocom/core/crc16.h>
-/** CRC table for the CRC-16. The poly is 0x8005 (x^16 + x^15 + x^2 + 1) */
+/*! \brief CRC table for the CRC-16. The poly is 0x8005 (x^16 + x^15 + x^2 + 1) */
uint16_t const osmo_crc16_table[256] = {
0x0000, 0xC0C1, 0xC181, 0x0140, 0xC301, 0x03C0, 0x0280, 0xC241,
0xC601, 0x06C0, 0x0780, 0xC741, 0x0500, 0xC5C1, 0xC481, 0x0440,
@@ -46,13 +46,11 @@ uint16_t const osmo_crc16_table[256] = {
0x8201, 0x42C0, 0x4380, 0x8341, 0x4100, 0x81C1, 0x8081, 0x4040
};
-/**
- * crc16 - compute the CRC-16 for the data buffer
- * @crc: previous CRC value
- * @buffer: data pointer
- * @len: number of bytes in the buffer
- *
- * Returns the updated CRC value.
+/*! \brief compute the CRC-16 for the data buffer
+ * \param crc[in] previous CRC value
+ * \param buffer[in] data pointer
+ * \param len[in] number of bytes in input \ref buffer
+ * \return updated CRC value
*/
uint16_t osmo_crc16(uint16_t crc, uint8_t const *buffer, size_t len)
{
diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c
index 82690a9..7a63771 100644
--- a/src/gsmtap_util.c
+++ b/src/gsmtap_util.c
@@ -99,6 +99,7 @@ uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t link_id)
* \param[in] snr Signal/Noise Ratio (SNR)
* \param[in] data Pointer to data buffer
* \param[in] len Length of \ref data
+ * \return dynamically allocated message buffer containing data
*
* This function will allocate a new msgb and fill it with a GSMTAP
* header containing the information
@@ -145,6 +146,7 @@ struct msgb *gsmtap_makemsg_ex(uint8_t type, uint16_t arfcn, uint8_t ts, uint8_t
* \param[in] snr Signal/Noise Ratio (SNR)
* \param[in] data Pointer to data buffer
* \param[in] len Length of \ref data
+ * \return message buffer or NULL in case of error
*
* This function will allocate a new msgb and fill it with a GSMTAP
* header containing the information
@@ -165,6 +167,7 @@ struct msgb *gsmtap_makemsg(uint16_t arfcn, uint8_t ts, uint8_t chan_type,
/*! \brief Create a new (sending) GSMTAP source socket
* \param[in] host host name or IP address in string format
* \param[in] port UDP port number in host byte order
+ * \return file descriptor of the new socket
*
* Opens a GSMTAP source (sending) socket, conncet it to host/port and
* return resulting fd. If \a host is NULL, the destination address
@@ -217,6 +220,7 @@ int gsmtap_source_add_sink_fd(int gsmtap_fd)
/*! \brief Send a \ref msgb through a GSMTAP source
* \param[in] gti GSMTAP instance
* \param[in] msg message buffer
+ * \return 0 in case of success; negative in case of error
*/
int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg)
{
@@ -312,7 +316,21 @@ static int gsmtap_sink_fd_cb(struct osmo_fd *fd, unsigned int flags)
return 0;
}
-/*! \brief Add a local sink to an existing GSMTAP source instance */
+/*! \brief Add a local sink to an existing GSMTAP source and return fd
+ * \param[in] gsmtap_fd file descriptor of the gsmtap socket
+ * \returns file descriptor of locally bound receive socket
+ *
+ * In case the GSMTAP socket is connected to a local destination
+ * IP/port, this function creates a corresponding receiving socket
+ * bound to that destination IP + port.
+ *
+ * In case the gsmtap socket is not connected to a local IP/port, or
+ * creation of the receiving socket fails, a negative error code is
+ * returned.
+ *
+ * The file descriptor of the receiving socket is automatically added
+ * to the libosmocore select() handling.
+ */
int gsmtap_source_add_sink(struct gsmtap_inst *gti)
{
int fd;
@@ -340,6 +358,7 @@ int gsmtap_source_add_sink(struct gsmtap_inst *gti)
* \param[in] host host name or IP address in string format
* \param[in] port UDP port number in host byte order
* \param[in] ofd_wq_mode Register \ref osmo_wqueue (1) or not (0)
+ * \return callee-allocated \ref gsmtap_inst
*
* Open GSMTAP source (sending) socket, connect it to host/port,
* allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue
diff --git a/src/logging.c b/src/logging.c
index 4d6fd40..b2f8d43 100644
--- a/src/logging.c
+++ b/src/logging.c
@@ -142,13 +142,19 @@ static int subsys_lib2index(int subsys)
return (subsys * -1) + (osmo_log_info->num_cat_user-1);
}
-/*! \brief Parse a human-readable log level into a numeric value */
+/*! \brief Parse a human-readable log level into a numeric value
+ * \param lvl[in] zero-terminated string containing log level name
+ * \returns numeric log level
+ */
int log_parse_level(const char *lvl)
{
return get_string_value(loglevel_strs, lvl);
}
-/*! \brief convert a numeric log level into human-readable string */
+/*! \brief convert a numeric log level into human-readable string
+ * \param lvl[in] numeric log level
+ * \returns zero-terminated string (log level name)
+ */
const char *log_level_str(unsigned int lvl)
{
return get_value_string(loglevel_strs, lvl);
@@ -353,7 +359,14 @@ static inline int check_log_to_target(struct log_target *tar, int subsys, int le
return 1;
}
-/*! \brief vararg version of logging function */
+/*! \brief vararg version of logging function
+ * \param[in] subsys Logging sub-system
+ * \param[in] level Log level
+ * \param[in] file name of source code file
+ * \param[in] cont continuation (1) or new line (0)
+ * \param[in] format format string
+ * \param[in] ap vararg-list containing format string arguments
+ */
void osmo_vlogp(int subsys, int level, const char *file, int line,
int cont, const char *format, va_list ap)
{
@@ -376,7 +389,12 @@ void osmo_vlogp(int subsys, int level, const char *file, int line,
}
}
-/*! \brief logging function used by DEBUGP() macro */
+/*! \brief logging function used by DEBUGP() macro
+ * \param[in] subsys Logging sub-system
+ * \param[in] file name of source code file
+ * \param[in] cont continuation (1) or new line (0)
+ * \param[in] format format string
+ */
void logp(int subsys, const char *file, int line, int cont,
const char *format, ...)
{
@@ -387,7 +405,13 @@ void logp(int subsys, const char *file, int line, int cont,
va_end(ap);
}
-/*! \brief logging function used by LOGP() macro */
+/*! \brief logging function used by LOGP() macro
+ * \param[in] subsys Logging sub-system
+ * \param[in] level Log level
+ * \param[in] file name of source code file
+ * \param[in] cont continuation (1) or new line (0)
+ * \param[in] format format string
+ */
void logp2(int subsys, unsigned int level, const char *file, int line, int cont, const char *format, ...)
{
va_list ap;
@@ -422,6 +446,7 @@ void log_reset_context(void)
/*! \brief Set the logging context
* \param[in] ctx_nr logging context number
* \param[in] value value to which the context is to be set
+ * \returns 0 in case of success; negative otherwise
*
* A logging context is something like the subscriber identity to which
* the currently processed message relates, or the BTS through which it
@@ -537,7 +562,12 @@ static void _file_output(struct log_target *target, unsigned int level,
fflush(target->tgt_file.out);
}
-/*! \brief Create a new log target skeleton */
+/*! \brief Create a new log target skeleton
+ * \returns dynamically-allocated log target
+ * This funcition allocates a \ref log_target and initializes it
+ * with some default values. The newly created target is not
+ * registered yet.
+ */
struct log_target *log_target_create(void)
{
struct log_target *target;
@@ -574,7 +604,8 @@ struct log_target *log_target_create(void)
return target;
}
-/*! \brief Create the STDERR log target */
+/*! \brief Create the STDERR log target
+ * \returns dynamically-allocated \ref log_target for STDERR */
struct log_target *log_target_create_stderr(void)
{
/* since C89/C99 says stderr is a macro, we can safely do this! */
@@ -639,7 +670,8 @@ struct log_target *log_target_find(int type, const char *fname)
return NULL;
}
-/*! \brief Unregister, close and delete a log target */
+/*! \brief Unregister, close and delete a log target
+ * \param target[in] log target to unregister, close and delete */
void log_target_destroy(struct log_target *target)
{
@@ -661,7 +693,9 @@ void log_target_destroy(struct log_target *target)
talloc_free(target);
}
-/*! \brief close and re-open a log file (for log file rotation) */
+/*! \brief close and re-open a log file (for log file rotation)
+ * \param[in] target log target to re-open
+ * \returns 0 in case of success; negative otherwise */
int log_target_file_reopen(struct log_target *target)
{
fclose(target->tgt_file.out);
@@ -675,7 +709,8 @@ int log_target_file_reopen(struct log_target *target)
return 0;
}
-/*! \brief close and re-open a log file (for log file rotation) */
+/*! \brief close and re-open all log files (for log file rotation)
+ * \returns 0 in case of success; negative otherwise */
int log_targets_reopen(void)
{
struct log_target *tar;
@@ -697,6 +732,7 @@ int log_targets_reopen(void)
/*! \brief Generates the logging command string for VTY
* \param[in] unused_info Deprecated parameter, no longer used!
+ * \returns vty command string for use by VTY command node
*/
const char *log_vty_command_string(const struct log_info *unused_info)
{
@@ -774,6 +810,7 @@ err:
/*! \brief Generates the logging command description for VTY
* \param[in] unused_info Deprecated parameter, no longer used!
+ * \returns logging command description for use by VTY command node
*/
const char *log_vty_command_description(const struct log_info *unused_info)
{
diff --git a/src/macaddr.c b/src/macaddr.c
index a6e1304..f83e054 100644
--- a/src/macaddr.c
+++ b/src/macaddr.c
@@ -20,12 +20,24 @@
*
*/
+/*! \addtogroup utils
+ * @{
+ */
+
+/*! \file loggingrb.c */
+
#include <stdint.h>
#include <string.h>
#include <stdlib.h>
#include <unistd.h>
-
+/*! \brief Parse a MAC address from human-readable notation
+ * This function parses an ethernet MAC address in the commonly-used
+ * hex/colon notation (00:00:00:00:00:00) and generates the binary
+ * representation from it.
+ * \param[out] out pointer to caller-allocated buffer of 6 bytes
+ * \param[in] in pointer to input data as string with hex/colon notation
+ */
int osmo_macaddr_parse(uint8_t *out, const char *in)
{
/* 00:00:00:00:00:00 */
@@ -54,7 +66,11 @@ int osmo_macaddr_parse(uint8_t *out, const char *in)
#include <net/if_dl.h>
#include <net/if_types.h>
-
+/*! \brief Obtain the MAC address of a given network device
+ * \param[out] mac_out pointer to caller-allocated buffer of 6 bytes
+ * \param[in] dev_name string name of the network device
+ * \returns 0 in case of success; negative otherwise
+ */
int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
{
int rc = -1;
@@ -92,6 +108,11 @@ int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
#include <netinet/in.h>
#include <netinet/ip.h>
+/*! \brief Obtain the MAC address of a given network device
+ * \param[out] mac_out pointer to caller-allocated buffer of 6 bytes
+ * \param[in] dev_name string name of the network device
+ * \returns 0 in case of success; negative otherwise
+ */
int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
{
int fd, rc;
@@ -114,3 +135,5 @@ int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
return 0;
}
#endif
+
+/*! @} */
diff --git a/src/msgb.c b/src/msgb.c
index 6361913..f09da90 100644
--- a/src/msgb.c
+++ b/src/msgb.c
@@ -40,6 +40,7 @@ void *tall_msgb_ctx;
/*! \brief Allocate a new message buffer
* \param[in] size Length in octets, including headroom
* \param[in] name Human-readable name to be associated with msgb
+ * \returns dynamically-allocated \ref msgb
*
* This function allocates a 'struct msgb' as well as the underlying
* memory buffer for the actual message data (size specified by \a size)
diff --git a/src/panic.c b/src/panic.c
index 84bab33..0ce50db 100644
--- a/src/panic.c
+++ b/src/panic.c
@@ -24,7 +24,9 @@
* @{
*/
-/*! \file panic.c */
+/*! \file panic.c
+ * \brief Routines for panic handling
+ */
#include <osmocom/gsm/gsm_utils.h>
#include <osmocom/core/panic.h>
@@ -58,7 +60,19 @@ static void osmo_panic_default(const char *fmt, va_list args)
#endif
-/*! \brief Terminate the current program with a panic */
+/*! \brief Terminate the current program with a panic
+ *
+ * You can call this function in case some severely unexpected situation
+ * is detected and the program is supposed to terminate in a way that
+ * reports the fact that it terminates.
+ *
+ * The application can register a panic handler function using \ref
+ * osmo_set_panic_handler. If it doesn't, a default panic handler
+ * function is called automatically.
+ *
+ * The default function on most systems will generate a backtrace and
+ * then abort() the process.
+ */
void osmo_panic(const char *fmt, ...)
{
va_list args;
@@ -74,7 +88,12 @@ void osmo_panic(const char *fmt, ...)
}
-/*! \brief Set the panic handler */
+/*! \brief Set the panic handler
+ * \param[in] h New panic handler function
+ *
+ * This changes the panic handling function from the currently active
+ * function to a new call-back function supplied by the caller.
+ */
void osmo_set_panic_handler(osmo_panic_handler_t h)
{
osmo_panic_handler = h;
diff --git a/src/prim.c b/src/prim.c
index c2e7198..3f41c41 100644
--- a/src/prim.c
+++ b/src/prim.c
@@ -1,6 +1,8 @@
#include <osmocom/core/utils.h>
#include <osmocom/core/prim.h>
+/*! \brief human-readable string mapping for
+ * \ref osmo_prim_operation */
const struct value_string osmo_prim_op_names[5] = {
{ PRIM_OP_REQUEST, "request" },
{ PRIM_OP_RESPONSE, "response" },
diff --git a/src/rate_ctr.c b/src/rate_ctr.c
index 436deef..f995f3f 100644
--- a/src/rate_ctr.c
+++ b/src/rate_ctr.c
@@ -153,7 +153,10 @@ int rate_ctr_init(void *tall_ctx)
return 0;
}
-/*! \brief Search for counter group based on group name and index */
+/*! \brief Search for counter group based on group name and index
+ * \param[in] name Name of the counter group you're looking for
+ * \param[in] idx Index inside the counter group
+ * \returns \ref rate_ctr_group or NULL in case of error */
struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const unsigned int idx)
{
struct rate_ctr_group *ctrg;
@@ -170,7 +173,11 @@ struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const un
return NULL;
}
-/*! \brief Search for counter group based on group name */
+/*! \brief Search for counter based on group + name
+ * \param[in] ctrg pointer to \ref rate_ctr_group
+ * \param[in] name name of counter inside group
+ * \returns \ref rate_ctr or NULL in caes of error
+ */
const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, const char *name)
{
int i;
@@ -189,6 +196,12 @@ const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, c
return NULL;
}
+/*! \brief Iterate over each counter in group and call function
+ * \param[in] counter group over whose counter to iterate
+ * \param[in] handle_counter function pointer
+ * \param[in] data Data to hand transparently to \ref handle_counter
+ * \returns 0 on success; negative otherwise
+ */
int rate_ctr_for_each_counter(struct rate_ctr_group *ctrg,
rate_ctr_handler_t handle_counter, void *data)
{
@@ -206,6 +219,11 @@ int rate_ctr_for_each_counter(struct rate_ctr_group *ctrg,
return rc;
}
+/*! \brief Iterate over all counter groups
+ * \param[in] handle_group function pointer of callback function
+ * \param[in] data Data to hand transparently to \ref handle_group
+ * \returns 0 on success; negative otherwise
+ */
int rate_ctr_for_each_group(rate_ctr_group_handler_t handle_group, void *data)
{
struct rate_ctr_group *statg;
@@ -220,5 +238,4 @@ int rate_ctr_for_each_group(rate_ctr_group_handler_t handle_group, void *data)
return rc;
}
-
/*! @} */
diff --git a/src/select.c b/src/select.c
index 02bc2cc..192cae2 100644
--- a/src/select.c
+++ b/src/select.c
@@ -47,6 +47,7 @@ static int unregistered_count;
/*! \brief Register a new file descriptor with select loop abstraction
* \param[in] fd osmocom file descriptor to be registered
+ * \returns 0 on success; negative in case of error
*/
int osmo_fd_register(struct osmo_fd *fd)
{
@@ -160,6 +161,7 @@ restart:
/*! \brief select main loop integration
* \param[in] polling should we pollonly (1) or block on select (0)
+ * \returns 0 if no fd handled; 1 if fd handled; negative in case of error
*/
int osmo_select_main(int polling)
{
@@ -189,7 +191,9 @@ int osmo_select_main(int polling)
return osmo_fd_disp_fds(&readset, &writeset, &exceptset);
}
-/*! \brief find an osmo_fd based on the integer fd */
+/*! \brief find an osmo_fd based on the integer fd
+ * \param[in] fd file descriptor to use as search key
+ * \returns \ref osmo_fd for \ref fd; NULL in case it doesn't exist */
struct osmo_fd *osmo_fd_get_by_fd(int fd)
{
struct osmo_fd *ofd;
diff --git a/src/signal.c b/src/signal.c
index 6384384..8402591 100644
--- a/src/signal.c
+++ b/src/signal.c
@@ -46,6 +46,7 @@ struct signal_handler {
* \param[in] subsys Subsystem number
* \param[in] cbfn Callback function
* \param[in] data Data passed through to callback
+ * \returns 0 on success; negative in case of error
*/
int osmo_signal_register_handler(unsigned int subsys,
osmo_signal_cbfn *cbfn, void *data)
diff --git a/src/socket.c b/src/socket.c
index 567939b..7e610bf 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -57,6 +57,7 @@
* \param[in] host remote host name or IP address in string form
* \param[in] port remote port number in host byte order
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket file descriptor on success; negative on error
*
* This function creates a new socket of the designated \a family, \a
* type and \a proto and optionally binds or connects it, depending on
@@ -153,6 +154,7 @@ int osmo_sock_init(uint16_t family, uint16_t type, uint8_t proto,
/*! \brief fill \ref osmo_fd for a give sfd
* \param[out] ofd file descriptor (will be filled in)
* \param[in] sfd socket file descriptor
+ * \returns socket fd on success; negative on error
*
* This function fills the \a ofd structure.
*/
@@ -183,6 +185,7 @@ static inline int osmo_fd_init_ofd(struct osmo_fd *ofd, int sfd)
* \param[in] host remote host name or IP address in string form
* \param[in] port remote port number in host byte order
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates (and optionall binds/connects) a socket using
* \ref osmo_sock_init, but also fills the \a ofd structure.
@@ -198,6 +201,7 @@ int osmo_sock_init_ofd(struct osmo_fd *ofd, int family, int type, int proto,
* \param[in] type Socket type like SOCK_DGRAM, SOCK_STREAM
* \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates (and optionall binds/connects) a socket using
* \ref osmo_sock_init, but also fills the \a ss structure.
@@ -294,6 +298,7 @@ int osmo_sockaddr_is_local(struct sockaddr *addr, unsigned int addrlen)
* \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
* \param[in] socket_path path to identify the socket
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates a new unix domain socket, \a
* type and \a proto and optionally binds or connects it, depending on
@@ -365,6 +370,7 @@ err:
* \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
* \param[in] socket_path path to identify the socket
* \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ * \returns socket fd on success; negative on error
*
* This function creates (and optionall binds/connects) a socket using
* \ref osmo_sock_unix_init, but also fills the \a ofd structure.
diff --git a/src/timer.c b/src/timer.c
index 21b7015..0358b89 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -249,6 +249,8 @@ restart:
return work;
}
+/*! \brief Check how many timers we have in the system
+ * \returns number of \ref osmo_timer_list registered */
int osmo_timers_check(void)
{
struct rb_node *node;
diff --git a/src/write_queue.c b/src/write_queue.c
index 9a8b05c..3e488ae 100644
--- a/src/write_queue.c
+++ b/src/write_queue.c
@@ -33,6 +33,7 @@
/*! \brief Select loop function for write queue handling
* \param[in] fd osmocom file descriptor
* \param[in] what bit-mask of events that have happened
+ * \returns 0 on success; negative on error
*
* This function is provided so that it can be registered with the
* select loop abstraction code (\ref osmo_fd::cb).
@@ -99,6 +100,7 @@ void osmo_wqueue_init(struct osmo_wqueue *queue, int max_length)
/*! \brief Enqueue a new \ref msgb into a write queue
* \param[in] queue Write queue to be used
* \param[in] data to-be-enqueued message buffer
+ * \returns 0 on success; negative on error
*/
int osmo_wqueue_enqueue(struct osmo_wqueue *queue, struct msgb *data)
{