Start documentation section for Enclustra. Cover Enclustra Intel SoMs and related carrier board setups.
- Mercury AA1 (Arria10)
Signed-off-by: Lothar Rubusch l.rubusch@gmail.com --- doc/board/enclustra/index.rst | 9 ++ doc/board/enclustra/mercury-aa1.rst | 207 ++++++++++++++++++++++++++++ doc/board/index.rst | 1 + 3 files changed, 217 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..7c82fed212 --- /dev/null +++ b/doc/board/enclustra/mercury-aa1.rst @@ -0,0 +1,207 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later +.. sectionauthor:: Lothar Rubusch l.rubusch@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. 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 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 ``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 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 +``bitstream.its`` in board/enclustra then is used to bundle them. + + .. code-block:: bash + + $ cp <from quartus design>/bitstream.periph.rbf ./board/enclustra/mercury_aa1/ + $ cp <from quartus design>/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. + + .. 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 + +Note: 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 official 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@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@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