The main difference between the two different editions exists in the SoC devices that are supported, as mentioned in the previous section.

Download information for these components are located in the Installing the Intel^® SoC FPGA EDS section.

Depending on your role in hardware or software development, you need a different subset of the SoC EDS toolkit. The following table lists some typical engineering development roles and indicates the tools that each role typically requires.

For more information about each of these tools, refer to the Intel^® SoC FPGA Embedded Development Suite page.

As a hardware engineer, you typically design the FPGA hardware in Platform Designer. You can use the debugger of Arm* DS* for Intel^® SoC FPGA Edition to connect to the Arm* cores and test the hardware. A convenient feature of the Arm* DS* for Intel^® SoC FPGA Edition debugger is the soft IP register visibility, using Cortex Microcontroller Software Interface Standard (CMSIS) System View Description (.svd) files. With this feature, you can easily read and modify the soft IP registers from the Arm* side.

As a hardware engineer, you may generate the Preloader for your hardware configuration. The Preloader is a piece of software that configures the HPS component according to the hardware design.

As a hardware engineer, you may also perform the board bring-up. You can use Arm* DS* for Intel^® SoC FPGA Edition debugger to verify that they can connect to the Arm and the board is working correctly.

These tasks require JTAG debugging, which is provided by the Arm* DS* for Intel^® SoC FPGA Edition, which is provided through a separate download.

For more information, refer to the Installing the Intel^® SoC FPGA EDS section.

As a Bare Metal or a RTOS developer, you need JTAG debugging and low-level visibility into the system. The following tasks require JTAG debugging, which is enabled by the Arm* DS* for Intel^® SoC FPGA Edition.

For more information, see the "Licensing" section.

As a Linux* kernel or driver developer, you may use the same tools the RTOS developers use, because you need low-level access and visibility into the system. However, you must use the Linux* compiler instead of the Bare Metal compiler.

These tasks require JTAG debugging, which is enabled by the Arm* DS* for Intel^® SoC FPGA Edition, which is provided through a separate download.

For more information, refer to the Installing the Intel^® SoC FPGA EDS section.

For information about how to create a device tree, refer to the "HOWTO Create a Device Tree" web page on Rocketboards.org.

As a Linux* application developer, you write code that targets the Linux* OS running on the board. Because the OS provides drivers for all the hardware, you do not need low-level visibility over JTAG. Arm* DS* for Intel^® SoC FPGA Edition offers a very detailed view of the OS, showing information about the threads that are running and the drivers that are loaded.

Arm* DS* for Intel^® SoC FPGA Edition is provided through a separate download.

For more information, refer to the Installing the Intel^® SoC FPGA EDS section.

The Intel hardware-to-software handoff utilities allow hardware and software teams to work independently and follow their respective familiar design flows.

The following handoff files are created when the hardware project is compiled:

• Handoff folder – contains information about how the HPS component is configured, including things like which peripherals are enabled, the pin MUXing and IOCSR settings, and memory parameters. The handoff folder is used by the second stage bootloader generator to create the preloader.

  For more information about the handoff folder, refer to the "BSP Generation Flow" section.

• .svd file – contains descriptions of the HPS registers and of the soft IP registers on the FPGA side implemented in the FPGA portion of the device. The .svd file contains register descriptions for the HPS peripheral registers and soft IP components in the FPGA portion of the SoC. This file is used by the Arm* DS* for Intel^® SoC FPGA Edition Debugger to allow you to inspect and modify these registers.
• .sopcinfo file – contains a description of the entire system. The SOPC Information (.sopcinfo) file, containing a description of the entire system, is used by the Linux* device tree generator to create the device tree used by the Linux* kernel.
  For more information, refer to the "Linux* Device Tree Generator" section.

  Note: The soft IP register descriptions are not generated for all soft IP cores.

  Note: For Intel^® Stratix^® 10 SoC and Intel^® Agilex™ SoC, the handoff information is part of the configuration bitstream, and the bootloader has direct access to it. Because of that there is no need for a Bootloader Generator tool in this case.

The tools provided with SoC EDS need to be run from an Embedded Command Shell. Additionally, the Arm* DS* tools need to be run from an Arm* DS* shell.

Starting Embedded Command Shell

