[PATCH 1/9] doc: board: enclustra: add Enclustra Intel AA1 SoM
Lothar Rubusch
l.rubusch at gmail.com
Thu Sep 12 08:06:41 CEST 2024
Start documentation section for Enclustra. Cover Enclustra Intel SoMs and
related carrier board setups.
- Mercury AA1 (Arria10)
Signed-off-by: Lothar Rubusch <l.rubusch at gmail.com>
---
doc/board/enclustra/index.rst | 9 ++
doc/board/enclustra/mercury-aa1.rst | 209 ++++++++++++++++++++++++++++
doc/board/index.rst | 1 +
3 files changed, 219 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..0331756045
--- /dev/null
+++ b/doc/board/enclustra/mercury-aa1.rst
@@ -0,0 +1,209 @@
+.. 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 yocto
+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
+- Yocto 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 folder ``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. Also,
+optionally prepare an environment file. Examples of boot command files and
+environment files are provided.
+
+.. code-block:: bash
+
+ $ ./tools/mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "Uboot mmc startscript" -d board/enclustra/bootscripts/sd-aa1.cmd boot.scr
+ $ ./tools/mkenvimage -s 0x80000 -o uboot.env board/enclustra/mercury_aa1/mercury_aa1.env
+
+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:
+
+* ``type=c, start=2048, size=409600``
+* ``type=a2, start=411648, size=14336``
+* ``type=83, start=425984, size=1619968``
+
+.. code-block:: bash
+
+ $ sudo fdisk /dev/sda
+ n,p,1,2048,+20M
+ t,1,c
+ n,p,2,409600,+1M
+ t,2,a2
+ n,p,3,425984,<REST>
+ t,3,83
+ w
+
+Note: The ``bitstream.itb`` is needed to start the bootloader. A kernel
+``devicetree.dtb`` is needed to boot into the system. Both are not part of
+u-boot, but are be provided through yocto 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 yocto's deploy folder. The
+``bitstream.its`` in board/enclustra then is used to bundle them.
+
+ .. code-block:: bash
+
+ $ cp bitstream.periph.rbf ./board/enclustra/mercury_aa1/
+ $ cp bitstream.core.rbf ./board/enclustra/mercury_aa1/
+ $ ./tools/mkimage -E -f ./board/enclustra/mercury_aa1/bitstream.its bitstream.itb
+
+Format the SD card, and copy the following artifacts to the mounted boot
+partition, e.g. on /dev/sda (check before).
+
+ .. code-block:: bash
+
+ $ mkfs.vfat -n boot /dev/sda1
+ $ mount /dev/sda1 /media/boot
+ $ cp ./{boot.scr,u-boot.img,uboot.env,bitstream.itb,Image,devicetree.dtb} /media/boot/
+ $ umount /dev/sda1
+
+Flash the SPL directly.
+
+ .. code-block:: bash
+
+ $ 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
+
+NB: eMMC and QSPI can be flashed from off the u-boot shell. Usually after
+flashing, the coorect boot mode needs to be set by a BSEL switch. Approaches
+are described consistently in the offical Enclustra documentation according to
+their releases mentioned as links.
+
+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-rc4-00416-gf0b9c383e6c3 (Sep 08 2024 - 14:03:59 +0000)
+ 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-rc4-00416-gf0b9c383e6c3 (Sep 08 2024 - 14:03:59 +0000)
+ 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-rc4-00416-gf0b9c383e6c3 (Sep 08 2024 - 14:03:59 +0000)socfpga_arria10
+
+ 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 417c128c7a..42244a689b 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -24,6 +24,7 @@ Board-specific doc
congatec/index
coreboot/index
emulation/index
+ enclustra/index
gateworks/index
google/index
highbank/index
--
2.25.1
More information about the U-Boot
mailing list