[PATCH v2 3/3] doc: samsung: exynos-mobile: add documentation for exynos7870

[Kaustabh Chakraborty]

Document the image preparation and flashing techniques for
Exynos7870-based boards. This is done in a separate file in a
sub-directory, which is linked back to the main documentation.

Signed-off-by: Kaustabh Chakraborty <kauschluss at disroot.org>
---
 doc/board/samsung/exynos-mobile.rst            |  5 ++
 doc/board/samsung/exynos-mobile/exynos7870.rst | 85 ++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)

diff --git a/doc/board/samsung/exynos-mobile.rst b/doc/board/samsung/exynos-mobile.rst
index d5c1c83a4e84ac0fc9401b02de0ec786c9397892..9634991c0a171da832c65e119d6fe3e3b8331840 100644
--- a/doc/board/samsung/exynos-mobile.rst
+++ b/doc/board/samsung/exynos-mobile.rst
@@ -38,3 +38,8 @@ Preparation and Flashing
 ^^^^^^^^^^^^^^^^^^^^^^^^
 Since U-Boot supports multiple boards, and devices have different requirements,
 this step will vary depending on your target.
+
+.. toctree::
+	:maxdepth: 1
+
+	exynos-mobile/exynos7870
diff --git a/doc/board/samsung/exynos-mobile/exynos7870.rst b/doc/board/samsung/exynos-mobile/exynos7870.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bbd857580b8275a7cc87b539075a9a9c17c630cc
--- /dev/null
+++ b/doc/board/samsung/exynos-mobile/exynos7870.rst
@@ -0,0 +1,85 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Kaustabh Chakraborty <kauschluss at disroot.org>
+
+Samsung Exynos 7870 Boards
+==========================
+
+Preparation
+-----------
+Create the following device tree (named ``stub.dts``)
+
+.. code-block:: devicetree
+
+	/dts-v1/;
+
+	/ {
+		compatible = "samsung,exynos7870";
+		#address-cells = <2>;
+		#size-cells = <1>;
+
+		model_info-chip = <7870>;
+		model_info-hw_rev = <0>;
+		model_info-hw_rev_end = <255>;
+
+		chosen {
+		};
+
+		memory at 80000000 {
+			device_type = "memory";
+			reg = <0x0 0x80000000 0x0>;
+		};
+
+		memory at 100000000 {
+			device_type = "memory";
+			reg = <0x1 0x00000000 0x0>;
+		};
+	};
+
+The chosen node and memory ranges are populated by S-BOOT. A certain device
+model may have multiple variants, with differing amounts of RAM and storage. The
+RAM capacity information is graciously provided by S-BOOT's device tree
+overlays.
+
+Compile it to a device tree blob, then pack it in the QCDT format [1]_ using
+``dtbTool-exynos`` [2]_ by issuing the following commands:
+
+.. prompt:: bash $
+
+	dtc -I dts -O dtb -o stub.dtb stub.dts
+	dtbTool-exynos -o stub-dt.img stub.dtb
+
+Finally, use ``mkbootimg`` by osm0sis [3]_ to generate the boot image:
+
+.. prompt:: bash $
+
+	mkbootimg -o u-boot.img \
+		--kernel	.output/u-boot.bin \
+		--dt		stub-dt.img
+
+Offsets are not provided to ``mkbootimg`` as S-BOOT ignores them.
+
+Flashing
+--------
+If flashing for the first time, it must be done via Samsung's Download (Odin)
+mode. Heimdall [4]_ can be used for flashing, like so:
+
+.. prompt:: bash $
+
+	heimdall flash --BOOT u-boot.img
+
+However, if U-Boot is already installed, you may also use its fastboot interface
+for flashing. Boot into the boot menu by holding the volume down key. Enable
+fastboot mode from there, connect the device to your host, then run:
+
+.. prompt:: bash $
+
+	fastboot flash boot u-boot.img
+
+To flash an OS image in internal storage, fastboot is a reliable option.
+
+References
+----------
+.. [1] https://wiki.postmarketos.org/wiki/QCDT
+.. [2] https://github.com/dsankouski/dtbtool-exynos
+.. [3] https://github.com/osm0sis/mkbootimg
+.. [4] https://git.sr.ht/~grimler/Heimdall

-- 
2.51.0