How to run JTAG by hand on an Acorn on a Raspberry Pi 5

You have an Acorn wired to a Raspberry Pi 5 and want to see its JTAG answer, then load a design over it.

The boot check reads the IDCODE and the device DNA over P1 by itself (jtag): Acorn tests and their wires on a Raspberry Pi 5. On a Compute Blade the commands differ: How to run JTAG by hand on an Acorn on a Compute Blade.

What you need

  • An Acorn wired as on Acorn wiring on a Raspberry Pi 5, in the M.2 HAT slot, where the card is at 0001:01:00.0.

  • openFPGALoader on the Pi, with the libgpiod cable.

  • The pin order 10:9:11:8 (TDI:TDO:TCK:TMS) for the --pins option.

  • The fpgas.online Acorn design’s .bit file in SOC:

    The design these steps load is the fpgas.online Acorn design, the only design a package installs. fpgas-online-acorn-bitstreams puts it in /usr/share/fpgas-online/acorn-pcie/images/, for each variant (cle-215p, cle-215, cle-101) as acorn-<variant>-sqrl_acorn.bit for a JTAG load, beside the two flash images. Put its name in SOC once per shell; the example is a CLE-101, so put another card’s variant in place of cle-101, here and in the release file names of the loopback and pin-ID designs:

    $ SOC=/usr/share/fpgas-online/acorn-pcie/images/acorn-cle-101-sqrl_acorn.bit
    

Steps

  1. On the Pi, detach the card’s PCIe endpoint, so that the load cannot remove it under the host (why); lspci no longer lists the card.

    $ echo 1 | sudo tee /sys/bus/pci/devices/0001:01:00.0/remove
    
  2. On the Pi, make sure gpiochip0 is the header’s GPIO chip, because the libgpiod cable opens /dev/gpiochip0.

    The header’s GPIO chip is the one gpiodetect lists as pinctrl-rp1; its number varies from 11 to 15. Where the Acorn packages are installed, the boot check makes gpiochip0 a link to it when gpiochip0 is missing. The link is gone at each reboot. Check which chip gpiochip0 is:

    $ sudo gpiodetect
    $ ls -l /dev/gpiochip0
    

    Skip the link if ls -l shows -> gpiochipN with N the number of pinctrl-rp1, or gpiodetect lists gpiochip0 itself as pinctrl-rp1. If /dev/gpiochip0 is missing or another chip, link it. The line below is for gpiochip15: put your chip’s number in place of 15.

    $ sudo ln -sfn /dev/gpiochip15 /dev/gpiochip0
    
  3. On the Pi, read the IDCODE with a read-only --detect, which is safe without step 1; it prints the IDCODE of the chip.

    $ openFPGALoader --cable libgpiod --pins 10:9:11:8 --detect
    
  4. On the Pi, load the design into SRAM, which takes about 16 s for a 1.6 MB XC7A200T bitstream over libgpiod.

    $ openFPGALoader --cable libgpiod --pins 10:9:11:8 $SOC
    
  5. On the Pi, bring the endpoint back with echo 1 | sudo tee /sys/bus/pci/rescan, or reboot; the card is enumerated again.

Check

The IDCODE from step 3 tells the chip: 0x3636093 for an XC7A200T (CLE-215+, CLE-215, NiteFury) and 0x3631093 for an XC7A100T (CLE-101, LiteFury).

idcode 0x3636093 (XC7A200T)

A load over JTAG lands in SRAM and works on every variant. An SRAM load is lost at power-off, so a reboot restores whatever is in flash. Never pass --write-flash here: How to install the fpgas.online images on an Acorn writes the flash.

If it fails

  • JTAG init failed with: Unable to open gpio chip: the gpiochip0 link of step 2 is missing; link the chip again.

  • No idcode line from --detect, but PCIe enumerates: the P1 cable is unmated or miswired; check TCK for the Acorn’s pull-up and reseat P1.

  • Open file … FAIL in under 0.1 s: the bitstream is gone. /home/pi is a memory overlay (overlayroot=tmpfs) that loses its files at reboot; copy it again.

  • The Pi drops SSH and reboots during the load: the endpoint was still enumerated; detach it (step 1) before every load.

  • JTAG programming fails: the pin order is wrong; use --pins 10:9:11:8.

Next