From 18fc465b7ff9818338fa8eb350ee4f20c9acb2c8 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Wed, 17 Aug 2011 14:14:17 +0200 Subject: doxygen documentation for logging framework --- include/osmocom/core/logging.h | 69 +++++++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 25 deletions(-) (limited to 'include/osmocom/core/logging.h') diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h index 537dc609..94762118 100644 --- a/include/osmocom/core/logging.h +++ b/include/osmocom/core/logging.h @@ -1,10 +1,12 @@ #ifndef _OSMOCORE_LOGGING_H #define _OSMOCORE_LOGGING_H -/*! \file logging.h - * \brief Osmocom logging framework +/*! \defgroup logging Osmocom logging framework + * @{ */ +/*! \file logging.h */ + #include #include #include @@ -45,12 +47,12 @@ void logp(int subsys, char *file, int line, int cont, const char *format, ...) _ #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 @@ -68,53 +70,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 { @@ -133,6 +149,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); }; @@ -169,12 +191,7 @@ struct log_target *log_target_create_syslog(const char *ident, int option, int facility); int log_target_file_reopen(struct log_target *tgt); -/*! \brief Add a new logging target - */ void log_add_target(struct log_target *target); - -/*! \brief Deelete an existing logging target - */ void log_del_target(struct log_target *target); /* Generate command string for VTY use */ @@ -184,4 +201,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 */ -- cgit v1.2.3