diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/application.c | 2 | ||||
| -rw-r--r-- | src/backtrace.c | 2 | ||||
| -rw-r--r-- | src/bitcomp.c | 16 | ||||
| -rw-r--r-- | src/bits.c | 1 | ||||
| -rw-r--r-- | src/bitvec.c | 51 | ||||
| -rw-r--r-- | src/crc16.c | 14 | ||||
| -rw-r--r-- | src/gsmtap_util.c | 21 | ||||
| -rw-r--r-- | src/logging.c | 57 | ||||
| -rw-r--r-- | src/macaddr.c | 27 | ||||
| -rw-r--r-- | src/msgb.c | 1 | ||||
| -rw-r--r-- | src/panic.c | 25 | ||||
| -rw-r--r-- | src/prim.c | 2 | ||||
| -rw-r--r-- | src/rate_ctr.c | 23 | ||||
| -rw-r--r-- | src/select.c | 6 | ||||
| -rw-r--r-- | src/signal.c | 1 | ||||
| -rw-r--r-- | src/socket.c | 6 | ||||
| -rw-r--r-- | src/timer.c | 2 | ||||
| -rw-r--r-- | src/write_queue.c | 2 |
18 files changed, 212 insertions, 47 deletions
diff --git a/src/application.c b/src/application.c index 9c3fe52b..8a325c8a 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 5b93becb..6cd798c5 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 bf359274..8b3090e6 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) { @@ -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 a92fd716..88343c4f 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 2741cf53..9dd46727 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 82690a9c..7a63771a 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 4d6fd40d..b2f8d437 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 a6e1304a..f83e0546 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 + +/*! @} */ @@ -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 84bab33b..0ce50db2 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; @@ -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 436deef9..f995f3fd 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 02bc2cc3..192cae2f 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 63843849..84025915 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 567939b7..7e610bf3 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 21b7015e..0358b89e 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 9a8b05c4..3e488aea 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) { |