Crate fpgad_cli 

FPGA CLI (fpgad_cli) - Command-line interface for managing FPGA devices.

This is FPGAd’s commandline interface (CLI) . Due to strict confinement of the snap, this can only be used from a terminal or from a script which is not part of another snap. It is a useful helper for one-off control of the FPGA device or testing, and serves as an example implementation for the DBus interface.

Common Concepts

The following concepts are shared across all CLI submodules (load, remove, set, status).

Device Handles

A “device handle” refers to the name of an FPGA device as it appears in /sys/class/fpga_manager/. Common examples include:

• fpga0 - The first FPGA device
• fpga1 - The second FPGA device (if multiple FPGAs are present)

These handles uniquely identify FPGA devices in the system and are used throughout the CLI to specify which device to operate on.

Overlay Handles

An “overlay handle” refers to the name of a device tree overlay as it appears in /sys/kernel/config/device-tree/overlays/. Common examples include:

• overlay0 - A generic overlay name
• fpga-design - A custom overlay name specified during loading

These handles are used to identify and manage loaded device tree overlays. When loading an overlay, you can specify a custom handle or let the system choose one based on the device handle.

Error Handling

All CLI functions communicate with the fpgad daemon via DBus and return Result<String, zbus::Error> (or variants with Vec<String> or HashMap<String, String>).

When the fpgad daemon returns an application-level error (not a DBus communication error), the error will be of type zbus::Error::Failure and the error message will begin with FpgadError::<variant>: followed by the error details. For example:

FpgadError::Argument: Device fpga0 not found.
FpgadError::IOWrite: Failed to write bitstream: Permission denied
FpgadError::IORead: Failed to read state: No such file or directory

This allows callers to distinguish between:

• DBus communication errors - Problems connecting to or communicating with the daemon
• Application errors - Errors from the daemon itself (prefixed with FpgadError::)

Usage

Usage: [snap run] fpgad [OPTIONS] <COMMAND>

OPTIONS:
  -h, --help                      Print help
  -p, --platform <PLATFORM>       Platform override string (bypasses platform detection logic).
                                  When provided, this platform string is passed directly to the
                                  daemon instead of auto-detecting from the device handle.
                                  Examples: "universal", "xlnx,zynqmp-pcap-fpga"
  -d, --device <DEVICE_HANDLE>    FPGA device handle to be used for the operations.
                                  Default value is calculated at runtime - the application
                                  picks the first available FPGA device in the system
                                  (under `/sys/class/fpga_manager/`).
                                  Examples: "fpga0", "fpga1"

SUBCOMMAND OPTIONS:
  -n, --name <OVERLAY_NAME>       (Used with load/remove overlay subcommands)
                                  Name for the overlay directory in configfs
                                  (under `/sys/kernel/config/device-tree/overlays/`).
                                  If not provided, defaults to the device handle or "overlay0".

COMMANDS:
├── load                Load a bitstream or overlay
│   ├── overlay <FILE> [--name <OVERLAY_HANDLE> --platform <PLATFORM>]
│   │       Load overlay (.dtbo) into the system using the default OVERLAY_HANDLE
│   │           (either the provided DEVICE_HANDLE or "overlay0") or provide
│   │       --name: to name the overlay directory
│   └── bitstream <FILE> [--platform <PLATFORM>]
│           Load bitstream (e.g. `.bit.bin` file) into the FPGA
│
├── set <ATTRIBUTE> <VALUE>
│       Set an attribute/flag under `/sys/class/fpga_manager/<DEVICE_HANDLE>/<ATTRIBUTE>`
│
├── status [--device <DEVICE_HANDLE> --platform <PLATFORM>]
│       Show FPGA status (all devices and overlays) or provide
│       --device: for a specific device status
│
└── remove              Remove an overlay or bitstream
    ├── overlay [--name <OVERLAY_HANDLE> --platform <PLATFORM>]
    │       Removes the first overlay found (call repeatedly to remove all) or provide
    │       --name: to remove overlay previously loaded with given OVERLAY_HANDLE
    └── bitstream [--name <BITSTREAM_HANDLE> --platform <PLATFORM>]
            Remove active bitstream from FPGA (bitstream removal is vendor specific)

Loading

fpgad [--device=<device_handle>] [--platform=<platform>] load ( (overlay <file> [--name=<overlay_name>]) | (bitstream <file>) )

Removing

fpgad [--device=<device_handle>] [--platform=<platform>] remove ( ( overlay [--name=<overlay_name>] ) | ( bitstream ) )

Set

fpgad [--device=<device_handle>] set ATTRIBUTE VALUE

Status

fpgad [--device=<device_handle>] [--platform=<platform>] status

examples (for testing)

Load

sudo ./target/debug/cli load bitstream /lib/firmware/k26-starter-kits.bit.bin
sudo ./target/debug/cli --device=fpga0 load bitstream /lib/firmware/k26-starter-kits.bit.bin
sudo ./target/debug/cli --platform=universal load bitstream /lib/firmware/k26-starter-kits.bit.bin
sudo ./target/debug/cli --platform=xlnx load bitstream /lib/firmware/k26-starter-kits.bit.bin

sudo ./target/debug/cli load overlay /lib/firmware/k26-starter-kits.dtbo
sudo ./target/debug/cli load overlay /lib/firmware/k26-starter-kits.dtbo --name=overlay_handle
sudo ./target/debug/cli --device=fpga0 load overlay /lib/firmware/k26-starter-kits.dtbo --name=overlay_handle
sudo ./target/debug/cli --platform=universal load overlay /lib/firmware/k26-starter-kits.dtbo --name=overlay_handle
sudo ./target/debug/cli --platform=xlnx --device=fpga0 load overlay /lib/firmware/k26-starter-kits.dtbo --name=overlay_handle

Remove

sudo ./target/debug/cli --device=fpga0 remove overlay
sudo ./target/debug/cli --device=fpga0 remove overlay --name=overlay_handle

Set

sudo ./target/debug/cli set flags 0
sudo ./target/debug/cli --device=fpga0 set flags 0

Status

./target/debug/cli status
./target/debug/cli --device=fpga0 status

Modules

load

Load command implementation for the FPGA CLI.

remove

Remove command implementation for the FPGA CLI.

set

Set command implementation for the FPGA CLI.

status

Status command implementation for the FPGA CLI.

Structs

Cli

Command-line interface structure for FPGA management operations.

Enums

Commands

Top-level commands supported by the CLI.

LoadSubcommand

Subcommands for loading FPGA components.

RemoveSubcommand

Subcommands for removing FPGA components.