Merge commit 'fe28dedd4c25b5f0f3df39d5e33ce3639574406c'

19 files changed, 593 insertions, 172 deletions

diff --git a/src/shared/libosmocore/include/osmocom/core/Makefile.am b/src/shared/libosmocore/include/osmocom/core/Makefile.am
index 1ef37693..f131269d 100644
--- a/src/shared/libosmocore/include/osmocom/core/Makefile.am
+++ b/src/shared/libosmocore/include/osmocom/core/Makefile.am
@@ -2,11 +2,23 @@ osmocore_HEADERS = signal.h linuxlist.h timer.h select.h msgb.h bits.h \
 		   bitvec.h statistics.h utils.h socket.h \
 		   gsmtap.h write_queue.h prim.h \
 		   logging.h rate_ctr.h gsmtap_util.h \
-		   plugin.h crc16.h panic.h process.h msgfile.h \
+		   crc16.h panic.h process.h \
 		   backtrace.h conv.h application.h
 
+if ENABLE_PLUGIN
+osmocore_HEADERS += plugin.h
+endif
+
 if ENABLE_TALLOC
 osmocore_HEADERS += talloc.h
 endif
 
+if ENABLE_MSGFILE
+osmocore_HEADERS += msgfile.h
+endif
+
+if ENABLE_SERIAL
+osmocore_HEADERS += serial.h
+endif
+
 osmocoredir = $(includedir)/osmocom/core
diff --git a/src/shared/libosmocore/include/osmocom/core/application.h b/src/shared/libosmocore/include/osmocom/core/application.h
index 5d098961..34571698 100644
--- a/src/shared/libosmocore/include/osmocom/core/application.h
+++ b/src/shared/libosmocore/include/osmocom/core/application.h
@@ -1,13 +1,18 @@
 #ifndef OSMO_APPLICATION_H
 #define OSMO_APPLICATION_H
 
-/**
- * Routines for helping with the application setup.
+/*!
+ * \file application.h
+ * \brief Routines for helping with the osmocom application setup.
  */
 
+/*! \brief information containing the available logging subsystems */
 struct log_info;
+
+/*! \brief one instance of a logging target (file, stderr, ...) */
 struct log_target;
 
+/*! \brief the default logging target, logging to stderr */
 extern struct log_target *osmo_stderr_target;
 
 void osmo_init_ignore_signals(void);
diff --git a/src/shared/libosmocore/include/osmocom/core/bits.h b/src/shared/libosmocore/include/osmocom/core/bits.h
index eb22d07c..b541b9ce 100644
--- a/src/shared/libosmocore/include/osmocom/core/bits.h
+++ b/src/shared/libosmocore/include/osmocom/core/bits.h
@@ -3,9 +3,17 @@
 
 #include <stdint.h>
 
-typedef int8_t  sbit_t;		/* soft bit (-127...127) */
-typedef uint8_t ubit_t;		/* unpacked bit (0 or 1) */
-typedef uint8_t pbit_t;		/* packed bis (8 bits in a byte) */
+/*! \defgroup bits soft, unpacked and packed bits
+ *  @{
+ */
+
+/*! \file bits.h
+ *  \brief Osmocom bit level support code
+ */
+
+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:
@@ -13,7 +21,9 @@ typedef uint8_t pbit_t;		/* packed bis (8 bits in a byte) */
    Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
 */
 
-/* determine how many bytes we would need for 'num_bits' packed bits */
+/*! \brief determine how many bytes we would need for \a num_bits packed bits
+ *  \param[in] num_bits Number of packed bits
+ */
 static inline unsigned int osmo_pbit_bytesize(unsigned int num_bits)
 {
 	unsigned int pbit_bytesize = num_bits / 8;
@@ -24,22 +34,45 @@ static inline unsigned int osmo_pbit_bytesize(unsigned int num_bits)
 	return pbit_bytesize;
 }
 
-/* convert unpacked bits to packed bits, return length in bytes */
 int osmo_ubit2pbit(pbit_t *out, const ubit_t *in, unsigned int num_bits);
 
-/* convert packed bits to unpacked bits, return length in bytes */
 int osmo_pbit2ubit(ubit_t *out, const pbit_t *in, unsigned int num_bits);
 
-/* convert unpacked bits to packed bits (extended options but slower),
- * return length in bytes (max written ofs of output buffer + 1) */
 int osmo_ubit2pbit_ext(pbit_t *out, unsigned int out_ofs,
                        const ubit_t *in, unsigned int in_ofs,
                        unsigned int num_bits, int lsb_mode);
 
-/* convert packed bits to unpacked bits (extended options but slower),
- * return length in bytes (max written ofs of output buffer + 1) */
 int osmo_pbit2ubit_ext(ubit_t *out, unsigned int out_ofs,
                        const pbit_t *in, unsigned int in_ofs,
                        unsigned int num_bits, int lsb_mode);
 
-#endif
+
+/* BIT REVERSAL */
+
+/*! \brief bit-reversal mode for osmo_bit_reversal() */
+enum osmo_br_mode {
+	/*! \brief reverse all bits in a 32bit dword */
+	OSMO_BR_BITS_IN_DWORD	= 31,
+	/*! \brief reverse byte order in a 32bit dword */
+	OSMO_BR_BYTES_IN_DWORD	= 24,
+	/*! \brief reverse bits of each byte in a 32bit dword */
+	OSMO_BR_BITS_IN_BYTE	= 7,
+	/*! \brief swap the two 16bit words in a 32bit dword */
+	OSMO_BR_WORD_SWAP	= 16,
+};
+
+/*! \brief generic bit reversal function */
+uint32_t osmo_bit_reversal(uint32_t x, enum osmo_br_mode k);
+
+/* \brief reverse the bits within each byte of a 32bit word */
+uint32_t osmo_revbytebits_32(uint32_t x);
+
+/* \brief reverse the bits within a byte */
+uint32_t osmo_revbytebits_8(uint8_t x);
+
+/* \brief reverse the bits of each byte in a given buffer */
+void osmo_revbytebits_buf(uint8_t *buf, int len);
+
+/*! }@ */
+
+#endif /* _OSMO_BITS_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/bitvec.h b/src/shared/libosmocore/include/osmocom/core/bitvec.h
index 7cb8a873..c2422e6d 100644
--- a/src/shared/libosmocore/include/osmocom/core/bitvec.h
+++ b/src/shared/libosmocore/include/osmocom/core/bitvec.h
@@ -23,56 +23,48 @@
  *
  */
 
+/*! \defgroup bitvec Bit vectors
+ *  @{
+ */
+
+/*! \file bitvec.h
+ *  \brief Osmocom bit vector abstraction
+ */
+
 #include <stdint.h>
 
-/* In GSM mac blocks, every bit can be 0 or 1, or L or H.  L/H are
+/*! \brief A single GSM bit
+ *
+ * In GSM mac blocks, every bit can be 0 or 1, or L or H.  L/H are
  * defined relative to the 0x2b padding pattern */
 enum bit_value {
-	ZERO	= 0,
-	ONE	= 1,
-	L	= 2,
-	H	= 3,
+	ZERO	= 0, 	/*!< \brief A zero (0) bit */
+	ONE	= 1,	/*!< \brief A one (1) bit */
+	L	= 2,	/*!< \brief A CSN.1 "L" bit */
+	H	= 3,	/*!< \brief A CSN.1 "H" bit */
 };
 
