From 2f8f5e23539819dcf9c995d7a829dbac67d0ba27 Mon Sep 17 00:00:00 2001
From: Heinrich Schuchardt <xypron.glpk@gmx.de>
Date: Wed, 20 May 2020 23:27:27 +0200
Subject: doc: driver-model: there is no UCLASS_SATA

%s/UCLASS_SATA/UCLASS_AHCI/g

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 doc/driver-model/design.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst
index 635effcef6..9e9272777d 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)
-- 
cgit 


From b44c751efe09e0069ba4ca6fca246b935bf5efcc Mon Sep 17 00:00:00 2001
From: Patrick Delaunay <patrick.delaunay@st.com>
Date: Wed, 27 May 2020 09:43:31 +0200
Subject: doc: log: correct option name CONFIG_LOG_MAX_LEVEL

Replace CONFIG_(SPL_)MAX_LOG_LEVEL by the correct name as defined in
common/Kconfig:
line 668:config LOG_MAX_LEVEL
line 688:config SPL_LOG_MAX_LEVEL
line 708:config TPL_LOG_MAX_LEVEL

Signed-off-by: Patrick Delaunay <patrick.delaunay@st.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 doc/README.log | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'doc')

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
-- 
cgit 


From a7813918fe4fa27146ed5777ee63329ae7564af9 Mon Sep 17 00:00:00 2001
From: Heinrich Schuchardt <xypron.glpk@gmx.de>
Date: Sun, 31 May 2020 10:46:12 +0200
Subject: doc: move README.log to HTML documentation

Convert README.log to reStructuredText and add it to the generated HTML
documentation.

Assign doc/develop/logging.rst to the maintainer of LOGGING.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 doc/develop/index.rst   |   1 +
 doc/develop/logging.rst | 290 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 291 insertions(+)
 create mode 100644 doc/develop/logging.rst

(limited to 'doc')

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
-- 
cgit 


From cea8f2c995b9d87af6ef42f967402e1c8a3506db Mon Sep 17 00:00:00 2001
From: Dario Binacchi <dariobin@libero.it>
Date: Thu, 4 Jun 2020 14:58:13 +0200
Subject: doc: driver-model: fix typo in design.rst

Fix the 'memeber' typo in doc/driver-model/design.rst.

Signed-off-by: Dario Binacchi <dariobin@libero.it>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 doc/driver-model/design.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst
index 9e9272777d..96525b6ccc 100644
--- a/doc/driver-model/design.rst
+++ b/doc/driver-model/design.rst
@@ -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.
-- 
cgit 


From f3767bcb31d0ce5c6381d5f6c33a951774ee6d41 Mon Sep 17 00:00:00 2001
From: Denis 'GNUtoo' Carikli <GNUtoo@cyberdimension.org>
Date: Sat, 30 May 2020 05:24:25 +0200
Subject: board: tbs2910: add documentation

This documents the u-boot installation procedure and the
hardware in order to get started.

