Troubleshooting and Known Issues¶

Grouped by symptom. When networking won't come up at all, use a USB-UART serial console. It shows you the boot messages that ssh can't. Connect a USB-UART adapter to the board's UART header and open the port at 115200 baud in a terminal program (for example PuTTY, screen, or minicom). The authoritative, continuously updated list is the known-issue note. This page reorganizes it and adds the debugging tools.

Boot and networking¶

Can't `ssh` to the board on first boot¶

Delete /etc/network/interfaces.new, a leftover from image creation that can break the network configuration, from the SD card's rootfs partition (on your PC). If it still fails, use the UART console (/dev/ttyUSBx, /dev/ttyCH341USBx, …) to watch the boot.

No UART console device appears¶

On ANTSDR-E200 and similar CH341 adapters, try sudo apt remove brltty, since brltty grabs the CH341 device. (Reference: the CH341SER notes.)

`EXT4-fs error (device mmcblk0p2)` on first boot¶

Seen on neptunesdr. The flashing tool is suspect, so re-flash with a different one (GNOME Disks, Startup Disk Creator, or win32diskimager).

ZCU102 kernel panic, "Unable to mount root fs on unknown-block(179,2)"¶

The same SD card boots on some ZCU102 units but not others. The SD interface likely needs to run slower. Add these to the mmc/sdhci node of the ZCU102 device tree to cap the speed (see Boot, Kernel & Device Tree for how openwifi builds and edits a board's device tree):

xlnx,has-cd = <0x1>;
xlnx,has-power = <0x0>;
xlnx,has-wp = <0x1>;
disable-wp;
no-1-8-v;
broken-cd;
xlnx,mio-bank = <1>;
sdhci-caps-mask = <0 0x200000>;
sdhci-caps = <0 0>;
max-frequency = <19000000>;

Board won't boot at all (SPI flash suspected)¶

The on-board SPI flash holds some config (kernel file, AD9361 crystal frequency ad9361_ext_refclk=0x2625a8b). Interrupt boot in the UART console (press Enter before Linux loads) and reset the environment:

Zynq> env default -a
Zynq> saveenv

This resets all U-Boot variables

env default -a + saveenv permanently restores factory defaults and erases any custom U-Boot variables you set. Reboot the board afterwards. It should then boot normally.

Wrong memory size on ADRV9361-Z7035 SoM¶

Linux detects only half the RAM. An old u-boot.elf hard-coded 512 MB. Rebuild U-Boot from analogdevicesinc/u-boot-xlnx and regenerate BOOT.BIN (build flow: Boot, Kernel & Device Tree):

source environment_setting.sh          # from the u-boot-xlnx checkout
export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
make zynq_adrv9361_defconfig && make -j8 && make u-boot.elf

The 1 GB fix is already in u-boot-xlnx master (zynq-adrv9361.dts), so a current checkout needs no source edits.

Client and link problems¶

Client connects but gets no IP¶

Restart the DHCP server on the board and reconnect from the client:

service isc-dhcp-server restart

Big packet loss at slow ping, but fine at fast ping¶

The other device's Wi-Fi power save is the usual cause, because it sleeps between your infrequent packets. Turn it off on that device:

iw dev wlan0 get power_save
sudo iw dev wlan0 set power_save off

Ping-by-hostname fails (DNS)¶

Set nameserver 8.8.8.8 in /etc/resolv.conf on the board.

Reception dies after ~2 hours¶

./sdrctl dev sdr0 get reg rx 20 is frozen. This is the Xilinx Viterbi decoder evaluation license halting, which is expected behavior, not a bug. Reload the FPGA (see dynamic reloading) or power-cycle. A proper license removes the limit.

Hardware quirks¶

FMCOMMS board causes a Linux crash (bad or empty EEPROM)¶

Some FMCOMMS2/3/4 boards ship with a wrong or empty FRU EEPROM, which crashes some platforms (for example the ZCU102). Reprogram it with fru_tools:

Boot the FMCOMMS board on a platform that does come up (for example a 32-bit zed_fmcs2, zc706_fmcs2, or zc702_fmcs2).
Build fru_tools.
Locate the EEPROM with find /sys -name eeprom.
Confirm the mismatch with fru-dump -i <eeprom> -b.

Write the correct master file, e.g.:

fru-dump -i ./masterfiles/AD-FMCOMMS4-EBZ-FRU.bin -o /sys/.../0-0050/eeprom

Reboot and re-read to confirm.

`Unsupported PRODUCT_ID 0xFF` at AD9361 probe¶

Same root cause as the bad/empty EEPROM above, and the same fru_tools fix applies.

`Unsupported PRODUCT_ID 0x00` at AD9361 probe¶

A different failure from the 0xFF case above. 0x00 means the AD9361 or FMCOMMS front end did not power up correctly. The driver reads back all zeros because the chip is not responding, and a bad EEPROM is not the cause. Check the board's power. Make sure the FMCOMMS card is fully seated, its supply rails are up, and the carrier delivers enough current to the front end.

ZCU102 kernel panic (RTC, capacitor, and current load)¶

Some ZCU102 boards kernel-panic during boot, a failure traced to the RTC capacitor and current load. Tracked in issues #366 and #457.

Storage and long-run stability¶

"No space left on device"¶

journald can't write because logs filled the disk. Clean up and cap journald:

These commands are destructive

They delete every log on the board and permanently remove the rsyslog package. Fine on a throwaway demo image, not fine if you still need those logs.

sudo systemd-tmpfiles --clean
sudo systemd-tmpfiles --remove
sudo rm /var/log/* -rf
sudo apt --autoremove purge rsyslog

Then add to /etc/systemd/journald.conf:

SystemMaxUse=64M
Storage=volatile
RuntimeMaxUse=64M
ForwardToConsole=no
ForwardToWall=no

Instability after a long uptime¶

lightdm has a memory leak. If you don't need the desktop, disable it: sudo systemctl disable --now lightdm.

Tool crashes¶

`sdrctl` or `side_ch_ctl` segfaults after another update¶

Both are user-space binaries that stay on the board until you rebuild them. After a driver, kernel, or FPGA update, they may no longer agree with the kernel module's command layout. That mismatch can cause a segmentation fault instead of a clean error. Rebuild both from the current source after an update, even if they have not crashed yet. See Rebuilding sdrctl and Building side_ch_ctl.

Build-host problems¶

Kernel config prompts for new options (GCC plugins, stack canary, Xen…)¶

After a host toolchain or minor kernel bump, new Kconfig options may appear during a kernel build. Choose n / the weakest option for these to avoid build failures or subtle issues.

`libidn.so.11` missing while running `boot_bin_gen.sh`¶

Symlink your installed version (confirm the exact filename first):

sudo ln -s /usr/lib/x86_64-linux-gnu/libidn.so.12.6.3 /usr/lib/x86_64-linux-gnu/libidn.so.11

Vitis HLS error `'2xxxxxxxxx' is an invalid argument`¶

Seen during create_ip_repo.sh. Apply Xilinx article 76960.

FPGA tools need `libtinfo5` on Ubuntu 24¶

The default is libtinfo6. Install libtinfo5 manually (see Environment Setup).

OpenWrt-specific¶

No UART output on ZCU102 under OpenWrt¶

Support was validated only on ZCU102 HW Rev 1.1, and even then some 4 GB SODIMM modules fail with the U-Boot SPL bootflow. Known-good module: MTA8ATF51264HZ-2G6B1. Known-failing: MTA4ATF51264HZ-2G6E1. The fix is to use the Zynq FSBL instead of U-Boot SPL, since the FSBL reads the module's SPD EEPROM and configures DDR correctly. Build it with build_zynqmp_boot_bin.sh in the openwifi repo's kernel_boot/ directory, or generate boot.bin yourself with OpenWrt-built components. Full analysis is in the known-issue note.

Debugging tools¶

Driver dmesg logging¶

Turn on per-event driver prints (then read them with dmesg):

./sdrctl dev sdr0 set reg drv_tx 7 X
./sdrctl dev sdr0 set reg drv_rx 7 X

X is a bitmask:

Bit	Meaning
0	Errors
1	Regular unicast messages (`openwifi_tx`/`openwifi_tx_interrupt`/`openwifi_rx_interrupt`)
2	Broadcast messages
3	Queue stop/wake messages

So 3 = errors + unicast, and 1 = errors only. Search printk in sdr.c to see every print point.

Reading a TX print:

openwifi_tx: 70B RC0 10M FC0040 DI0000 ADDRffff.../6655443322aa/ffff... flag4001201e QoS00 SC20_1 retr1 ack0 prio0 q0 wr19 rd18

70B = length
10M = requested rate, printed in units of 100 kbps, so 1.0 Mbps 802.11b, which openwifi converts to 6 Mbps OFDM
FC0040 = Frame Control
ADDR = addr1/2/3
SC20_1 = sequence number 20, set by the driver
retr1 = no retransmission needed (retrN = up to N transmissions)
ack0 = no ACK needed
prio0/q0 = Linux priority / FPGA queue
wr19 rd18 = ring write/read indices

Reading a TX-interrupt print:

openwifi_tx_interrupt: tx_result [nof_retx 1 pass 1] SC20 prio0 q0 wr20 rd19 num_slot0 cw0 hwq len... no_room_flag0

nof_retx 1 = one transmission total
pass 1 = ACK received
num_slot = CSMA slots waited
cw = contention-window exponent (6 ⇒ CW 64, 0 ⇒ never contended)
hwq len = current FPGA queue length
no_room_flag = FPGA queue DMA nearly full

Reading an RX print:

openwifi_rx: 270B ht0aggr0/0 sgi0 240M FC0080 DI0000 ADDR.../00c88b113f5f/00c88b113f5f SC2133 fcs1 buf_idx10 -78dBm

ht0 = legacy 11a/g (ht1 = 11n)
aggr0/0 = not from an AMPDU / not the last AMPDU subframe
sgi0 = normal guard interval
240M = 24 Mbps
fcs1 = CRC OK (fcs0 = bad)
-78dBm = calibrated signal strength

Native Linux tools¶

tcpdump, tshark, and Wireshark all work over sdr0 exactly as with a commercial card, and are often the quickest way to see what's on the air.

FPGA ILA¶

For FPGA-internal signals, build with the ILA debug macros enabled and use Xilinx ILA to watch the state machines in xpu, tx_intf, and rx_intf. See FPGA Development → Debugging on hardware.

Still stuck?¶

Search this page and the FAQ, then check existing openwifi Discussions for a similar case. For Windows setup, see Tips for Windows users. If you still need help, use a question channel listed under Community and support.