From 5a3b8b943ecf1a3a63e15e83e6afe4a8053f5722 Mon Sep 17 00:00:00 2001 From: Thomas Dettbarn Date: Thu, 23 Apr 2026 09:47:13 +0200 Subject: [PATCH 1/6] OpenBSD-Patch: Added the #include in xvc_server.cpp to allow for compilation. Added a section to the README.md. --- README.md | 35 +++++++++++++++++++++++++++++++++++ src/xvc_server.cpp | 1 + 2 files changed, 36 insertions(+) diff --git a/README.md b/README.md index cc2d2c6f4..0e84b31e0 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,41 @@ OPENFPGALOADER_SOJ_DIR=/somewhere openFPGALoader xxxx `OPENFPGALOADER_SOJ_DIR` must point to directory containing **spiOverJtag** bitstreams. +## Disabling uftdi on OpenBSD + +Certain evaluation boards can cause the following error when running openFPGAloader on OpenBSD: + +``` +fail to read data usb bulk read failed +JTAG init failed with: low level FTDI init failed +``` + +This issue is most likely caused by the uftdi module, trying to access the device. To disable it, +the following commands can be used: + +```bash +# doas config -e -f -o /bsd.nouftdi /bsd +OpenBSD 7.8 (GENERIC) #54: Sun Oct 12 12:45:58 MDT 2025 + deraadt@amd64.openbsd.org:/usr/src/sys/arch/amd64/compile/GENERIC +Enter 'help' for information +ukc> disable uftdi* +356 uftdi* disabled +ukc> disable uftdi0 +ukc> disable uftdi1 +ukc> quit +Saving modified kernel. +# reboot +``` + +At the boot prompt, typing in + +``` +boot> boot /bsd.nouftdi +``` + +will boot the new kernel with the disabled module. + + ## Sponsors/Partners ![Sponsors](https://github.com/user-attachments/assets/cb4efce1-ed0c-461c-bd05-9caeb440870d) diff --git a/src/xvc_server.cpp b/src/xvc_server.cpp index f710a79d6..bd660ee11 100644 --- a/src/xvc_server.cpp +++ b/src/xvc_server.cpp @@ -6,6 +6,7 @@ #include "xvc_server.hpp" #include +#include #include #include #include From 7887cc059733cf9aeeb6effebca44cc1a1e7191c Mon Sep 17 00:00:00 2001 From: Thomas Dettbarn Date: Fri, 15 May 2026 15:01:37 +0200 Subject: [PATCH 2/6] Moved the Note regarding OpenBSD from the README.md into the doc/guide/troubleshooting.rst. --- README.md | 34 ---------------------------------- doc/guide/troubleshooting.rst | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 0e84b31e0..80c8bbf13 100644 --- a/README.md +++ b/README.md @@ -156,40 +156,6 @@ OPENFPGALOADER_SOJ_DIR=/somewhere openFPGALoader xxxx `OPENFPGALOADER_SOJ_DIR` must point to directory containing **spiOverJtag** bitstreams. -## Disabling uftdi on OpenBSD - -Certain evaluation boards can cause the following error when running openFPGAloader on OpenBSD: - -``` -fail to read data usb bulk read failed -JTAG init failed with: low level FTDI init failed -``` - -This issue is most likely caused by the uftdi module, trying to access the device. To disable it, -the following commands can be used: - -```bash -# doas config -e -f -o /bsd.nouftdi /bsd -OpenBSD 7.8 (GENERIC) #54: Sun Oct 12 12:45:58 MDT 2025 - deraadt@amd64.openbsd.org:/usr/src/sys/arch/amd64/compile/GENERIC -Enter 'help' for information -ukc> disable uftdi* -356 uftdi* disabled -ukc> disable uftdi0 -ukc> disable uftdi1 -ukc> quit -Saving modified kernel. -# reboot -``` - -At the boot prompt, typing in - -``` -boot> boot /bsd.nouftdi -``` - -will boot the new kernel with the disabled module. - ## Sponsors/Partners diff --git a/doc/guide/troubleshooting.rst b/doc/guide/troubleshooting.rst index e2475ada2..fa5a33c16 100644 --- a/doc/guide/troubleshooting.rst +++ b/doc/guide/troubleshooting.rst @@ -76,3 +76,37 @@ After changing groups or rules, reload udev rules, then unplug/replug the converter and log out/login again. Reference: `install guide (udev rules section) `_. + + +Unable to flash device on OpenBSD: `JTAG init failed with: DirtyJtag: fails to open device` +=========================================================================================== +Certain evaluation boards may show the following error message when running openFPGAloader on OpenBSD: + +.. code:: bash + fail to read data usb bulk read failed + JTAG init failed with: low level FTDI init failed + +This issue is most likely caused by the uftdi module, which has already locked the device. +Disabling the module can be achieved with the following commands: + +.. code:: bash + # doas config -e -f -o /bsd.nouftdi /bsd + OpenBSD 7.8 (GENERIC) #54: Sun Oct 12 12:45:58 MDT 2025 + deraadt@amd64.openbsd.org:/usr/src/sys/arch/amd64/compile/GENERIC + Enter 'help' for information + ukc> disable uftdi* + 356 uftdi* disabled + ukc> disable uftdi0 + ukc> disable uftdi1 + ukc> quit + Saving modified kernel. + # reboot + +At the boot prompt, typing in + +.. code:: bash + boot> boot /bsd.nouftdi + +will boot the new kernel with the disabled module. +Afterwards, openFPGALoader will access the development board as a generic USB device. + From 1cd7977c9c7882c39faafba11f71faad90b0e098 Mon Sep 17 00:00:00 2001 From: Thomas Dettbarn Date: Sat, 16 May 2026 07:40:02 +0200 Subject: [PATCH 3/6] reverted the README.md back to its original form. --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 80c8bbf13..b9e767b3b 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,9 @@ openFPGALoader -- a program to flash FPGA --cable-index arg probe index (FTDI and cmsisDAP) --busdev-num arg select a probe by it bus and device number (bus_num:device_addr) - --ftdi-serial arg FTDI chip serial number + --usb-serial-num arg USB iSerial (FTDI chip serial number or ESP32 + iSerialNumber substring) + --ftdi-serial arg FTDI chip serial number (Deprecated) --ftdi-channel arg FTDI chip channel number (channels 0-3 map to A-D) -d, --device arg device to use (/dev/ttyUSBx) @@ -119,6 +121,8 @@ openFPGALoader -- a program to flash FPGA -v, --verbose Produce verbose output --verbose-level arg verbose level -1: quiet, 0: normal, 1:verbose, 2:debug + --force-terminal-mode force progress bar output as if connected to + a terminal -h, --help Give this help list --verify Verify write operation (SPI Flash only) --xvc Xilinx Virtual Cable Functions @@ -130,7 +134,8 @@ openFPGALoader -- a program to flash FPGA -X, --read-xadc Read XADC (Xilinx FPGA only) --read-register arg Read Status Register(Xilinx FPGA only) --user-flash arg User flash file (Gowin LittleBee FPGA only) - -V, --Version Print program version + -V, --version Print program version + --Version Print program version (Deprecated) Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options. @@ -156,7 +161,6 @@ OPENFPGALOADER_SOJ_DIR=/somewhere openFPGALoader xxxx `OPENFPGALOADER_SOJ_DIR` must point to directory containing **spiOverJtag** bitstreams. - ## Sponsors/Partners ![Sponsors](https://github.com/user-attachments/assets/cb4efce1-ed0c-461c-bd05-9caeb440870d) From 354c087d78946abfb87dc3d6377b1ab2846f1e21 Mon Sep 17 00:00:00 2001 From: Thomas Dettbarn Date: Sat, 30 May 2026 06:03:56 +0200 Subject: [PATCH 4/6] Removed a copy&paste error in the main.cpp file. Updated the documentation on OpenBSD. --- README.md | 2 +- doc/guide/troubleshooting.rst | 23 ++++++++++++++++++++--- src/main.cpp | 4 ++-- 3 files changed, 23 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 0950423d2..2f85354c2 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ First steps • Install • Troubleshooting • Advanced usage

