@@ -49,6 +49,10 @@ void connman_debug(const char *format, ...)
} \
} while (0)
+/**
+ * Debug-level logging descriptor that may be used to control debug
+ * output on a per-file or -symbol basis.
+ */
struct connman_debug_desc {
const char *name;
const char *file;
@@ -58,12 +62,45 @@ struct connman_debug_desc {
unsigned int flags;
} __attribute__((aligned(8)));
+/**
+ * @def CONNMAN_DEBUG_DESC_INSTANTIATE(symbol, _name, _file, _flags)
+ *
+ * @brief
+ * Convenience preprocessor macro for declaring and instantiating an
+ * instance of #connmand_debug_desc.
+ *
+ * @param[in] symbol The name of the #connman_debug_desc instance
+ * to instantiate.
+ * @param[in] _name An optional pointer to an immutable null-
+ * terminated C string containing the name of
+ * the #connman_debug_desc- controlled symbol.
+ * @param[in] _file A pointer to an immutable null-terminated C
+ * string containing the name of the
+ * #connman_debug_desc-controlled source file.
+ * @param[in] _flags Flags that control the interpretation and
+ * behavior of the instantiated
+ * #connman_debug_desc instance.
+ *
+ */
#define CONNMAN_DEBUG_DESC_INSTANTIATE(symbol, _name, _file, _flags) \
static struct connman_debug_desc symbol \
__attribute__((used, section("__debug"), aligned(8))) = { \
.name = _name, .file = _file, .flags = _flags \
}
+/**
+ * @def CONNMAN_DEBUG_ALIAS(suffix)
+ *
+ * @brief
+ * Convenience preprocessor macro for declaring and instantiating
+ * an alias (see #CONNMAN_DEBUG_FLAG_ALIAS) instance of
+ * #connmand_debug_desc.
+ *
+ * @param[in] suffix The suffix to concatenate to the name of the
+ * #connman_debug_desc alias instance to
+ * instantiate.
+ *
+ */
#define CONNMAN_DEBUG_ALIAS(suffix) \
CONNMAN_DEBUG_DESC_INSTANTIATE(__debug_alias_##suffix, \
#suffix, \
@@ -71,12 +108,34 @@ struct connman_debug_desc {
CONNMAN_DEBUG_FLAG_ALIAS)
/**
- * DBG:
- * @fmt: format string
- * @arg...: list of arguments
+ * @def DBG(fmt, arg...)
+ *
+ * @brief
+ * Convenience preprocessor macro for declaring an instance of
+ * #connmand_debug_desc for controlling an invocation of
+ * #connman_debug with it that includes both the file and function
+ * name the macro was invoked in.
+ *
+ * This instantiates a scoped-instance of #connmand_debug_desc and
+ * then, if that instance has its #CONNMAN_DEBUG_FLAG_PRINT flag
+ * asserted, invokes a call to #connman_debug with the format:
+ *
+ * "<file>:<function>() <fmt> ..."
+ *
+ * where <file> is the preprocessor symbol __FILE__, <function> is
+ * the preprocessor symbol __func__, <fmt> is from @a fmt, and
+ * '...' is from @a 'arg...'.
+ *
+ * @param[in] fmt A pointer to an immutable null-terminated C
+ * string container the log message, consisting
+ * of a printf-style format string composed of
+ * zero or more output conversion directives.
+ * @param[in] arg... A variadic argument list, where each
+ * argument corresponds with its peer output
+ * conversion directive in @a fmt.
+ *
+ * @sa connman_debug
*
- * Simple macro around connman_debug() which also include the function
- * name it is called in.
*/
#define DBG(fmt, arg...) do { \
CONNMAN_DEBUG_DESC_INSTANTIATE(__connman_debug_desc, \
This adds documentation to the following debugging- / debug logging-related data types and preprocessor macros: * connman_debug_desc * CONNMAN_DEBUG_DESC_INSTANTIATE * CONNMAN_DEBUG_ALIAS and expands the existing documentation for the 'DBG' preprocessor macro. --- include/log.h | 69 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 5 deletions(-)