Resolving GPIO Direction Mismatch on PolarFire Icicle Kit

by

GPIO Pin Toggle Failure on PolarFire Icicle Kit: A Postmortem

Summary

A critical GPIO direction mismatch between the FPGA fabric and Linux GPIO subsystem prevented physical pin toggling on the PolarFire Icicle kit. Despite successful software operations (exporting pins, setting values via sysfs and libgpiod), the physical pins remained unresponsive. The root cause was the FPGA GPIO controller configuring pins as inputs by default, while the Linux driver attempted to control them as outputs.

  • The sysfs interface showed the pin direction reverting to “in” immediately after setting “out”
  • gpioinfo confirmed the line was registered as “input active-high”
  • debugfs displayed the pin in “hi” state but as an input, not an output
  • libgpiod’s gpioset command failed silently because the hardware lacked output capability

Root Cause

The FPGA GPIO block was configured with a fixed input direction in the HDL design, preventing the Linux GPIO subsystem from controlling pin direction or output states.

The specific failure points were:

  • The Microchip PolarFire SoC GPIO controller in the FPGA fabric has hard-coded direction registers that override software settings when not properly initialized
  • The 2025_07 reference design likely used default GPIO configuration that set all user GPIO pins to input mode for safety
  • The Linux gpiolib driver cannot override hardware-level direction settings enforced by the FPGA fabric
  • The pin muxing in Libero was set to GPIO input function without enabling the output driver path

Why This Happens in Real Systems

FPGA-based GPIO controllers differ fundamentally from fixed-function GPIO hardware like on Raspberry Pi or STM32 MCUs.

  • Hardware-first direction control: In FPGAs, GPIO direction is often determined at synthesis time via HDL, not runtime software
  • Fabric-level overrides: The FPGA fabric can enforce pin behavior that software cannot modify once the bitstream is loaded
  • Missing driver initialization: Reference designs often omit the proper GPIO direction initialization sequence required by the PolarFire SoC
  • Conflicting pin assignments: The pin may have been allocated to another fabric peripheral that also claims control
  • Incomplete device tree: The GPIO controller’s pin configuration in the device tree may lack the necessary properties to enable output mode

Real-World Impact

This issue manifests across multiple platforms and causes significant development delays:

  • Production schedules missed when hardware bring-up encounters unexplained GPIO failures
  • Wrong assumptions about hardware capability leading to firmware rewrites that never solve the underlying problem
  • Increased support burden as engineers spend days debugging what appears to be a software issue
  • Potential board respins if the problem is incorrectly diagnosed as a hardware fault

Example or Code (if necessary and relevant)

The problem can be diagnosed with these commands:

# Check current direction - will show "in" despite software attempts to set "out"
cat /sys/class/gpio/gpio514/direction

# Verify hardware state - shows input active-high
gpioinfo gpiochip0 | grep -A1 "line 2"

# Check debugfs - confirms hardware-level direction
cat /sys/kernel/debug/gpio

The expected FPGA HDL fix (in Verilog) would configure the GPIO direction:

// In the FPGA GPIO controller module
assign gpio_oen = 1'b0;  // Enable output driver (0 = output, 1 = input)
assign gpio_out = gpio_reg;  // Output data to pin

How Senior Engineers Fix It

Senior engineers verify hardware configuration before writing any software code.

  • Review FPGA design first: Examine the HDL to confirm GPIO direction is set to output in the fabric
  • Check device tree bindings: Verify the GPIO controller node has correct pin configuration properties
  • Use hardware debuggers: Inspect FPGA register maps to confirm direction bits are set correctly
  • Cross-reference with reference manual: Microchip’s documentation specifies required initialization sequences
  • Test with LED circuits: Simplest physical verification that output is actually working
  • Contact FAE support: FPGA GPIO quirks often require vendor-specific knowledge

The fix typically involves:

  1. Modifying the FPGA design to enable GPIO output direction
  2. Ensuring the device tree configures the pin correctly
  3. Adding proper GPIO controller initialization in the Linux boot sequence

Why Juniors Miss It

Junior engineers assume GPIO works like microcontrollers where software has full control.

  • Mental model from MCUs: Raspberry Pi and STM32 GPIO allow runtime direction changes—FPGAs do not by default
  • Trusting software output: Seeing “value” change in sysfs leads to incorrect conclusions about hardware state
  • Ignoring the FPGA layer: The PolarFire SoC has a programmable fabric layer that must be correctly configured
  • Skipping hardware docs: The Libero design tool and Microchip docs contain necessary configuration details
  • No FPGA experience: GPIO in FPGAs requires understanding both HDL and software interaction

The critical insight is that in FPGA-based systems, hardware design dictates GPIO behavior—software can only work within those constraints.

Leave a Comment