mpfs-hal

This repository contains a hardware abstraction layer for the Microchip PolarFire SoC, built on the Mirochip-provided platform, as well as Embassy support and a TTY application which can flash images to a board that is using the HSS bootloader.

Note

This repository is a work in progress. See the crate descriptions below for details about what features are supported. Currently only the BeagleV-Fire board is targeted, but additional board support should be fairly straightforward. See #1 for a list of peripherals that do not yet have support.

Tip

Using a more recent version of the HSS bootloader is highly recommended. DDR training on earlier versions hangs frequently. See the Gateware programming section for details about upgrading.

Primary crates:

mpfs-hal |

• critical_section
• alloc support via embedded-alloc (alloc feature)
• Board-specific GPIO (embedded-hal OutputPin and InputPin) with support for interrupts (embedded-hal-async Wait)
• UART (embedded-io Write and embedded-io-async Read)
• UART-based logger (log and log-colors features) and print macros (print feature)
• QSPI (embedded-hal and embedded-hal-async SpiBus)
• Ethernet (embassy-net-driver Driver)
• USB device (embassy-usb-driver Driver)
• USB host support (using the yet-to-be-released UsbHostDriver) in the works

Note

While the mpfs-hal crate implements some Embassy traits, it comes with no requirement to use Embassy. These traits were used in the absence of other async traits available in the ecosystem, and they come with the benefit of having USB/Ethernet stacks already implemented with embassy-usb and embassy-net (both of which also do not need to be used with the Embassy executor, if so desired).

mpfs-hal-embassy |

• Embassy integration, with an Executor and Time Driver, supporting multicore with timer interrupts for low-power application.
• Board-specific SD peripheral support via embassy-embedded-hal SpiDevice (which implements the embedded-hal and embedded-hal-async traits of the same name)

mpfs-pac |
A peripheral access crate for the PolarFire SoC. Largely bindgen-generated from the platform repository.

Utility crates:

hss-tty-flasher |
A TTY interface that allows you to flash ELF files to PolarFire SoC devices using the HSS bootloader.

Internal crates:

mpfs-hal-procmacros
Reexported by mpfs-hal and mpfs-hal-embassy. Sugar for defining entry points.

Prerequisites

When checking out this repository, clone the submodules as well:

$ git clone --recursive

You will need a RISCV toolchain. The SoftConsole-supplied one will work.

The RISC-V target can be added using rustup:

$ rustup target add riscv64gc-unknown-none-elf

Additionally, the only flow tested so far uses HSS as the bootloader. Installing the HSS Payload Generator is required.

Usage

See the examples:

$ cd examples
$ cargo build --bin embassy-multicore
$ hss-tty-flasher COM5 ../target/riscv64gc-unknown-none-elf/debug/embassy-multicore

Your application's .cargo/config.toml should specify both the target and the linker file:

[build]
target = "riscv64gc-unknown-none-elf"

[target.riscv64gc-unknown-none-elf]
rustflags = ["-C", "link-arg=-Tlinker.ld", "-C", "link-arg=--gc-sections"]

This ensures that the linker script is applied.

cargo check

Get cargo to check using the correct target:

$ cargo check --target riscv64gc-unknown-none-elf

Gateware programming

See beaglev-fire-zephyr-and-baremetal-with-gateware for an example project that contains the BeagleV-Fire gateware along with an updated bootloader (HSS). icicle-kit-minimal-bring-up-design-bitstream-builder similarly illustrates this for the Icicle Kit (though the HSS it uses is older).

You can find a pre-compiled bitstream in the former repo which can either be programmed by using a FlashPro Express 5 or 6 or by taking advantage of the MPFS's auto-update feature via the SPI flash memory, like the BeagleV-Fire change-gateware.sh script does.

If using a FlashPro Express, make sure that the SPI flash does not point to an auto-updateable bitstream. To this end, you can use this image to erase the the first block of the SPI flash memory. Just program it to the board using hss-tty-flasher and let it boot. This only needs to be done once.