~/intelFPGA_pro/20.1/embedded/embedded_command_shell.sh

~/intelFPGA/20.1/embedded/embedded_command_shell.sh

Starting Arm* DS* Shell

1. Start an Embedded Command Shell.

~/intelFPGA_pro/20.1/embedded/embedded_command_shell.sh

~/intelFPGA/20.1/embedded/embedded_command_shell.sh

/opt/arm/developmentstudio-2020.0/bin/suite_exec -t "Arm Compiler 5" bash

/opt/arm/developmentstudio-2020.0/bin/suite_exec -t "Arm Compiler 6" bash

Starting Arm* DS* Eclipse

Starting Embedded Command Shell

You can start an Embedded Command Shell through navigation:

For Intel^® Quartus^® Prime Pro Edition software version 20.1: Start menu > Intel FPGA 20.1 Pro Edition > SoC EDS Command Shell

For Intel^® Quartus^® Prime Standard Edition software version 20.1: Start menu > Intel FPGA 20.1 > SoC EDS Command Shell

Starting Arm* DS* Shell

Starting Arm* DS* Eclipse

The Arm* DS* for Intel^® SoC FPGA Edition is a device-specific exclusive offering from Intel^® and is a powerful Eclipse-based comprehensive Integrated Development Environment (IDE).

For the current version, refer to Table 1.

For information about the licensing options and how to obtain them, refer to the Intel^® SoC FPGA EDS Licensing section.

For examples of using Arm* DS* for Intel^® SoC FPGA Edition, refer to the SoC EDS and Arm* Development Studio webpage on RocketBoards.

You can access the Arm* Development Studio* for Intel^® SoC FPGA Edition reference material from Eclipse, by navigating to Help > Help Contents > Arm* Developer Studio Documentation or on the Arm* website.

You can also access additional material from Eclipse, by navigating to Help > Tutorials and Videos.

This section presents the BSP generation flow for the Cyclone^® V SoC, Arria^® V SoC, and Intel^® Arria^® 10 SoC bootloader. While the flows are similar, there are some important differences.

For Cyclone^® V SoC and Arria^® V SoC, the BSP Generator is required to be run first, to convert some of the handoff files into C source code. After that, you need to clone the U-Boot source code from github. Then you use an U-Boot script called qts-filter to extract the information from the handoff folder, and the set of files created by the BSP Generator, and put them in the U-Boot source code folder. Then you use the U-Boot makefile to build the SPL image. The SPL image can then be downloaded to a Flash device or FPGA RAM to be used for booting HPS.

The hardware handoff information contains various settings that you entered when creating the hardware design in Platform Designer and Intel^® Quartus^® Prime Standard Edition. These include the following:

• Pin-muxing for the HPS dedicated pins
• I/O settings for the HPS dedicated pins:
  • Voltage
  • Slew rate
  • Pull up/ down
• Configuration of the bridges between HPS and FPGA
• Clock tree settings:
  • PLL settings
  • Clock divider settings
  • Clock gating settings
• DDR settings:
  • Technology
  • Width
  • Speed

The handoff settings are output from the Intel^® Quartus^® Prime Standard Edition compilation and are located in the <quartus project directory>/hps_isw_handoff/<hps entity name> directory (where <hps entity name > is the HPS component name in Platform Designer).

You must update the hardware handoff files and regenerate the BSP each time a hardware change impacts the HPS, such as after pin multiplexing or pin assignment changes.

For complete instructions on how to build the bootloader for Cyclone^® V SoC and Arria^® V SoC, please visit "Building Bootloader" on RocketBoards.org.

The next step is to clone the U-Boot source code from GitHub, and copy the generated device tree into U-Boot source code. For complete instructions, go to the Building Bootloader web page on RocketBoards.org. Then the U-Boot is compiled using the make utility and it creates the combined bootloader image, which contains both the bootloader executable and the bootloader device tree. You can download the combined image to a Flash device or FPGA RAM to use for booting the HPS.

The hardware handoff information contains various settings that you entered when creating the hardware design in Platform Designer.. These include the following:

• Pin-muxing for the HPS dedicated pins
• I/O settings for the HPS dedicated pins:
  • Voltage
  • Slew rate
  • Pull up/ down
