Skip to content

Drive-On-Chip with Functional Safety Design Example for Agilex™ 5 Devices

Overview

In the Drive-On-Chip with Functional Safety Design Example for Agilex™ 5 Devices the HPS implements the secondary safety channel, runs speed estimation and monitoring, cross compares payload, automatically detects the devices, and generates GUI data. The HPS safety channel comprises

  • HPS configuration in Platform Designer.
  • The Yocto meta layer that you must add to the SD card image build.
  • HPS channel speed monitoring safety application source code, compilation, and running

This page describes the elements for getting a custom distribution of Linux based on YOCTO/KAS for this application.

The files and contents described in the following sections can be found in the doc-variants repository, within the sw directory see: meta-driveonchip.

HPS Channel Safety Software - Custom Linux

For the Drive-On-Chip Functional Safety Design Example for Agilex™ 5 Devices, Altera® provides the files to build the Linux system to run the HPS channel safety application. The custom version of linux is built based on KAS (see: meta-fpga-embedded). An it is compose of two main meta-layers. In this document the files relevant for the "Drive-On-Chip with Functional Safety Design Example for Agilex™ 5 Devices" are highlighted.

FPGA Embedded Layer

Drive-On-Chip Layer

Necessary elements in the meta-layers to bind Software and Hardware

This section explains the different elements included in the meta-layers that help to run the HSP Safety Application. These elements help to "bind" the FPGA Soft IP that implements the Safety function in the "FPGA Channel" with the software that runs in the HPS on top of Linux. This elements are explained in the following sections to clarify the interaction of the HPS Safety Application (Software), with the FPGA Safety Channel (soft logic).

Device Tree.

Adds a custom .dtsi (device tree fragment) file to the main device tree for Linux kernel boot up stage socfpga_agilex5_socdk.dts. it compiles into a DTB during kernel compilation and is added to the SD card image during the Yocto build. The recipe device-tree.bb. The specific file for this design example (agilex5_safety_dual_axis.dtsi), is appended using device-tree.bbappend directive. Look for these files in the different meta-layers provided above.


device-tree

Custom Device Tree Fragment.


You expand the device tree by appending the contents of the file agilex5_safety_dual_axis.dtsi that exposes seven devices as UIO devices in the RootFS. The figure shows the instances of the devices. These definitions should match with the devices that the HPS can access in the FPGA soft logic and you can verify the address map in the Platform Designer Project (.qsys).

For example, the interval timer has the address 0x0000_0020 in Platform Designer, but from the view of HPS you should add the offset reflecting the HPS-FPGA bridge 0x4000_0000 refer ( System Memory Mapping Scheme in the Hard Processor System Technical Reference Manual: Agilex™ 5 SoCs (24.3)) specifying the address 0x4000_0020 in the agilex5_safety_dual_axis.dtsi file. Components connected to the full HPS to FPGA bridge have an offset of 0x4000_0000 and components connected to lightweight HPS-to-FPGA bridge have an offset of 0x2000_0000.

All components are listed in the .dtsi as compatible generic_uio, which is a way to map devices using generic user IO interface in the Linux kernel and user space. If you modify or add memory mapped devices in Platform Designer, reflect the change in the .dtsi file. When the Yocto build refreshes, the Linux system lists the device in the corresponding /dev/uiox and populates the information in /sys/class/uio/uiox. The .dtsi and Platform Designer mapping should be consistent to provide the HPS safety function application to run correctly.

For example, the application looks for the names specified in the .dtsi, for example interval_timer0 and gets the device UIOX identifier, the address, the offset, and all meaningful information to access the device in the FPGA.

A particularity of the .dtsi in the previous figure is the interrupts metadata. The "interval timer" processes the safety function by issuing an interrupt to the HPS that is polled by software. The interrupt <0 17 4> is the first interrupt line accepted by the HPS from any FPGA (soft logic) device. In Platform Designer the interrupt line to the interval timer shows Interrupt number 0.


hps-irq-pd

Interval Timer Interrupt line connection to the HPS


You can check the number of interrupts triggered by the interval timer at any point by issuing the following command in the Agilex™ 5 command line:

cat /proc/interrupt


irq-count

Amount of Interrupts Triggered by the Interval Timer


Look for interrupt 53, subscribed to the Interval Timer. As shown in the previous figure, interrupt 53 has been allocated to core 2 (isolated core), using the directives in the start.sh file installed in /usr/bin (or start_agx5.sh file in the meta-layers).


FPGA Bitstream.

Adds the agilex5_modular_safety_dual_axis.core.rbf file to the build. The file is generated after Quartus® Prime compilation. The *core.rbf file is added to the boot partition of the SD card (renamed as top.core.rbf). The HPS configures the FPGA at initialization using u-boot load command in uboot.txt generated into boot.scr.uimg in the boot partition by u-boot-socfpga_%.bbappend (look for the files in the meta-layer).


rbf-program

FPGA configuration during HPS booting process.


Look for the print "..... FPGA reconfiguration OK " during the FPGA booting process, as shown in the previous figure to ensure the FPGA bitstream (top.core.rb) has been properly loaded.


Additional u-boot configuration.

An append to the u-boot arguments using IMAGE_BOOT_ARGS and IMAGE_BOOT_ARGS:append:agilex5_modular in different KAS/YOCTO configuration files to enable UIO drivers defined by uio_pdrv_genirq.of_id=generic-uio.

Additionally, this design isolates cores 2 and 3 for use exclusively in the application (speed estimation and main safety function). The u-boot arguments nohz_full=2,3 and isolcpus=2,3 inside the KAS/YOCTO configuration files ensure the isolation of cores for the application. You can verify the core allocation in the C source code.


HPS Channel Safety Application and Services (recipes-example)

Recipe to build and deploy the HPS safety application (hpssafechnnel_1.0.bb). The source code is contained in hpssafechannel_1.0.tar.gz and the Makefile is provided.

The recipe hpssafechannel_1.0.bb compiles and packages the executable into the SD card image (.wic). The recipe installs the executable in /opt/hpssafechannel/

The recipe hpsafechannel_1.0.bb also deploys the HPS safety application as a service, it installs the file hpssafechannel.service to /lib/system/system and launches it some seconds after kernel initialization using the start.sh script in /usr/bin/


Additional tools.

See the KAS configuration file for this example design kas_safety_dual_axis.yml. Some tools installed are:

  • hpssafechannel: custom HPS Channel Safety Application.
  • htop: cross-platform interactive process viewer to verify core isolation and affinity.
  • devemem2: to easily access memory-mapped devices.
  • uio-pdrv-genirq: kernel module to map devices as "User IO"


PREEMPT-RT patch.

This example show the user how to easily "patch" the Linux kernel with PREEMPT_RT patch, which provides soft Real Time characteristics particularly useful for embedded hardware applications. In this design example PREEMTP_RT patch helps to guarantee the processing time of the SRT (Safety Response Time) by giving priority to the interrupt raised by the Interval timer that synchronizes the FPGA and the HPS Safety Functions. See the file linux-socfpga-rt_6.6.bb


Back to Documentation


Last update: March 6, 2025
Created: March 6, 2025