Intel® SoC FPGA Bare-metal Developer Center

Bare-metal development uses a software runtime environment that does not use an operating system (OS) or a real-time operating system (RTOS). In a bare-metal configuration, the hard processing system (HPS) of SoC FPGAs can be used. Intel offers hardware libraries (HWLIBs) that consist of high-level application programming interfaces (APIs) and low-level macros that enable you to exercise most of the HPS peripherals.

You can access various resources to help you get started with bare-metal development on Intel® SoC FPGAs from the links below. If you are a first-time user, we recommend that you follow the resources linearly.

1. Prerequisites

Create Your My Intel Account

  • Create your My Intel account from the My Intel page.
  • Your My Intel account allows you to file service requests, register for classes, download software, access resources, training courses, and more.

Design Considerations

What is Bare-metal?

  • Bare metal represents the actual register interfaces and hardware features of the processor system.
  • Bare-metal development uses a software runtime environment that does not use an OS or an RTOS.
  • In bare-metal configurations, the HPS of SoC FPGAs can be used. Intel offers HWLIBs that consist of high-level APIs and low-level macros that enable you to exercise most of the HPS peripherals.

Why Bare-metal?

  • The advantages of using a bare-metal approach are:
  • Absolute control of hardware
  • Increased efficiency
  • Minimal size (both flash and memory footprint)
  • No dependency on other source codes or libraries
  • Easier to formally prove correctness and perform code coverage analysis
  • Other reasons for selecting bare-metal development are:
  • Need to perform board bring-up and focus on one peripheral at a time
  • Need to re-use existing legacy code that is already developed as bare-metal
  • Lack of experience with an OS or RTOS

Bare-metal Considerations

To develop a bare-metal application for the HPS, you must be familiar with developing runtime capabilities to ensure that your application makes efficient use of the resources available in your CPU subsystem. Examples of what may be required are as follows:

  • In-depth knowledge of the hardware platform
  • Developing runtime capabilities to manage the process between the core and the cache subsystem if you want to fully utilize the CPU subsystem, as a typical bare-metal application uses only a single core
  • Developing capabilities to manage and schedule processes, handle inter-process communications, and synchronize events within your application

If your scheduled project does not allow for effort it may take to become familiar with the above points, then it is recommended that you consider using a commercial Linux* or RTOS solution.

Alternative

Advantages

Comments