• Pin-muxing for the shared pins
• Configuration of the bridges between HPS and FPGA
• Clock tree settings:
  • PLL settings
  • Clock divider settings
  • Clock gating settings

The handoff settings are output from the Intel^® Quartus^® Prime Standard Edition compilation and are located in the <quartus project directory>/hps_isw_handoff directory.

The user must run the BSP Generator and re-generate the Bootloader device tree each time a hardware change results in a change of the above parameters.

However, you does not have to always recompile the Bootloader whenever a hardware setting is changed. The Bootloader needs to be recompiled only when changing the boot source.

The BSP generator GUI is deprecated, and you do not need to use it anymore. The settings are now customized directly in the bootloader files, and not from the BSP Generator. Only the bsp-create-settings command line tool needs to be ran, but without customized options, as they are not taken into consideration.

The bsp-create-settings tool converts the Intel^® Quartus^® Prime handoff information to source code for Cyclone^® V SoC and Arria^® V SoC, and to a Device Tree for Intel^® Arria^® 10 SoC.

The mkpimage tool runs on a host machine. The tool generates the header and CRC checksum and inserts them into the output image with the bootloader program image and its exception vector.

For certain flash memory tools, the position of the bootloader images must be aligned to a specific block size; the mkpimage tool generates any padding data that may be required.

The mkpimage tool optionally decodes and validates header information when given a pre-generated bootloader image.

As illustrated, the binary bootloader image is an input to the mkpimage tool. The compiler leaves an empty space between the bootloader exception vector and the program. The mkpimage tool overwrites this empty region with header information and calculates a checksum for the whole image.

When necessary, the mkpimage tool appends the padding data to the output image.

The mkpimage tool can operate with either one or four input files. Operation on four input files consists in processing each file individually, then concatenating the four resulted images.

The mkpimage header file format has two versions:

• Version 0, used for Cyclone^® V SoC and Arria^® V SoC FSBL (Preloader)
• Version 1, used for Intel^® Arria^® 10 SoC Bootloader

For Version 0, used for Cyclone^® V SoC and Arria^® V SoC Preloader, the header includes the following:

• Validation word (0x31305341)
• Version field (set to 0x0)
• Flags field (set to 0x0)
• Program length measured by the number of 32 bit words in the Preloader program
• 16-bit checksum of the header contents (0x40 – 0x49)

For Version 1, used for Intel^® Arria^® 10 SoC Bootloader, the header includes the following:

• Validation word (0x31305341).
• Version field (set to 0x1).
• Flags field (set to 0x0).
• Header length, in bytes, set to 0x14 (20 bytes).
• Total program length (including the exception vectors and the CRC field) in bytes. For an image to be valid, length must be a minimum of 0x5C (92 bytes) and a maximum of 0x32000 (200KiB).
• Program entry offset relative to the start of header (0x40) and should be 32-bit word-aligned. Default is 0x14, any value smaller than that is invalid.
• 16-bit checksum of the header contents (0x40 – 0x51):
  Figure 24. Header Format Version 1

The header checksum for both versions of the mkpimage header is the CRC checksum of the byte value from offset 0x0 to (n*4)-4 bytes where n is the program length.

x32 + x26 + x23 + x22 + x16 + x12 + x11 + x10 + x8 + x7 + x5 + x4 + x2 + x + 1

The mkimage tool has three usage models:

• Single image creation
• Quad image creation
• Single or quad image decoding

If an error is found during the make image process, the tool stops and reports the error. Possible error conditions include:

• For Cyclone^® V SoC and Arria^® V SoC Preloaders: input image is smaller than 81 bytes or larger than 60 KB.
• For Intel^® Arria^® 10 SoC Bootloaders: input image is smaller than 92 bytes or larger than 200 KB.

Type mkpimage to launch the tool. The --help option provides a tool description and tool usage and option information.

$ mkpimage --help
mkpimage version 19.1

Description: This tool creates an Intel BootROM-compatible image of Second
Stage Boot Loader (SSBL). The input and output files are in binary format.
It can also decode and check the validity of previously generated image.

Usage:
 Create quad image:
     mkpimage [options] -hv <num> -o <outfile> <infile> <infile> <infile> <infile>
 Create single image:
     mkpimage [options] -hv <num> -o <outfile> <infile>
 Decode single/quad image:
     mkpimage -d [-a <num>] <infile>

