[PATCH v3 7/7] doc: board: apple: Add Apple M1 documentation

[Mark Kettenis]

> From: Simon Glass <sjg at chromium.org>
> Date: Mon, 11 Oct 2021 13:10:02 -0600
> 
> Hi Mark,
> 
> On Mon, 11 Oct 2021 at 10:40, Mark Kettenis <kettenis at openbsd.org> wrote:
> >
> > Provide preliminary instructions on how to get U-Boot to run on
> > Apple Silicon Macs.
> 
> Apple-Silicon
> 
> This is ambiguous. The Macs are not made out of silicon. It is a Mac
> using Apple Silicon.

Well, this is the marketing term that tends to be used to distinguish
them from the Macs with an Intel CPU in them.  It doesn't have to make
sense ;).

> 
> >
> > Signed-off-by: Mark Kettenis <kettenis at openbsd.org>
> > ---
> >  doc/board/apple/index.rst |  9 +++++++
> >  doc/board/apple/m1.rst    | 56 +++++++++++++++++++++++++++++++++++++++
> >  doc/board/index.rst       |  1 +
> >  3 files changed, 66 insertions(+)
> >  create mode 100644 doc/board/apple/index.rst
> >  create mode 100644 doc/board/apple/m1.rst
> >
> > diff --git a/doc/board/apple/index.rst b/doc/board/apple/index.rst
> > new file mode 100644
> > index 0000000000..8446847818
> > --- /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
> > index 0000000000..2f2d940a4c
> > --- /dev/null
> > +++ b/doc/board/apple/m1.rst
> > @@ -0,0 +1,56 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +
> > +U-Boot for Apple Silicon Macs
> 
> Apple-Silicon
> 
> > +=============================
> > +
> > +Allows Apple Silicon Macs to boot U-Boot via the m1n1 bootloader
> 
> Apple-Silicon
> 
> > +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
> 
> Tested on MacBook Air 2020 A2337
> Tested-by: Simon Glass <sjg at chromium.org>
> 
> > +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
> 
> or just u-boot.bin which is more normal

But that one has the DTB baked in, so it makes no sense to use it in
this context as the DTB is provided separately.

> > +
> > +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 aa397ab942..1b93ced563 100644
> > --- 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
> > --
> > 2.33.0
> >
> 
> Regards,
> Simon
>