-
Notifications
You must be signed in to change notification settings - Fork 268
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
BuildTheDocs
authored and
BuildTheDocs
committed
Oct 24, 2023
0 parents
commit bd1d6f7
Showing
71 changed files
with
10,414 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Sphinx build info version 1 | ||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. | ||
config: a69ea4f91a9aa5f6188768965ba02ec7 | ||
tags: 645f666f9bcd5a90fca523b33c5a78b7 |
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
.. _compatibility:boards: | ||
|
||
Boards | ||
###### | ||
|
||
.. NOTE:: | ||
`arty` can be any of the board names from the first column. | ||
|
||
.. code-block:: bash | ||
openFPGALoader -b arty bitstream.bit # Loading in SRAM (volatile) | ||
openFPGALoader -b arty -f bitstream.bit # Writing in flash (non-volatile) | ||
.. include:: boards.inc | ||
|
||
* IF: Internal Flash | ||
* EF: External Flash | ||
* AS: Active Serial flash mode | ||
* NA: Not Available | ||
* NT: Not Tested |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
.. _compatibility:cables: | ||
|
||
Cables | ||
###### | ||
|
||
.. include:: cable.inc |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
.. _compatibility:fpgas: | ||
|
||
FPGAs | ||
##### | ||
|
||
.. include:: fpga.inc | ||
|
||
* IF: Internal Flash | ||
* AS: Active Serial flash mode | ||
* NA: Not Available | ||
* NT: Not Tested |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,101 @@ | ||
.. _advanced-usage: | ||
|
||
Advanced usage of openFPGALoader | ||
################################ | ||
|
||
Resetting an FPGA | ||
================= | ||
|
||
.. code-block:: bash | ||
openFPGALoader [options] -r | ||
Using negative edge for TDO's sampling | ||
====================================== | ||
|
||
If transaction are unstable you can try to change read edge by using | ||
|
||
.. code-block:: bash | ||
openFPGALoader [options] --invert-read-edge | ||
Reading the bitstream from STDIN | ||
================================ | ||
|
||
.. code-block:: bash | ||
cat /path/to/bitstream.ext | openFPGALoader --file-type ext [options] | ||
``--file-type`` is required to detect file type. | ||
|
||
.. NOTE:: | ||
It's possible to load a bitstream through network: | ||
|
||
.. code-block:: bash | ||
# FPGA side | ||
nc -lp port | openFPGALoader --file-type xxx [option | ||
# Bitstream side | ||
nc -q 0 host port < /path/to/bitstream.ext | ||
Automatic file type detection bypass | ||
==================================== | ||
Default behavior is to use file extension to determine file parser. | ||
To avoid this mechanism ``--file-type type`` must be used. | ||
FT231/FT232 bitbang mode and pins configuration | ||
=============================================== | ||
FT232R and ft231X may be used as JTAG programmer. | ||
JTAG communications are emulated in bitbang mode. | ||
To use these devices user needs to provides both the cable and the pin mapping: | ||
.. code-block:: bash | ||
openFPGALoader [options] -cft23XXX --pins=TDI:TDO:TCK:TMS /path/to/bitstream.ext | ||
where: | ||
* ft23XXX may be ``ft232RL`` or ``ft231X``. | ||
* TDI:TDO:TCK:TMS may be the pin ID (0 <= id <= 7) or string value. | ||
allowed values are: | ||
===== == | ||
value ID | ||
===== == | ||
TXD 0 | ||
RXD 1 | ||
RTS 2 | ||
CTS 3 | ||
DTR 4 | ||
DSR 5 | ||
DCD 6 | ||
RI 7 | ||
===== == | ||
Writing to an arbitrary address in flash memory | ||
=============================================== | ||
With FPGA using an external SPI flash (*xilinx*, *lattice ECP5/nexus/ice40*, *anlogic*, *efinix*) option ``-o`` allows | ||
one to write raw binary file to an arbitrary adress in FLASH. | ||
Using an alternative directory for *spiOverJtag* | ||
================================================ | ||
By setting ``OPENFPGALOADER_SOJ_DIR`` it's possible to override default | ||
*spiOverJtag* bitstreams directory: | ||
.. code-block:: bash | ||
export OPENFPGALOADER_SOJ_DIR=/somewhere | ||
openFPGALoader xxxx | ||
or | ||
.. code-block:: bash | ||
OPENFPGALOADER_SOJ_DIR=/somewhere openFPGALoader xxxx |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
.. _first-steps: | ||
|
||
First steps with openFPGALoader | ||
############################### | ||
|
||
Install | ||
======= | ||
|
||
Packages are available for Linux distributions, Windows (MSYS2) and macOS: | ||
|
||
* *Arch Linux*: ``sudo pacman -S openfpgaloader`` | ||
|
||
* *Fedora*: ``sudo dnf copr enable mobicarte/openFPGALoader; sudo dnf install openFPGALoader`` | ||
|
||
* *MSYS2*: ``pacman -S mingw-w64-ucrt-x86_64-openFPGALoader`` | ||
|
||
* *macOS*: ``brew install openfpgaloader`` | ||
|
||
More instructions for other installation scenarios are available in :ref:`install`. | ||
|
||
Programming a development board | ||
=============================== | ||
|
||
Just simply replace ``my_fpga_board`` with any FPGA board from :ref:`compatibility:boards` | ||
(or ``openFPGALoader --list-boards``) in any of the two commands below, depending on if you want to program the volatile | ||
part of your FPGA (faster but not persistent) or the flash part of your FPGA (slower but persistent): | ||
|
||
.. code-block:: bash | ||
openFPGALoader -b my_fpga_board my_bitstream.bit # Program to SRAM | ||
openFPGALoader -b my_fpga_board -f my_bitstream.bit # Program to flash | ||
.. NOTE:: | ||
When a bitstream file is compatible with both memory load and FLASH write, the default behavior is to load bitstream | ||
in memory. | ||
|
||
Programming an "standalone" FPGA | ||
================================ | ||
|
||
If your FPGA doesn't come with a built-in programmer or if you prefer to use an external cable, you can specify a cable | ||
to use from :ref:`compatibility:cables` (or ``openFPGALoader --list-cables``): | ||
|
||
.. code-block:: bash | ||
openFPGALoader -c my_cable my_bitstream.bit # Program to SRAM | ||
openFPGALoader -c my_cable -f my_bitstream.bit # Program to flash | ||
.. NOTE:: | ||
For some cable (like digilent adapters) signals from the converter are not just directly to the FPGA. | ||
For this case, the ``-c`` must be added. | ||
|
||
.. HINT:: | ||
FTDI/FTDI-compatible cable users: the ``-d`` option lets you specify a specific FTDI device: | ||
|
||
.. code-block:: bash | ||
openFPGALoader -d /dev/ttyUSBX | ||
When the ``-d`` option is not provided, openFPGALoader will opens the first FTDI adapter it finds. | ||
Therefore it is preferable to use this flag if your computer is connected to multiple FTDI devices. | ||
|
||
Troubleshooting | ||
=============== | ||
|
||
Please refer to :ref:`troubleshooting`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,181 @@ | ||
.. _install: | ||
|
||
Installing openFPGALoader | ||
######################### | ||
|
||
Linux | ||
===== | ||
|
||
Arch Linux | ||
---------- | ||
|
||
openFPGALoader is available in the default repositories: | ||
|
||
.. code-block:: bash | ||
sudo pacman -S openfpgaloader | ||
Alternatively, you could build from source. First: install required libraries: | ||
|
||
.. code-block:: bash | ||
sudo pacman -S git cmake make gcc pkgconf libftdi libusb zlib hidapi gzip | ||
Build step is similar as Debian | ||
|
||
Fedora | ||
------ | ||
|
||
openFPGALoader is available as a Copr repository: | ||
|
||
.. code-block:: bash | ||
sudo dnf copr enable mobicarte/openFPGALoader | ||
sudo dnf install openFPGALoader | ||
From source (Debian, Ubuntu) | ||
---------------------------- | ||
|
||
This application uses ``libftdi1``, so this library must be installed (and, depending on the distribution, headers too): | ||
|
||
.. code-block:: bash | ||
sudo apt install \ | ||
git \ | ||
gzip \ | ||
libftdi1-2 \ | ||
libftdi1-dev \ | ||
libhidapi-hidraw0 \ | ||
libhidapi-dev \ | ||
libudev-dev \ | ||
zlib1g-dev \ | ||
cmake \ | ||
pkg-config \ | ||
make \ | ||
g++ | ||
.. HINT:: | ||
``libudev-dev`` is optional, may be replaced by ``eudev-dev`` or just not installed. | ||
|
||
By default, ``(e)udev`` support is enabled (used to open a device by his ``/dev/xx`` node). | ||
If you don't want this option, use: | ||
|
||
.. code-block:: bash | ||
-DENABLE_UDEV=OFF | ||
By default, ``cmsisdap`` support is enabled (used for colorlight I5, I9). | ||
If you don't want this option, use: | ||
|
||
.. code-block:: bash | ||
-DENABLE_CMSISDAP=OFF | ||
Alternatively you can manually specify the location of ``libusb`` and ``libftdi1``: | ||
|
||
.. code-block:: bash | ||
-DUSE_PKGCONFIG=OFF \ | ||
-DLIBUSB_LIBRARIES=<path_to_libusb> \ | ||
-DLIBFTDI_LIBRARIES=<path_to_libftdi> \ | ||
-DLIBFTDI_VERSION=<version> \ | ||
-DCMAKE_CXX_FLAGS="-I<libusb_include_dir> -I<libftdi1_include_dir>" | ||
You may also need to add this if you see link errors between ``libusb`` and ``pthread``: | ||
|
||
.. code-block:: bash | ||
-DLINK_CMAKE_THREADS=ON | ||
By default, ``libgpiod`` support is enabled | ||
If you don't want this option, use: | ||
|
||
.. code-block:: bash | ||
-DENABLE_LIBGPIOD=OFF | ||
Additionaly you have to install ``libgpiod`` | ||
|
||
To build the app: | ||
|
||
.. code-block:: bash | ||
git clone https://github.com/trabucayre/openFPGALoader | ||
cd openFPGALoader | ||
mkdir build | ||
cd build | ||
cmake .. # add -DBUILD_STATIC=ON to build a static version | ||
# add -DENABLE_UDEV=OFF to disable udev support and -d /dev/xxx | ||
# add -DENABLE_CMSISDAP=OFF to disable CMSIS DAP support | ||
cmake --build . | ||
# or | ||
make -j$(nproc) | ||
To install | ||
|
||
.. code-block:: bash | ||
$ sudo make install | ||
The default install path is ``/usr/local``, to change it, use ``-DCMAKE_INSTALL_PREFIX=myInstallDir`` in cmake invokation. | ||
|
||
Udev rules | ||
---------- | ||
|
||
By default, users have no access to converters. | ||
A rule file (:ghsrc:`99-openfpgaloader.rules <99-openfpgaloader.rules>`) for ``udev`` is provided at the root directory | ||
of this repository. | ||
These rules set access right and group (``plugdev``) when a converter is plugged. | ||
|
||
.. code-block:: bash | ||
sudo cp 99-openfpgaloader.rules /etc/udev/rules.d/ | ||
sudo udevadm control --reload-rules && sudo udevadm trigger # force udev to take new rule | ||
sudo usermod -a $USER -G plugdev # add user to plugdev group | ||
After that you need to unplug and replug your device. | ||
|
||
.. HINT:: | ||
``usermod`` is used to add ``$USER`` as a member of ``plugdev`` group. | ||
However this update is not taken into account immediately: it's required to | ||
logout from current session and login again. | ||
Check, by using ``id $USER``, if ``plugdev`` is mentioned after ``groups=``. | ||
An alternate (and temporary) solution is to use ``sudo - $USER`` to have | ||
your user seen as a member of ``plugdev`` group (works only for the current terminal). | ||
|
||
macOS | ||
===== | ||
|
||
openFPGALoader is available as a `Homebrew <https://brew.sh>`__ formula: | ||
|
||
.. code-block:: bash | ||
brew install openfpgaloader | ||
Alternatively, if you want to build it by hand: | ||
|
||
.. code-block:: bash | ||
brew install --only-dependencies openfpgaloader | ||
brew install cmake pkg-config zlib gzip | ||
git clone https://github.com/trabucayre/openFPGALoader | ||
cd openFPGALoader | ||
mkdir build | ||
cd build | ||
cmake .. | ||
make -j | ||
Windows | ||
======= | ||
|
||
Common | ||
====== | ||
|
||
Bitstreams for *XC2C (coolrunner-II)* needs to be remapped using ``.map`` shipped with *ISE*. | ||
*ISE* path is set at configure time using: | ||
|
||
.. code-block:: bash | ||
-DISE_PATH=/somewhere/Xilinx/ISE_VERS/ | ||
default: ``/opt/Xilinx/14.7``. |
Oops, something went wrong.