doc: board: apple: Add Apple M1 documentation

Provide preliminary instructions on how to get U-Boot to run on
Apple Silicon Macs.

Signed-off-by: Mark Kettenis <kettenis@openbsd.org>
Reviewed-by: Simon Glass <sjg@chromium.org>

diff --git a/doc/board/apple/index.rst b/doc/board/apple/index.rst
new file mode 100644 (file)
index 0000000..8446847
--- /dev/null
+++ b/doc/board/apple/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Apple
+=====
+
+.. toctree::
+   :maxdepth: 2
+
+   m1

diff --git a/doc/board/apple/m1.rst b/doc/board/apple/m1.rst
new file mode 100644 (file)
index 0000000..9fa2176
--- /dev/null
+++ b/doc/board/apple/m1.rst
@@ -0,0 +1,59 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+U-Boot for Apple Silicon Macs
+=============================
+
+Allows Apple Silicon Macs to boot U-Boot via the m1n1 bootloader
+developed by the Asahi Linux project.  At this point the machines with
+the following SoCs work:
+
+ - Apple M1 SoC
+
+On these SoCs the following hardware is supported:
+
+ - S5L serial port
+ - Framebuffer
+ - USB 3.1 Type-C ports
+
+Device trees are currently provided for the M1 Mac mini (2020, J274)
+and M1 MacBook Pro 13" (2020, J293).  The M1 MacBook Air (2020) is
+expected to work with the J293 device tree.  The M1 iMac (2021) may
+work with the J274 device tree.
+
+Building U-Boot
+---------------
+
+.. code-block:: bash
+
+    $ export CROSS_COMPILE=aarch64-none-elf-
+    $ make apple_m1_defconfig
+    $ make
+
+This will build ``u-boot-nodtb.bin`` as well as devices trees for some
+of the supported machines.  These device trees can be found in the
+``arch/arm/dts`` subdirectory of your build.
+
+Image creation
+--------------
+
+In order to run U-Boot on an Apple Silicon Mac, U-Boot has to be used
+as a payload for the m1n1 bootloader.  Instructions for building m1n1
+can be found here:
+
+    https://github.com/AsahiLinux/docs/wiki/SW%3Am1n1
+
+.. code-block:: bash
+
+    $ cat m1n1.macho t8103-j274.dtb u-boot-nodtb.bin > u-boot.macho
+
+This uses ``u-boot-nodtb.bin`` as the device tree is passed to U-Boot
+by m1n1 after making some adjustments.
+
+Image installation
+------------------
+
+Instructions on how to install U-Boot on your Mac can be found at:
+
+    https://github.com/AsahiLinux/docs/wiki/Developer-Quickstart
+
+Just replace ``m1n1.macho`` with ``u-boot.macho`` in the instructions.

diff --git a/doc/board/index.rst b/doc/board/index.rst
index aa397ab94213e9fffab03acb0af81636340a06ea..1b93ced56346f05f0abb05b536808ae139a7a72c 100644 (file)
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -10,6 +10,7 @@ Board-specific doc
    advantech/index
    AndesTech/index
    amlogic/index
+   apple/index
    atmel/index
    congatec/index
    coreboot/index