summaryrefslogtreecommitdiffstats
path: root/include/osmocom
diff options
context:
space:
mode:
authorHarald Welte <laforge@gnumonks.org>2016-04-25 12:11:20 +0200
committerHarald Welte <laforge@gnumonks.org>2016-05-05 18:49:27 +0200
commit2d2e2cca0dc1d62addc9c9fcb3a59f343fc3baf6 (patch)
tree8ec3ba89d486e4c324d32d1980ce68d5118d2db1 /include/osmocom
parent0996c879255e4653740814112bf98d0ddc93100c (diff)
Update doxygen annotations in libosmocore
This adds and improves doxygen API descriptions all over libosmocore, reducing the 'white spots' that don't have any documentation.
Diffstat (limited to 'include/osmocom')
-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
9 files changed, 162 insertions, 139 deletions
diff --git a/include/osmocom/core/bits.h b/include/osmocom/core/bits.h
index e082313a..3218330b 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 c1ac3edb..c35582e1 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 a5c03e77..2e3d068d 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 01fd261a..1c833950 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 31934111..4b79c054 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 cdde353a..ebaa7a71 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 6f56496a..5ed4e151 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 1df28c92..6ef0912e 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 205fa283..27e1e188 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)