board: stemmy: Update documentation

Over the time, the "stemmy" U-Boot board was tested on several other
Samsung smartphones based on ST-Ericsson NovaThor Ux500. Convert the
documentation to reStructuredText at doc/board/ste/stemmy.rst and
make the device list complete. Also note that the board now boots
into USB Fastboot instead of just ending up at the U-Boot prompt.

The device table is mostly taken from the postmarketOS wiki article
(https://wiki.postmarketos.org/wiki/ST-Ericsson_NovaThor_U8500).
All the newly added devices were tested by Linus Walleij.

Signed-off-by: Stephan Gerhold <stephan@gerhold.net>

6 files changed, 99 insertions, 56 deletions

diff --git a/arch/arm/mach-u8500/Kconfig b/arch/arm/mach-u8500/Kconfig
index db7a29a54c..b067a719e7 100644
--- a/arch/arm/mach-u8500/Kconfig
+++ b/arch/arm/mach-u8500/Kconfig
@@ -13,14 +13,15 @@ config TARGET_STEMMY
 	  The Samsung "stemmy" board supports Samsung smartphones released with
 	  the ST-Ericsson NovaThor U8500 SoC, e.g.
 
-	      - Samsung Galaxy S III mini (GT-I8190)	"golden"
+	      - Samsung Galaxy Ace 2 (GT-I8160)		"codina"
+	      - Samsung Galaxy Amp (SGH-I407)		"kyle"
+	      - Samsung Galaxy Beam (GT-I8530)		"gavini"
+	      - Samsung Galaxy Exhibit (SGH-T599)	"codina" (TMO)
 	      - Samsung Galaxy S Advance (GT-I9070)	"janice"
+	      - Samsung Galaxy S III mini (GT-I8190)	"golden"
 	      - Samsung Galaxy Xcover 2 (GT-S7710)	"skomer"
-	      - Samsung Galaxy Ace 2 (GT-I8160)		"codina"
-
-	  and likely others as well (untested).
 
-	  See board/ste/stemmy/README for details.
+	  See doc/board/ste/stemmy.rst for details.
 
 endchoice
 
diff --git a/board/ste/stemmy/MAINTAINERS b/board/ste/stemmy/MAINTAINERS
index 37daabea9c..fa06488284 100644
--- a/board/ste/stemmy/MAINTAINERS
+++ b/board/ste/stemmy/MAINTAINERS
@@ -2,5 +2,6 @@ STEMMY BOARD
 M:	Stephan Gerhold <stephan@gerhold.net>
 S:	Maintained
 F:	board/ste/stemmy/
-F:	include/configs/stemmy.h
 F:	configs/stemmy_defconfig
+F:	doc/board/ste/stemmy.rst
+F:	include/configs/stemmy.h
diff --git a/board/ste/stemmy/README b/board/ste/stemmy/README
deleted file mode 100644
index 1b83b833c0..0000000000
--- a/board/ste/stemmy/README
+++ /dev/null
@@ -1,50 +0,0 @@
-ST-Ericsson U8500 Samsung "stemmy" board
-========================================
-
-The "stemmy" board supports Samsung smartphones released with
-the ST-Ericsson NovaThor U8500 SoC, e.g.
-
-	- Samsung Galaxy S III mini (GT-I8190)	"golden"
-	- Samsung Galaxy S Advance (GT-I9070)	"janice"
-	- Samsung Galaxy Xcover 2 (GT-S7710)	"skomer"
-	- Samsung Galaxy Ace 2 (GT-I8160)	"codina"
-
-and likely others as well (untested).
-
-At the moment, U-Boot is intended to be chain-loaded from
-the original Samsung bootloader, not replacing it entirely.
-
-Installation
-------------
-
-1. Setup cross compiler, e.g. export CROSS_COMPILE=arm-none-eabi-
-2. make stemmy_defconfig
-3. make
-
-For newer devices (golden and skomer), the U-Boot binary has to be packed into
-an Android boot image. janice boots the raw U-Boot binary from the boot partition.
-
-4. Obtain mkbootimg, e.g. https://android.googlesource.com/platform/system/core/+/refs/tags/android-7.1.2_r37/mkbootimg/mkbootimg
-5. mkbootimg \
-    --kernel=u-boot.bin \
-    --base=0x00000000 \
-    --kernel_offset=0x00100000 \
-    --ramdisk_offset=0x02000000 \
-    --tags_offset=0x00000100 \
-    --output=u-boot.img
-
-6. Enter Samsung download mode (press Power + Home + Volume Down)
-7. Flash U-Boot image to Android boot partition using Heimdall:
-     https://gitlab.com/BenjaminDobell/Heimdall
-
-   heimdall flash --Kernel u-boot.(bin|img)
-
-8. After reboot U-Boot prompt should appear via UART.
-
-UART
-----
-
-UART is available through the micro USB port, similar to the Carkit standard.
-With a ~619kOhm resistor between ID and GND, 1.8V RX/TX is available at D+/D-.
-
-Make sure to connect the UART cable *before* turning on the phone.
diff --git a/doc/board/index.rst b/doc/board/index.rst
index 33087074fa..8588e453d5 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -26,6 +26,7 @@ Board-specific doc
    sipeed/index
    socionext/index
    st/index
+   ste/index
    tbs/index
    ti/index
    toradex/index
diff --git a/doc/board/ste/index.rst b/doc/board/ste/index.rst
new file mode 100644
index 0000000000..bef520ce63
--- /dev/null
+++ b/doc/board/ste/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+ST-Ericsson
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   stemmy
diff --git a/doc/board/ste/stemmy.rst b/doc/board/ste/stemmy.rst
new file mode 100644
index 0000000000..6d77fe9c83
--- /dev/null
+++ b/doc/board/ste/stemmy.rst
@@ -0,0 +1,81 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Stephan Gerhold <stephan@gerhold.net>
+
+ST-Ericsson U8500 Samsung "stemmy" board
+========================================
+
+The "stemmy" board supports Samsung smartphones released with
+the ST-Ericsson NovaThor U8500 SoC, e.g.
+
+    +---------------------------+----------+--------------+----------------+
+    | Device                    | Model    | Codename     | U-Boot         |
+    +===========================+==========+==============+================+
+    | Samsung Galaxy Ace 2      | GT-I8160 | codina       | ``u-boot.bin`` |
+    +---------------------------+----------+--------------+----------------+
+    | Samsung Galaxy Amp        | SGH-I407 | kyle         | ``u-boot.img`` |
+    +---------------------------+----------+--------------+----------------+
+    | Samsung Galaxy Beam       | GT-I8530 | gavini       | ``u-boot.bin`` |
+    +---------------------------+----------+--------------+----------------+
+    | Samsung Galaxy Exhibit    | SGH-T599 | codina (TMO) | ``u-boot.bin`` |
+    +---------------------------+----------+--------------+----------------+
+    | Samsung Galaxy S Advance  | GT-I9070 | janice       | ``u-boot.bin`` |
+    +---------------------------+----------+--------------+----------------+
+    | Samsung Galaxy S III mini | GT-I8190 | golden       | ``u-boot.img`` |
+    +---------------------------+----------+--------------+----------------+
+    | Samsung Galaxy Xcover 2   | GT-S7710 | skomer       | ``u-boot.img`` |
+    +---------------------------+----------+--------------+----------------+
+
+At the moment, U-Boot is intended to be chain-loaded from
+the original Samsung bootloader, not replacing it entirely.
+
+Installation
+------------
+First, setup ``CROSS_COMPILE`` for ARMv7. Then, build U-Boot for ``stemmy``::
+
+  $ export CROSS_COMPILE=arm-none-eabi-
+  $ make stemmy_defconfig
+  $ make
+
+This will build ``u-boot.bin`` in the configured output directory.
+
+For newer devices (check ``u-boot.img`` in the table above), the U-Boot binary
+has to be packed into an Android boot image. Devices with ``u-boot.bin`` boot
+the raw U-Boot binary from the boot partition. You can build the Android boot
+image with ``mkbootimg``, e.g. from from android-7.1.2_r37_::
+
+  $ mkbootimg \
+    --kernel=u-boot.bin \
+    --base=0x00000000 \
+    --kernel_offset=0x00100000 \
+    --ramdisk_offset=0x02000000 \
+    --tags_offset=0x00000100 \
+    --output=u-boot.img
+
+.. _android-7.1.2_r37: https://android.googlesource.com/platform/system/core/+/refs/tags/android-7.1.2_r37/mkbootimg/mkbootimg
+
+To flash the U-Boot binary, enter the Samsung download mode
+(press Power + Home + Volume Down). Use Heimdall_ to flash the U-Boot image to
+the Android boot partition::
+
+  $ heimdall flash --Kernel u-boot.(bin|img)
+
+If this is not working but there are messages like ``Android recovery image`` in
+the UART console, you can try flashing to the recovery partition instead::
+
+  $ heimdall flash --Kernel2 u-boot.(bin|img)
+
+.. _Heimdall: https://gitlab.com/BenjaminDobell/Heimdall
+
+After a reboot the U-Boot prompt should appear via UART. Unless interrupted it
+automatically boots to USB Fastboot mode where Android boot images can be booted
+via ``fastboot boot boot.img``. It is mainly intended to boot mainline Linux,
+but booting original Samsung Android boot images is also supported (e.g. for
+charging).
+
+UART
+----
+UART is available through the micro USB port, similar to the Carkit standard.
+With a ~619kOhm resistor between ID and GND, 1.8V RX/TX is available at D+/D-.
+
+.. note::
+  Make sure to connect the UART cable **before** turning on the phone.