+/*! \brief structure describing a bit vector */
 struct bitvec {
-	unsigned int cur_bit;	/* curser to the next unused bit */
-	unsigned int data_len;	/* length of data array in bytes */
-	uint8_t *data;		/* pointer to data array */
+	unsigned int cur_bit;	/*!< \brief curser to the next unused bit */
+	unsigned int data_len;	/*!< \brief length of data array in bytes */
+	uint8_t *data;		/*!< \brief pointer to data array */
 };
 
-/* check if the bit is 0 or 1 for a given position inside a bitvec */
 enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr);
-
-/* check if the bit is L or H for a given position inside a bitvec */
 enum bit_value bitvec_get_bit_pos_high(const struct bitvec *bv,
 					unsigned int bitnr);
-
-/* get the Nth set bit inside the bit vector */
 unsigned int bitvec_get_nth_set_bit(const struct bitvec *bv, unsigned int n);
-
-/* Set a bit at given position */
 int bitvec_set_bit_pos(struct bitvec *bv, unsigned int bitnum,
 			enum bit_value bit);
-
-/* Set the next bit in the vector */
 int bitvec_set_bit(struct bitvec *bv, enum bit_value bit);
-
-/* get the next bit (low/high) inside a bitvec */
 int bitvec_get_bit_high(struct bitvec *bv);
-
-/* Set multiple bits at the current position */
 int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, int count);
-
-/* Add an unsigned integer (of length count bits) to current position */
 int bitvec_set_uint(struct bitvec *bv, unsigned int in, int count);
-
-/* get multiple bits (based on numeric value) from current pos */
 int bitvec_get_uint(struct bitvec *bv, int num_bits);
-
-/* find the first bit set in bit vector */
 int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n, enum bit_value val);
-
-/* Pad the bit vector up to a certain bit position */
 int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit);
 
+/*! }@ */
+
 #endif /* _BITVEC_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/conv.h b/src/shared/libosmocore/include/osmocom/core/conv.h
index af676eed..db3058cd 100644
--- a/src/shared/libosmocore/include/osmocom/core/conv.h
+++ b/src/shared/libosmocore/include/osmocom/core/conv.h
@@ -20,6 +20,14 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
+/*! \defgroup conv Convolutional encoding and decoding routines
+ *  @{
+ */
+
+/*! \file conv.h
+ *  \file Osmocom convolutional encoder and decoder
+ */
+
 #ifndef __OSMO_CONV_H__
 #define __OSMO_CONV_H__
 
@@ -27,6 +35,7 @@
 
 #include <osmocom/core/bits.h>
 