Signed-off-by: Denis 'GNUtoo' Carikli <GNUtoo@cyberdimension.org>
[trini: Add MAINTAINERS entry for doc file per Soeren's request]
---
 doc/board/index.rst       |   1 +
 doc/board/tbs/index.rst   |   9 +++
 doc/board/tbs/tbs2910.rst | 191 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 201 insertions(+)
 create mode 100644 doc/board/tbs/index.rst
 create mode 100644 doc/board/tbs/tbs2910.rst

(limited to 'doc')

diff --git a/doc/board/index.rst b/doc/board/index.rst
index 01b233f737..bb4473152a 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -18,5 +18,6 @@ Board-specific doc
    rockchip/index
    sifive/index
    st/index
+   tbs/index
    toradex/index
    xilinx/index
diff --git a/doc/board/tbs/index.rst b/doc/board/tbs/index.rst
new file mode 100644
index 0000000000..b677bc624f
--- /dev/null
+++ b/doc/board/tbs/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+TBS
+===
+
+.. toctree::
+   :maxdepth: 2
+
+   tbs2910
diff --git a/doc/board/tbs/tbs2910.rst b/doc/board/tbs/tbs2910.rst
new file mode 100644
index 0000000000..e97f2b6e61
--- /dev/null
+++ b/doc/board/tbs/tbs2910.rst
@@ -0,0 +1,191 @@
+TBS2910 Matrix ARM miniPC
+=========================
+
+Building
+--------
+To build u-boot for the TBS2910 Matrix ARM miniPC, you can use the following
+procedure:
+
+First add the ARM toolchain to your PATH
+
+Then setup the ARCH and cross compilation environment variables.
+
+When this is done you can then build u-boot for the TBS2910 Matrix ARM miniPC
+with the following commands:
+
+.. code-block:: none
+
+   make mrproper
+   make tbs2910_defconfig
+   make
+
+Once the build is complete, you can find the resulting image as u-boot.imx in
+the current directory.
+
+UART
+----
+The UART voltage is at 3.3V and its settings are 115200bps 8N1
+
+BOOT/UPDATE boot switch:
+------------------------
+The BOOT/UPDATE switch (SW11) is connected to the BOOT_MODE0 and
+BOOT_MODE1 SoC pins. It has "BOOT" and "UPDATE" markings both on
+the PCB and on the plastic case.
+
+When set to the "UPDATE" position, the SoC will use the "Boot From Fuses"
+configuration, and since BT_FUSE_SEL is 0, this makes the SOC jump to serial
+downloader.
+
+When set in the "BOOT" position, the SoC will use the "Internal boot"
+configuration, and since BT_FUSE_SEL is 0, it will then use the GPIO pins
+for the boot configuration.
+
+SW6 binary DIP switch array on the PCB revision 2.1:
+----------------------------------------------------
+On that PCB revision, SW6 has 8 positions.
+
+Switching a position to ON sets the corresponding
+register to 1.
+
+See the following table for a correspondence between the switch positions and
+registers:
+
+===============    ============
+Switch position    Register
+===============    ============
+1                  BOOT_CFG2[3]
+2                  BOOT_CFG2[4]
+3                  BOOT_CFG2[5]
+4                  BOOT_CFG2[6]
+5                  BOOT_CFG1[4]
+6                  BOOT_CFG1[5]
+7                  BOOT_CFG1[6]
+8                  BOOT_CFG1[7]
+===============    ============
+
+For example:
+
+  - To boot from the eMMC: 1:ON , 2:ON, 3:ON, 4:OFF, 5:OFF, 6:ON, 7:ON, 8:OFF
+  - To boot from the microSD slot: 1: ON, 2: OFF, 3: OFF, 4: OFF, 5:OFF, 6:OFF,
+    7:ON, 8:OFF
+  - To boot from the SD slot: 1: OFF, 2: ON, 3: OFF, 4: OFF, 5:OFF, 6:OFF, 7:ON,
+    8:OFF
+  - To boot from SATA: 1: OFF, 2: OFF, 3: OFF, 4: OFF, 5:OFF, 6:ON, 7:OFF, 8:OFF
+
+You can refer to the BOOT_CFG registers in the I.MX6Q reference manual for
+additional details.
+
+SW6 binary DIP switch array on the PCB revision 2.3:
+----------------------------------------------------
+On that PCB revision, SW6 has only 4 positions.
+
+Switching a position to ON sets the corresponding
+register to 1.
+
+See the following table for a correspondence between the switch positions and
+registers:
+
+===============    ============
+Switch position    Register
+===============    ============
+1                  BOOT_CFG2[3]
+2                  BOOT_CFG2[4]
+3                  BOOT_CFG2[5]
+4                  BOOT_CFG1[5]
+===============    ============
+
+For example:
+
+- To boot from the eMMC: 1:ON, 2:ON, 3:ON, 4:ON
+- To boot from the microSD slot: 1:ON, 2:OFF, 3:OFF, 4:OFF
+- To boot from the SD slot: 1:OFF, 2:ON, 3:OFF, 4:OFF
+
+You can refer to the BOOT_CFG registers in the I.MX6Q reference manual for
+additional details.
+
+Loading u-boot from USB:
+------------------------
+If you need to load u-boot from USB, you can use the following instructions:
+
+First build imx_usb_loader, as we will need it to load u-boot from USB. This
+can be done with the following commands:
+
+.. code-block:: none
+
+   git clone git://github.com/boundarydevices/imx_usb_loader.git
+   cd imx_usb_loader
+   make
+
+This will create the resulting imx_usb binary.
+
+When this is done, you can copy the u-boot.imx image that you built earlier
+in in the imx_usb_loader directory.
+
+You will then need to power off the TBS2910 Matrix ARM miniPC and make sure that
+the boot switch is set to "UPDATE"
+
+Once this is done you can connect an USB cable between the computer that will
+run imx_usb and the TBS2910 Matrix ARM miniPC.
+
+If you also need to access the u-boot console, you will also need to connect an
+UART cable between the computer running imx_usb and the TBS2910 Matrix ARM
+miniPC.
+
+Once everything is connected you can finally power on the TBS2910 Matrix ARM
+miniPC. The SoC will then jump to the serial download and wait for you.
+
+Finlay, you can load u-boot through USB with with the following command:
+
+.. code-block:: none
+
+   sudo ./imx_usb -v u-boot.imx
+
+The u-boot boot messages will then appear in the serial console.
+
+Install u-boot on the eMMC:
+---------------------------
+To install u-boot on the eMMC, you first need to boot the TBS2910 Matrix ARM
+miniPC.
+
+Once booted, you can flash u-boot.imx to mmcblk0boot0 with the
+following commands:
+
+.. code-block:: none
+
+   sudo echo 0 >/sys/block/mmcblk0boot0/force_ro
+   sudo dd if=u-boot.imx of=/dev/mmcblk0boot0 bs=1k seek=1; sync
+
+Note that the eMMC card node may vary, so adjust this as needed.
+
+Once the new u-boot version is installed, to boot on it you then need to power
+off the TBS2910 Matrix ARM miniPC.
+
+Once it is off, you need make sure that the boot switch is set to "BOOT" and
+that the SW6 switch is set to boot on the eMMC as described in the previous
+sections.
+
+If you also need to access the u-boot console, you will also need to connect an
+UART cable between the computer running imx_usb and the TBS2910 Matrix ARM
+miniPC.
+
+You can then power up the TBS2910 Matrix ARM miniPC and U-Boot messages will
+appear in the serial console.
+
+Booting a distribution:
+-----------------------
+When booting on the TBS2910 Matrix ARM miniPC, by default U-Boot will first try
+to boot from hardcoded offsets from the start of the eMMC. This is for
+compatibility with the stock GNU/Linux distribution.
+
+If that fails it will then try to boot from several interfaces using
+'distro_bootcmd': It will first try to boot from the microSD slot, then the
+SD slot, then the internal eMMC, then the SATA interface and finally the USB
+interface. For more information on how to configure your distribution to boot,
+see 'README.distro'.
+
+Links:
+------
+  - https://www.tbsdtv.com/download/document/tbs2910/TBS2910-Matrix-ARM-mini-PC-SCH_rev2.1.pdf
+    - The schematics for the revision 2.1 of the TBS2910 Matrix ARM miniPC.
+  - https://cache.freescale.com/files/32bit/doc/ref_manual/IMX6DQRM.pdf - The
+    SoC reference manual for additional details on the BOOT_CFG registers.
-- 
cgit 


From f459d322a9bdd06b06833b4a20c06c25059b8aa1 Mon Sep 17 00:00:00 2001
From: Pali Rohár <pali@kernel.org>
Date: Mon, 1 Jun 2020 00:26:32 +0200
Subject: Nokia RX-51: Add link for u-boot-gen-combined script to README file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This patch updates Nokia RX-51 README file.

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 doc/README.nokia_rx51 | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc')

diff --git a/doc/README.nokia_rx51 b/doc/README.nokia_rx51
index 33c275b416..320b5efc7d 100644
--- a/doc/README.nokia_rx51
+++ b/doc/README.nokia_rx51
@@ -16,6 +16,11 @@ SD card or internal eMMC memory. If this fails or keyboard is closed then
 the appended kernel image will be booted using some generated and some
 stored ATAGs (see boot order).
 
+For generating combined image of u-boot and kernel there is a simple script
+called u-boot-gen-combined. It is available in following repository:
+
+  https://github.com/pali/u-boot-maemo
+
 There is support for hardware watchdog. Hardware watchdog is started by
 NOLO so u-boot must kick watchdog to prevent reboot device (but not very
 often, max every 2 seconds). There is also support for framebuffer display
-- 
cgit 


From 6b3984c6318447e954942c9780b714a676f977e6 Mon Sep 17 00:00:00 2001
From: Johannes Krottmayer <krjdev@gmail.com>
Date: Wed, 3 Jun 2020 11:50:06 +0200
Subject: doc: board: xilinx: zynq.rst: add description how to flash a SD card

Add a short description in the ZYNQ documentation how to prepare a SD card and
copy the related images to SD card.

Signed-off-by: Johannes Krottmayer <krjdev@gmail.com>
Cc: Michal Simek <michal.simek@xilinx.com>
Signed-off-by: Michal Simek <michal.simek@xilinx.com>
---
 doc/board/xilinx/zynq.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

(limited to 'doc')

diff --git a/doc/board/xilinx/zynq.rst b/doc/board/xilinx/zynq.rst
index 6a09df1d15..f564434b69 100644
--- a/doc/board/xilinx/zynq.rst
+++ b/doc/board/xilinx/zynq.rst
@@ -60,6 +60,25 @@ SLCR bootmode register Bit[3:0] values
 "modeboot" variable can assign any of "norboot", "sdboot" or "jtagboot"
 bootmode strings at runtime.
 
+Flashing
+--------
+
+SD Card
+^^^^^^^
+
+To write an image that boots from a SD card first create a FAT32 partition
+and a FAT32 filesystem on the SD card::
+
+        sudo fdisk /dev/sdx
+        sudo mkfs.vfat -F 32 /dev/sdx1
+
+Mount the SD card and copy the SPL and U-Boot to the root directory of the
+SD card::
+
+        sudo mount -t vfat /dev/sdx1 /mnt
+        sudo cp spl/boot.bin /mnt
+        sudo cp u-boot.img /mnt
+
 Mainline status
 ---------------
 
-- 
cgit 


From 78ce0bd3acafc51e94157ff99aec3ed82e685ef5 Mon Sep 17 00:00:00 2001
From: Sean Anderson <seanga2@gmail.com>
Date: Wed, 24 Jun 2020 06:41:06 -0400
Subject: clk: Always use the supplied struct clk

CCF clocks should always use the struct clock passed to their methods for
extracting the driver-specific clock information struct. Previously, many
functions would use the clk->dev->priv if the device was bound. This could
cause problems with composite clocks. The individual clocks in a composite
clock did not have the ->dev field filled in. This was fine, because the
device-specific clock information would be used. However, since there was
no ->dev, there was no way to get the parent clock. This caused the
recalc_rate method of the CCF divider clock to fail. One option would be to
use the clk->priv field to get the composite clock and from there get the
appropriate parent device. However, this would tie the implementation to
the composite clock. In general, different devices should not rely on the
contents of ->priv from another device.

The simple solution to this problem is to just always use the supplied
struct clock. The composite clock now fills in the ->dev pointer of its
child clocks.  This allows child clocks to make calls like clk_get_parent()
without issue.

imx avoided the above problem by using a custom get_rate function with
composite clocks.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Acked-by: Lukasz Majewski <lukma@denx.de>
---
 doc/imx/clk/ccf.txt | 63 +++++++++++++++++++++++++++--------------------------
 1 file changed, 32 insertions(+), 31 deletions(-)

(limited to 'doc')

diff --git a/doc/imx/clk/ccf.txt b/doc/imx/clk/ccf.txt
index 36b60dc438..e40ac360e8 100644
--- a/doc/imx/clk/ccf.txt
+++ b/doc/imx/clk/ccf.txt
@@ -1,42 +1,37 @@
 Introduction:
 =============
 
-This documentation entry describes the Common Clock Framework [CCF]
-port from Linux kernel (v5.1.12) to U-Boot.
+This documentation entry describes the Common Clock Framework [CCF] port from
+Linux kernel (v5.1.12) to U-Boot.
 
-This code is supposed to bring CCF to IMX based devices (imx6q, imx7
-imx8). Moreover, it also provides some common clock code, which would
-allow easy porting of CCF Linux code to other platforms.
+This code is supposed to bring CCF to IMX based devices (imx6q, imx7 imx8).
+Moreover, it also provides some common clock code, which would allow easy
+porting of CCF Linux code to other platforms.
 
 Design decisions:
 =================
 
-* U-Boot's driver model [DM] for clk differs from Linux CCF. The most
-  notably difference is the lack of support for hierarchical clocks and
-  "clock as a manager driver" (single clock DTS node acts as a starting
-  point for all other clocks).
+* U-Boot's driver model [DM] for clk differs from Linux CCF. The most notably
+  difference is the lack of support for hierarchical clocks and "clock as a
+  manager driver" (single clock DTS node acts as a starting point for all other
+  clocks).
 