-Universal utility for programming FPGAs. Compatible with many boards, cables and FPGA from major manufacturers (Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic, Cologne Chip). openFPGALoader works on Linux, Windows and macOS. +Universal utility for programming FPGAs. Compatible with many boards, cables and FPGA from major manufacturers (Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic, Cologne Chip). openFPGALoader works on Linux, Windowso, macOS and OpenBSD. Not sure if your hardware is supported? Check the hardware compatibility lists: diff --git a/doc/guide/troubleshooting.rst b/doc/guide/troubleshooting.rst index fa5a33c16..ad7489ce7 100644 --- a/doc/guide/troubleshooting.rst +++ b/doc/guide/troubleshooting.rst @@ -83,13 +83,28 @@ Unable to flash device on OpenBSD: `JTAG init failed with: DirtyJtag: fails to o Certain evaluation boards may show the following error message when running openFPGAloader on OpenBSD: .. code:: bash + fail to read data usb bulk read failed JTAG init failed with: low level FTDI init failed -This issue is most likely caused by the uftdi module, which has already locked the device. -Disabling the module can be achieved with the following commands: +This issue is most likely caused by the uftdi module, which has attached itself to the device, whereas openFPGALoader requires it to be accessible as a ugen device. + +Unfortunately, due to the security concept of OpenBSD, it is not possible to detach it without modifying the kernel and rebooting the system. However, there are two ways to resolve the issue: Either by patching and recompiling the kernel; or by deactivating the uftdi module. + +After COMMENTING OUT the problematic devices in `/usr/src/sys/dev/usb/uftdi.c`, the code would look like this: + +.. code:: c + + { USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SEMC_DSS20 }, + //{ USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SERIAL_2232C }, + { USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SERIAL_2232L }, + +Afterwards, the steps in `https://www.openbsd.org/faq/faq5.html ` can be used to recompile the kernel. + +Without recompilation, DEACTIVATING the uftdi module can be achieved using the following commands: .. code:: bash + # doas config -e -f -o /bsd.nouftdi /bsd OpenBSD 7.8 (GENERIC) #54: Sun Oct 12 12:45:58 MDT 2025 deraadt@amd64.openbsd.org:/usr/src/sys/arch/amd64/compile/GENERIC @@ -105,8 +120,10 @@ Disabling the module can be achieved with the following commands: At the boot prompt, typing in .. code:: bash + boot> boot /bsd.nouftdi will boot the new kernel with the disabled module. -Afterwards, openFPGALoader will access the development board as a generic USB device. + +Either way, openFPGALoader will then be able to access the development board as a generic USB device. diff --git a/src/main.cpp b/src/main.cpp index 3998aee02..44de606a5 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -569,7 +569,7 @@ int main(int argc, char **argv) fpga = new CologneChip(jtag, args.bit_file, args.file_type, args.prg_type, args.board, args.cable, args.verify, args.verbose); #else - printError("Support for Gowin FPGAs was not enabled at compile time"); + printError("Support for Cologne Chip FPGAs was not enabled at compile time"); delete(jtag); return EXIT_FAILURE; #endif @@ -756,7 +756,7 @@ int spi_comm(struct arguments args, const cable_t &cable, board->reset_pin, board->done_pin, DBUS6, board->oe_pin, args.verify, args.verbose); #else - printError("Support for Gowin FPGAs was not enabled at compile time"); + printError("Support for Cologne Chip FPGAs was not enabled at compile time"); return EXIT_FAILURE; #endif } else { From 7f7f4717310146db288d75c22b43c8449a13e49b Mon Sep 17 00:00:00 2001 From: Thomas Dettbarn Date: Sat, 30 May 2026 06:12:29 +0200 Subject: [PATCH 5/6] slight change to reflect the nomenclature of modules/devices in OpenBSD. --- doc/guide/troubleshooting.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/guide/troubleshooting.rst b/doc/guide/troubleshooting.rst index ad7489ce7..cb10e00d7 100644 --- a/doc/guide/troubleshooting.rst +++ b/doc/guide/troubleshooting.rst @@ -87,9 +87,9 @@ Certain evaluation boards may show the following error message when running open fail to read data usb bulk read failed JTAG init failed with: low level FTDI init failed -This issue is most likely caused by the uftdi module, which has attached itself to the device, whereas openFPGALoader requires it to be accessible as a ugen device. +This issue is most likely caused by the uftdi(4) module, which has attached itself to the device, whereas openFPGALoader requires it to be accessible as a ugen(4) device. -Unfortunately, due to the security concept of OpenBSD, it is not possible to detach it without modifying the kernel and rebooting the system. However, there are two ways to resolve the issue: Either by patching and recompiling the kernel; or by deactivating the uftdi module. +Unfortunately, due to the security concept of OpenBSD, it is not possible to detach it without modifying the kernel and rebooting the system. However, there are two ways to resolve the issue: Either by patching and recompiling the kernel; or by deactivating the uftdi(4) module. After COMMENTING OUT the problematic devices in `/usr/src/sys/dev/usb/uftdi.c`, the code would look like this: @@ -99,9 +99,9 @@ After COMMENTING OUT the problematic devices in `/usr/src/sys/dev/usb/uftdi.c`, //{ USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SERIAL_2232C }, { USB_VENDOR_FTDI, USB_PRODUCT_FTDI_SERIAL_2232L }, -Afterwards, the steps in `https://www.openbsd.org/faq/faq5.html ` can be used to recompile the kernel. +With this manual patch applied, the steps in `https://www.openbsd.org/faq/faq5.html ` can be used to recompile the kernel. -Without recompilation, DEACTIVATING the uftdi module can be achieved using the following commands: +Without recompilation, DEACTIVATING uftdi(4) can be achieved using the following commands: .. code:: bash @@ -125,5 +125,5 @@ At the boot prompt, typing in will boot the new kernel with the disabled module. -Either way, openFPGALoader will then be able to access the development board as a generic USB device. +Either way, openFPGALoader will then be able to access the development board as a generic USB device via ugen(4). From 642dbf843e11e3209112f6ab66998444dfa75ec0 Mon Sep 17 00:00:00 2001 From: Thomas Dettbarn Date: Sat, 30 May 2026 11:26:47 +0200 Subject: [PATCH 6/6] "Windows" is spelled with only one "o". --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f85354c2..042e49275 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ First steps • Install • Troubleshooting • Advanced usage

-Universal utility for programming FPGAs. Compatible with many boards, cables and FPGA from major manufacturers (Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic, Cologne Chip). openFPGALoader works on Linux, Windowso, macOS and OpenBSD. +Universal utility for programming FPGAs. Compatible with many boards, cables and FPGA from major manufacturers (Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic, Cologne Chip). openFPGALoader works on Linux, Windows, macOS and OpenBSD. Not sure if your hardware is supported? Check the hardware compatibility lists: