[PATCH 14/15] doc: bcm283x: add initial docs for Raspberry Pi 4 support

[Ahmad Fatoum]

Separate out the barebox-dt-2nd documentation. There's much duplication
that way, but as we intend to remove the board-specific raspberry pi
images, this is ok for now.

Signed-off-by: Ahmad Fatoum <a.fatoum at pengutronix.de>
---
 Documentation/boards/bcm2835.rst | 61 +++++++++++++++++++++++++++++---
 1 file changed, 56 insertions(+), 5 deletions(-)

diff --git a/Documentation/boards/bcm2835.rst b/Documentation/boards/bcm2835.rst
index 0b5299a34078..b27c6f34a50b 100644
--- a/Documentation/boards/bcm2835.rst
+++ b/Documentation/boards/bcm2835.rst
@@ -4,6 +4,17 @@ Broadcom BCM283x
 Raspberry Pi
 ------------
 
+barebox supports has support for BCM283x-based Raspberry Pi single board
+computers. Support is most extensive for BCM283[567]. Forthe newer BCM2711
+used in the Raspberry Pi 4, only basic support is available currently
+(Serial Port @115200 Baud, Pinctrl, SD-Card).
+
+Legacy Raspberry Pi Images
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This format will be eventually phased out in favor of using the generic
+``barebox-dt-2nd.img`` binary for all configurations.
+
   1. Prepare an SD or microSD card with a FAT filesystem of at least 30 MB in size.
 
   2. Download the `Raspberry Pi firmware`_ (120 MB), unzip it, and copy the
@@ -19,11 +30,6 @@ Raspberry Pi
      Copy the respective image for your model to your SD card and name it
      ``barebox.img``.
 
-     Alternatively, ``images/barebox-dt-2nd.img`` can be used as single bootloader for all
-     supported 32-bit boards. In this case the device tree supplied by the video core
-     is directly used by barebox to probe. The device trees in ``arch/arm/dts/*.dtb``
-     will need to be renamed for alignment with the naming scheme expected by the videocore.
-
   4. Create a text file ``config.txt`` on the SD card with the following content::
 
          kernel=barebox.img
@@ -53,5 +59,50 @@ The original command-line from VideoCore device tree is available to the Barebox
 
     global linux.bootargs.vc="$global.vc.bootargs"
 
+Generic DT image
+~~~~~~~~~~~~~~~~
+
+  1. Prepare an SD or microSD card with a FAT filesystem of at least 30 MB in size.
+
+  2. Download the `Raspberry Pi firmware`_ (120 MB), unzip it, and copy the
+     contents of the ``boot/`` folder to your card.
+
+  3. Use ``make rpi_defconfig; make`` to build barebox for 32-Bit or ``make rpi_v8a_defconfig; make`` to build it for 64-Bit
+
+     This will create ``images/barebox-dt-2nd.img``, which can be used as single bootloader
+     for all supported boards. In this case the device tree supplied by the video core
+     is directly used by barebox to probe. The device trees in ``arch/arm/dts/*.dtb``
+     will need to be renamed for alignment with the naming scheme expected by the videocore.
+     (left is name in FAT, right is name used by barebox, here in genimage syntax)::
+
+         file bcm2836-rpi-2-b.dtb { image = bcm2836-rpi-2.dtb }
+         file bcm2836-rpi-2-b.dtb { image = bcm2836-rpi-2.dtb }
+         file bcm2837-rpi-3-b.dtb { image = bcm2837-rpi-3.dtb }
+         file bcm2837-rpi-3-a-plus.dtb { image = bcm2837-rpi-3.dtb }
+         file bcm2837-rpi-3-b-plus.dtb { image = bcm2837-rpi-3.dtb }
+         file bcm2837-rpi-cm3-io3.dtb { image = bcm2837-rpi-cm3.dtb }
+         file bcm2711-rpi-4-b.dtb { image = bcm2711-rpi-4-b.dtb }
+
+  4. Create a text file ``config.txt`` on the SD card with the following content::
+
+         kernel=barebox-dt-2nd.img
+         arm_64bit=1 # remove for 32-bit mode
+         upstream_kernel=1 # use upstream DT file names
+         enable_uart=1
+
+     If you want to use the mini-uart instead of the PL011, you may need to additionally set::
+
+         uart_2ndstage=1
+
+     This is required on boards, like the Raspberry Pi Zero W, that use the mini-uart as the
+     primary UART. It is needed on boards like the CM3 as well if the mini-uart is to be used.
+
+     (For more information, refer to the `documentation for config.txt`_.)
+
+  5. Connect to board's UART (115200 8N1);
+     Use PIN6 (GND), PIN8 (UART_TX), PIN10 (UART_RX) pins.
+
+  6. Turn board's power on.
+
 .. _Raspberry Pi firmware: https://codeload.github.com/raspberrypi/firmware/zip/80e1fbeb78f9df06701d28c0ed3a3060a3f557ef
 .. _documentation for config.txt: https://www.raspberrypi.org/documentation/configuration/config-txt/
-- 
2.30.2