README.log 8.7 KB

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