-* The clk_get_rate() caches the previously read data if CLK_GET_RATE_NOCACHE
-  is not set (no need for recursive access).
+* The clk_get_rate() caches the previously read data if CLK_GET_RATE_NOCACHE is
+  not set (no need for recursive access).
 
-* On purpose the "manager" clk driver (clk-imx6q.c) is not using large
-  table to store pointers to clocks - e.g. clk[IMX6QDL_CLK_USDHC2_SEL] = ....
-  Instead we use udevice's linked list for the same class (UCLASS_CLK).
+* On purpose the "manager" clk driver (clk-imx6q.c) is not using large table to
+  store pointers to clocks - e.g. clk[IMX6QDL_CLK_USDHC2_SEL] = .... Instead we
+  use udevice's linked list for the same class (UCLASS_CLK).
 
   Rationale:
   ----------
-    When porting the code as is from Linux, one would need ~1KiB of RAM to
-    store it. This is way too much if we do plan to use this driver in SPL.
+    When porting the code as is from Linux, one would need ~1KiB of RAM to store
+    it. This is way too much if we do plan to use this driver in SPL.
 
 * The "central" structure of this patch series is struct udevice and its
   uclass_priv field contains the struct clk pointer (to the originally created
   one).
 
-* Up till now U-Boot's driver model (DM) CLK operates on udevice (main
-  access to clock is by udevice ops)
-  In the CCF the access to struct clk (embodying pointer to *dev) is
-  possible via dev_get_clk_ptr() (it is a wrapper on dev_get_uclass_priv()).
-
 * To keep things simple the struct udevice's uclass_priv pointer is used to
   store back pointer to corresponding struct clk. However, it is possible to
   modify clk-uclass.c file and add there struct uc_clk_priv, which would have
@@ -45,13 +40,17 @@ Design decisions:
   setting .per_device_auto_alloc_size = sizeof(struct uc_clk_priv)) the
   uclass_priv stores the pointer to struct clk.
 
+* Non-CCF clocks do not have a pointer to a clock in clk->dev->priv. In the case
+  of composite clocks, clk->dev->priv may not match clk. Drivers should always
+  use the struct clk which is passed to them, and not clk->dev->priv.
+
 * It is advised to add common clock code (like already added rate and flags) to
   the struct clk, which is a top level description of the clock.
 
 * U-Boot's driver model already provides the facility to automatically allocate
-  (via private_alloc_size) device private data (accessible via dev->priv).
-  It may look appealing to use this feature to allocate private structures for
-  CCF clk devices e.g. divider (struct clk_divider *divider) for IMX6Q clock.
+  (via private_alloc_size) device private data (accessible via dev->priv). It
+  may look appealing to use this feature to allocate private structures for CCF
+  clk devices e.g. divider (struct clk_divider *divider) for IMX6Q clock.
 
   The above feature had not been used for following reasons:
   - The original CCF Linux kernel driver is the "manager" for clocks - it
@@ -64,21 +63,23 @@ Design decisions:
 
 * I've added the clk_get_parent(), which reads parent's dev->uclass_priv to
   provide parent's struct clk pointer. This seems the easiest way to get
-  child/parent relationship for struct clk in U-Boot's udevice based clocks.
+  child/parent relationship for struct clk in U-Boot's udevice based clocks.  In
+  the future arbitrary parents may be supported by adding a get_parent function
+  to clk_ops.
 
 * Linux's CCF 'struct clk_core' corresponds to U-Boot's udevice in 'struct clk'.
   Clock IP block agnostic flags from 'struct clk_core' (e.g. NOCACHE) have been
-  moved from this struct one level up to 'struct clk'.
+  moved from this struct one level up to 'struct clk'. Many flags are
+  unimplemented at the moment.
 
 * For tests the new ./test/dm/clk_ccf.c and ./drivers/clk/clk_sandbox_ccf.c
   files have been introduced. The latter setups the CCF clock structure for
