Skip to content

cli-reference.md

Latest commit

 

History

History
101 lines (79 loc) · 4.51 KB

cli-reference.md

File metadata and controls

101 lines (79 loc) · 4.51 KB
Raw

CLI Reference

Syntax

directc_jtag [-h] [-a <action> | --action <action>] [options] [filename]

The action can be passed as a separate argument after -a or --action, or attached to -a for backward compatibility:

./directc_jtag -a program image.dat
./directc_jtag --action program image.dat
./directc_jtag -aprogram image.dat      # legacy attached form

The filename is loaded before GPIO initialization. A filename is currently required even for actions that conceptually only read an IDCODE.

Runtime Backend Selection

The runtime backend is independent of the Makefile BACKEND build choice. The default combined executable uses GPIO unless an FTDI option is given.

Runtime option Selected backend Requirements
no option GPIO Built with BACKEND=all or BACKEND=gpio
--interface gpio GPIO GPIO backend included and target GPIO access
--interface ftdi FTDI MPSSE FTDI backend included and USB access
--ftdi FTDI MPSSE Alias for --interface ftdi

An executable built with only one backend cannot select the other backend at runtime. For dynamic selection, build with make or make BACKEND=all.

FTDI Options

GPIO remains the default interface. The --ftdi shortcut selects an FT2232 adapter and MPSSE mode. The standard FT2232 JTAG mapping is D0/TCK, D1/TDI, D2/TDO, and D3/TMS.

--interface gpio|ftdi
--ftdi
--ftdi-mode mpsse
--ftdi-vid <hex>
--ftdi-pid <hex>
--ftdi-channel A|B
--ftdi-serial <string>
--jtag-frequency <hz>
--jtag-reset tap
--verbose

FTDI defaults are VID 0x0403, PID 0x6010, channel A, 1 MHz JTAG clock, and TAP reset through TMS. An explicit FTDI invocation is:

./directc_jtag --ftdi --ftdi-vid 0x0403 --ftdi-pid 0x6010 \
  --ftdi-channel A --jtag-frequency 6000000 -a program image.dat

Actions

Action Description Input and effect
program Erase, program, and verify supported blocks Requires a matching DAT file; modifies the target
erase Erase supported blocks Requires DAT metadata; destructive
read_idcode Read and display the JTAG IDCODE Current CLI still requires a filename; read-only
verify Verify supported blocks Requires DAT data; read-only
device_info Display device design information and security status Requires DAT context; target-dependent
enc_data_authentication Authenticate encrypted array data Requires compatible encrypted DAT data
verify_digest Verify a PolarFire digest PolarFire-specific; target-dependent
validate_user_enc_keys Validate user encryption keys Security state and DAT dependent
read_device_certificate Read the device certificate Read-only; target-dependent
zeroize_like_new Zeroize the device in a recoverable mode Destructive; confirm the target first
zeroize_unrecoverable Zeroize the device irreversibly Destructive and potentially unrecoverable
spi_flash_read_idcode Read the three-byte JEDEC ID Requires a filename in the current CLI; read-only
spi_flash_read Read image_size bytes from SPI Flash Output can be large; read-only
spi_flash_erase Erase the entire supported SPI Flash Destructive
spi_flash_program Erase required sectors and program the image Requires a compatible DAT image
spi_flash_verify Verify the image region in SPI Flash Requires the expected image in the DAT file
spi_flash_blank_check Check the complete Flash address space for 0xFF Read-only but potentially very slow

The action is selected with -a <action> or --action <action>; the legacy attached form -a<action> is also accepted. Action names are matched case-insensitively. Unknown names map to the internal DP_NO_ACTION_FOUND action and should be treated as an error.

Typical Commands

./directc_jtag -a read_idcode image.dat
./directc_jtag -a device_info image.dat
./directc_jtag -a program image.dat
./directc_jtag -a verify image.dat
./directc_jtag -a spi_flash_read_idcode image.dat
./directc_jtag -a spi_flash_program image.dat
./directc_jtag -a spi_flash_verify image.dat

Output

Normal output may include device identification, progress, operation status, elapsed time, and an error code. For a failed operation, record both the printed error code and the preceding diagnostic text.

The current main() function does not consistently copy the hardware operation result into the process exit status. Until that is corrected, scripts should not rely on a zero/non-zero shell status alone.