Linux Networking, storage, multitasking, interprocess communication, synchronization, and more. You do not have to be a Linux kernel expert to use Linux in your project. For example, you could write a Linux user space application and access the FPGA intellectual property (IP) registers directly, similar to how a bare-metal application would behave.
RTOS Multicore processing, multitasking, interprocess communication, and synchronization, depending on RTOS. Using a simple RTOS is easy. It is similar to using the C libraries of functions that are already implemented, instead of writing those functions yourself.
Bootloader Faster boot time, and access to the features already implemented in the bootloader, such as mass storage and networking Available bootloaders are:
  • U-Boot: open-source GPL license, available on all SoCs
  • MPL: open-source 3-clause BSD license, available on all SoCs
  • UEFI: open-source 3-clause BSD license, not available on Arria® V SoC and Cyclone® V SoC
  • Design Flow Diagram

    The typical design flow diagram for bare-metal development is shown below:

    A summary of the flow is as follows:

    • Start with a hardware design, which includes:
    • HPS configuration: clock settings, pin multiplexing and configuration, DDR settings, connected peripherals, and so on.
    • FPGA fabric contents: IP cores instantiated in the FPGA, and FPGA pin, memory controller, and phase-locked loop (PLL) configuration
    • The hardware design is compiled with the Intel® FPGA Complete Design Suite tools, which generate the following files:
    • SOF file: used to configure the FPGA fabric through various methods – external programmer, external flash, HPS bootloader, or even HPS application
    • Handoff: contains information used by the Second Stage Bootloader Generator to create the bootloader that will be used on the HPS
    • SOPCINFO file: can be used to automatically create header files with the FPGA soft IP addresses
    • SVD file: contains information about the FPGA soft IP registers so that the ARM* Development Studio 5* (DS-5*) Intel SoC FPGA Edition debugger can show them in a user-friendly format during debugging
    • User writes custom source code, with the aid of the HWLIBs, and potentially using the FPGA IP address header files
    • User compiles the bare-metal application with the aid of the bare-metal compilers
    • User debugs the bare-metal application by using the ARM DS-5 Intel SoC FPGA Edition

    2. Getting Started

    Select Target Board

    • We recommend starting your development on an SoC Development Kit provided by Intel because the getting started bare-metal examples are targeted to run on those boards.
    • To see the available SoC FPGA boards, go to All Development Kits web page and click on “SoC Series Kits”.

    Install Intel SoC FPGA EDS

    • The Intel SoC FPGA EDS provides essential tools that are required for all SoC FPGA development, including bare metal. Refer to the overview page for more details.
    • Download the Intel SoC FPGA EDS from the Download Center.
    • Follow these instructions to install the Intel SoC FPGA EDS.
    • If the ARM DS-5 Intel SoC FPGA Edition is used for debugging and/or tracing bare-metal applications, you will need to obtain a license. The license is typically included with your Intel SoC FPGA Development Kit purchase. Refer to the SoC EDS User Guide's license setup instructions.

    Select Build Tools

    • The Intel SoC FPGA EDS provides the following bare-metal build tools:
    • Intel SoC FPGA version of Mentor CodeSourcery – GCC-based, no license required
    • ARM Compiler 5 – license included with the Intel SoC FPGA EDS license
    • Other build tool suites targeting ARM platforms can be used – go to the Ecosystem web page, and click on “Dev Tools” to see more.
    • The getting started example projects are available for both GCC and ARMCC compilers provided as part of the Intel SoC FPGA EDS.

    Select Debug and Trace Tools

    • The Intel SoC FPGA EDS includes the ARM DS-5 Intel SoC FPGA Edition, which fully supports debugging and tracing of bare-metal programs – license required
    • Other build tool suites targeting ARM platform can be used – go to Ecosystem web page and click on “Dev Tools”
    • The getting started example projects are using ARM DS-5 Intel SoC FPGA Edition for both debugging and tracing

    Exercise the Getting Started Application

    • A sample getting started application is available for Cyclone V, Arria V, and Intel® Arria® 10 devices, supporting both ARMCC and GCC compilers.
    • The sample application exercises the following
    • HPS SDRAM, MMU, caches,
    • HPS timers, interrupts
    • HPS-to-FPGA bridges
    • FPGA soft IP: SysID
    • FPGA interrupts
    • Use the following links to download the version that you need:

    3. Creating Your Own Project

    Types of Bare-Metal Projects

    There are two different types of projects that can be managed by the ARM DS-5 Intel SoC FPGA Edition:

    • Makefile-based projects: the project is managed by manually editing the makefile, and the ARM DS-5 Intel SoC FPGA Edition just calls 'make all' and 'make clean' on that makefile to build and to clean your project, respectively.
    • Plugin-based projects: The ARM DS-5 Intel SoC FPGA Edition completely manages your project, including files to compile, compiler options, building, and cleaning.

    The advantage of a makefile-based project is that it can invoke any other tools, not just the bare-metal compiler, thus offering more flexibility. The only advantage of using a plugin-based project is that the settings are easily accessible from the ARM DS-5 Intel SoC FPGA Edition graphical interface as opposed to editing the makefile with a text editor.

    Recommended Method to Create Your Own Project

    We recommend getting started using the provided script to automatically create your plugin-based or makefile-based project. Full instructions are available here.

    The script performs the following actions:

    • Create project folder
    • Create C project file, with all the required compilation settings
    • Create a simple main.c file, that simply prints a 'hello world' message
    • Bring in all the relevant HWLIBs files
    • Create the system.h file having the base addresses of the FPGA fabric peripherals (requires the Intel® Quartus® Prime software to be first installed, otherwise this step will be skipped)
    • Create a debug configuration for debugging the application
    • Create a debug configuration for running the bootloader [optional]
    • Create an external tool launcher for configuring FPGA fabric from the ARM DS-5 Intel SoC FPGA Edition [optional]
    • Create an external tool launcher for re-generating the system.h file when needed [optional]

    Note that all the getting started projects described in the Getting Started section were created using this method.

    Alternative Methods to Create Your Project

    You can also create your own projects using the following alternatives:

    • Option 1: Manually create a makefile, then follow these instructions to enable the project in the ARM DS-5 Intel SoC FPGA Edition as a makefile-based project. Manually creating the makefile is beyond the scope of this guide, and requires you to familiarize yourself with all the build tools and their options. If a makefile is required, the recommended method is to use the provided script to create it.
    • Option 2: Manually create a plugin-based project from scratch, following these instructions. This consists of manually reproducing the procedure that the provided script follows in order to create the project. Note that the script offers more features, and is the recommended method to create your project. This option is documented for reference only.
    • Option 3: Start with an existing project and modify it to suit your needs. This can be done especially for short tests and experiments but this method is not recommended.

    4. Examples

    What Bare-Metal Examples Are Available

    A. Getting started bare-metal applications, targeting Intel SoC Development Boards and exercising:

    • HPS SDRAM
    • HPS MMU and caches
    • HPS timer, with interrupts
    • FPGA IP: SysID and PIO – push buttons, dual in-line package (DIP) switches, and LEDs
    • FPGA interrupts

    B. Bare-metal examples included with the Intel SoC FPGA EDS, targeting Intel SoC Development Boards and available from <SoC FPGA Installation Folder>\embedded\examples\software\:

    Example Name

    Description

    Device

    Compiler

    HardwareLib-16550

    Uses UART and interrupt APIs to implement a console application.

    Cyclone V

    ARMCC
    GCC

    HardwareLib-ECCL2

    Sets up the MMU tables and shows the ECC capabilities of the L2 cache.

    Cyclone V

    ARMCC
    GCC

    HardwareLib-FPGA

    Configures FPGA HPS using direct memory access (DMA), opens the H2F bridges and talks to a GPIO soft IP component inside the FPGA fabric.

    Cyclone V

    ARMCC
    GCC

    HardwareLib-SPI

    Communicates with a SPI EEPROM on an external board.

    Cyclone V

    ARMCC
    GCC

    HardwareLib-Timer

    Sets up timers and interrupts.

    Cyclone V
    Arria V
    Intel Arria 10

    ARMCC
    GCC

    HelloWorld-Baremetal Prints "hello world" message using semihosting. Cyclone V
    Arria V
    Intel Arria 10
    ARMCC
    GCC

    C. Additional bare-metal examples, targeting Intel SoC Development Boards and available from Design Examples page, all using the GCC compiler:

    Example

    Description

    Device (Project File)

    Device (Readme File)

    DMA

    Initializes DMA, performs memory to memory transfers and zero to memory transfers.

    Arria V
    Cyclone V
    Intel Arria 10

    Arria V
    Cyclone V
    Intel Arria 10

    ECC

    Sets up and enables ECC for for on-chip RAM, SD/MMC, quad serial peripheral interface (SPI), DMA and L2 cache. Injects single/double bit errors and sets up the interrupts for single/double bit error detections.

    Arria V
    Cyclone V
    Intel Arria 10

    Arria V
    Cyclone V
    Intel Arria 10

    GPIO

    Sets up general-purpose input/output (GPIO) as output ports to drive HPS LEDs, and to sets up GPIO as input ports for HPS push buttons.

    Arria V
    Cyclone V
    Intel Arria 10

    Arria V
    Cyclone V
    Intel Arria 10

    I2C

    Communicates over I2C with LCD screen, EEPROM memory as well as between two I2C modules.

    Arria V
    Cyclone V
    Intel Arria 10

    Arria V
    Cyclone V
    Intel Arria 10

    Quad SPI

    Performs reading and writing to the quad SPI using generic block I/O mode, indirect mode and DMA mode. Also sets up MMU and caches.

    Arria V
    Cyclone V

    Arria V
    Cyclone V

    SD/MMC

    Initializes SD/MMC card, reads and writes using block I/O functions.

    Arria V
    Cyclone V

    Arria V
    Cyclone V

    Timer

    Uses timers in free-running, one-shot and watchdog modes. Performs global timer measurements.

    Arria V
    Cyclone V
    Intel Arria 10

    Arria V
    Cyclone V
    Intel Arria 10

    Unhosted Uses UART for printf output instead of semihosting. Also demonstrates how to boot a bare-metal program from a SD card.

    Arria V

    Cyclone V

    Arria V

    Cyclone V

    SPI Communicates between two SPI modules connected through the FPGA fabric.

    Arria V

    Cyclone V

    Intel Arria 10

    Arria V

    Cyclone V

    Intel Arria 10

    HPS-to-FPGA Bridges Exercises the memory mapped interfaces of the hard processor system (HPS) exposed to the FPGA fabric. Performs memory tests by writing and reading the HPS memory using various ports of the HPS and measures the performance of the data movements. Example

    Arria 10

    Cyclone V

    How to Implement Execute in Place (XIP) on Cyclone V FPGAs

    Refer to the Cyclone V QSPI XIP Example Design page on Intel FPGA Wiki for complete instructions on how to run a bare-metal application from QSPI flash.

    How to Boot Bare-Metal Applications on Cyclone V FPGAs

    Refer to Application Note 709, Boot Examples chapter for examples on booting a Cyclone V SoC bare-metal application from:

    • SD/MMC
    • QSPI
    • FPGA

    5. Additional Resources

    Support Resources

    Help is just a click away! The Support Resources provides online technical resources, from training classes to design examples to forums, that guide you through every step of the design process.

    Knowledge Base

    The Knowledge Base provides a vast number of support solutions, reference articles, error messages, and troubleshooting guides, and it is also fully searchable.

    Intel Community

    Intel Community is a community website enabling collaboration between Intel FPGA users. Check out the "Embedded Design Suite (EDS)" and "SoC Discussion" sections. Use the search engine to find relevant material. You are also are encouraged to update and contribute.

    My Intel

    Your My Intel account allows you to file a service request to get help on specific topics. You can also use it to register for training classes and access other resources. Registration is required first.

    Foundational Learning - Training Classes

    Below are foundational training classes that you can take before starting your bare-metal development.

    Resource

    Type

    Developed Skills

    Software Design Flow for an ARM-based SoC

    Free 27 Minutes Online Course

    • Explain the software development tools provided in the SoC Embedded Development Suite (EDS)
    • Explain the boot flow of the HPSCreate the second stage bootloader software from hardware software handoff files
    • Use the SoC EDS and hardware libraries to create a bare-metal or OS specific application
    • Select an operating system to run on the ARM processor
    • Perform FPGA-adaptive SoC Debug

    SoC Bare-metal Programming and Hardware Libraries

    Free 28 Minutes Online Course

    • Use the tools in the SoC EDS to develop bare-metal programs
    • Utilize the features of the hardware libraries to develop low-level software
    • Understand the SoC EDS features available to debug a bare-metal application

    Developing Software for an ARM-based SoC

    8 hours Instructor-Led / Virtual Class Course

    • Explain the hardware-to-software file handoff
    • Explain the stages in the HPS boot sequence & the boot scenarios
    • Create the second-state bootloader
    • Write bare-metal applications using Intel FPGA’s Hardware Libraries
    • Get started with a variety of OSs for the ARM processor
    • Use DS-5 Development Studio to perform FPGA-adaptive software debug

    Foundational Learning -Intel SoC FPGA EDS User Guide

    The SoC EDS User Guide is a foundational document describing all the Intel SoC FPGA EDS tools and components. We highly recommend reviewing the following sections relevant to bare-metal development:

    SoC EDS Section

    Description

    Introduction

    Overview and the hardware-software development flow.

    Installing

    How to install the Intel SoC FPGA EDS and the ARM DS-5 Intel SoC FPGA Edition.

    Licensing

    Licensing options for the Intel SoC FPGA EDS and how to install the license.

    Embedded Command Shell

    How to start the shell and use it to access the rest of the Intel SoC FPGA EDS tools.

    ARM DS-5 Intel SoC FPGA Edition

    Basic operations, such as starting the ARM DS-5 Intel SoC FPGA Edition, bare-metal project management, and debugging.

    Hardware Libraries

    Overview of HWLIBs and how to get to the Doxygen information included with the Intel SoC FPGA EDS installation.

    Bare-Metal compilers

    Overview of the two bare-metal compilers included with the Intel SoC FPGA EDS: ARMCC and GCC.

    Foundational Learning - Intel SoC FPGA EDS Getting Started Guides

    The SoC EDS Getting Started Guides on the Intel FPGA Wiki is a set of foundational basic instructions to help you easily get started with the Intel SoC FPGA EDS.

    Guide

    Description

    Getting Started with Board Setup

    Set up the Intel SoC development board.

    Getting Started with Running the Tools

    Run some of the tools provided with the Intel SoC FPGA EDS.

    Getting Started with Basic Bare-metal Development

    Import, compile, and debug the Hello World bare-metal application example provided.

    Getting Started with HWLIBs Bare-Metal Development

    Complete example that demonstrates how to:

    • Import sample projects (available for Cyclone V, Arria V, and Intel Arria 10 devices, supporting both GCC and ARMCC compilers)
    • Build the sample application
    • Run the bootloader from the ARM DS-5 Intel SoC FPGA Edition
    • Configure the FPGA from the ARM DS-5 Intel SoC FPGA Edition
    • Debug application
    • Perform program tracing
    • Perform cross-triggering

    Creating a Bare-Metal HWLIBs Project Automatically

    Create a complete bare-metal HWLIBs-based project through a script.

    Creating a Bare-Metal HWLIBs Project Manually

    Manually create a bare-metal HWLIBs-based project.

    Cyclone V HWLIBs FPGA Bare-Metal Example

    Configure the FPGA and exercise soft IP control from the HPS with the HWLIBs.

    Additional Documentation and Resources

     

    Technical Reference Manuals

    Technical reference manuals contain detailed descriptions of the hardware, including the behavior, base addresses, interrupt mapping, and control/status registers for all the peripherals.

    SoC Documentation Pages

    The SoC documentation pages conveniently provide a single location to access all relevant SoC documentation, such as tecnhical reference manuals, datasheets, and application notes.

    Additional Resources

    Resource

    Description

    SoC FPGA EDS Download

    Download SoC FPGA EDS.

    Intel FPGA Development Kits

    See all the the available FPGA Development Kits. Click on SoC Series Kits on the left navigation pane to see the boards supporting an SoC FPGA.

    SoC FPGA Design Examples

    Access various design examples. Click on SoC Design Examples on the left navigation pane to see the examples targeting an SoC FPGA.

    Intel FPGA Training Curricula

    Access the entire Intel FPGA training curricula. Select Software Development on the left navigation pane, then search for "SoC" for specific SoC FPGA related courses. Or select any other areas of interest.

    Intel FPGA Training Catalog

    Access the entire Intel FPGA training catalog. Search for "SoC" for specific SoC FPGA related courses. Or select any other courses of interest.

    Intel SoC FPGA EDS Overview

    See an overview of the Intel SoC FPGA EDS, including what is new in the latest release, release notes, and release history.

    SoC FPGA Ecosystem

    Get links to various SoC FPGA related resources, such as operating systems, development tools, IP cores, and boards.

    Intel FPGA Engineer to Engineer Videos

    Access more than 200 videos created by Intel FPGA engineers. Some videos are generic, while others are related to SoC FPGA products.

    Intel Community

    Collaborate with other Intel FPGA users through this community website. Check out the Embedded Design Suite (EDS) and SoC Discussion sections. Use the search engine to find relevant material. All are encouraged to update and contribute.