logging.rst 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. .. Copyright (c) 2017 Simon Glass <sjg@chromium.org>
  3. Logging in U-Boot
  4. =================
  5. Introduction
  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. Most of the time this internal detail is not useful. Displaying it on the
  11. console would delay booting (U-Boot's primary purpose) and confuse users.
  12. But for digging into what is happening in a particular area, or for debugging
  13. a problem it is often useful to see what U-Boot is doing in more detail than
  14. is visible from the basic console output.
  15. U-Boot's logging feature aims to satisfy this goal for both users and
  16. developers.
  17. Logging levels
  18. --------------
  19. There are a number logging levels available.
  20. .. kernel-doc:: include/log.h
  21. :identifiers: log_level_t
  22. Logging category
  23. ----------------
  24. Logging can come from a wide variety of places within U-Boot. Each log message
  25. has a category which is intended to allow messages to be filtered according to
  26. their source.
  27. .. kernel-doc:: include/log.h
  28. :identifiers: log_category_t
  29. Enabling logging
  30. ----------------
  31. The following options are used to enable logging at compile time:
  32. * CONFIG_LOG - Enables the logging system
  33. * CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled
  34. out)
  35. * CONFIG_LOG_CONSOLE - Enable writing log records to the console
  36. If CONFIG_LOG is not set, then no logging will be available.
  37. The above have SPL and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and
  38. CONFIG_TPL_LOG_MAX_LEVEL.
  39. Temporary logging within a single file
  40. --------------------------------------
  41. Sometimes it is useful to turn on logging just in one file. You can use this
  42. .. code-block:: c
  43. #define LOG_DEBUG
  44. to enable building in of all logging statements in a single file. Put it at
  45. the top of the file, before any #includes.
  46. To actually get U-Boot to output this you need to also set the default logging
  47. level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (:c:type:`LOGL_DEBUG`) or more.
  48. Otherwise debug output is suppressed and will not be generated.
  49. Using DEBUG
  50. -----------
  51. U-Boot has traditionally used a #define called DEBUG to enable debugging on a
  52. file-by-file basis. The debug() macro compiles to a printf() statement if
  53. DEBUG is enabled, and an empty statement if not.
  54. With logging enabled, debug() statements are interpreted as logging output
  55. with a level of LOGL_DEBUG and a category of LOGC_NONE.
  56. The logging facilities are intended to replace DEBUG, but if DEBUG is defined
  57. at the top of a file, then it takes precedence. This means that debug()
  58. statements will result in output to the console and this output will not be
  59. logged.
  60. Logging statements
  61. ------------------
  62. The main logging function is:
  63. .. code-block:: c
  64. log(category, level, format_string, ...)
  65. Also debug() and error() will generate log records - these use LOG_CATEGORY
  66. as the category, so you should #define this right at the top of the source
  67. file to ensure the category is correct.
  68. You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
  69. can be used whenever your function returns an error value:
  70. .. code-block:: c
  71. return log_ret(uclass_first_device(UCLASS_MMC, &dev));
  72. This will write a log record when an error code is detected (a value < 0). This
  73. can make it easier to trace errors that are generated deep in the call stack.
  74. Convenience functions
  75. ~~~~~~~~~~~~~~~~~~~~~
  76. A number of convenience functions are available to shorten the code needed
  77. for logging:
  78. * log_err(_fmt...)
  79. * log_warning(_fmt...)
  80. * log_notice(_fmt...)
  81. * log_info(_fmt...)
  82. * log_debug(_fmt...)
  83. * log_content(_fmt...)
  84. * log_io(_fmt...)
  85. With these the log level is implicit in the name. The category is set by
  86. LOG_CATEGORY, which you can only define once per file, above all #includes, e.g.
  87. .. code-block:: c
  88. #define LOG_CATEGORY LOGC_ALLOC
  89. or
  90. .. code-block:: c
  91. #define LOG_CATEGORY UCLASS_SPI
  92. Remember that all uclasses IDs are log categories too.
  93. Logging destinations
  94. --------------------
  95. If logging information goes nowhere then it serves no purpose. U-Boot provides
  96. several possible determinations for logging information, all of which can be
  97. enabled or disabled independently:
  98. * console - goes to stdout
  99. * syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514
  100. The syslog driver sends the value of environmental variable 'log_hostname' as
  101. HOSTNAME if available.
  102. Filters
  103. -------
  104. Filters are attached to log drivers to control what those drivers emit. FIlters
  105. can either allow or deny a log message when they match it. Only records which
  106. are allowed by a filter make it to the driver.
  107. Filters can be based on several criteria:
  108. * minimum or maximum log level
  109. * in a set of categories
  110. * in a set of files
  111. If no filters are attached to a driver then a default filter is used, which
  112. limits output to records with a level less than CONFIG_MAX_LOG_LEVEL.
  113. Log command
  114. -----------
  115. The 'log' command provides access to several features:
  116. * level - list log levels or set the default log level
  117. * categories - list log categories
  118. * drivers - list log drivers
  119. * filter-list - list filters
  120. * filter-add - add a new filter
  121. * filter-remove - remove filters
  122. * format - access the console log format
  123. * rec - output a log record
  124. Type 'help log' for details.
  125. Log format
  126. ~~~~~~~~~~
  127. You can control the log format using the 'log format' command. The basic
  128. format is::
  129. LEVEL.category,file.c:123-func() message
  130. In the above, file.c:123 is the filename where the log record was generated and
  131. func() is the function name. By default ('log format default') only the message
  132. is displayed on the console. You can control which fields are present, but not
  133. the field order.
  134. Adding Filters
  135. ~~~~~~~~~~~~~~
  136. To add new filters at runtime, use the 'log filter-add' command. For example, to
  137. suppress messages from the SPI and MMC subsystems, run::
  138. log filter-add -D -c spi -c mmc
  139. You will also need to add another filter to allow other messages (because the
  140. default filter no longer applies)::
  141. log filter-add -A -l info
  142. Log levels may be either symbolic names (like above) or numbers. For example, to
  143. disable all debug and above (log level 7) messages from ``drivers/core/lists.c``
  144. and ``drivers/core/ofnode.c``, run::
  145. log filter-add -D -f drivers/core/lists.c,drivers/core/ofnode.c -L 7
  146. To view active filters, use the 'log filter-list' command. Some example output
  147. is::
  148. => log filter-list
  149. num policy level categories files
  150. 2 deny >= DEBUG drivers/core/lists.c,drivers/core/ofnode.c
  151. 0 deny <= IO spi
  152. mmc
  153. 1 allow <= INFO
  154. Note that filters are processed in-order from top to bottom, not in the order of
  155. their filter number. Filters are added to the top of the list if they deny when
  156. they match, and to the bottom if they allow when they match. For more
  157. information, consult the usage of the 'log' command, by running 'help log'.
  158. Code size
  159. ---------
  160. Code size impact depends largely on what is enabled. The following numbers are
  161. generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in
  162. bytes)::
  163. This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
  164. CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
  165. CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
  166. The last option turns every debug() statement into a logging call, which
  167. bloats the code hugely. The advantage is that it is then possible to enable
  168. all logging within U-Boot.
  169. To Do
  170. -----
  171. There are lots of useful additions that could be made. None of the below is
  172. implemented! If you do one, please add a test in test/log/log_test.c
  173. log filter-add -D -f drivers/core/lists.c,drivers/core/ofnode.c -l 6
  174. Convenience functions to support setting the category:
  175. * log_arch(level, format_string, ...) - category LOGC_ARCH
  176. * log_board(level, format_string, ...) - category LOGC_BOARD
  177. * log_core(level, format_string, ...) - category LOGC_CORE
  178. * log_dt(level, format_string, ...) - category LOGC_DT
  179. More logging destinations:
  180. * device - goes to a device (e.g. serial)
  181. * buffer - recorded in a memory buffer
  182. Convert debug() statements in the code to log() statements
  183. Support making printf() emit log statements at L_INFO level
  184. Convert error() statements in the code to log() statements
  185. Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
  186. Add a way to browse log records
  187. Add a way to record log records for browsing using an external tool
  188. Add commands to add and remove log devices
  189. Allow sharing of printf format strings in log records to reduce storage size
  190. for large numbers of log records
  191. Consider making log() calls emit an automatic newline, perhaps with a logn()
  192. function to avoid that
  193. Passing log records through to linux (e.g. via device tree /chosen)
  194. Provide a command to access the number of log records generated, and the
  195. number dropped due to them being generated before the log system was ready.
  196. Add a printf() format string pragma so that log statements are checked properly
  197. Add a command to delete existing log records.
  198. Logging API
  199. -----------
  200. .. kernel-doc:: include/log.h
  201. :internal: