some more doxygen work (include the notion of modules)
diff --git a/include/osmocom/core/application.h b/include/osmocom/core/application.h
index 5d09896..3457169 100644
--- a/include/osmocom/core/application.h
+++ b/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/include/osmocom/core/bits.h b/include/osmocom/core/bits.h
index 9f8e1fb..ab4cf77 100644
--- a/include/osmocom/core/bits.h
+++ b/include/osmocom/core/bits.h
@@ -3,6 +3,10 @@
#include <stdint.h>
+/*! \defgroup bits soft, unpacked and packed bits
+ * @{
+ */
+
/*! \file bits.h
* \brief Osmocom bit level support code
*/
@@ -30,44 +34,18 @@
return pbit_bytesize;
}
-/*! \brief convert unpacked bits to packed bits, return length in bytes
- * \param[out] out output buffer of packed bits
- * \param[in] in input buffer of unpacked bits
- * \param[in] num_bits number of bits
- */
int osmo_ubit2pbit(pbit_t *out, const ubit_t *in, unsigned int num_bits);
-/*! \brief convert packed bits to unpacked bits, return length in bytes
- * \param[out] out output buffer of unpacked bits
- * \param[in] in input buffer of packed bits
- * \param[in] num_bits number of bits
- */
int osmo_pbit2ubit(ubit_t *out, const pbit_t *in, unsigned int num_bits);
-/*! \brief convert unpacked bits to packed bits (extended options)
- * \param[out] out output buffer of packed bits
- * \param[in] out_ofs offset into output buffer
- * \param[in] in input buffer of unpacked bits
- * \param[in] in_ofs offset into input buffer
- * \param[in] num_bits number of bits
- * \param[in] lsb_mode Encode bits in LSB orde instead of MSB
- * \returns length in bytes (max written offset 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);
-/*! \brief convert packed bits to unpacked bits (extended options)
- * \param[out] out output buffer of unpacked bits
- * \param[in] out_ofs offset into output buffer
- * \param[in] in input buffer of packed bits
- * \param[in] in_ofs offset into input buffer
- * \param[in] num_bits number of bits
- * \param[in] lsb_mode Encode bits in LSB orde instead of MSB
- * \returns length in bytes (max written offset 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
+/*! }@ */
+
+#endif /* _OSMO_BITS_H */
diff --git a/include/osmocom/core/bitvec.h b/include/osmocom/core/bitvec.h
index 7cb8a87..c2422e6 100644
--- a/include/osmocom/core/bitvec.h
+++ b/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/include/osmocom/core/conv.h b/include/osmocom/core/conv.h
index af676ee..db3058c 100644
--- a/include/osmocom/core/conv.h
+++ b/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 @@
/* 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 @@
/* 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 @@
const sbit_t *input, ubit_t *output);
+/*! }@ */
+
#endif /* __OSMO_CONV_H__ */
diff --git a/include/osmocom/core/msgb.h b/include/osmocom/core/msgb.h
index c579b8a..9f46e6c 100644
--- a/include/osmocom/core/msgb.h
+++ b/include/osmocom/core/msgb.h
@@ -24,6 +24,10 @@
#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'
@@ -63,46 +67,10 @@
unsigned char _data[0]; /*!< \brief optional immediate data array */
};
-/*! \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
- *
- * This function allocates a 'struct msgb' as well as the underlying
- * memory buffer for the actual message data (size specified by \a size)
- * using the talloc memory context previously set by \ref msgb_set_talloc_ctx
- */
extern struct msgb *msgb_alloc(uint16_t size, const char *name);
-
-/*! \brief Release given message buffer
- * \param[in] m Message buffer to be free'd
- */
extern void msgb_free(struct msgb *m);
-
-/*! \brief Enqueue message buffer to tail of a queue
- * \param[in] queue linked list header of queue
- * \param[in] msgb message buffer to be added to the queue
- *
- * The function will append the specified message buffer \a msg to the
- * queue implemented by \ref llist_head \a queue
- */
extern void msgb_enqueue(struct llist_head *queue, struct msgb *msg);
-
-/*! \brief Dequeue message buffer from head of queue
- * \param[in] queue linked list header of queue
- * \returns message buffer (if any) or NULL if queue empty
- *
- * The function will remove the first message buffer from the queue
- * implemented by 'ref llist_head \a queue.
- */
extern struct msgb *msgb_dequeue(struct llist_head *queue);
-
-/*! \brief Re-set all message buffer pointers
- * \param[in] m message buffer that is to be resetted
- *
- * This will re-set the various internal pointers into the underlying
- * message buffer, i.e. remvoe all headroom and treat the msgb as
- * completely empty. It also initializes the control buffer to zero.
- */
extern void msgb_reset(struct msgb *m);
#ifdef MSGB_DEBUG
@@ -367,21 +335,10 @@
/* non inline functions to ease binding */
-/*! \brief get pointer to data section of message buffer
- * \param[in] msg message buffer
- * \returns pointer to data section of message buffer
- */
uint8_t *msgb_data(const struct msgb *msg);
-
-/*! \brief get length of message buffer
- * \param[in] msg message buffer
- * \returns length of data section in message buffer
- */
uint16_t msgb_length(const struct msgb *msg);
-
-/*! \brief Set the talloc context for \ref msgb_alloc
- * \param[in] ctx talloc context to be used as root for msgb allocations
- */
void msgb_set_talloc_ctx(void *ctx);
+/*! }@ */
+
#endif /* _MSGB_H */
diff --git a/include/osmocom/core/select.h b/include/osmocom/core/select.h
index b1b8267..18aad35 100644
--- a/include/osmocom/core/select.h
+++ b/include/osmocom/core/select.h
@@ -3,6 +3,10 @@
#include <osmocom/core/linuxlist.h>
+/*! \defgroup select Select loop abstraction
+ * @{
+ */
+
/*! \file select.h
* \brief select loop abstraction
*/
@@ -32,19 +36,10 @@
unsigned int priv_nr;
};
-/*! \brief Register a new file descriptor with select loop abstraction
- * \param[in] fd osmocom file descriptor to be registered
- */
int osmo_fd_register(struct osmo_fd *fd);
-
-/*! \brief Unregister a file descriptor from select loop abstraction
- * \param[in] fd osmocom file descriptor to be unregistered
- */
void osmo_fd_unregister(struct osmo_fd *fd);
-
-/*! \brief select main loop integration
- * \param[in] polling should we pollonly (1) or block on select (0)
- */
int osmo_select_main(int polling);
+/*! }@ */
+
#endif /* _BSC_SELECT_H */
diff --git a/include/osmocom/core/socket.h b/include/osmocom/core/socket.h
index e915f78..c5288df 100644
--- a/include/osmocom/core/socket.h
+++ b/include/osmocom/core/socket.h
@@ -1,6 +1,10 @@
#ifndef _OSMOCORE_SOCKET_H
#define _OSMOCORE_SOCKET_H
+/*! \defgroup socket Socket convenience functions
+ * @{
+ */
+
/*! \file socket.h
* \brief Osmocom socket convenience functions
*/
@@ -14,53 +18,17 @@
#define OSMO_SOCK_F_BIND (1 << 1)
#define OSMO_SOCK_F_NONBLOCK (1 << 2)
-/*! \brief Initialize a socket (including bind/connect)
- * \param[in] family Address Family like AF_INET, AF_INET6, AF_UNSPEC
- * \param[in] type Socket type like SOCK_DGRAM, SOCK_STREAM
- * \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
- * \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
- *
- * This function creates a new socket of the designated \a family, \a
- * type and \a proto and optionally binds or connects it, depending on
- * the value of \a flags parameter.
- */
int osmo_sock_init(uint16_t family, uint16_t type, uint8_t proto,
const char *host, uint16_t port, unsigned int flags);
-/*! \brief Initialize a socket and fill \ref osmo_fd
- * \param[out] osmocom file descriptor (will be filled in)
- * \param[in] family Address Family like AF_INET, AF_INET6, AF_UNSPEC
- * \param[in] type Socket type like SOCK_DGRAM, SOCK_STREAM
- * \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
- * \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
- *
- * This function creates (and optionall binds/connects) a socket using
- * \ref osmo_sock_init, but also fills the \a ofd structure.
- */
int osmo_sock_init_ofd(struct osmo_fd *ofd, int family, int type, int proto,
const char *host, uint16_t port, unsigned int flags);
-/*! \brief Initialize a socket and fill \ref sockaddr
- * \param[out] ss socket address (will be filled in)
- * \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
- *
- * This function creates (and optionall binds/connects) a socket using
- * \ref osmo_sock_init, but also fills the \a ss structure.
- */
int osmo_sock_init_sa(struct sockaddr *ss, uint16_t type,
uint8_t proto, unsigned int flags);
-/*! \brief Determine if the given address is a local address
- * \param[in] addr Socket Address
- * \param[in] addrlen Length of socket address in bytes
- * \returns 1 if address is local, 0 otherwise.
- */
int osmo_sockaddr_is_local(struct sockaddr *addr, unsigned int addrlen);
+/*! }@ */
+
#endif /* _OSMOCORE_SOCKET_H */
diff --git a/include/osmocom/core/timer.h b/include/osmocom/core/timer.h
index 326a0c8..8f8c826 100644
--- a/include/osmocom/core/timer.h
+++ b/include/osmocom/core/timer.h
@@ -18,6 +18,10 @@
*
*/
+/*! \defgroup timer Osmocom timers
+ * @{
+ */
+
/*! \file timer.h
* \brief Osmocom timer handling routines
*/
@@ -61,38 +65,12 @@
* timer management
*/
-/*! \brief add a new timer to the timer management
- * \param[in] timer the timer that should be added
- */
void osmo_timer_add(struct osmo_timer_list *timer);
-/*! \brief schedule a timer at a given future relative time
- * \param[in] timer the to-be-added timer
- * \param[in] seconds number of seconds from now
- * \param[in] microseconds number of microseconds from now
- *
- * This function can be used to (re-)schedule a given timer at a
- * specified number of seconds+microseconds in the future. It will
- * internally add it to the timer management data structures, thus
- * osmo_timer_add() is automatically called.
- */
void osmo_timer_schedule(struct osmo_timer_list *timer, int seconds, int microseconds);
-/*! \brief delete a timer from timer management
- * \param[in] timer the to-be-deleted timer
- *
- * This function can be used to delete a previously added/scheduled
- * timer from the timer management code.
- */
void osmo_timer_del(struct osmo_timer_list *timer);
-/*! \brief check if given timer is still pending
- * \param[in] timer the to-be-checked timer
- * \return 1 if pending, 0 otherwise
- *
- * This function can be used to determine whether a given timer
- * has alredy expired (returns 0) or is still pending (returns 1)
- */
int osmo_timer_pending(struct osmo_timer_list *timer);
@@ -104,4 +82,6 @@
int osmo_timers_update(void);
int osmo_timers_check(void);
+/*! }@ */
+
#endif