Hackster's FPGAdventures: Experimenting with Microchip's PolarFire SoC Icicle Kit Linux Code Samples

In our last look at Microchip's flexible PolarFire SoC Icicle Kit, which blends low-power high-performance field-programmable gate array (FPGA) technology with Linux-capable processing cores built around the free and open source RISC-V instruction set architecture (ISA), we built our own Linux distribution using the Yocto board support package (BSP) and ran a selection of workloads to put the system through its paces.

The Icicle Kit isn't designed as a single-board computer you just pick up and use to run pre-built binaries, though: it's a development tool first and foremost, and whether you're a professional or a hobbyist you're going to want to get your hands dirty coding in order to make the most of the board's capabilities.

The samples

Microchip, thankfully, doesn't throw its users in at the deep end unaided. The Linux distribution we compiled and flashed to the board's 8GB eMMC chip last month comes with a selection of sample applications in /opt/microchip, both in precompiled binary and source-code format — a hands-on getting-started resource, which doesn't even require you to connect the board to the network.

The same examples are also available on Microchip's GitHub repository, where — depending on when you last refreshed the Linux distribution and Hart Support Services (HSS) image on your Icicle Kit — they may be more up-to-date. All except one, oddly. The /opt/microchip directory, as built using the target on the most up-to-date BSP, contains everything you'll find on GitHub plus one extra: the CoreMark-PRO benchmark suite. Its absence from GitHub makes sense: it's not a Microchip creation, and its source code reveals nothing about the specifics of the PolarFire SoC platform.

Microchip's own sample programs are designed to be accessed in any order, depending on what you're hoping to achieve — but the best starting point is the general-purpose input/output (GPIO) sample. This is split into two separate programs. The first offers two modes of operation, the first toggling the four user-programmable LEDs on and off and the second reading the status of one of the board's four push-button switches. The second program offers more complex control, using interrupt-driven events to read when the switch is pushed and released — though it makes no distinction between the two, only reporting that the event has been triggered and counting up how many times.

A comment block at the top of the source code provides a quick reference to accessing the GPIO pins — whether the ones tied to the on-board LEDs and push-button switches or those located on the Raspberry Pi-format 40-pin GPIO header — for both writing and reading. The code itself is also commented, albeit more sparsely, and is fairly easy to understand providing you're not an absolute beginner to C.

Servicing the system

The "system services" demo is where things begin to get interesting: It's the first example of communication taking place between the SiFive processor cores running Linux and the FPGA blocks of the PolarFire SoC. As with the GPIO sample, full source code is provided alongside pre-compiled binaries to get you started as quickly as possible.

When running the first of the two system services demonstration apps, you're greeted with four key functions — two relating to the FPGA hardware itself and two its ability to offer security and authentication functionality to the host operating system. Triggering the first two options provides the serial number and device digests from the FPGA; triggering the third continuously reads and prints hexadecimal-format random data from the SoC's true random number generator (TRNG); and the last requests an Elliptic Curve Digital Signature Algorithm (ECDSA) signature.

The latter feature is part of the PolarFire SoC's security functionality. When configured for secure boot, the PolarFire SoC uses ECDSA to authenticate a Secure Boot Image Certificate — generating a tamper warning signal to the FPGA fabric if authentication fails. The same functionality can be accessed in userspace, too, with a second demonstration app showcasing the creation and verification of a signature within Linux using the chip's security blocks.

Sadly, the code for these isn't as well commented as the earlier GPIO example. It's still relatively easy to follow, aided by the fact that the complex cryptography takes place in hardware rather than in software, but not so readily accessible to beginners.

Cross communication

It's easy, and understandable, to think of the PolarFire SoC at the heart of the Icicle Kit as two separate devices: the general-purpose processing half, running on RISC-V cores; and the FPGA half, providing glue logic and ready to run your own gateware on-demand. That's not exactly true, though: the whole point of the PolarFire SoC's integrated approach is that the two halves are interlinked, providing a means of bolstering one with the other — turning the FPGA into an accelerator for a specific workload ill-suited to general-purpose processors, for example.

To do that, the two halves have to be able to talk — and Microchip has provided source code showing two ways that can happen. The first is using userspace input/output (UIO) to access the FPGA's LSRAM. For this, a simple demo application is provided — which, on the surface, doesn't appear to offer much in the way of functionality: when run, it simply tests the LSRAM. In doing so, though, it uses exactly the functionality you'd need in your own applications: writing data from Linux to LSRAM, then reading it back to compare it to what was written as a simple way to check for memory errors.

The other method provided by Microchip is using direct memory access (DMA), in which a shared section of the board's LPDDR4 memory is used to host a copy of the FPGA's LSRAM — allowing the program, running under Linux, to read and write memory that the FPGA can also use. This is, effectively, an extension of the UIO approach: UIO is used to transfer data from the FPGA's LSRAM to LPDDR4.

Bonus features

There are a few other sample applications including in /opt/microchip with which the curious can experiment. One is the source code for the simple webserver that serves as a "hello, world" app for the board: providing a web page with hardware sensor readings over the board's Ethernet port.

Another provides a Controller Area Network (CAN) bus implementation, which uses the same UIO functionality as the shared-memory access in order to find a CAN device, initialize it, put it into loopback mode, send it a message, then receive it back again as proof-of-life. There's a CAN connector on the board for this, located just below the Vitesse Ethernet PHY chip.

For those hoping to use additional hardware with the board, Microchip has provided an example for using device tree overlays (DT overlays) in order to provide compatibility — using as its demo the Raspberry Pi Sense HAT add-on, which can be connected to the PolarFire SoC Icicle Kit's 40-pin GPIO header and used as a device for input and output.

The header is oriented at 180 degrees to how you might expect, for a simple reason: it avoids any add-on hardware, whether the Sense HAT or another board, from fouling on the Ethernet hardware directly below. It does, however, mean that the board sits outside the main footprint — and in the case of the Sense HAT or other HATs with buttons or joysticks, care has to be taken not to bend the header as you interact with the device.

When you've worked through the examples, though, you're left to your own devices: Microchip provides little in the way of public documentation for programming the PolarFire SoC within Linux userspace, preferring instead to concentrate on the use of its Libero SoC software to create bitstreams for the FPGA — a task that is, admittedly, less transferable from other Linux-based devices.

Join us next month as we take a look at the PolarFire SoC's asymmetric multiprocessing (AMP) mode and tool around with its real-time operating system (RTOS) support.

More information on the PolarFire SoC Icicle Kit is available on the Microchip website and can be found on Avnet's product page as well.

Read the whole series:

• FPGAdventures Series #1: Unboxing the PolarFire SoC Icicle
• FPGAdventures Series #2: Installing Microchip's Libero SoC
• FPGAdventures Series #3: First Steps with Libero SoC
• FPGAdventures Series #4: Linux on RISC-V
• FPGAdventures Series #6: Split Personalities with AMP