Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit 1d0f30a8e080fd490ec4df50d5ccfc742e771ca0

Authored by Simon Glass
Committed by Tom Rini
1 parent 20faa27c2b
Exists in smarc_8mq_lf_v2020.04 and in 17 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc-imx6_v2018.03_4.14.98_2.0.0_ga, smarc-imx7_v2018.03_4.14.98_2.0.0_ga, smarc-imx_v2018.03_4.14.78_1.0.0_ga, smarc_8m-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8m_00d0-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0

log: Add documentation 

Add documentation for the log system.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Bin Meng <bmeng.cn@gmail.com>

Showing 1 changed file with 214 additions and 0 deletions Side-by-side Diff

  1 +Logging in U-Boot
  2 +=================
  3 +
  4 +Introduction
  5 +------------
  6 +
  7 +U-Boot's internal operation involves many different steps and actions. From
  8 +setting up the board to displaying a start-up screen to loading an Operating
  9 +System, there are many component parts each with many actions.
  10 +
  11 +Most of the time this internal detail is not useful. Displaying it on the
  12 +console would delay booting (U-Boot's primary purpose) and confuse users.
  13 +
  14 +But for digging into what is happening in a particular area, or for debugging
  15 +a problem it is often useful to see what U-Boot is doing in more detail than
  16 +is visible from the basic console output.
  17 +
  18 +U-Boot's logging feature aims to satisfy this goal for both users and
  19 +developers.
  20 +
  21 +
  22 +Logging levels
  23 +--------------
  24 +
  25 +There are a number logging levels available, in increasing order of verbosity:
  26 +
  27 + LOGL_EMERG - Printed before U-Boot halts
  28 + LOGL_ALERT - Indicates action must be taken immediate or U-Boot will crash
  29 + LOGL_CRIT - Indicates a critical error that will cause boot failure
  30 + LOGL_ERR - Indicates an error that may cause boot failure
  31 + LOGL_WARNING - Warning about an unexpected condition
  32 + LOGL_NOTE - Important information about progress
  33 + LOGL_INFO - Information about normal boot progress
  34 + LOGL_DEBUG - Debug information (useful for debugging a driver or subsystem)
  35 + LOGL_DEBUG_CONTENT - Debug message showing full message content
  36 + LOGL_DEBUG_IO - Debug message showing hardware I/O access
  37 +
  38 +
  39 +Logging category
  40 +----------------
  41 +
  42 +Logging can come from a wide variety of places within U-Boot. Each log message
  43 +has a category which is intended to allow messages to be filtered according to
  44 +their source.
  45 +
  46 +The following main categories are defined:
  47 +
  48 + LOGC_NONE - Unknown category (e.g. a debug() statement)
  49 + UCLASS_... - Related to a particular uclass (e.g. UCLASS_USB)
  50 + LOGC_ARCH - Related to architecture-specific code
  51 + LOGC_BOARD - Related to board-specific code
  52 + LOGC_CORE - Related to core driver-model support
  53 + LOGC_DT - Related to device tree control
  54 +
  55 +
  56 +Enabling logging
  57 +----------------
  58 +
  59 +The following options are used to enable logging at compile time:
  60 +
  61 + CONFIG_LOG - Enables the logging system
  62 + CONFIG_MAX_LOG_LEVEL - Max log level to build (anything higher is compiled
  63 + out)
  64 + CONFIG_LOG_CONSOLE - Enable writing log records to the console
  65 +
  66 +If CONFIG_LOG is not set, then no logging will be available.
  67 +
  68 +The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL.
  69 +
  70 +
  71 +Using DEBUG
  72 +-----------
  73 +
  74 +U-Boot has traditionally used a #define called DEBUG to enable debugging on a
  75 +file-by-file basis. The debug() macro compiles to a printf() statement if
  76 +DEBUG is enabled, and an empty statement if not.
  77 +
  78 +With logging enabled, debug() statements are interpreted as logging output
  79 +with a level of LOGL_DEBUG and a category of LOGC_NONE.
  80 +
  81 +The logging facilities are intended to replace DEBUG, but if DEBUG is defined
  82 +at the top of a file, then it takes precedence. This means that debug()
  83 +statements will result in output to the console and this output will not be
  84 +logged.
  85 +
  86 +
  87 +Logging destinations
  88 +--------------------
  89 +
  90 +If logging information goes nowhere then it serves no purpose. U-Boot provides
  91 +several possible determinations for logging information, all of which can be
  92 +enabled or disabled independently:
  93 +
  94 + console - goes to stdout
  95 +
  96 +
  97 +Filters
  98 +-------
  99 +
  100 +Filters are attached to log drivers to control what those drivers emit. Only
  101 +records that pass through the filter make it to the driver.
  102 +
  103 +Filters can be based on several criteria:
  104 +
  105 + - maximum log level
  106 + - in a set of categories
  107 + - in a set of files
  108 +
  109 +If no filters are attached to a driver then a default filter is used, which
  110 +limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.
  111 +
  112 +
  113 +Logging statements
  114 +------------------
  115 +
  116 +The main logging function is:
  117 +
  118 + log(category, level, format_string, ...)
  119 +
  120 +Also debug() and error() will generate log records - these use LOG_CATEGORY
  121 +as the category, so you should #define this right at the top of the source
  122 +file to ensure the category is correct.
  123 +
  124 +
  125 +Code size
  126 +---------
  127 +
  128 +Code size impact depends largely on what is enabled. The following numbers are
  129 +for snow, which is a Thumb-2 board:
  130 +
  131 +This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
  132 +CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
  133 +CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
  134 +
  135 +The last option turns every debug() statement into a logging call, which
  136 +bloats the code hugely. The advantage is that it is then possible to enable
  137 +all logging within U-Boot.
  138 +
  139 +
  140 +To Do
  141 +-----
  142 +
  143 +There are lots of useful additions that could be made. None of the below is
  144 +implemented! If you do one, please add a test in test/py/tests/test_log.py
  145 +
  146 +Convenience functions to support setting the category:
  147 +
  148 + log_arch(level, format_string, ...) - category LOGC_ARCH
  149 + log_board(level, format_string, ...) - category LOGC_BOARD
  150 + log_core(level, format_string, ...) - category LOGC_CORE
  151 + log_dt(level, format_string, ...) - category LOGC_DT
  152 +
  153 +Convenience functions to support a category defined for a single file, for
  154 +example:
  155 +
  156 + #define LOG_CATEGORY UCLASS_USB
  157 +
  158 +all of these can use LOG_CATEGORY as the category, and a log level
  159 +corresponding to the function name:
  160 +
  161 + logc(level, format_string, ...)
  162 +
  163 +More logging destinations:
  164 +
  165 + device - goes to a device (e.g. serial)
  166 + buffer - recorded in a memory buffer
  167 +
  168 +Convert debug() statements in the code to log() statements
  169 +
  170 +Support making printf() emit log statements a L_INFO level
  171 +
  172 +Convert error() statements in the code to log() statements
  173 +
  174 +Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
  175 +
  176 +Figure out what to do with assert()
  177 +
  178 +Add a way to browse log records
  179 +
  180 +Add a way to record log records for browsing using an external tool
  181 +
  182 +Add commands to add and remove filters
  183 +
  184 +Add commands to add and remove log devices
  185 +
  186 +Allow sharing of printf format strings in log records to reduce storage size
  187 +for large numbers of log records
  188 +
  189 +Add a command-line option to sandbox to set the default logging level
  190 +
  191 +Convert core driver model code to use logging
  192 +
  193 +Convert uclasses to use logging with the correct category
  194 +
  195 +Consider making log() calls emit an automatic newline, perhaps with a logn()
  196 + function to avoid that
  197 +
  198 +Passing log records through to linux (e.g. via device tree /chosen)
  199 +
  200 +Provide a command to access the number of log records generated, and the
  201 +number dropped due to them being generated before the log system was ready.
  202 +
  203 +Add a printf() format string pragma so that log statements are checked properly
  204 +
  205 +Enhance the log console driver to show level / category / file / line
  206 +information
  207 +
  208 +Add a command to add new log records and delete existing records.
  209 +
  210 +Provide additional log() functions - e.g. logc() to specify the category
  211 +
  212 +--
  213 +Simon Glass <sjg@chromium.org>
  214 +15-Sep-17