This updates logging documentation with some examples of the new commands
added in the previous commits. It also removes some items from the to-do
list which have been implemented.
Signed-off-by: Sean Anderson
Reviewed-by: Simon Glass
---
Changes in v4:
- Add some more examples to docs
Changes in v3:
- Fix heading level of Filters section
- Remove a few more already-implemented features from the TODO list
Changes in v2:
- Add a few informational commands
- Clarify wording of filter documentation
- Include enum definitions instead of re-documenting them
- Reorganize log documentation; related sections should now be more proximate
doc/develop/logging.rst | 221
1 file changed, 110 insertions(+), 111 deletions(-)
diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst
index 52ccd2009e..7fdd1132ef 100644
--- a/doc/develop/logging.rst
+++ b/doc/develop/logging.rst
@@ -21,23 +21,13 @@ is visible from the basic console output.
U-Boot's logging feature aims to satisfy this goal for both users and
developers.
-
Logging levels
--
-There are a number logging levels available, in increasing order of verbosity:
-
-* LOGL_EMERG - Printed before U-Boot halts
-* LOGL_ALERT - Indicates action must be taken immediate or U-Boot will crash
-* LOGL_CRIT - Indicates a critical error that will cause boot failure
-* LOGL_ERR - Indicates an error that may cause boot failure
-* LOGL_WARNING - Warning about an unexpected condition
-* LOGL_NOTE - Important information about progress
-* LOGL_INFO - Information about normal boot progress
-* LOGL_DEBUG - Debug information (useful for debugging a driver or subsystem)
-* LOGL_DEBUG_CONTENT - Debug message showing full message content
-* LOGL_DEBUG_IO - Debug message showing hardware I/O access
+There are a number logging levels available.
+.. kernel-doc:: include/log.h
+ :identifiers: log_level_t
Logging category
@@ -46,16 +36,8 @@ Logging can come from a wide variety of places within
U-Boot. Each log message
has a category which is intended to allow messages to be filtered according to
their source.
-The following main categories are defined:
-
-* LOGC_NONE - Unknown category (e.g. a debug() statement)
-* UCLASS\_... - Related to a particular uclass (e.g. UCLASS_USB)
-* LOGC_ARCH - Related to architecture-specific code
-* LOGC_BOARD - Related to board-specific code
-* LOGC_CORE - Related to core driver-model support
-* LOGC_DT - Related to device tree control
-* LOGC_EFI - Related to EFI implementation
-
+.. kernel-doc:: include/log.h
+ :identifiers: log_category_t
Enabling logging
@@ -72,7 +54,6 @@ If CONFIG_LOG is not set, then no logging will be available.
The above have SPL and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and
CONFIG_TPL_LOG_MAX_LEVEL.
-
Temporary logging within a single file
--
@@ -83,12 +64,52 @@ Sometimes it is useful to turn on logging just in one file.
You can use this
#define LOG_DEBUG
to enable building in of all logging statements in a single file. Put it at
-the top of the file, before any #includes. This overrides any log-level setting
-in U-Boot, including CONFIG_LOG_DEFAULT_LEVEL, but just for that file.
+the top of the file, before any #includes.
+To actually get U-Boot to output this you need to also set the default logging
+level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (:c:type:`LOGL_DEBUG`) or more.
+Otherwise debug output is suppressed and will not be generated.
+
+Using DEBUG
+---
+
+U-Boot has traditionally used a #define called DEBUG to enable debugging on a
+file-by-file basis. The debug() macro compiles to a printf() statement if
+DEBUG is enabled, and an empty statement if not.
+
+With logging enabled, debug() statements are interpreted as logging output
+with a level of LOGL_DEBUG and a category of LOGC_NONE.
+
+The logging facilities are intended to replace DEBUG, but if DEBUG is defined
+at the top of a file, then it takes precedence. This means that debug()
+statements will result in output to the console and this output will not be
+logged.
+
+Logging statements
+--
+
+The main logging function is:
+
+.. code-block:: c
+
+ log(category, level, format_string, ...)
+
+Also debug() and error() will generate log records - these use LOG_CATEGORY
+as the category, so you should #define this right at the top of the source
+file to ensure the category is correct.
+
+You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
+can be used whenever your function returns an error value:
+
+.. code-block:: c
+
+ return log_ret(uclass_first_device(UCLASS_MMC, ));
+
+This will write a log record when an error code is detected (a value < 0). This
+can make it easier to trace errors that are generated deep in the call stack.
Convenience functions
--
+~
A number of convenience