-  sandbox by reusing, if possible, generic clock primitives - like divier
-  and mux. The former file provides code to tests this setup.
+  sandbox by reusing, if possible, generic clock primitives - like divier and
+  mux. The former file provides code to tests this setup.
 
   For sandbox new CONFIG_SANDBOX_CLK_CCF Kconfig define has been introduced.
-  All new primitives added for new architectures must have corresponding test
-  in the two aforementioned files.
-
+  All new primitives added for new architectures must have corresponding test in
+  the two aforementioned files.
 
 Testing (sandbox):
 ==================
-- 
cgit 


From f9c7d4f99f51ac9c1cf513111c21395f93d2dd53 Mon Sep 17 00:00:00 2001
From: Sean Anderson <seanga2@gmail.com>
Date: Wed, 24 Jun 2020 06:41:11 -0400
Subject: clk: Add K210 clock support

Due to the large number of clocks, I decided to use the CCF. The overall
structure is modeled after the imx code. Clocks parameters are stored in
several arrays, and are then instantiated at run-time. There are some
translation macros (FOOIFY()) which allow for more dense packing.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
CC: Lukasz Majewski <lukma@denx.de>
---
 .../mfd/kendryte,k210-sysctl.txt                   | 33 ++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 doc/device-tree-bindings/mfd/kendryte,k210-sysctl.txt

(limited to 'doc')

diff --git a/doc/device-tree-bindings/mfd/kendryte,k210-sysctl.txt b/doc/device-tree-bindings/mfd/kendryte,k210-sysctl.txt
new file mode 100644
index 0000000000..5b24abcb62
--- /dev/null
+++ b/doc/device-tree-bindings/mfd/kendryte,k210-sysctl.txt
@@ -0,0 +1,33 @@
+Kendryte K210 Sysctl
+
+This binding describes the K210 sysctl device, which contains many miscellaneous
+registers controlling system functionality. This node is a register map and can
+be reference by other bindings which need a phandle to the K210 sysctl regmap.
+
+Required properties:
+- compatible: should be
+	"kendryte,k210-sysctl", "syscon", "simple-mfd"
+- reg: address and length of the sysctl registers
+- reg-io-width: must be <4>
+
+Clock sub-node
+
+This node is a binding for the clock tree driver
+
+Required properties:
+- compatible: should be "kendryte,k210-clk"
+- clocks: phandle to the "in0" external oscillator
+- #clock-cells: must be <1>
+
+Example:
+sysctl: syscon@50440000 {
+	compatible = "kendryte,k210-sysctl", "syscon", "simple-mfd";
+	reg = <0x50440000 0x100>;
+	reg-io-width = <4>;
+
+	sysclk: clock-controller {
+		compatible = "kendryte,k210-clk";
+		clocks = <&in0>;
+		#clock-cells = <1>;
+	};
+};
-- 
cgit 


From 4a3390f1d3b71f0645eb281176f00cd0d5ac2dcb Mon Sep 17 00:00:00 2001
From: Sean Anderson <seanga2@gmail.com>
Date: Wed, 24 Jun 2020 06:41:12 -0400
Subject: dm: Add support for simple-pm-bus

This type of bus is used in Linux to designate buses which have power
domains and/or clocks which need to be enabled before their child devices
can be used. Because power domains are automatically enabled before probing
in U-Boot, we just need to enable any clocks present.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 doc/device-tree-bindings/bus/simple-pm-bus.txt | 44 ++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 doc/device-tree-bindings/bus/simple-pm-bus.txt

(limited to 'doc')

diff --git a/doc/device-tree-bindings/bus/simple-pm-bus.txt b/doc/device-tree-bindings/bus/simple-pm-bus.txt
new file mode 100644
index 0000000000..6f15037131
--- /dev/null
+++ b/doc/device-tree-bindings/bus/simple-pm-bus.txt
@@ -0,0 +1,44 @@
+Simple Power-Managed Bus
+========================
+
+A Simple Power-Managed Bus is a transparent bus that doesn't need a real
+driver, as it's typically initialized by the boot loader.
+
+However, its bus controller is part of a PM domain, or under the control of a
+functional clock.  Hence, the bus controller's PM domain and/or clock must be
+enabled for child devices connected to the bus (either on-SoC or externally)
+to function.
+
+While "simple-pm-bus" follows the "simple-bus" set of properties, as specified
+in the Devicetree Specification, it is not an extension of "simple-bus".
+
+
+Required properties:
+  - compatible: Must contain at least "simple-pm-bus".
+		Must not contain "simple-bus".
+		It's recommended to let this be preceded by one or more
+		vendor-specific compatible values.
+  - #address-cells, #size-cells, ranges: Must describe the mapping between
+		parent address and child address spaces.
+
+Optional platform-specific properties for clock or PM domain control (at least
+one of them is required):
+  - clocks: Must contain a reference to the functional clock(s),
+  - power-domains: Must contain a reference to the PM domain.
+Please refer to the binding documentation for the clock and/or PM domain
+providers for more details.
+
+
+Example:
+
+	bsc: bus@fec10000 {
+		compatible = "renesas,bsc-sh73a0", "renesas,bsc",
+			     "simple-pm-bus";
+		#address-cells = <1>;
+		#size-cells = <1>;
+		ranges = <0 0 0x20000000>;
+		reg = <0xfec10000 0x400>;
+		interrupts = <0 39 IRQ_TYPE_LEVEL_HIGH>;
+		clocks = <&zb_clk>;
+		power-domains = <&pd_a4s>;
+	};
-- 
cgit 