Options:
 -a (--alignment) <num>       : Address alignment in kilobytes for output image
                                (64, 128, 256, etc.), default to 64 for header
                                version 0 and 256 for header version 1,
                                override if the NAND flash has a different
                                block size. If outputting a single image, value
                                of '0' is permitted to specify no flash block
                                padding (needed for SSBL image encryption).
 -d (--decode)                : Flag to decode the header information from
                                input file and display it
 -f (--force)                 : Flag to force decoding even if the input file
                                is an unpadded image
 -h (--help)                  : Display this help message and exit
 -hv (--header-version) <num> : Header version to be created (Arria/
               Cyclone® V SoC =
                                0, 
               Intel®
               Arria® 10 SoC = 1)
 -o (--output) <outfile>      : Output file, relative and absolute path
                                supported
 -off (--offset) <num>        : Program entry offset relative to start of
                                header (0x40), default to 0x14. Used for header
                                version 1 only
 -v (--version)               : Display version and exit

The bootable SSBL image must be placed at 0x0 for NAND and QSPI flash. For SD/MMC the image can also be placed at 0x0, but typically the image is placed at offset 0x0 in a custom partition of type 0xA2. The custom partition does not have a filesystem on it. The BootROM is able to locate the partition using the MBR (Master Boot Record) located at 0x0 on the SD/MMC card.

The mkpimage tool always places the output image at the start of the output binary file, regardless of the target flash memory type. The flash programming tool is responsible for placing the image at the desired location on the flash memory device.

For Cyclone^® V SoC and Arria^® V SoC, a single Preloader has a maximum 60 KB image size. You can store up to four preloader images in flash. If the BootROM does not find a valid preloader image at the first location, it attempts to read an image from the next location and so on. To take advantage of this feature, program four preloader images in flash.

For Intel^® Arria^® 10 SoC, a single Bootloader has a maximum 200 KB image size. You can store up to four Bootloader images in flash. If the BootROM does not find a valid Bootloader image at the first location, it attempts to read the next one and so on. To take advantage of this feature, program four Bootloader images in flash.

For Cyclone^® V SoC and Arria^® V SoC, every Preloader image has to be aligned to a 64KB boundary, except for NAND devices. For NAND devices, each Preloader image has to be aligned to the greater of 64 KB or NAND block size.

For Intel^® Arria^® 10 SoC, every Bootloader image has to be aligned to a 256 KB boundary, except for NAND devices. For NAND devices, each Bootloader image has to be aligned to the greater of 256 KB or NAND block size.

The following tables present typical image layouts, that are used for QSPI, SD/MMC and NAND devices with NAND erase block size equal or less to 64 KB (for Cyclone^® V SoC/ Arria^® V SoC) or 256 KB (for Intel^® Arria^® 10 SoC).

The mkpimage tool is unaware of the target flash memory type. If you do not specify the block size, the default is 64 KB.

Each Preloader or Bootloader image occupies an integer number of blocks. A block is the smallest entity that can be erased, so updates to a particular boot image do not impact the other images.

For example for Cyclone^® V SoC and Arria^® V SoC, a single Preloader image has a maximum size of 64 KB. But it the NAND block is 128 KB, then the Preloader images will need to be located at 128 KB intervals.

Each QSPI boot image occupies an integer number of sectors unless subsector erase is supported; this ensures that updating one image does not affect other images.

The master boot record, located at the first 512 bytes of the device memory, contains partition address and size information. The Preloader and Bootloader images are stored in partitions of type 0xA2. Other items may be stored in other partition types according to the target file system format.

You can use the fdisk tool to set up and manage the master boot record. When the fdisk tool partitions an SD/MMC device, the tool creates the master boot record at the first sector, with partition address and size information for each partition on the SD/MMC.

The mkimage tool inserts a CRC checksum in the unused region of the image. Padding fills the remaining unused regions. The contents of the padded and unused regions of the image are undefined.

For complete details on how to build the Cyclone^® V SoC and Arria^® V SoC bootloaders, please visit "Building Bootloader" on RocketBoards.org.

For complete details on how to build the Intel^® Arria^® 10 SoC bootloaders, please visit "Building Bootloader" on RocketBoards.org.

