colibri_imx6: fix video stdout in default environment

[oweals/u-boot.git] / doc / README.log

diff --git a/doc/README.log b/doc/README.log
index 54d9a8e1b90ea4f13418390522c49a6b86ed113d..1057981f452eda35a58f302e034bb742ca9cfb88 100644 (file)
--- a/doc/README.log
+++ b/doc/README.log
@@ -51,6 +51,7 @@ The following main categories are defined:
    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
 
 
 Enabling logging
@@ -68,6 +69,47 @@ If CONFIG_LOG is not set, then no logging will be available.
 The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL.
 
 
+Temporary logging within a single file
+--------------------------------------
+
+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.
+
+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 (LOGL_DEBUG) or more. Otherwise
+debug output is suppressed and will not be generated.
+
+
+Convenience functions
+---------------------
+
+A number of convenience functions are available to shorten the code needed
+for logging:
+
+       log_err(_fmt...)
+       log_warning(_fmt...)
+       log_notice(_fmt...)
+       log_info(_fmt...)
+       log_debug(_fmt...)
+       log_content(_fmt...)
+       log_io(_fmt...)
+
+With these the log level is implicit in the name. The category is set by
+LOG_CATEGORY, which you can only define once per file, above all #includes:
+
+       #define LOG_CATEGORY LOGC_ALLOC
+
+or
+
+       #define LOG_CATEGORY UCLASS_SPI
+
+Remember that all uclasses IDs are log categories too.
+
+
 Log commands
 ------------
 
@@ -105,7 +147,10 @@ several possible determinations for logging information, all of which can be
 enabled or disabled independently:
 
    console - goes to stdout
+   syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514
 
+The syslog driver sends the value of environmental variable 'log_hostname' as
+HOSTNAME if available.
 
 Log format
 ----------
@@ -148,12 +193,21 @@ 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:
+
+   return log_ret(uclass_first_device(UCLASS_MMC, &dev));
+
+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.
+
 
 Code size
 ---------
 
 Code size impact depends largely on what is enabled. The following numbers are
-for snow, which is a Thumb-2 board:
+generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in
+bytes):
 
 This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
 CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
@@ -177,16 +231,6 @@ Convenience functions to support setting the category:
    log_core(level, format_string, ...) - category LOGC_CORE
    log_dt(level, format_string, ...) - category LOGC_DT
 
-Convenience functions to support a category defined for a single file, for
-example:
-
-   #define LOG_CATEGORY   UCLASS_USB
-
-all of these can use LOG_CATEGORY as the category, and a log level
-corresponding to the function name:
-
-   logc(level, format_string, ...)
-
 More logging destinations:
 
    device - goes to a device (e.g. serial)