Merge tag 'dm-pull-12jun20' of git://git.denx.de/u-boot-dm into next

patman improvements to allow it to work with Zephyr
change to how sequence numbers are assigned to devices
minor fixes and improvements

4 files changed, 296 insertions, 4 deletions

diff --git a/doc/README.log b/doc/README.log
index 1057981f45..ba838824a9 100644
--- a/doc/README.log
+++ b/doc/README.log
@@ -60,13 +60,14 @@ Enabling logging
 The following options are used to enable logging at compile time:
 
    CONFIG_LOG		- Enables the logging system
-   CONFIG_MAX_LOG_LEVEL - Max log level to build (anything higher is compiled
+   CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled
 				out)
    CONFIG_LOG_CONSOLE	- Enable writing log records to the console
 
 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.
+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
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 072db63b5c..eb5095a9eb 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -8,3 +8,4 @@ Develop U-Boot
    :maxdepth: 2
 
    crash_dumps
+   logging
diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst
new file mode 100644
index 0000000000..7ce8482ab6
--- /dev/null
+++ b/doc/develop/logging.rst
@@ -0,0 +1,290 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2017 Simon Glass <sjg@chromium.org>
+
+Logging in U-Boot
+=================
+
+Introduction
+------------
+
+U-Boot's internal operation involves many different steps and actions. From
+setting up the board to displaying a start-up screen to loading an Operating
+System, there are many component parts each with many actions.
+
+Most of the time this internal detail is not useful. Displaying it on the
+console would delay booting (U-Boot's primary purpose) and confuse users.
+
+But for digging into what is happening in a particular area, or for debugging
+a problem it is often useful to see what U-Boot is doing in more detail than
+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
+
+
+Logging category
+----------------
+
+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
+
+
+Enabling logging
+----------------
+
+The following options are used to enable logging at compile time:
+
+* CONFIG_LOG - Enables the logging system
+* CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled
+  out)
+* CONFIG_LOG_CONSOLE - Enable writing log records to the console
+
+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
+--------------------------------------
+
+Sometimes it is useful to turn on logging just in one file. You can use this
+
+.. code-block:: c
+
+   #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, e.g.
+
+.. code-block:: c
+
+	#define LOG_CATEGORY LOGC_ALLOC
+
+Remember that all uclasses IDs are log categories too.
+
+
+Log command
+-----------
+
+The 'log' command provides access to several features:
+
+* level - access the default log level
+* format - access the console log format
+* rec - output a log record
+* test - run tests
+
+Type 'help log' for details.
+
+
+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 destinations
+--------------------
+
+If logging information goes nowhere then it serves no purpose. U-Boot provides
+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
+----------
+
+You can control the log format using the 'log format' command. The basic
+format is::
+
+   LEVEL.category,file.c:123-func() message
+
+In the above, file.c:123 is the filename where the log record was generated and
+func() is the function name. By default ('log format default') only the
+function name and message are displayed on the console. You can control which
+fields are present, but not the field order.
+
+
+Filters
+-------
+
+Filters are attached to log drivers to control what those drivers emit. Only
+records that pass through the filter make it to the driver.
+
+Filters can be based on several criteria:
+
+* maximum log level
+* in a set of categories
+* in a set of files
+
+If no filters are attached to a driver then a default filter is used, which
+limits output to records with a level less than CONFIG_MAX_LOG_LEVEL.
+
+
+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, &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
+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
+    CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
+
+The last option turns every debug() statement into a logging call, which
+bloats the code hugely. The advantage is that it is then possible to enable
+all logging within U-Boot.
+
+
+To Do
+-----
+
+There are lots of useful additions that could be made. None of the below is
+implemented! If you do one, please add a test in test/py/tests/test_log.py
+
+Convenience functions to support setting the category:
+
+* log_arch(level, format_string, ...) - category LOGC_ARCH
+* log_board(level, format_string, ...) - category LOGC_BOARD
+* log_core(level, format_string, ...) - category LOGC_CORE
+* log_dt(level, format_string, ...) - category LOGC_DT
+
+More logging destinations:
+
+* device - goes to a device (e.g. serial)
+* buffer - recorded in a memory buffer
+
+Convert debug() statements in the code to log() statements
+
+Support making printf() emit log statements at L_INFO level
+
+Convert error() statements in the code to log() statements
+
+Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
+
+Figure out what to do with assert()
+
+Add a way to browse log records
+
+Add a way to record log records for browsing using an external tool
+
+Add commands to add and remove filters
+
+Add commands to add and remove log devices
+
+Allow sharing of printf format strings in log records to reduce storage size
+for large numbers of log records
+
+Add a command-line option to sandbox to set the default logging level
+
+Convert core driver model code to use logging
+
+Convert uclasses to use logging with the correct category
+
+Consider making log() calls emit an automatic newline, perhaps with a logn()
+function to avoid that
+
+Passing log records through to linux (e.g. via device tree /chosen)
+
+Provide a command to access the number of log records generated, and the
+number dropped due to them being generated before the log system was ready.
+
+Add a printf() format string pragma so that log statements are checked properly
+
+Enhance the log console driver to show level / category / file / line
+information
+
+Add a command to add new log records and delete existing records.
+
+Provide additional log() functions - e.g. logc() to specify the category
diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst
index 635effcef6..96525b6ccc 100644
--- a/doc/driver-model/design.rst
+++ b/doc/driver-model/design.rst
@@ -613,7 +613,7 @@ be connected on a SATA bus or standalone with no bus::
    xhci_usb (UCLASS_USB)
       flash (UCLASS_FLASH_STORAGE)  - parent data/methods defined by USB bus
 
-   sata (UCLASS_SATA)
+   sata (UCLASS_AHCI)
       flash (UCLASS_FLASH_STORAGE)  - parent data/methods defined by SATA bus
 
    flash (UCLASS_FLASH_STORAGE)  - no parent data/methods (not on a bus)
@@ -628,7 +628,7 @@ parent device which is a bus, causes the device to start behaving like a
 bus device, regardless of its own views on the matter.
 
 The uclass for the device can also contain data private to that uclass.
-But note that each device on the bus may be a memeber of a different
+But note that each device on the bus may be a member of a different
 uclass, and this data has nothing to do with the child data for each child
 on the bus. It is the bus' uclass that controls the child with respect to
 the bus.