On Intel^® Stratix^® 10 SoC and Intel^® Agilex™ devices, the SDM loads the FSBL from the configuration bitstream. The configuration bitstream contains the hardware handoff data, which is made available to the FSBL. Because of this, there is no need for a Bootloader Generator tool to pass additional information to the Bootloader building process.

For information about how to build the Intel^® Stratix^® 10 SoC U-Boot, refer to the Building Bootloader webpage on RocketBoards.

For information about ATF and UEFI, refer to Intel^® Stratix^® 10 SoC UEFI Boot Loader User Guide.

For information about the Intel^® Stratix^® 10 SoC bootloaders, refer to the Intel^® Stratix^® 10 SoC FPGA Boot User Guide.

The Intel SoC FPGA Hardware Library (HWLIB) was created to address the needs of low-level software programmers who require full access to the configuration and control facilities of SoC FPGA hardware. An additional purpose of the HWLIB is to mitigate the complexities of managing the operation of a sophisticated, multi-core application processor and its integration with hardened IP peripheral blocks and programmable logic in a SoC architecture.

Within the context of the SoC hardware and software ecosystem, the HWLIB is capable of supporting software development in conjunction with full featured operating systems or standalone BareMetal programming environments. The relationship of the HWLIB within a complete SoC HW/SW environment is illustrated in the above figure.

The HWLIB provides a symbolic register abstraction layer known as the SoC Abstraction Layer (SoCAL) that enables direct access and control of HPS device registers within the address space. This layer is necessary for enabling several key stakeholders (boot loader developers, driver developers, BSP developers, debug agent developers, and board bring-up engineers) requiring a precise degree of access and control of the hardware resources.

The HWLIB also deploys a set of Hardware Manager (HW Manager) APIs that provides more complex functionality and drivers for higher level use case scenarios.

The HWLIB has been developed as a source code distribution. The intent of this model is to provide a useful set of out-of-the-box functionality and to serve as a source code reference implementation that a user can tailor accordingly to meet their target system requirements.

The capabilities of the HWLIB are expected to evolve and expand over time particularly as common use case patterns become apparent from practical application in actual systems.

In general, the HWLIB assumes to be part of the system software that is executing on the Hard Processor System (HPS) in privileged supervisor mode and in the secure state.

The anticipated HWLIB clients include:

• BareMetal application developers
• Custom preloader and boot loader software developers
• BSP developers
• Diagnostic tool developers
• Software driver developers
• Debug agent developers
• Board bring-up engineers
• Other developers requiring full access to SoC FPGA hardware capabilities

This section provides a description of the operational features and functional capabilities present in the HWLIB. An overview and brief description of the HWLIB architecture is also presented.

The HWLIB is a software library architecturally comprised of two major functional components:

• SoC Abstraction Layer (SoCAL)
• HW Manager

The SoC Abstraction Layer (SoCAL) presents the software API closest to the actual HPS hardware. Its purpose is to provide a logical interface abstraction and decoupling layer to the physical devices and registers that comprise the hardware interface of the HPS.

The SoCAL provides the benefits of:

• A logical interface abstraction to the HPS physical devices and registers including the bit-fields comprising them.
• A loosely coupled software interface to the underlying hardware that promotes software isolation from hardware changes in the system address map and device register bit field layouts.

The HW Manager component provides a group of functional APIs that address more complex configuration and operational control aspects of selected HPS resources.

The HW Manager functions have the following characteristics:

• Functions employ a combination of low level device operations provided by the SoCAL executed in a specific sequence to effect a desired operation.
• Functions may employ cross functional (such as from different IP blocks) device operations to implement a desired effect.
• Functions may have to satisfy specific timing constraints for the application of operations and validation of expected device responses.
• Functions provide a level of user protection and error diagnostics through parameter constraint and validation checks.

The HW Manager functions are implemented using elemental operations provided by the SoCAL API to implement more complex functional capabilities and services. The HW Manager functions may also be implemented by the compound application of other functions in the HW Manager API to build more complex operations (for example, software controlled configuration of the FPGA).

Reference documentation for the SoCAL and HW Manager are distributed as part of the Intel^® SoC FPGA EDS. The documentation is in HTML format and is located at <SoC EDS installation directory>/ip/altera/hps/doc. You can view this documentation with any web browser.

