luke
/
openFPGALoader
mirror of https://github.com/trabucayre/openFPGALoader.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: convert guide from md to rst

This commit is contained in:
umarcor 2021-11-28 09:11:51 +01:00
parent 2cb92af70f
commit bfa1167892
9 changed files with 294 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
INSTALL.md
View File

@ -1,109 +0,0 @@
# Installing openFPGALoader
## Linux
### Arch Linux
openFPGALoader is available in the default repositories:
```
sudo pacman -S openfpgaloader
```
### Fedora
openFPGALoader is available as a Copr repository:
```
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 of the distribution, headers too)
```bash
apt-get install libftdi1-2 libftdi1-dev libhidapi-hidraw0 libhidapi-dev libudev-dev \
zlib1g-dev cmake pkg-config make g++
```
**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:
```bash
-DENABLE_UDEV=OFF
```
By default, **cmsisdap** support is enabled (used for colorlight I5).
If you don't want this option, use:
```bash
-DENABLE_CMSISDAP=OFF
```
Alternatively you can manually specify the location of **libusb** and **libftdi1**:
```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**:
```bash
-DLINK_CMAKE_THREADS=ON
```
To build the app:
```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
```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
(*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.
```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:
```
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
```
-DISE_PATH=/somewhere/Xilinx/ISE_VERS/
```
default: `/opt/Xilinx/14.7`

59
doc/advanced-usage.md
View File

@ -1,59 +0,0 @@
# Advanced usage of openFPGALoader
## Resetting an FPGA
```bash
openFPGALoader [options] -r
```
## Reading the bitstream from STDIN
```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:
```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:
```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.

47
doc/first-steps.md
View File

@ -1,47 +0,0 @@
# First steps with openFPGALoader
## Install
Packages are available for Linux distributions and macOS:
**Arch Linux**: `sudo pacman -S openfpgaloader`
**Fedora**: `sudo dnf copr enable mobicarte/openFPGALoader; sudo dnf install openFPGALoader`
**macOS**: `brew install openfpgaloader`
More instructions for other installation scenarios (including Windows) are available in [the installation manual](../INSTALL.md).
## Programming a development board
Just simply replace `my_fpga_board` with any FPGA board from the [board compatibility list](board-compatibility-list.md) (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):
```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 a "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 the [cable compatibility list](cable-compatibility-list.md) (or `openFPGALoader --list-cables`):
```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.
**FTDI/FTDI-compatible cable users:** The `-d` option lets you specify a specific FTDI device:
```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 [the troubleshooting documentation](troubleshooting.md).

75
doc/guide/advanced.rst Normal file
View File

@ -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.

65
doc/guide/first-steps.rst Normal file
View File

@ -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`.

140
doc/guide/install.rst Normal file
View File

@ -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``.

10
doc/guide/troubleshooting.rst Normal file
View File

@ -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.

8
doc/index.rst
View File

@ -7,10 +7,10 @@ Welcome to the documentation of openFPGALoader (a universal utility for programm
:caption: User Guide
:hidden:
first-steps
install
troubleshooting
advanced-usage
guide/first-steps
guide/install
guide/troubleshooting
guide/advanced
.. toctree::
:caption: Compatibility

5
doc/troubleshooting.md
View File

@ -1,5 +0,0 @@
# 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.