From de6e4983e7f83794e45af5a70b036ed9f4437ab5 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Thu, 6 Dec 2012 21:25:27 +0100 Subject: add some missing doxygen annotation for libosmocore functions --- src/bits.c | 30 ++++++++++++++++++++++++++++-- src/gsmtap_util.c | 15 ++++++++++++++- src/logging.c | 9 +++++++++ src/panic.c | 1 + src/plugin.c | 9 +++++++++ src/timer.c | 12 +++++------- src/utils.c | 10 +++++++++- 7 files changed, 75 insertions(+), 11 deletions(-) diff --git a/src/bits.c b/src/bits.c index a159fc96..f3453e5c 100644 --- a/src/bits.c +++ b/src/bits.c @@ -128,7 +128,16 @@ int osmo_pbit2ubit_ext(ubit_t *out, unsigned int out_ofs, return out_ofs + num_bits; } -/* generalized bit reversal function, Chapter 7 "Hackers Delight" */ +/*! \brief generalized bit reversal function + * \param[in] x the 32bit value to be reversed + * \param[in] k the type of reversal requested + * \returns the reversed 32bit dword + * + * This function reverses the bit order within a 32bit word. Depending + * on "k", it either reverses all bits in a 32bit dword, or the bytes in + * the dword, or the bits in each byte of a dword, or simply swaps the + * two 16bit words in a dword. See Chapter 7 "Hackers Delight" + */ uint32_t osmo_bit_reversal(uint32_t x, enum osmo_br_mode k) { if (k & 1) x = (x & 0x55555555) << 1 | (x & 0xAAAAAAAA) >> 1; @@ -140,7 +149,12 @@ uint32_t osmo_bit_reversal(uint32_t x, enum osmo_br_mode k) return x; } -/* generalized bit reversal function, Chapter 7 "Hackers Delight" */ +/*! \brief reverse the bit-order in each byte of a dword + * \param[in] x 32bit input value + * \returns 32bit value where bits of each byte have been reversed + * + * See Chapter 7 "Hackers Delight" + */ uint32_t osmo_revbytebits_32(uint32_t x) { x = (x & 0x55555555) << 1 | (x & 0xAAAAAAAA) >> 1; @@ -150,6 +164,12 @@ uint32_t osmo_revbytebits_32(uint32_t x) return x; } +/*! \brief reverse the bit order in a byte + * \param[in] x 8bit input value + * \returns 8bit value where bits order has been reversed + * + * See Chapter 7 "Hackers Delight" + */ uint32_t osmo_revbytebits_8(uint8_t x) { x = (x & 0x55) << 1 | (x & 0xAA) >> 1; @@ -159,6 +179,12 @@ uint32_t osmo_revbytebits_8(uint8_t x) return x; } +/*! \brief reverse bit-order of each byte in a buffer + * \param buf buffer containing bytes to be bit-reversed + * \param[in] length of buffer in bytes + * + * This function reverses the bits in each byte of the buffer + */ void osmo_revbytebits_buf(uint8_t *buf, int len) { unsigned int i; diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c index ce722da9..77ab0c6e 100644 --- a/src/gsmtap_util.c +++ b/src/gsmtap_util.c @@ -182,7 +182,18 @@ int gsmtap_source_init_fd(const char *host, uint16_t port) OSMO_SOCK_F_CONNECT); } -/*! \brief Add a local sink to an existing GSMTAP source and return fd */ +/*! \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. + */ int gsmtap_source_add_sink_fd(int gsmtap_fd) { struct sockaddr_storage ss; @@ -360,3 +371,5 @@ struct gsmtap_inst *gsmtap_source_init(const char *host, uint16_t port, } #endif /* HAVE_SYS_SOCKET_H */ + +/*! @} */ diff --git a/src/logging.c b/src/logging.c index f58265f7..1b94ec0b 100644 --- a/src/logging.c +++ b/src/logging.c @@ -108,6 +108,7 @@ static const struct log_info_cat internal_cat[OSMO_NUM_DLIB] = { }, }; +/*! \brief descriptive string for each log level */ /* You have to keep this in sync with the structure loglevel_strs. */ const char *loglevel_descriptions[LOGLEVEL_DEFS+1] = { "Log simply everything", @@ -318,6 +319,7 @@ void osmo_vlogp(int subsys, int level, const char *file, int line, } } +/*! \brief logging function used by DEBUGP() macro */ void logp(int subsys, const char *file, int line, int cont, const char *format, ...) { @@ -328,6 +330,7 @@ void logp(int subsys, const char *file, int line, int cont, va_end(ap); } +/*! \brief logging function used by LOGP() macro */ void logp2(int subsys, unsigned int level, const char *file, int line, int cont, const char *format, ...) { va_list ap; @@ -431,6 +434,12 @@ void log_set_log_level(struct log_target *target, int log_level) target->loglevel = log_level; } +/*! \brief Set a category filter on a given log target + * \param[in] target Log target to be affected + * \param[in] category Log category to be affected + * \param[in] enable whether to enable or disable the filter + * \param[in] level Log level of the filter + */ void log_set_category_filter(struct log_target *target, int category, int enable, int level) { diff --git a/src/panic.c b/src/panic.c index be644ff1..84bab33b 100644 --- a/src/panic.c +++ b/src/panic.c @@ -80,3 +80,4 @@ void osmo_set_panic_handler(osmo_panic_handler_t h) osmo_panic_handler = h; } +/*! @} */ diff --git a/src/plugin.c b/src/plugin.c index 998bca35..52887acf 100644 --- a/src/plugin.c +++ b/src/plugin.c @@ -20,6 +20,11 @@ * */ +/*! \file plugin.c + * \brief Routines for loading and managing shared library plug-ins. + */ + + #include "../config.h" #if HAVE_DLFCN_H @@ -32,6 +37,10 @@ #include +/*! \brief Load all plugins available in given directory + * \param[in] directory full path name of directory containing plug-ins + * \returns number of plugins loaded in case of success, negative in case of error + */ int osmo_plugin_load_all(const char *directory) { unsigned int num = 0; diff --git a/src/timer.c b/src/timer.c index 6d4abc26..98cbf6e6 100644 --- a/src/timer.c +++ b/src/timer.c @@ -154,7 +154,9 @@ int osmo_timer_remaining(const struct osmo_timer_list *timer, return 0; } -/* +/*! \brief Determine time between now and the nearest timer + * \returns pointer to timeval of nearest timer, NULL if there is none + * * if we have a nearest time return the delta between the current * time and the time of the nearest timer. * If the nearest timer timed out return NULL and then we will @@ -184,9 +186,7 @@ static void update_nearest(struct timeval *cand, struct timeval *current) } } -/* - * Find the nearest time and update s_nearest_time - */ +/*! \brief Find the nearest time and update nearest_p */ void osmo_timers_prepare(void) { struct rb_node *node; @@ -204,9 +204,7 @@ void osmo_timers_prepare(void) } } -/* - * fire all timers... and remove them - */ +/*! \brief fire all timers... and remove them */ int osmo_timers_update(void) { struct timeval current_time; diff --git a/src/utils.c b/src/utils.c index cf0c9344..c36979c9 100644 --- a/src/utils.c +++ b/src/utils.c @@ -64,12 +64,20 @@ char osmo_bcd2char(uint8_t bcd) return 'A' + (bcd - 0xa); } -/* only works for numbers in ascii */ +/*! \brief Convert number in ASCII to BCD value + * \param[in] c ASCII character + * \returns BCD encoded value of character + */ uint8_t osmo_char2bcd(char c) { return c - 0x30; } +/*! \brief Parse a string ocntaining hexadecimal digits + * \param[in] str string containing ASCII encoded hexadecimal digits + * \param[out] b output buffer + * \param[in] max_len maximum space in output buffer + */ int osmo_hexparse(const char *str, uint8_t *b, int max_len) { -- cgit v1.2.3