[PATCH 17/18] doc: Add log kerneldocs to documentation
Sean Anderson
seanga2 at gmail.com
Tue Oct 6 21:16:09 CEST 2020
The functions in log.h are already mostly documented, so add them to the
generated documentation. This commit adds no new documentation, so several
enum members are left undocumented.
Signed-off-by: Sean Anderson <seanga2 at gmail.com>
---
doc/develop/logging.rst | 5 ++
include/log.h | 118 +++++++++++++++++++++++++---------------
2 files changed, 79 insertions(+), 44 deletions(-)
diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst
index 7ce8482ab6..6a22062073 100644
--- a/doc/develop/logging.rst
+++ b/doc/develop/logging.rst
@@ -288,3 +288,8 @@ information
Add a command to add new log records and delete existing records.
Provide additional log() functions - e.g. logc() to specify the category
+
+Logging API
+-----------
+.. kernel-doc:: include/log.h
+ :internal:
diff --git a/include/log.h b/include/log.h
index 4e5e3159f6..bbc8d94acb 100644
--- a/include/log.h
+++ b/include/log.h
@@ -17,18 +17,30 @@
struct cmd_tbl;
-/** Log levels supported, ranging from most to least important */
+/**
+ * enum log_level_t - Log levels supported, ranging from most to least important
+ */
enum log_level_t {
- LOGL_EMERG = 0, /* U-Boot is unstable */
- LOGL_ALERT, /* Action must be taken immediately */
- LOGL_CRIT, /* Critical conditions */
- LOGL_ERR, /* Error that prevents something from working */
- LOGL_WARNING, /* Warning may prevent optimial operation */
- LOGL_NOTICE, /* Normal but significant condition, printf() */
- LOGL_INFO, /* General information message */
- LOGL_DEBUG, /* Basic debug-level message */
- LOGL_DEBUG_CONTENT, /* Debug message showing full message content */
- LOGL_DEBUG_IO, /* Debug message showing hardware I/O access */
+ /** @LOGL_EMERG: U-Boot is unstable */
+ LOGL_EMERG = 0,
+ /** @LOGL_ALERT: Action must be taken immediately */
+ LOGL_ALERT,
+ /** @LOGL_CRIT: Critical conditions */
+ LOGL_CRIT,
+ /** @LOGL_ERR: Error that prevents something from working */
+ LOGL_ERR,
+ /** @LOGL_WARNING: Warning may prevent optimial operation */
+ LOGL_WARNING,
+ /** @LOGL_NOTICE: Normal but significant condition, printf() */
+ LOGL_NOTICE,
+ /** @LOGL_INFO: General information message */
+ LOGL_INFO,
+ /** @LOGL_DEBUG: Basic debug-level message */
+ LOGL_DEBUG,
+ /** @LOGL_DEBUG_CONTENT: Debug message showing full message content */
+ LOGL_DEBUG_CONTENT,
+ /** @LOGL_DEBUG_IO: Debug message showing hardware I/O access */
+ LOGL_DEBUG_IO,
LOGL_COUNT,
LOGL_NONE,
@@ -38,28 +50,42 @@ enum log_level_t {
};
/**
- * Log categories supported. Most of these correspond to uclasses (i.e.
- * enum uclass_id) but there are also some more generic categories
+ * enum log_category_t - Log categories supported.
+ *
+ * Most of these correspond to uclasses (i.e. &enum uclass_id) but there are
+ * also some more generic categories
*/
enum log_category_t {
LOGC_FIRST = 0, /* First part mirrors UCLASS_... */
LOGC_NONE = UCLASS_COUNT, /* First number is after all uclasses */
- LOGC_ARCH, /* Related to arch-specific code */
- LOGC_BOARD, /* Related to board-specific code */
- LOGC_CORE, /* Related to core features (non-driver-model) */
- LOGC_DM, /* Core driver-model */
- LOGC_DT, /* Device-tree */
- LOGC_EFI, /* EFI implementation */
- LOGC_ALLOC, /* Memory allocation */
- LOGC_SANDBOX, /* Related to the sandbox board */
- LOGC_BLOBLIST, /* Bloblist */
- LOGC_DEVRES, /* Device resources (devres_... functions) */
- /* Advanced Configuration and Power Interface (ACPI) */
+ /** @LOGC_ARCH: Related to arch-specific code */
+ LOGC_ARCH,
+ /** @LOGC_BOARD: Related to board-specific code */
+ LOGC_BOARD,
+ /** @LOGC_CORE: Related to core features (non-driver-model) */
+ LOGC_CORE,
+ /** @LOGC_DM: Core driver-model */
+ LOGC_DM,
+ /** @LOGC_DT: Device-tree */
+ LOGC_DT,
+ /** @LOGC_EFI: EFI implementation */
+ LOGC_EFI,
+ /** @LOGC_ALLOC: Memory allocation */
+ LOGC_ALLOC,
+ /** @LOGC_SANDBOX: Related to the sandbox board */
+ LOGC_SANDBOX,
+ /** @LOGC_BLOBLIST: Bloblist */
+ LOGC_BLOBLIST,
+ /** @LOGC_DEVRES: Device resources (``devres_...`` functions) */
+ LOGC_DEVRES,
+ /** @LOGC_ACPI: Advanced Configuration and Power Interface (ACPI) */
LOGC_ACPI,
- LOGC_COUNT, /* Number of log categories */
- LOGC_END, /* Sentinel value for a list of log categories */
+ /** @LOGC_COUNT: Number of log categories */
+ LOGC_COUNT,
+ /** @LOGC_END: Sentinel value for lists of log categories */
+ LOGC_END,
};
/* Helper to cast a uclass ID to a log category */
@@ -78,7 +104,7 @@ static inline int log_uc_cat(enum uclass_id id)
* @func: Function where log record was generated
* @fmt: printf() format string for log record
* @...: Optional parameters, according to the format string @fmt
- * @return 0 if log record was emitted, -ve on error
+ * Return: 0 if log record was emitted, -ve on error
*/
int _log(enum log_category_t cat, enum log_level_t level, const char *file,
int line, const char *func, const char *fmt, ...)
@@ -231,7 +257,7 @@ void __assert_fail(const char *assertion, const char *file, unsigned int line,
* full pathname as it may be huge. Only use this when the user should be
* warning, similar to BUG_ON() in linux.
*
- * @return true if assertion succeeded (condition is true), else false
+ * Return: true if assertion succeeded (condition is true), else false
*/
#define assert_noisy(x) \
({ bool _val = (x); \
@@ -304,8 +330,9 @@ struct log_device;
*/
struct log_driver {
const char *name;
+
/**
- * emit() - emit a log record
+ * @emit: emit a log record
*
* Called by the log system to pass a log record to a particular driver
* for processing. The filter is checked before calling this function.
@@ -359,7 +386,7 @@ enum log_filter_flags {
* @filter_num: Sequence number of this filter. This is returned when adding a
* new filter, and must be provided when removing a previously added
* filter.
- * @flags: Flags for this filter (LOGFF_...)
+ * @flags: Flags for this filter (``LOGFF_...``)
* @cat_list: List of categories to allow (terminated by LOGC_END). If empty
* then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
* can be provided
@@ -384,8 +411,8 @@ struct log_filter {
* log_get_cat_name() - Get the name of a category
*
* @cat: Category to look up
- * @return category name (which may be a uclass driver name) if found, or
- * "<invalid>" if invalid, or "<missing>" if not found
+ * Return: category name (which may be a uclass driver name) if found, or
+ * "<invalid>" if invalid, or "<missing>" if not found
*/
const char *log_get_cat_name(enum log_category_t cat);
@@ -393,7 +420,7 @@ const char *log_get_cat_name(enum log_category_t cat);
* log_get_cat_by_name() - Look up a category by name
*
* @name: Name to look up
- * @return category ID, or LOGC_NONE if not found
+ * Return: category ID, or LOGC_NONE if not found
*/
enum log_category_t log_get_cat_by_name(const char *name);
@@ -401,7 +428,7 @@ enum log_category_t log_get_cat_by_name(const char *name);
* log_get_level_name() - Get the name of a log level
*
* @level: Log level to look up
- * @return log level name (in ALL CAPS)
+ * Return: log level name (in ALL CAPS)
*/
const char *log_get_level_name(enum log_level_t level);
@@ -409,7 +436,7 @@ const char *log_get_level_name(enum log_level_t level);
* log_get_level_by_name() - Look up a log level by name
*
* @name: Name to look up
- * @return log level ID, or LOGL_NONE if not found
+ * Return: log level ID, or LOGL_NONE if not found
*/
enum log_level_t log_get_level_by_name(const char *name);
@@ -417,7 +444,7 @@ enum log_level_t log_get_level_by_name(const char *name);
* log_device_find_by_name() - Look up a log device by its driver's name
*
* @drv_name: Name of the driver
- * @return the log device, or NULL if not found
+ * Return: the log device, or NULL if not found
*/
struct log_device *log_device_find_by_name(const char *drv_name);
@@ -442,15 +469,16 @@ int do_log_test(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]);
*
* @drv_name: Driver name to add the filter to (since each driver only has a
* single device)
- * @flags: Flags for this filter (LOGFF_...)
+ * @flags: Flags for this filter (``LOGFF_...``)
* @cat_list: List of categories to allow (terminated by LOGC_none). If empty
* then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries
* can be provided
* @level: Maximum (or minimum, if LOGFF_LEVEL_MIN) log level to allow
* @file_list: List of files to allow, separated by comma. If NULL then all
* files are permitted
- * @return the sequence number of the new filter (>=0) if the filter was added,
- * or a -ve value on error
+ * Return:
+ * the sequence number of the new filter (>=0) if the filter was added, or a
+ * -ve value on error
*/
int log_add_filter_flags(const char *drv_name, enum log_category_t cat_list[],
enum log_level_t level, const char *file_list,
@@ -467,8 +495,9 @@ int log_add_filter_flags(const char *drv_name, enum log_category_t cat_list[],
* @max_level: Maximum log level to allow
* @file_list: List of files to allow, separated by comma. If NULL then all
* files are permitted
- * @return the sequence number of the new filter (>=0) if the filter was added,
- * or a -ve value on error
+ * Return:
+ * the sequence number of the new filter (>=0) if the filter was added, or a
+ * -ve value on error
*/
static inline int log_add_filter(const char *drv_name,
enum log_category_t cat_list[],
@@ -485,8 +514,9 @@ static inline int log_add_filter(const char *drv_name,
* @drv_name: Driver name to remove the filter from (since each driver only has
* a single device)
* @filter_num: Filter number to remove (as returned by log_add_filter())
- * @return 0 if the filter was removed, -ENOENT if either the driver or the
- * filter number was not found
+ * Return:
+ * 0 if the filter was removed, -ENOENT if either the driver or the filter
+ * number was not found
*/
int log_remove_filter(const char *drv_name, int filter_num);
@@ -494,7 +524,7 @@ int log_remove_filter(const char *drv_name, int filter_num);
/**
* log_init() - Set up the log system ready for use
*
- * @return 0 if OK, -ENOMEM if out of memory
+ * Return: 0 if OK, -ENOMEM if out of memory
*/
int log_init(void);
#else
--
2.28.0
More information about the U-Boot
mailing list