[PATCH v4 v5 01/10] doc: board: enclustra: add Enclustra Mercury+ AA1
Lothar Rubusch
l.rubusch at gmail.com
Tue Nov 19 23:46:34 CET 2024
Start documentation section for Enclustra. Cover Enclustra Intel SoMs and
related carrier board setups. The section covers the Mercury+ AA1 SoM
(Intel/arria10).
Signed-off-by: Lothar Rubusch <l.rubusch at gmail.com>
---
doc/board/enclustra/index.rst | 9 ++
doc/board/enclustra/mercury-aa1.rst | 202 ++++++++++++++++++++++++++++
doc/board/index.rst | 1 +
3 files changed, 212 insertions(+)
create mode 100644 doc/board/enclustra/index.rst
create mode 100644 doc/board/enclustra/mercury-aa1.rst
diff --git a/doc/board/enclustra/index.rst b/doc/board/enclustra/index.rst
new file mode 100644
index 0000000000..00727d0861
--- /dev/null
+++ b/doc/board/enclustra/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Enclustra
+=========
+
+.. toctree::
+ :maxdepth: 2
+
+ mercury-aa1
diff --git a/doc/board/enclustra/mercury-aa1.rst b/doc/board/enclustra/mercury-aa1.rst
new file mode 100644
index 0000000000..dec7cc3bdd
--- /dev/null
+++ b/doc/board/enclustra/mercury-aa1.rst
@@ -0,0 +1,202 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. sectionauthor:: Lothar Rubusch <l.rubusch at gmail.com>
+
+Mercury AA1 Module (Arria1 10)
+==============================
+
+- SoM: https://www.enclustra.com/en/products/system-on-chip-modules/mercury-aa1/
+- Carrier board Mercury+ ST1: https://www.enclustra.com/en/products/base-boards/mercury-st1/
+- Carrier board Mercury+ PE1: https://www.enclustra.com/en/products/base-boards/mercury-pe1-200-300-400/
+- Carrier board Mercury+ PE3: https://www.enclustra.com/en/products/base-boards/mercury-pe3/
+
+There are slightly different variants of the AA1 SoM, going by the identifier.
+
+- Me-aa1-270-2i2-d11e-nfx3
+- Me-aa1-270-3e4-d11e-nfx3
+- Me-aa1-480-2i3-d12e-nfx3
+
+The u-boot setup is specific to a quartus design. Generate handoff files from
+the design. Pass them to a python script to produce a handoff.h file. This is
+needed as input for building the device-tree for u-boot. Eventually, building
+the final u-boot depends on the particular Quartus design, the particular
+carrier board, the selected boot media and boot mode.
+
+Enclustra provides reference design examples which can be built with
+OpenEmbedded using their meta-layer.
+
+- Reference Design AA1 on ST1: https://github.com/enclustra/Mercury_AA1_ST1_Reference_Design
+- Reference Design AA1 on PE1: https://github.com/enclustra/Mercury_AA1_PE1_Reference_Design
+- Reference Design AA1 on PE3: https://github.com/enclustra/Mercury_AA1_PE3_Reference_Design
+- OpenEmbedded meta-layer: https://github.com/enclustra/meta-enclustra-socfpga
+
+Quick Start
+-----------
+
+- Setup and build a Quartus design project
+- Obtain the hps.xml file from the Quartus design project
+- Generate the handoff.h file for u-boot
+- Adjust the device-tree file according to your setup
+- Build u-boot
+- Flash u-boot
+
+Build U-Boot
+------------
+
+The Quartus design produces a design specific ``hps.xml``, an ``emif.xml`` and
+a corresponding ``id`` file contained in a directory ``handoff``.
+
+Generate the handoff.h file for u-boot, from a provided ``hps.xml`` using the
+script provided in u-boot.
+
+.. code-block:: bash
+
+ $ arch/arm/mach-socfpga/qts-filter-a10.sh <where you saved it>/hps.xml arch/arm/dts/socfpga_arria10_mercury_aa1_handoff.h
+
+Adjust the device-tree file according to your setup. Follow the comments in the
+file.
+
+.. code-block:: bash
+
+ $ vi ./arch/arm/dts/enclustra-aa1.dts
+
+Build u-boot. Source your favorite toolchain for ARM first.
+
+.. code-block:: bash
+
+ $ make socfpga_enclustra_mercury_aa1_defconfig
+ $ make -j8
+
+Setup and compile a boot script as needed. Depending on the boot-mode select
+``sd-aa1.cmd`` for SD/eMMC, or ``qspi-aa1.cmd`` for QSPI flash.
+
+.. code-block:: bash
+
+ $ ./tools/mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "U-boot mmc startscript" -d board/enclustra/bootscripts/sd-aa1.cmd boot.scr
+
+Device-Tree setup
+-----------------
+
+The basic u-boot device-tree fragments are provided here. The handoff tools
+will generate further u-boot device-tree fragments. The various .dtsi files
+then need to be included in a top-level .dts file.
+
+Flash the U-Boot Binary to a Micro SD Card
+------------------------------------------
+
+The following example describes the full approach. Prepare a micro SD card with
+three partitions as follows e.g. on /dev/sda (check before):
+
+* ``type=c, start=2048, size=409600``
+* ``type=a2, start=411648, size=14336``
+* ``type=83, start=425984, size=1619968``
+
+.. code-block:: bash
+
+ $ cat ./partitionmap.txt
+ start= 2048, size= 102400, type=b, bootable
+ start= 104448, size= 4096, type=a2
+ start= 108544, size= 819200, type=83
+
+ $ sudo sfdisk /dev/sde < ./partitionmap.txt
+
+Note: The ``fpga.itb`` is needed to start the bootloader. A kernel
+``system.dtb`` is needed to boot into the system. Both are not part of
+u-boot, but are be provided through OpenEmbedded using Enclustra's meta-layer.
+
+Generally the bitstream files depend on the logic design, but the meta-layer
+provides a demo design. Copy the ``bitstream.periph.rbf`` and
+``bitstream.core.rbf`` from your design or OpenEmbedded's deploy directory. The
+``fpga.its`` in board/enclustra then is used to bundle them.
+
+ .. code-block:: bash
+
+ $ cp <from quartus design>/bitstream.periph.rbf ./
+ $ cp <from quartus design>/bitstream.core.rbf ./
+ $ ./tools/mkimage -E -f ./board/enclustra/mercury_aa1/fpga.its fpga.itb
+
+Format the SD card, and copy the following artifacts to the mounted boot
+partition, e.g. on /dev/sda.
+
+ .. code-block:: bash
+
+ $ mkfs.vfat -n boot /dev/sda1
+ $ mount /dev/sda1 /media/boot
+ $ cp ./{boot.scr,u-boot.img,fpga.itb,Image,system.dtb} /media/boot/
+ $ umount /dev/sda1
+
+Flash the SPL directly.
+
+ .. code-block:: bash
+
+ $ sudo dd if=./spl/u-boot-splx4.sfp of=/dev/sda2 conv=fdatasync bs=4k status=progress
+
+Format and flash a rootfs from image or files to the third partition.
+
+ .. code-block:: bash
+
+ $ mkfs.ext4 -L rootfs /dev/sda3
+ $ mount /dev/sda3 /media/rootfs
+ $ tar xf ./rootfs.tar -C /media/rootfs
+ $ umount /dev/sda3
+
+Boot Media
+----------
+
+Alternative boot media are possible as officially documented by Enclustra.
+
+* Micro-SD card
+* eMMC
+* QSPI
+
+Note: eMMC and QSPI can be flashed from off the u-boot shell. Usually after
+flashing, the correct boot mode needs to be set by a BSEL switch.
+
+Before turning on the setup, make sure to have the correct voltage configured
+at the carrier board, using the jumpers on the voltage pin header. Also make
+sure to have switched to the correct boot media using typically some dip
+switches to be found on the carrier board.
+
+Boot Log
+--------
+
+The demo shows booting a AA1 + ST1 setup and stopping at the u-boot shell.
+
+Here is the console output::
+
+ U-Boot SPL 2024.10
+ FPGA: Checking FPGA configuration setting ...
+ FPGA: Start to program peripheral/full bitstream ...
+ FPGA: Early Release Succeeded.
+ FPGA: Checking FPGA configuration setting ...
+ FPGA: Start to program peripheral/full bitstream ...
+ FPGA: Early Release Succeeded.
+
+ U-Boot SPL 2024.10
+ DDRCAL: Success
+ DDRCAL: Scrubbing ECC RAM (2048 MiB).
+ DDRCAL: Scrubbing ECC RAM done.
+ FPGA: Checking FPGA configuration setting ...
+ FPGA: Start to program core bitstream ...
+ Full Configuration Succeeded.
+ FPGA: Enter user mode.
+ Trying to boot from MMC1
+
+
+ U-Boot 2024.10
+
+ CPU: Altera SoCFPGA Arria 10
+ BOOT: SD/MMC External Transceiver (1.8V)
+ Model: Enclustra Mercury+ AA1
+ DRAM: 2 GiB
+ Core: 80 devices, 20 uclasses, devicetree: separate
+ MMC: dwmmc0 at ff808000: 0
+ Loading Environment from FAT... OK
+ In: serial
+ Out: serial
+ Err: serial
+ Model: Enclustra Mercury+ AA1
+ ethaddr set to 20:B0:F7:06:0D:BE
+ eth1addr set to 20:B0:F7:06:0D:BF
+ Net: eth0: ethernet at ff800000
+ =>
+
diff --git a/doc/board/index.rst b/doc/board/index.rst
index 3fb7c84f10..26feff48cd 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -25,6 +25,7 @@ Board-specific doc
congatec/index
coreboot/index
emulation/index
+ enclustra/index
gateworks/index
google/index
highbank/index
--
2.39.2
More information about the U-Boot
mailing list