mirror of
https://github.com/trabucayre/openFPGALoader.git
synced 2026-09-02 19:48:19 +02:00
doc: convert guide from md to rst
This commit is contained in:
umarcor
@@ -0,0 +1,75 @@
|
||||
.. _advanced-usage:
|
||||
|
||||
Advanced usage of openFPGALoader
|
||||
################################
|
||||
|
||||
Resetting an FPGA
|
||||
=================
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
openFPGALoader [options] -r
|
||||
|
||||
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 mecanism ``--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.
|
||||
@@ -0,0 +1,65 @@
|
||||
.. _first-steps:
|
||||
|
||||
First steps with openFPGALoader
|
||||
###############################
|
||||
|
||||
Install
|
||||
=======
|
||||
|
||||
Packages are available for Linux distributionsm, 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`.
|
||||
@@ -0,0 +1,140 @@
|
||||
.. _install:
|
||||
|
||||
Installing openFPGALoader
|
||||
#########################
|
||||
|
||||
Linux
|
||||
=====
|
||||
|
||||
Arch Linux
|
||||
----------
|
||||
|
||||
openFPGALoader is available in the default repositories:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo pacman -S openfpgaloader
|
||||
|
||||
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
|
||||
|
||||
apt-get install
|
||||
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).
|
||||
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
|
||||
|
||||
|
||||
To build the app:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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.
|
||||
|
||||
macOS
|
||||
=====
|
||||
|
||||
openFPGALoader is available as a `Homebrew <https://brew.sh>`__ formula:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
brew install openfpgaloader
|
||||
|
||||
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``.
|
||||
@@ -0,0 +1,10 @@
|
||||
.. _troubleshooting:
|
||||
|
||||
Troubleshooting
|
||||
###############
|
||||
|
||||
I installed openFPGALoader but it says `command not found` when I try to launch it
|
||||
==================================================================================
|
||||
|
||||
The correct spelling of the program is *openFPGALoader* with FPGA and the "L" of "Loader" in uppercase.
|
||||
Ensure the spelling of the program is correct.
|
||||
Reference in New Issue
Block a user