The addresses of the HPS hard IP modules are accessible through the provided SoCAL macros. SoCAL also provides macros for accessing the individual registers and register fields of the HPS hard IP modules.

For the FPGA IP modules, the macros for accessing IP registers and register fields are usually part of the IP deliverables. However, the actual IP modules-based addresses are often changed at system integration time, in the Platform Designer (Standard) tool.

The basic usage of the tool is to invoke it with the .sopcinfo file as a single parameter. For example, in order to generate the include files for the Intel^® Arria^® 10 SoC GHRD, the following command can be executed in that folder: sopc-create-header-files ghrd_10as066n2.sopcinfo.

The tool creates a separate include file for each of the masters in the system, showing the system addresses from that master's point of view. Use the file <hps_component_name>_a9_0.h for HPS software development, as it shows the system addresses from the HPS point of view.

sopc-create-header-files ghrd_10as066n2.sopcinfo --module\ 
arria10_hps_0_arm_a9_0 --single arria10_hps_0_arm_a9_0.h 

This creates just one file, called "arria10_hps_0_arm_a9_0.h".

You can also run "sopc-create-header-files --help" for more details about the tool, or refer to Intel^® Quartus^® Prime Standard Edition documentation.

Figure 28.  HPS Flash Programmer

The HPS flash programmer determines the type of flash to program by sampling the boot select (BSEL) pins during cold reset; you do not need to specify the type of flash to program.

The HPS flash programmer command-line syntax is:

quartus_hps <options> <file.bin>

The Arm* Bare Metal compilers are part of the Arm* DS* for Intel^® SoC FPGA Edition, which is provided as a separate download. For more information about installation, refer to the Installing the Intel^® SoC FPGA EDS section.

The Arm* Bare Metal Compiler 5 targets 32-bit platforms (Cortex-A9 on Cyclone^® V SoC, Arria^® V SoC and Intel^® Arria^® 10 SoC).

The Arm* Bare Metal Compiler 6 targets both 32-bit platforms and 64-bit platforms (Cortex-A53 on Intel^® Stratix^® 10 SoC).

The Arm* Bare Metal compilers documentation is integrated in Arm* DS* for Intel^® SoC FPGA Edition, like with all the Arm* DS* for Intel^® SoC FPGA Edition components.

The Linaro* GCC compiler is provided as an additional download. For information about installation, refer to the Installing the Intel^® SoC FPGA EDS section.

<SoC EDS installation directory>/host_tools/linaro/gcc

The Embedded Command Shell sets the correct environment PATH variables for the bare metal compilation tools to be invoked. You can open the shell from the <SoC EDS installation directory>. After starting the shell, commands like arm-eabi-gcc can be invoked directly. When the Arm* DS* for Intel^® SoC FPGA Edition IDE is started from the embedded command shell, it inherits the environment settings, and it can call these compilation tools directly.

<SoC EDS installation directory>/host_tools/linaro/gcc

<SoC EDS installation directory>/host_tools/linaro/gcc/share/doc

The documentation is offered in HTML format.

Sample Output from Utility

The utility is a command line program. The table describes all the command line options; and the figure shows the --help output from the tool.

$ alt-boot-disk-util --help
Altera Boot Disk Utility
Copyright (C) 1991-2014 Altera Corporation

Usage:
#write preloader to disk
    alt-boot-disk-util -p preloader -a write disk_file

#write bootloader to disk
    alt-boot-disk-util -b bootloader -a write disk_file

#write BOOTloader and PREloader to disk
    alt-boot-disk-util -p preloader -b bootloader -a write disk_file

#write Arria10 Bootloader to disk
    alt-boot-disk-util -B a10bootloader -a write disk_file

#write BOOTloader and PREloader to disk drive 'E'
    alt-boot-disk-util -p preloader -b bootloader -a write -d E



Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -b FILE, --bootloader=FILE
                        bootloader image file'
  -p FILE, --preloader=FILE
                        preloader image file'
  -a ACTION, --action=ACTION
                        only supports 'write' action'
  -B FILE, --a10-bootloader=FILE
                        arria10 bootloader image file
  -d DRIVE, --drive=DRIVE
                        specify disk drive letter to write to