update 308e47c

.buildinfo

@@ -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: 5ee66292091ff32fcf1050388dd8a28f
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/compatibility/board.rst.txt

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

_sources/compatibility/cable.rst.txt

@@ -0,0 +1,6 @@
+.. _compatibility:cables:
+
+Cables
+######
+
+.. include:: cable.inc

_sources/compatibility/fpga.rst.txt

@@ -0,0 +1,11 @@
+.. _compatibility:fpgas:
+
+FPGAs
+#####
+
+.. include:: fpga.inc
+
+* IF: Internal Flash
+* AS: Active Serial flash mode
+* NA: Not Available
+* NT: Not Tested

_sources/guide/advanced.rst.txt

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

_sources/guide/first-steps.rst.txt

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

_sources/guide/install.rst.txt

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