From 038b13ee8134ba755a323732f3b2b838b9dc17a4 Mon Sep 17 00:00:00 2001
From: Sean Anderson <seanga2@gmail.com>
Date: Wed, 24 Jun 2020 06:41:14 -0400
Subject: reset: Add generic reset driver

This patch adds a generic reset driver. It is designed to be useful when
one has a register in a regmap which contains bits that reset other
devices. I thought this seemed like a very generic use, so here is a
generic driver. The overall structure has been modeled on the syscon-reboot
driver.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 doc/device-tree-bindings/reset/syscon-reset.txt | 36 +++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 doc/device-tree-bindings/reset/syscon-reset.txt

(limited to 'doc')

diff --git a/doc/device-tree-bindings/reset/syscon-reset.txt b/doc/device-tree-bindings/reset/syscon-reset.txt
new file mode 100644
index 0000000000..f136b3d225
--- /dev/null
+++ b/doc/device-tree-bindings/reset/syscon-reset.txt
@@ -0,0 +1,36 @@
+Generic SYSCON mapped register reset driver
+
+This is a generic reset driver using syscon to map the reset register.
+The reset is generally performed with a write to the reset register
+defined by the register map pointed by syscon reference plus the offset and
+shifted by the reset specifier/
+
+To assert a reset on some device, the equivalent of the following operation is
+performed, where reset_id is the reset specifier from the device's resets
+property.
+
+	if (BIT(reset_id) & mask)
+		regmap[offset][reset_id] = assert-high;
+
+Required properties:
+- compatible: should contain "syscon-reset"
+- #reset-cells: must be 1
+- regmap: this is phandle to the register map node
+- offset: offset in the register map for the reboot register (in bytes)
+
+Optional properties:
+- mask: accept only the reset specifiers defined by the mask (32 bit)
+- assert-high: Bit to write when asserting a reset. Defaults to 1.
+
+Default will be little endian mode, 32 bit access only.
+
+Example:
+
+	reset-controller {
+		compatible = "syscon-reset";
+		#reset-cells = <1>;
+		regmap = <&sysctl>;
+		offset = <0x20>;
+		mask = <0x27FFFFFF>;
+		assert-high = <0>;
+	};
-- 
cgit 


From de09f71108eef3f50481901abb910b5b6109c121 Mon Sep 17 00:00:00 2001
From: Sean Anderson <seanga2@gmail.com>
Date: Wed, 24 Jun 2020 06:41:24 -0400
Subject: doc: riscv: Add documentation for Sipeed Maix Bit

This patch adds documentation for the Sipeed Maix bit, and more generally
for the Kendryte K210 processor.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
---
 doc/board/index.rst        |   1 +
 doc/board/sipeed/index.rst |   9 ++
 doc/board/sipeed/maix.rst  | 298 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 308 insertions(+)
 create mode 100644 doc/board/sipeed/index.rst
 create mode 100644 doc/board/sipeed/maix.rst

(limited to 'doc')

diff --git a/doc/board/index.rst b/doc/board/index.rst
index 19733a6398..0a15899180 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -18,6 +18,7 @@ Board-specific doc
    renesas/index
    rockchip/index
    sifive/index
+   sipeed/index
    st/index
    tbs/index
    toradex/index
