doxygen documentation for logging framework
diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h
index 537dc60..9476211 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 <stdio.h>
#include <stdint.h>
#include <osmocom/core/linuxlist.h>
@@ -45,12 +47,12 @@
#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 @@
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 @@
} 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 @@
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 @@
struct log_target *log_target_find(int type, const char *fname);
extern struct llist_head osmo_log_target_list;
+/*! }@ */
+
#endif /* _OSMOCORE_LOGGING_H */