+/*! \brief structure describing a given convolutional code */
 struct osmo_conv_code {
 	int N;
 	int K;
@@ -45,11 +54,12 @@ struct osmo_conv_code {
 /* Encoding */
 
 	/* Low level API */
+/*! \brief convolutional encoder state */
 struct osmo_conv_encoder {
-	const struct osmo_conv_code *code;
-	int i_idx;	/* Next input bit index */
-	int p_idx;	/* Current puncture index */
-	uint8_t state;	/* Current state */
+	const struct osmo_conv_code *code; /*!< \brief for which code? */
+	int i_idx;	/*!< \brief Next input bit index */
+	int p_idx;	/*!< \brief Current puncture index */
+	uint8_t state;	/*!< \brief Current state */
 };
 
 void osmo_conv_encode_init(struct osmo_conv_encoder *encoder,
@@ -66,19 +76,21 @@ int  osmo_conv_encode(const struct osmo_conv_code *code,
 /* Decoding */
 
 	/* Low level API */
+/*! \brief convolutional decoder state */
 struct osmo_conv_decoder {
+	/*! \brief description of convolutional code */
 	const struct osmo_conv_code *code;
 
-	int n_states;
+	int n_states;		/*!< \brief number of states */
 
-	int len;		/* Max o_idx (excl. termination) */
+	int len;		/*!< \brief Max o_idx (excl. termination) */
 
-	int o_idx;		/* output index */
-	int p_idx;		/* puncture index */
+	int o_idx;		/*!< \brief output index */
+	int p_idx;		/*!< \brief puncture index */
 
-	unsigned int *ae;	/* accumulater error */
-	unsigned int *ae_next;	/* next accumulated error (tmp in scan) */
-	uint8_t *state_history;	/* state history [len][n_states] */
+	unsigned int *ae;	/*!< \brief accumulater error */
+	unsigned int *ae_next;	/*!< \brief next accumulated error (tmp in scan) */
+	uint8_t *state_history;	/*!< \brief state history [len][n_states] */
 };
 
 void osmo_conv_decode_init(struct osmo_conv_decoder *decoder,
@@ -98,4 +110,6 @@ int osmo_conv_decode(const struct osmo_conv_code *code,
                      const sbit_t *input, ubit_t *output);
 
 
+/*! }@ */
+
 #endif /* __OSMO_CONV_H__ */
diff --git a/src/shared/libosmocore/include/osmocom/core/gsmtap_util.h b/src/shared/libosmocore/include/osmocom/core/gsmtap_util.h
index f553c17a..36cbf532 100644
--- a/src/shared/libosmocore/include/osmocom/core/gsmtap_util.h
+++ b/src/shared/libosmocore/include/osmocom/core/gsmtap_util.h
@@ -5,46 +5,41 @@
 #include <osmocom/core/write_queue.h>
 #include <osmocom/core/select.h>
 
-/* convert RSL channel number to GSMTAP channel type */
+/*! \defgroup gsmtap GSMTAP
+ *  @{
+ */
+/*! \file gsmtap_util.h */
+
 uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t rsl_link_id);
 
-/* generate msgb from data + metadata */
 struct msgb *gsmtap_makemsg(uint16_t arfcn, uint8_t ts, uint8_t chan_type,
 			    uint8_t ss, uint32_t fn, int8_t signal_dbm,
 			    uint8_t snr, const uint8_t *data, unsigned int len);
 
-/* one gsmtap instance */
+/*! \brief one gsmtap instance */
 struct gsmtap_inst {
-	int ofd_wq_mode;
-	struct osmo_wqueue wq;
-	struct osmo_fd sink_ofd;
+	int ofd_wq_mode;	/*!< \brief wait queue mode? */
+	struct osmo_wqueue wq;	/*!< \brief the wait queue */
+	struct osmo_fd sink_ofd;/*!< \brief file descriptor */
 };
 
+/*! \brief obtain the file descriptor associated with a gsmtap instance */
 static inline int gsmtap_inst_fd(struct gsmtap_inst *gti)
 {
 	return gti->wq.bfd.fd;
 }
 
-/* Open a GSMTAP source (sending) socket, conncet it to host/port and
- * return resulting fd */
 int gsmtap_source_init_fd(const char *host, uint16_t port);
 
-/* Add a local sink to an existing GSMTAP source and return fd */
 int gsmtap_source_add_sink_fd(int gsmtap_fd);
 
-/* Open GSMTAP source (sending) socket, connect it to host/port,
- * allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue
- * registration */
 struct gsmtap_inst *gsmtap_source_init(const char *host, uint16_t port,
 					int ofd_wq_mode);
 
-/* Add a local sink to an existing GSMTAP source instance */
 int gsmtap_source_add_sink(struct gsmtap_inst *gti);
 
-/* Send a msgb through a GSMTAP source */
 int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg);
 
-/* generate a message and send it via GSMTAP */
 int gsmtap_send(struct gsmtap_inst *gti, uint16_t arfcn, uint8_t ts,
 		uint8_t chan_type, uint8_t ss, uint32_t fn,
 		int8_t signal_dbm, uint8_t snr, const uint8_t *data,
diff --git a/src/shared/libosmocore/include/osmocom/core/logging.h b/src/shared/libosmocore/include/osmocom/core/logging.h
index 154ee198..72e4c93e 100644
--- a/src/shared/libosmocore/include/osmocom/core/logging.h
+++ b/src/shared/libosmocore/include/osmocom/core/logging.h
@@ -1,11 +1,20 @@
 #ifndef _OSMOCORE_LOGGING_H
 #define _OSMOCORE_LOGGING_H
 
+/*! \defgroup logging Osmocom logging framework
+ *  @{
+ */
+
+/*! \file logging.h */
+
 #include <stdio.h>
 #include <stdint.h>
+#include <stdarg.h>
 #include <osmocom/core/linuxlist.h>
 
+/*! \brief Maximum number of logging contexts */
 #define LOG_MAX_CTX		8
+/*! \brief Maximum number of logging filters */
 #define LOG_MAX_FILTERS	8
 
 #define DEBUG
@@ -19,20 +28,35 @@
 #endif
 
 
+void osmo_vlogp(int subsys, int level, char *file, int line,
+		int cont, const char *format, va_list ap);
+
 void logp(int subsys, char *file, int line, int cont, const char *format, ...) __attribute__ ((format (printf, 5, 6)));
 
-/* new logging interface */
+/*! \brief Log a new message through the Osmocom logging framework
+ *  \param[in] ss logging subsystem (e.g. \ref DLGLOBAL)
+ *  \param[in] level logging level (e.g. \ref LOGL_NOTICE)
+ *  \param[in] fmt format string
+ *  \param[in] args variable argument list
+ */
 #define LOGP(ss, level, fmt, args...) \
 	logp2(ss, level, __FILE__, __LINE__, 0, fmt, ##args)
+
+/*! \brief Continue a log message through the Osmocom logging framework
+ *  \param[in] ss logging subsystem (e.g. \ref DLGLOBAL)
+ *  \param[in] level logging level (e.g. \ref LOGL_NOTICE)
+ *  \param[in] fmt format string
+ *  \param[in] args variable argument list
+ */
 #define LOGPC(ss, level, fmt, args...) \
 	logp2(ss, level, __FILE__, __LINE__, 1, fmt, ##args)
 
-/* different levels */
-#define LOGL_DEBUG	1	/* debugging information */
+/*! \brief different log levels */
+#define LOGL_DEBUG	1	/*!< \brief debugging information */
 #define LOGL_INFO	3
-#define LOGL_NOTICE	5	/* abnormal/unexpected condition */
-#define LOGL_ERROR	7	/* error condition, requires user action */
-#define LOGL_FATAL	8	/* fatal, program aborted */
+#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 */
 
 #define LOG_FILTER_ALL	0x0001
 
@@ -50,53 +74,67 @@ struct log_category {
 	uint8_t enabled;
 };
 
+/*! \brief Information regarding one logging category */
 struct log_info_cat {
-	const char *name;
-	const char *color;
-	const char *description;
-	uint8_t loglevel;
-	uint8_t enabled;
+	const char *name;		/*!< name of category */
+	const char *color;		/*!< color string for cateyory */
+	const char *description;	/*!< description text */
+	uint8_t loglevel;		/*!< currently selected log-level */
+	uint8_t enabled;		/*!< is this category enabled or not */
 };
 
-/* log context information, passed to filter */
+/*! \brief Log context information, passed to filter */
 struct log_context {
 	void *ctx[LOG_MAX_CTX+1];
 };
 
 struct log_target;
 
+/*! \brief Log filter function */
 typedef int log_filter(const struct log_context *ctx,
 		       struct log_target *target);
 
+/*! \brief Logging configuration, passed to \ref log_init */
 struct log_info {
-	/* filter callback function */
+	/* \brief filter callback function */
 	log_filter *filter_fn;
 
-	/* per-category information */
+	/*! \brief per-category information */
 	struct log_info_cat *cat;
+	/*! \brief total number of categories */
 	unsigned int num_cat;
+	/*! \brief total number of user categories (not library) */
 	unsigned int num_cat_user;
 };
 
+/*! \brief Type of logging target */
 enum log_target_type {
-	LOG_TGT_TYPE_VTY,
-	LOG_TGT_TYPE_SYSLOG,
-	LOG_TGT_TYPE_FILE,
-	LOG_TGT_TYPE_STDERR,
+	LOG_TGT_TYPE_VTY,	/*!< \brief VTY logging */
+	LOG_TGT_TYPE_SYSLOG,	/*!< \brief syslog based logging */
+	LOG_TGT_TYPE_FILE,	/*!< \brief text file logging */
+	LOG_TGT_TYPE_STDERR,	/*!< \brief stderr logging */
 };
 
+/*! \brief structure representing a logging target */
 struct log_target {
-        struct llist_head entry;
+        struct llist_head entry;		/*!< \brief linked list */
 
+	/*! \brief Internal data for filtering */
 	int filter_map;
+	/*! \brief Internal data for filtering */
 	void *filter_data[LOG_MAX_FILTERS+1];
 
+	/*! \brief logging categories */
 	struct log_category *categories;
 
+	/*! \brief global log level */
 	uint8_t loglevel;
+	/*! \brief should color be used when printing log messages? */
 	unsigned int use_color:1;
+	/*! \brief should log messages be prefixed with a timestamp? */
 	unsigned int print_timestamp:1;
 
+	/*! \brief the type of this log taget */
 	enum log_target_type type;
 
 	union {
@@ -115,6 +153,12 @@ struct log_target {
 		} tgt_vty;
 	};
 
+	/*! \brief call-back function to be called when the logging framework
+	 *	   wants to log somethnig.
+	 *  \param[[in] target logging target
+	 *  \param[in] level log level of currnet message
+	 *  \param[in] string the string that is to be written to the log
+	 */
         void (*output) (struct log_target *target, unsigned int level,
 			const char *string);
 };
@@ -161,4 +205,6 @@ const char *log_vty_command_description(const struct log_info *info);
 struct log_target *log_target_find(int type, const char *fname);
 extern struct llist_head osmo_log_target_list;
 
+/*! }@ */
+
 #endif /* _OSMOCORE_LOGGING_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/msgb.h b/src/shared/libosmocore/include/osmocom/core/msgb.h
index 915c4a04..9f46e6c6 100644
--- a/src/shared/libosmocore/include/osmocom/core/msgb.h
+++ b/src/shared/libosmocore/include/osmocom/core/msgb.h
@@ -24,39 +24,47 @@
 #include <osmocom/core/linuxlist.h>
 #include <osmocom/core/utils.h>
 
+/*! \defgroup msgb Message buffers
+ *  @{
+ */
+
+/*! \file msgb.h
+ *  \brief Osmocom message buffers
+ * The Osmocom message buffers are modelled after the 'struct skb'
+ * inside the Linux kernel network stack.  As they exist in userspace,
+ * they are much simplified.  However, terminology such as headroom,
+ * tailroom, push/pull/put etc. remains the same.
+ */
+
 #define MSGB_DEBUG
 
+/*! \brief Osmocom message buffer */
 struct msgb {
-	struct llist_head list;
+	struct llist_head list; /*!< \brief linked list header */
 
 
 	/* Part of which TRX logical channel we were received / transmitted */
 	/* FIXME: move them into the control buffer */
 	union {
-		void *dst;
+		void *dst; /*!< \brief reference of origin/destination */
 		struct gsm_bts_trx *trx;
 	};
-	struct gsm_lchan *lchan;
-
-	/* the Layer1 header (if any) */
-	unsigned char *l1h;
-	/* the A-bis layer 2 header: OML, RSL(RLL), NS */
-	unsigned char *l2h;
-	/* the layer 3 header. For OML: FOM; RSL: 04.08; GPRS: BSSGP */
-	unsigned char *l3h;
-	/* the layer 4 header */
-	unsigned char *l4h;
-
-	/* the 'control buffer', large enough to contain 5 pointers */
-	unsigned long cb[5];
-
-	uint16_t data_len;
-	uint16_t len;
-
-	unsigned char *head;
-	unsigned char *tail;
-	unsigned char *data;
-	unsigned char _data[0];
+	struct gsm_lchan *lchan; /*!< \brief logical channel */
+
+	unsigned char *l1h; /*!< \brief pointer to Layer1 header (if any) */
+	unsigned char *l2h; /*!< \brief pointer to A-bis layer 2 header: OML, RSL(RLL), NS */
+	unsigned char *l3h; /*!< \brief pointer to Layer 3 header. For OML: FOM; RSL: 04.08; GPRS: BSSGP */
+	unsigned char *l4h; /*!< \brief pointer to layer 4 header */
+
+	unsigned long cb[5]; /*!< \brief control buffer */
+
+	uint16_t data_len;   /*!< \brief length of underlying data array */
+	uint16_t len;	     /*!< \brief length of bytes used in msgb */
+
+	unsigned char *head;	/*!< \brief start of underlying memory buffer */
+	unsigned char *tail;	/*!< \brief end of message in buffer */
+	unsigned char *data;	/*!< \brief start of message in buffer */
+	unsigned char _data[0]; /*!< \brief optional immediate data array */
 };
 
 extern struct msgb *msgb_alloc(uint16_t size, const char *name);
@@ -74,41 +82,99 @@ extern void msgb_reset(struct msgb *m);
 #define MSGB_ABORT(msg, fmt, args ...)
 #endif
 
+/*! \brief obtain L1 header of msgb */
 #define msgb_l1(m)	((void *)(m->l1h))
+/*! \brief obtain L2 header of msgb */
 #define msgb_l2(m)	((void *)(m->l2h))
+/*! \brief obtain L3 header of msgb */
 #define msgb_l3(m)	((void *)(m->l3h))
+/*! \brief obtain SMS header of msgb */
 #define msgb_sms(m)	((void *)(m->l4h))
 
+/*! \brief determine length of L1 message
+ *  \param[in] msgb message buffer
+ *  \returns size of L1 message in bytes
+ *
+ * This function computes the number of bytes between the tail of the
+ * message and the layer 1 header.
+ */
 static inline unsigned int msgb_l1len(const struct msgb *msgb)
 {
 	return msgb->tail - (uint8_t *)msgb_l1(msgb);
 }
 
+/*! \brief determine length of L2 message
+ *  \param[in] msgb message buffer
+ *  \returns size of L2 message in bytes
+ *
+ * This function computes the number of bytes between the tail of the
+ * message and the layer 2 header.
+ */
 static inline unsigned int msgb_l2len(const struct msgb *msgb)
 {
 	return msgb->tail - (uint8_t *)msgb_l2(msgb);
 }
 
+/*! \brief determine length of L3 message
+ *  \param[in] msgb message buffer
+ *  \returns size of L3 message in bytes
+ *
+ * This function computes the number of bytes between the tail of the
+ * message and the layer 3 header.
+ */
 static inline unsigned int msgb_l3len(const struct msgb *msgb)
 {
 	return msgb->tail - (uint8_t *)msgb_l3(msgb);
 }
 
+/*! \brief determine the length of the header
+ *  \param[in] msgb message buffer
+ *  \returns number of bytes between start of buffer and start of msg
+ *
+ * This function computes the length difference between the underlying
+ * data buffer and the used section of the \a msgb.
+ */
 static inline unsigned int msgb_headlen(const struct msgb *msgb)
 {
 	return msgb->len - msgb->data_len;
 }
 
+/*! \brief determine how much tail room is left in msgb
+ *  \param[in] msgb message buffer
+ *  \returns number of bytes remaining at end of msgb
+ *
+ * This function computes the amount of octets left in the underlying
+ * data buffer after the end of the message.
+ */
 static inline int msgb_tailroom(const struct msgb *msgb)
 {
 	return (msgb->head + msgb->data_len) - msgb->tail;
 }
 
+/*! \brief determine the amount of headroom in msgb
+ *  \param[in] msgb message buffer
+ *  \returns number of bytes left ahead of message start in msgb
+ *
+ * This function computes the amount of bytes left in the underlying
+ * data buffer before the start of the actual message.
+ */
 static inline int msgb_headroom(const struct msgb *msgb)
 {
 	return (msgb->data - msgb->head);
 }
 
+/*! \brief append data to end of message buffer
+ *  \param[in] msgb message buffer
+ *  \param[in] len number of bytes to append to message
+ *  \returns pointer to start of newly-appended data
+ *
+ * This function will move the \a tail pointer of the message buffer \a
+ * len bytes further, thus enlarging the message by \a len bytes.
+ *
+ * The return value is a pointer to start of the newly added section at
+ * the end of the message and can be used for actually filling/copying
+ * data into it.
+ */
 static inline unsigned char *msgb_put(struct msgb *msgb, unsigned int len)
 {
 	unsigned char *tmp = msgb->tail;
@@ -119,17 +185,32 @@ static inline unsigned char *msgb_put(struct msgb *msgb, unsigned int len)
 	msgb->len += len;
 	return tmp;
 }
+
+/*! \brief append a uint8 value to the end of the message
+ *  \param[in] msgb message buffer
+ *  \param[in] word unsigned 8bit byte to be appended
+ */
 static inline void msgb_put_u8(struct msgb *msgb, uint8_t word)
 {
 	uint8_t *space = msgb_put(msgb, 1);
 	space[0] = word & 0xFF;
 }
+
+/*! \brief append a uint16 value to the end of the message
+ *  \param[in] msgb message buffer
+ *  \param[in] word unsigned 16bit byte to be appended
+ */
 static inline void msgb_put_u16(struct msgb *msgb, uint16_t word)
 {
 	uint8_t *space = msgb_put(msgb, 2);
 	space[0] = word >> 8 & 0xFF;
 	space[1] = word & 0xFF;
 }
+
+/*! \brief append a uint32 value to the end of the message
+ *  \param[in] msgb message buffer
+ *  \param[in] word unsigned 32bit byte to be appended
+ */
 static inline void msgb_put_u32(struct msgb *msgb, uint32_t word)
 {
 	uint8_t *space = msgb_put(msgb, 4);
@@ -138,6 +219,11 @@ static inline void msgb_put_u32(struct msgb *msgb, uint32_t word)
 	space[2] = word >> 8 & 0xFF;
 	space[3] = word & 0xFF;
 }
+
+/*! \brief remove data from end of message
+ *  \param[in] msgb message buffer
+ *  \param[in] len number of bytes to remove from end
+ */
 static inline unsigned char *msgb_get(struct msgb *msgb, unsigned int len)
 {
 	unsigned char *tmp = msgb->data;
@@ -145,21 +231,46 @@ static inline unsigned char *msgb_get(struct msgb *msgb, unsigned int len)
 	msgb->len -= len;
 	return tmp;
 }
+/*! \brief remove uint8 from end of message
+ *  \param[in] msgb message buffer
+ *  \returns 8bit value taken from end of msgb
+ */
 static inline uint8_t msgb_get_u8(struct msgb *msgb)
 {
 	uint8_t *space = msgb_get(msgb, 1);
 	return space[0];
 }
+/*! \brief remove uint16 from end of message
+ *  \param[in] msgb message buffer
+ *  \returns 16bit value taken from end of msgb
+ */
 static inline uint16_t msgb_get_u16(struct msgb *msgb)
 {
 	uint8_t *space = msgb_get(msgb, 2);
 	return space[0] << 8 | space[1];
 }
+/*! \brief remove uint32 from end of message
+ *  \param[in] msgb message buffer
+ *  \returns 32bit value taken from end of msgb
+ */
 static inline uint32_t msgb_get_u32(struct msgb *msgb)
 {
 	uint8_t *space = msgb_get(msgb, 4);
 	return space[0] << 24 | space[1] << 16 | space[2] << 8 | space[3];
 }
+
+/*! \brief prepend (push) some data to start of message
+ *  \param[in] msgb message buffer
+ *  \param[in] len number of bytes to pre-pend
+ *  \returns pointer to newly added portion at start of \a msgb
+ *
+ * This function moves the \a data pointer of the \ref msgb further
+ * to the front (by \a len bytes), thereby enlarging the message by \a
+ * len bytes.
+ *
+ * The return value is a pointer to the newly added section in the
+ * beginning of the message.  It can be used to fill/copy data into it.
+ */
 static inline unsigned char *msgb_push(struct msgb *msgb, unsigned int len)
 {
 	if (msgb_headroom(msgb) < (int) len)
@@ -169,19 +280,48 @@ static inline unsigned char *msgb_push(struct msgb *msgb, unsigned int len)
 	msgb->len += len;
 	return msgb->data;
 }
+/*! \brief remove (pull) a header from the front of the message buffer
+ *  \param[in] msgb message buffer
+ *  \param[in] len number of octets to be pulled
+ *  \returns pointer to new start of msgb
+ *
+ * This function moves the \a data pointer of the \ref msgb further back
+ * in the message, thereby shrinking the size of the message by \a len
+ * bytes.
+ */
 static inline unsigned char *msgb_pull(struct msgb *msgb, unsigned int len)
 {
 	msgb->len -= len;
 	return msgb->data += len;
 }
 
-/* increase the headroom of an empty msgb, reducing the tailroom */
+/*! \brief Increase headroom of empty msgb, reducing the tailroom
+ *  \param[in] msg message buffer
+ *  \param[in] len amount of extra octets to be reserved as headroom
+ *
+ * This function reserves some memory at the beginning of the underlying
+ * data buffer.  The idea is to reserve space in case further headers
+ * have to be pushed to the \ref msgb during further processing.
+ *
+ * Calling this function leads to undefined reusults if it is called on
+ * a non-empty \ref msgb.
+ */
 static inline void msgb_reserve(struct msgb *msg, int len)
 {
 	msg->data += len;
 	msg->tail += len;
 }
 
+/*! \brief Allocate message buffer with specified headroom
+ *  \param[in] size size in bytes, including headroom
+ *  \param[in] headroom headroom in bytes
+ *  \param[in] name human-readable name
+ *  \returns allocated message buffer with specified headroom
+ *
+ * This function is a convenience wrapper around \ref msgb_alloc
+ * followed by \ref msgb_reserve in order to create a new \ref msgb with
+ * user-specified amount of headroom.
+ */
 static inline struct msgb *msgb_alloc_headroom(int size, int headroom,
 						const char *name)
 {
@@ -194,10 +334,11 @@ static inline struct msgb *msgb_alloc_headroom(int size, int headroom,
 }
 
 /* non inline functions to ease binding */
+
 uint8_t *msgb_data(const struct msgb *msg);
 uint16_t msgb_length(const struct msgb *msg);
-
-/* set the talloc context for msgb_alloc[_headroom] */
 void msgb_set_talloc_ctx(void *ctx);
 
+/*! }@ */
+
 #endif /* _MSGB_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/panic.h b/src/shared/libosmocore/include/osmocom/core/panic.h
index c28a8440..fd5cf208 100644
--- a/src/shared/libosmocore/include/osmocom/core/panic.h
+++ b/src/shared/libosmocore/include/osmocom/core/panic.h
@@ -1,11 +1,20 @@
 #ifndef OSMOCORE_PANIC_H
 #define OSMOCORE_PANIC_H
 
+/*! \addtogroup utils
+ *  @{
+ */
+
+/*! \file panic.h */
+
 #include <stdarg.h>
 
+/*! \brief panic handler callback function type */
 typedef void (*osmo_panic_handler_t)(const char *fmt, va_list args);
 
 extern void osmo_panic(const char *fmt, ...);
 extern void osmo_set_panic_handler(osmo_panic_handler_t h);
 
-#endif
+/*! @} */
+
+#endif /* OSMOCORE_PANIC_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/prim.h b/src/shared/libosmocore/include/osmocom/core/prim.h
index e892c62c..2e60c46d 100644
--- a/src/shared/libosmocore/include/osmocom/core/prim.h
+++ b/src/shared/libosmocore/include/osmocom/core/prim.h
@@ -1,14 +1,21 @@
 #ifndef OSMO_PRIMITIVE_H
 #define OSMO_PRIMITIVE_H
 
+/*! \defgroup prim Osmocom primitives
+ *  @{
+ */
+
+/*! \file prim.c */
+
 #include <stdint.h>
 #include <osmocom/core/msgb.h>
 
+/*! \brief primitive operation */
 enum osmo_prim_operation {
-	PRIM_OP_REQUEST,
-	PRIM_OP_RESPONSE,
-	PRIM_OP_INDICATION,
-	PRIM_OP_CONFIRM,
+	PRIM_OP_REQUEST,	/*!< \brief request */
+	PRIM_OP_RESPONSE,	/*!< \brief response */
+	PRIM_OP_INDICATION,	/*!< \brief indication */
+	PRIM_OP_CONFIRM,	/*!< \brief cofirm */
 };
 
 #define _SAP_GSM_SHIFT	24
@@ -16,13 +23,21 @@ enum osmo_prim_operation {
 #define _SAP_GSM_BASE	(0x01 << _SAP_GSM_SHIFT)
 #define _SAP_TETRA_BASE	(0x02 << _SAP_GSM_SHIFT)
 
+/*! \brief primitive header */
 struct osmo_prim_hdr {
-	unsigned int sap;
-	unsigned int primitive;
-	enum osmo_prim_operation operation;
-	struct msgb *msg;	/* message containing associated data */
+	unsigned int sap;	/*!< \brief Service Access Point */
+	unsigned int primitive;	/*!< \brief Primitive number */
+	enum osmo_prim_operation operation; /*! \brief Primitive Operation */
+	struct msgb *msg;	/*!< \brief \ref msgb containing associated data */
 };
 
+/*! \brief initialize a primitive header
+ *  \param[in,out] oph primitive header
+ *  \param[in] sap Service Access Point
+ *  \param[in] primtive Primitive Number
+ *  \param[in] operation Primitive Operation (REQ/RESP/IND/CONF)
+ *  \param[in] msg Message
+ */
 static inline void
 osmo_prim_init(struct osmo_prim_hdr *oph, unsigned int sap,
 		unsigned int primitive, enum osmo_prim_operation operation,
@@ -34,5 +49,7 @@ osmo_prim_init(struct osmo_prim_hdr *oph, unsigned int sap,
 	oph->msg = msg;
 }
 
+/*! \brief primitive handler callback type */
 typedef int (*osmo_prim_cb)(struct osmo_prim_hdr *oph, void *ctx);
-#endif
+
+#endif /* OSMO_PRIMITIVE_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/rate_ctr.h b/src/shared/libosmocore/include/osmocom/core/rate_ctr.h
index ebb8646c..c38e5f9b 100644
--- a/src/shared/libosmocore/include/osmocom/core/rate_ctr.h
+++ b/src/shared/libosmocore/include/osmocom/core/rate_ctr.h
@@ -1,80 +1,88 @@
 #ifndef _RATE_CTR_H
 #define _RATE_CTR_H
 
+/*! \defgroup rate_ctr Rate counters
+ *  @{
+ */
+
+/*! \file rate_ctr.h */
+
 #include <stdint.h>
 
 #include <osmocom/core/linuxlist.h>
 
+/*! \brief Number of rate counter intervals */
 #define RATE_CTR_INTV_NUM	4
 
+/*! \brief Rate counter interval */
 enum rate_ctr_intv {
-	RATE_CTR_INTV_SEC,
-	RATE_CTR_INTV_MIN,
-	RATE_CTR_INTV_HOUR,
-	RATE_CTR_INTV_DAY,
+	RATE_CTR_INTV_SEC,	/*!< \brief last second */
+	RATE_CTR_INTV_MIN,	/*!< \brief last minute */
+	RATE_CTR_INTV_HOUR,	/*!< \brief last hour */
+	RATE_CTR_INTV_DAY,	/*!< \brief last day */
 };
 
-/* for each of the intervals, we keep the following values */
+/*! \brief data we keep for each of the intervals */
 struct rate_ctr_per_intv {
-	uint64_t last;
-	uint64_t rate;
+	uint64_t last;		/*!< \brief counter value in last interval */
+	uint64_t rate;		/*!< \brief counter rate */
 };
 
-/* for each actual value, we keep the following data */
+/*! \brief data we keep for each actual value */
 struct rate_ctr {
-	uint64_t current;
+	uint64_t current;	/*!< \brief current value */
+	/*! \brief per-interval data */
 	struct rate_ctr_per_intv intv[RATE_CTR_INTV_NUM];
 };
 
+/*! \brief rate counter description */
 struct rate_ctr_desc {
-	const char *name;
-	const char *description;
+	const char *name;	/*!< \brief name of the counter */
+	const char *description;/*!< \brief description of the counter */
 };
 
-/* Describe a counter group class */
+/*! \brief description of a rate counter group */
 struct rate_ctr_group_desc {
-	/* The prefix to the name of all counters in this group */
+	/*! \brief The prefix to the name of all counters in this group */
 	const char *group_name_prefix;
-	/* The human-readable description of the group */
+	/*! \brief The human-readable description of the group */
 	const char *group_description;
-	/* The number of counters in this group */
+	/*! \brief The number of counters in this group */
 	const unsigned int num_ctr;
-	/* Pointer to array of counter names */
+	/*! \brief Pointer to array of counter names */
 	const struct rate_ctr_desc *ctr_desc;
 };
 
-/* One instance of a counter group class */
+/*! \brief One instance of a counter group class */
 struct rate_ctr_group {
-	/* Linked list of all counter groups in the system */
+	/*! \brief Linked list of all counter groups in the system */
 	struct llist_head list;
-	/* Pointer to the counter group class */
+	/*! \brief Pointer to the counter group class */
 	const struct rate_ctr_group_desc *desc;
-	/* The index of this ctr_group within its class */
+	/*! \brief The index of this ctr_group within its class */
 	unsigned int idx;
-	/* Actual counter structures below */
+	/*! \brief Actual counter structures below */
 	struct rate_ctr ctr[0];
 };
 
-/* Allocate a new group of counters according to description */
 struct rate_ctr_group *rate_ctr_group_alloc(void *ctx,
 					    const struct rate_ctr_group_desc *desc,
 					    unsigned int idx);
 
-/* Free the memory for the specified group of counters */
 void rate_ctr_group_free(struct rate_ctr_group *grp);
 
-/* Add a number to the counter */
 void rate_ctr_add(struct rate_ctr *ctr, int inc);
 
-/* Increment the counter by 1 */
+/*! \brief Increment the counter by 1 */
 static inline void rate_ctr_inc(struct rate_ctr *ctr)
 {
 	rate_ctr_add(ctr, 1);
 }
 
-/* Initialize the counter module */
 int rate_ctr_init(void *tall_ctx);
 
 struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const unsigned int idx);
 const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, const char *name);
+
+/*! }@ */
 #endif /* RATE_CTR_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/select.h b/src/shared/libosmocore/include/osmocom/core/select.h
index 476c564e..18aad35f 100644
--- a/src/shared/libosmocore/include/osmocom/core/select.h
+++ b/src/shared/libosmocore/include/osmocom/core/select.h
@@ -3,20 +3,43 @@
 
 #include <osmocom/core/linuxlist.h>
 
+/*! \defgroup select Select loop abstraction
+ *  @{
+ */
+
+/*! \file select.h
+ *  \brief select loop abstraction
+ */
+
+/*! \brief Indicate interest in reading from the file descriptor */
 #define BSC_FD_READ	0x0001
+/*! \brief Indicate interest in writing to the file descriptor */
 #define BSC_FD_WRITE	0x0002
+/*! \brief Indicate interest in exceptions from the file descriptor */
 #define BSC_FD_EXCEPT	0x0004
 
+/*! \brief Structure representing a file dsecriptor */
 struct osmo_fd {
-	struct llist_head list;
+	/*! linked list for internal management */
+	struct llist_head list;	
+	/*! actual operating-system level file decriptor */
 	int fd;
+	/*! bit-mask or of \ref BSC_FD_READ, \ref BSC_FD_WRITE and/or
+	 * \ref BSC_FD_EXCEPT */
 	unsigned int when;
+	/*! call-back function to be called once file descriptor becomes
+	 * available */
 	int (*cb)(struct osmo_fd *fd, unsigned int what);
+	/*! data pointer passed through to call-back function */
 	void *data;
+	/*! private number, extending \a data */
 	unsigned int priv_nr;
 };
 
 int osmo_fd_register(struct osmo_fd *fd);
 void osmo_fd_unregister(struct osmo_fd *fd);
 int osmo_select_main(int polling);
+
+/*! }@ */
+
 #endif /* _BSC_SELECT_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/serial.h b/src/shared/libosmocore/include/osmocom/core/serial.h
new file mode 100644
index 00000000..73854251
--- /dev/null
+++ b/src/shared/libosmocore/include/osmocom/core/serial.h
@@ -0,0 +1,43 @@
+/*
+ * serial.h
+ *
+ * Copyright (C) 2011  Sylvain Munaut <tnt@246tNt.com>
+ *
+ * All Rights Reserved
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+/*! \defgroup serial Utility functions to deal with serial ports
+ *  @{
+ */
+
+/*! \file serial.h
+ *  \file Osmocom serial port helpers
+ */
+
+#ifndef __OSMO_SERIAL_H__
+#define __OSMO_SERIAL_H__
+
+#include <termios.h>
+
+int osmo_serial_init(const char *dev, speed_t baudrate);
+int osmo_serial_set_baudrate(int fd, speed_t baudrate);
+int osmo_serial_set_custom_baudrate(int fd, int baudrate);
+int osmo_serial_clear_custom_baudrate(int fd);
+
+/*! }@ */
+
+#endif /* __OSMO_SERIAL_H__ */
diff --git a/src/shared/libosmocore/include/osmocom/core/signal.h b/src/shared/libosmocore/include/osmocom/core/signal.h
index 2442e510..07d0e6fb 100644
--- a/src/shared/libosmocore/include/osmocom/core/signal.h
+++ b/src/shared/libosmocore/include/osmocom/core/signal.h
@@ -3,13 +3,18 @@
 
 #include <stdint.h>
 
+/*! \defgroup signal Intra-application signals
+ *  @{
+ */
+/*! \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. */
 #define OSMO_SIGNAL_SS_APPS		0
-#define OSMO_SIGNAL_SS_RESERVED		2147483648
+#define OSMO_SIGNAL_SS_RESERVED		2147483648u
 
-/* signal subsystems. */
+/*! \brief signal subsystems */
 enum {
 	SS_L_GLOBAL		= OSMO_SIGNAL_SS_RESERVED,
 	SS_L_INPUT,
@@ -17,13 +22,14 @@ enum {
 
 /* application-defined signal types. */
 #define OSMO_SIGNAL_T_APPS		0
-#define OSMO_SIGNAL_T_RESERVED		2147483648
+#define OSMO_SIGNAL_T_RESERVED		2147483648u
 
-/* signal types. */
+/*! \brief signal types. */
 enum {
 	S_L_GLOBAL_SHUTDOWN	= OSMO_SIGNAL_T_RESERVED,
 };
 
+/*! signal callback function type */
 typedef int osmo_signal_cbfn(unsigned int subsys, unsigned int signal, void *handler_data, void *signal_data);
 
 
@@ -34,4 +40,6 @@ void osmo_signal_unregister_handler(unsigned int subsys, osmo_signal_cbfn *cbfn,
 /* Dispatch */
 void osmo_signal_dispatch(unsigned int subsys, unsigned int signal, void *signal_data);
 
+/*! }@ */
+
 #endif /* OSMO_SIGNAL_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/socket.h b/src/shared/libosmocore/include/osmocom/core/socket.h
index 612b12c8..c5288dfc 100644
--- a/src/shared/libosmocore/include/osmocom/core/socket.h
+++ b/src/shared/libosmocore/include/osmocom/core/socket.h
@@ -1,6 +1,14 @@
 #ifndef _OSMOCORE_SOCKET_H
 #define _OSMOCORE_SOCKET_H
 
+/*! \defgroup socket Socket convenience functions
+ *  @{
+ */
+
+/*! \file socket.h
+ *  \brief Osmocom socket convenience functions
+ */
+
 #include <stdint.h>
 
 struct sockaddr;
@@ -19,7 +27,8 @@ int osmo_sock_init_ofd(struct osmo_fd *ofd, int family, int type, int proto,
 int osmo_sock_init_sa(struct sockaddr *ss, uint16_t type,
 		      uint8_t proto, unsigned int flags);
 
-/* determine if the given address is a local address */
 int osmo_sockaddr_is_local(struct sockaddr *addr, unsigned int addrlen);
 
+/*! }@ */
+
 #endif /* _OSMOCORE_SOCKET_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/statistics.h b/src/shared/libosmocore/include/osmocom/core/statistics.h
index 18493277..04816c16 100644
--- a/src/shared/libosmocore/include/osmocom/core/statistics.h
+++ b/src/shared/libosmocore/include/osmocom/core/statistics.h
@@ -1,33 +1,53 @@
 #ifndef _STATISTICS_H
 #define _STATISTICS_H
 
+/*! \file statistics.h
+ *  \brief Common routines regarding statistics */
+
+/*! structure representing a single counter */
 struct osmo_counter {
-	struct llist_head list;
-	const char *name;
-	const char *description;
-	unsigned long value;
+	struct llist_head list;		/*!< \brief internal list head */
+	const char *name;		/*!< \brief human-readable name */
+	const char *description;	/*!< \brief humn-readable description */
+	unsigned long value;		/*!< \brief current value */
 };
 
+/*! \brief Increment counter */
 static inline void osmo_counter_inc(struct osmo_counter *ctr)
 {
 	ctr->value++;
 }
 
+/*! \brief Get current value of counter */
 static inline unsigned long osmo_counter_get(struct osmo_counter *ctr)
 {
 	return ctr->value;
 }
 
+/*! \brief Reset current value of counter to 0 */
 static inline void osmo_counter_reset(struct osmo_counter *ctr)
 {
 	ctr->value = 0;
 }
 
+/*! \brief Allocate a new counter */
 struct osmo_counter *osmo_counter_alloc(const char *name);
+
+/*! \brief Free the specified counter
+ *  \param[ctr] Counter
+ */
 void osmo_counter_free(struct osmo_counter *ctr);
 
+/*! \brief Iteate over all counters
+ *  \param[in] handle_counter Call-back function
+ *  \param[in] data Private dtata handed through to \a handle_counter
+ */
 int osmo_counters_for_each(int (*handle_counter)(struct osmo_counter *, void *), void *data);
 
+/*! \brief Resolve counter by human-readable name
+ *  \param[in] name human-readable name of counter
+ *  \returns pointer to counter (\ref osmo_counter) or NULL otherwise
+ */
 struct osmo_counter *osmo_counter_get_by_name(const char *name);
 
 #endif /* _STATISTICS_H */
diff --git a/src/shared/libosmocore/include/osmocom/core/timer.h b/src/shared/libosmocore/include/osmocom/core/timer.h
index 6c2e8c50..8f8c826d 100644
--- a/src/shared/libosmocore/include/osmocom/core/timer.h
+++ b/src/shared/libosmocore/include/osmocom/core/timer.h
@@ -18,6 +18,14 @@
  *
  */
 
+/*! \defgroup timer Osmocom timers
+ *  @{
+ */
+
+/*! \file timer.h
+ *  \brief Osmocom timer handling routines
+ */
+
 #ifndef TIMER_H
 #define TIMER_H
 
@@ -41,27 +49,32 @@
  *        the timers.
  *
  */
+/*! \brief A structure representing a single instance of a timer */
 struct osmo_timer_list {
-	struct llist_head entry;
-	struct timeval timeout;
-	unsigned int active  : 1;
-	unsigned int handled : 1;
-	unsigned int in_list : 1;
-
-	void (*cb)(void*);
-	void *data;
+	struct llist_head entry;  /*!< \brief linked list header */
+	struct timeval timeout;   /*!< \brief expiration time */
+	unsigned int active  : 1; /*!< \brief is it active? */
+	unsigned int handled : 1; /*!< \brief did we already handle it */
+	unsigned int in_list : 1; /*!< \brief is it in the global list? */
+
+	void (*cb)(void*);	  /*!< \brief call-back called at timeout */
+	void *data;		  /*!< \brief user data for callback */
 };
 
 /**
  * timer management
  */
+
 void osmo_timer_add(struct osmo_timer_list *timer);
+
 void osmo_timer_schedule(struct osmo_timer_list *timer, int seconds, int microseconds);
+
 void osmo_timer_del(struct osmo_timer_list *timer);
+
 int osmo_timer_pending(struct osmo_timer_list *timer);
 
 
-/**
+/*
  * internal timer list management
  */
 struct timeval *osmo_timers_nearest(void);
@@ -69,4 +82,6 @@ void osmo_timers_prepare(void);
 int osmo_timers_update(void);
 int osmo_timers_check(void);
 
+/*! }@ */
+
 #endif
diff --git a/src/shared/libosmocore/include/osmocom/core/utils.h b/src/shared/libosmocore/include/osmocom/core/utils.h
index a1a18e30..940c25f8 100644
--- a/src/shared/libosmocore/include/osmocom/core/utils.h
+++ b/src/shared/libosmocore/include/osmocom/core/utils.h
@@ -1,18 +1,29 @@
 #ifndef OSMOCORE_UTIL_H
 #define OSMOCORE_UTIL_H
 
+/*! \defgroup utils General-purpose utility functions
+ *  @{
+ */
+
+/*! \file utils.h */
+
+/*! \brief Determine number of elements in an array of static size */
 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+/*! \brief Return the maximum of two specified values */
 #define OSMO_MAX(a, b) (a) >= (b) ? (a) : (b)
+/*! \brief Return the minimum of two specified values */
 #define OSMO_MIN(a, b) (a) >= (b) ? (b) : (a)
 
 #include <stdint.h>
 
+/*! \brief A mapping between human-readable string and numeric value */
 struct value_string {
-	unsigned int value;
-	const char *str;
+	unsigned int value;	/*!< \brief numeric value */
+	const char *str;	/*!< \brief human-readable string */
 };
 
 const char *get_value_string(const struct value_string *vs, uint32_t val);
+
 int get_string_value(const struct value_string *vs, const char *str);
 
 char osmo_bcd2char(uint8_t bcd);
@@ -20,9 +31,10 @@ char osmo_bcd2char(uint8_t bcd);
 uint8_t osmo_char2bcd(char c);
 
 int osmo_hexparse(const char *str, uint8_t *b, int max_len);
+
+char *osmo_ubit_dump(const uint8_t *bits, unsigned int len);
 char *osmo_hexdump(const unsigned char *buf, int len);
 char *osmo_osmo_hexdump_nospc(const unsigned char *buf, int len);
-char *osmo_ubit_dump(const uint8_t *bits, unsigned int len);
 
 #define osmo_static_assert(exp, name) typedef int dummy##name [(exp) ? 1 : -1];
 
@@ -38,4 +50,6 @@ do {								\
 	rem -= ret;						\
 } while (0)
 
+/*! }@ */
+
 #endif
diff --git a/src/shared/libosmocore/include/osmocom/core/write_queue.h b/src/shared/libosmocore/include/osmocom/core/write_queue.h
index 41748d72..8b896d15 100644
--- a/src/shared/libosmocore/include/osmocom/core/write_queue.h
+++ b/src/shared/libosmocore/include/osmocom/core/write_queue.h
@@ -23,18 +23,33 @@
 #ifndef OSMO_WQUEUE_H
 #define OSMO_WQUEUE_H
 
+/*! \defgroup write_queue Osmocom msgb write queues
+ *  @{
+ */
+
+/*! \file write_queue.h
+ */
+
 #include <osmocom/core/select.h>
 #include <osmocom/core/msgb.h>
 
+/*! write queue instance */
 struct osmo_wqueue {
+	/*! \brief osmocom file descriptor */
 	struct osmo_fd bfd;
+	/*! \brief maximum length of write queue */
 	unsigned int max_length;
+	/*! \brief current length of write queue */
 	unsigned int current_length;
 
+	/*! \brief actual linked list implementing the queue */
 	struct llist_head msg_queue;
 
+	/*! \brief call-back in case qeueue is readable */
 	int (*read_cb)(struct osmo_fd *fd);
+	/*! \brief call-back in case qeueue is writable */
 	int (*write_cb)(struct osmo_fd *fd, struct msgb *msg);
+	/*! \brief call-back in case qeueue has exceptions */
 	int (*except_cb)(struct osmo_fd *fd);
 };
 
@@ -43,4 +58,6 @@ void osmo_wqueue_clear(struct osmo_wqueue *queue);
 int osmo_wqueue_enqueue(struct osmo_wqueue *queue, struct msgb *data);
 int osmo_wqueue_bfd_cb(struct osmo_fd *fd, unsigned int what);
 
+/*! }@ */
+
 #endif