diff --git a/doc/board/sipeed/index.rst b/doc/board/sipeed/index.rst
new file mode 100644
index 0000000000..3518e2d8f4
--- /dev/null
+++ b/doc/board/sipeed/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Sipeed
+======
+
+.. toctree::
+   :maxdepth: 2
+
+   maix
diff --git a/doc/board/sipeed/maix.rst b/doc/board/sipeed/maix.rst
new file mode 100644
index 0000000000..06e0008b9f
--- /dev/null
+++ b/doc/board/sipeed/maix.rst
@@ -0,0 +1,298 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
+
+Maix Bit
+========
+
+Several of the Sipeed Maix series of boards cotain the Kendryte K210 processor,
+a 64-bit RISC-V CPU. This processor contains several peripherals to accelerate
+neural network processing and other "ai" tasks. This includes a "KPU" neural
+network processor, an audio processor supporting beamforming reception, and a
+digital video port supporting capture and output at VGA resolution. Other
+peripherals include 8M of SRAM (accessible with and without caching); remappable
+pins, including 40 GPIOs; AES, FFT, and SHA256 accelerators; a DMA controller;
+and I2C, I2S, and SPI controllers. Maix peripherals vary, but include spi flash;
+on-board usb-serial bridges; ports for cameras, displays, and sd cards; and
+ESP32 chips. Currently, only the Sipeed Maix Bit V2.0 (bitm) is supported, but
+the boards are fairly similar.
+
+Documentation for Maix boards is available from
+`Sipeed's website <http://dl.sipeed.com/MAIX/HDK/>`_.
+Documentation for the Kendryte K210 is available from
+`Kendryte's website <https://kendryte.com/downloads/>`_. However, hardware
+details are rather lacking, so most technical reference has been taken from the
+`standalone sdk <https://github.com/kendryte/kendryte-standalone-sdk>`_.
+
+Build and boot steps
+--------------------
+
+To build u-boot, run
+
+.. code-block:: none
+
+    make sipeed_maix_bitm_defconfig
+    make CROSS_COMPILE=<your cross compile prefix>
+
+To flash u-boot to a maix bit, run
+
+.. code-block:: none
+
+    kflash -tp /dev/<your tty here> -B bit_mic u-boot-dtb.bin
+
+Boot output should look like the following:
+
+.. code-block:: none
+
+    U-Boot 2020.04-rc2-00087-g2221cc09c1-dirty (Feb 28 2020 - 13:53:09 -0500)
+
+    DRAM:  8 MiB
+    In:    serial@38000000
+    Out:   serial@38000000
+    Err:   serial@38000000
+    =>
+
+Loading Images
+^^^^^^^^^^^^^^
+
+To load a kernel, transfer it over serial.
+
+.. code-block:: none
+
+    => loady 80000000 1500000
+    ## Switch baudrate to 1500000 bps and press ENTER ...
+
+    *** baud: 1500000
+
+    *** baud: 1500000 ***
+    ## Ready for binary (ymodem) download to 0x80000000 at 1500000 bps...
+    C
+    *** file: loader.bin
+    $ sz -vv loader.bin
+    Sending: loader.bin
+    Bytes Sent:2478208   BPS:72937
+    Sending:
+    Ymodem sectors/kbytes sent:   0/ 0k
+    Transfer complete
+
+    *** exit status: 0 ***
+    ## Total Size      = 0x0025d052 = 2478162 Bytes
+    ## Switch baudrate to 115200 bps and press ESC ...
+
+    *** baud: 115200
+
+    *** baud: 115200 ***
+    =>
+
+Running Programs
+^^^^^^^^^^^^^^^^
+
+Binaries
+""""""""
+
+To run a bare binary, use the ``go`` command:
+
+.. code-block:: none
+
+    => loady
+    ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
+    C
+    *** file: ./examples/standalone/hello_world.bin
+    $ sz -vv ./examples/standalone/hello_world.bin
+    Sending: hello_world.bin
+    Bytes Sent:   4864   BPS:649
+    Sending:
+    Ymodem sectors/kbytes sent:   0/ 0k
+    Transfer complete
+
+    *** exit status: 0 ***
+    (CAN) packets, 5 retries
+    ## Total Size      = 0x000012f8 = 4856 Bytes
+    => go 80000000
+    ## Starting application at 0x80000000 ...
+    Example expects ABI version 9
+    Actual U-Boot ABI version 9
+    Hello World
+    argc = 1
+    argv[0] = "80000000"
+    argv[1] = "<NULL>"
+    Hit any key to exit ...
+
+Legacy Images
+"""""""""""""
+
+To run legacy images, use the ``bootm`` command:
+
+.. code-block:: none
+
+    $ tools/mkimage -A riscv -O u-boot -T standalone -C none -a 80000000 -e 80000000 -d examples/standalone/hello_world.bin hello_world.img
+    Image Name:
+    Created:      Thu Mar  5 12:04:10 2020
+    Image Type:   RISC-V U-Boot Standalone Program (uncompressed)
+    Data Size:    4856 Bytes = 4.74 KiB = 0.00 MiB
+    Load Address: 80000000
+    Entry Point:  80000000
+
+    $ picocom -b 115200 /dev/ttyUSB0i
+    => loady
+    ## Ready for binary (ymodem) download to 0x80000000 at 115200 bps...
+    C
+    *** file: hello_world.img
+    $ sz -vv hello_world.img
+    Sending: hello_world.img
+    Bytes Sent:   4992   BPS:665
+    Sending:
+    Ymodem sectors/kbytes sent:   0/ 0k
+    Transfer complete
+
+    *** exit status: 0 ***
+    CAN) packets, 3 retries
+    ## Total Size      = 0x00001338 = 4920 Bytes
+    => bootm
+    ## Booting kernel from Legacy Image at 80000000 ...
+       Image Name:
+       Image Type:   RISC-V U-Boot Standalone Program (uncompressed)
+       Data Size:    4856 Bytes = 4.7 KiB
+       Load Address: 80000000
+       Entry Point:  80000000
+       Verifying Checksum ... OK
+       Loading Standalone Program
+    Example expects ABI version 9
+    Actual U-Boot ABI version 9
+    Hello World
+    argc = 0
+    argv[0] = "<NULL>"
+    Hit any key to exit ...
+
+Over- and Under-clocking
+------------------------
+
+To change the clock speed of the K210, you will need to enable
+``CONFIG_CLK_K210_SET_RATE`` and edit the board's device tree. To do this, add a
+section to ``arch/riscv/arch/riscv/dts/k210-maix-bit.dts`` like the following:
+
+.. code-block:: none
+
+    &sysclk {
+	assigned-clocks = <&sysclk K210_CLK_PLL0>;
+	assigned-clock-rates = <800000000>;
+    };
+
+There are three PLLs on the K210: PLL0 is the parent of most of the components,
+including the CPU and RAM. PLL1 is the parent of the neural network coprocessor.
+PLL2 is the parent of the sound processing devices. Note that child clocks of
+PLL0 and PLL2 run at *half* the speed of the PLLs. For example, if PLL0 is
+running at 800 MHz, then the CPU will run at 400 MHz. This is the example given
+above. The CPU can be overclocked to around 600 MHz, and underclocked to 26 MHz.
+
+It is possible to set PLL2's parent to PLL0. The plls are more accurate when
+converting between similar frequencies. This makes it easier to get an accurate
+frequency for I2S. As an example, consider sampling an I2S device at 44.1 kHz.
+On this device, the I2S serial clock runs at 64 times the sample rate.
+Therefore, we would like to run PLL2 at an even multiple of 2.8224 MHz. If
+PLL2's parent is IN0, we could use a frequency of 390 MHz (the same as the CPU's
+default speed).  Dividing by 138 yields a serial clock of about 2.8261 MHz. This
+results in a sample rate of 44.158 kHz---around 50 Hz or .1% too fast. If,
+instead, we set PLL2's parent to PLL1 running at 390 MHz, and request a rate of
+2.8224 * 136 = 383.8464 MHz, the achieved rate is 383.90625 MHz. Dividing by 136
+yields a serial clock of about 2.8228 MHz. This results in a sample rate of
+44.107 kHz---just 7 Hz or .02% too fast. This configuration is shown in the
+following example:
+
+.. code-block:: none
+
+    &sysclk {
+	assigned-clocks = <&sysclk K210_CLK_PLL1>, <&sysclk K210_CLK_PLL2>;
+	assigned-clock-parents = <0>, <&sysclk K210_CLK_PLL1>;
+	assigned-clock-rates = <390000000>, <383846400>;
+    };
+
+There are a couple of quirks to the PLLs. First, there are more frequency ratios
+just above and below 1.0, but there is a small gap around 1.0. To be explicit,
+if the input frequency is 100 MHz, it would be impossible to have an output of
+99 or 101 MHz. In addition, there is a maximum frequency for the internal VCO,
+so higher input/output frequencies will be less accurate than lower ones.
+
+Technical Details
+-----------------
+
+Boot Sequence
+^^^^^^^^^^^^^
+
+1. ``RESET`` pin is deasserted.
+2. Both harts begin executing at ``0x00001000``.
+3. Both harts jump to firmware at ``0x88000000``.
+4. One hart is chosen as a boot hart.
+5. Firmware reads value of pin ``IO_16`` (ISP).
+
+   * If the pin is low, enter ISP mode. This mode allows loading data to ram,
+     writing it to flash, and booting from specific addresses.
+   * If the pin is high, continue boot.
+6. Firmware reads the next stage from flash (SPI3) to address ``0x80000000``.
+
+   * If byte 0 is 1, the next stage is decrypted using the built-in AES
+     accelerator and the one-time programmable, 128-bit AES key.
+   * Bytes 1 to 4 hold the length of the next stage.
+   * The SHA-256 sum of the next stage is automatically calculated, and verified
+     against the 32 bytes following the next stage.
+7. The boot hart sends an IPI to the other hart telling it to jump to the next
+   stage.
+8. The boot hart jumps to ``0x80000000``.
+
+Memory Map
+^^^^^^^^^^
+
+========== ========= ===========
+Address    Size      Description
+========== ========= ===========
+0x00000000 0x1000    debug
+0x00001000 0x1000    rom
+0x02000000 0xC000    clint
+0x0C000000 0x4000000 plic
+0x38000000 0x1000    uarths
+0x38001000 0x1000    gpiohs
+0x40000000 0x400000  sram0 (non-cached)
+0x40400000 0x200000  sram1 (non-cached)
+0x40600000 0x200000  airam (non-cached)
+0x40800000 0xC00000  kpu
+0x42000000 0x400000  fft
+0x50000000 0x1000    dmac
+0x50200000 0x200000  apb0
+0x50200000 0x80      gpio
+0x50210000 0x100     uart0
+0x50220000 0x100     uart1
+0x50230000 0x100     uart2
+0x50240000 0x100     spi slave
+0x50250000 0x200     i2s0
+0x50250200 0x200     apu
+0x50260000 0x200     i2s1
+0x50270000 0x200     i2s2
+0x50280000 0x100     i2c0
+0x50290000 0x100     i2c1
+0x502A0000 0x100     i2c2
+0x502B0000 0x100     fpioa
+0x502C0000 0x100     sha256
+0x502D0000 0x100     timer0
+0x502E0000 0x100     timer1
+0x502F0000 0x100     timer2
+0x50400000 0x200000  apb1
+0x50400000 0x100     wdt0
+0x50410000 0x100     wdt1
+0x50420000 0x100     otp control
+0x50430000 0x100     dvp
+0x50440000 0x100     sysctl
+0x50450000 0x100     aes
+0x50460000 0x100     rtc
+0x52000000 0x4000000 apb2
+0x52000000 0x100     spi0
+0x53000000 0x100     spi1
+0x54000000 0x200     spi3
+0x80000000 0x400000  sram0 (cached)
+0x80400000 0x200000  sram1 (cached)
+0x80600000 0x200000  airam (cached)
+0x88000000 0x20000   otp
+0x88000000 0xC200    firmware
+0x8801C000 0x1000    riscv priv spec 1.9 config
+0x8801D000 0x2000    flattened device tree (contains only addresses and
+                     interrupts)
+0x8801f000 0x1000    credits
+========== ========= ===========
-- 
cgit