mirror of
https://github.com/m-labs/artiq.git
synced 2024-12-25 03:08:27 +08:00
manual: split source install instructions to a separate page
This commit is contained in:
parent
21574bdfa9
commit
48c0812df0
@ -8,6 +8,7 @@ Contents:
|
||||
|
||||
introduction
|
||||
installing
|
||||
installing_from_source
|
||||
release_notes
|
||||
getting_started_core
|
||||
compiler
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
.. _install-from-conda:
|
||||
|
||||
Installing ARTIQ
|
||||
================
|
||||
|
||||
The preferred way of installing ARTIQ is through the use of the conda package manager.
|
||||
The conda package contains pre-built binaries that you can directly flash to your board.
|
||||
But you can also :ref:`install from sources <install-from-sources>`.
|
||||
|
||||
.. warning::
|
||||
NIST users on Linux need to pay close attention to their ``umask``.
|
||||
@ -11,16 +12,13 @@ But you can also :ref:`install from sources <install-from-sources>`.
|
||||
The usual umask is 022.
|
||||
|
||||
|
||||
Installing using conda
|
||||
----------------------
|
||||
|
||||
.. warning::
|
||||
Conda packages are supported for Linux (64-bit) and Windows (32- and 64-bit).
|
||||
Users of other operating systems (32-bit Linux, BSD, OSX ...) should and can :ref:`install from source <install-from-sources>`.
|
||||
|
||||
|
||||
Installing Anaconda or Miniconda
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
--------------------------------
|
||||
|
||||
You can either install Anaconda (choose Python 3.5) from https://store.continuum.io/cshop/anaconda/ or install the more minimalistic Miniconda (choose Python 3.5) from http://conda.pydata.org/miniconda.html
|
||||
|
||||
@ -31,7 +29,7 @@ After installing either Anaconda or Miniconda, open a new terminal (also known a
|
||||
Executing just ``conda`` should print the help of the ``conda`` command [1]_.
|
||||
|
||||
Installing the ARTIQ packages
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
-----------------------------
|
||||
|
||||
Add the M-Labs ``main`` Anaconda package repository containing stable releases and release candidates to your conda configuration::
|
||||
|
||||
@ -76,7 +74,7 @@ This activation has to be performed in every new shell you open to make the ARTI
|
||||
|
||||
|
||||
Upgrading ARTIQ
|
||||
^^^^^^^^^^^^^^^
|
||||
---------------
|
||||
|
||||
When upgrading ARTIQ or when testing different versions it is recommended that new environments are created instead of upgrading the packages in existing environments.
|
||||
Keep previous environments around until you are certain that they are not needed anymore and a new environment is known to work correctly.
|
||||
@ -92,7 +90,7 @@ You can list the environments you have created using::
|
||||
See also the `conda documentation <http://conda.pydata.org/docs/using/envs.html>`_ for managing environments.
|
||||
|
||||
Preparing the core device FPGA board
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
------------------------------------
|
||||
|
||||
You now need to write three binary images onto the FPGA board:
|
||||
|
||||
@ -105,7 +103,7 @@ They are all shipped in the conda packages, along with the required flash proxy
|
||||
.. _install-openocd:
|
||||
|
||||
Installing OpenOCD
|
||||
..................
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
OpenOCD can be used to write the binary images into the core device FPGA board's flash memory. It can be installed using conda on both Linux and Windows::
|
||||
|
||||
@ -144,211 +142,6 @@ Then, you can flash the board:
|
||||
|
||||
For the KC705, the next step is to flash the MAC and IP addresses to the board. See :ref:`those instructions <flash-mac-ip-addr>`.
|
||||
|
||||
.. _install-from-sources:
|
||||
|
||||
Installing from source
|
||||
----------------------
|
||||
|
||||
Preparing the build environment for the core device
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These steps are required to generate code that can run on the core
|
||||
device. They are necessary both for building the MiSoC BIOS
|
||||
and the ARTIQ kernels.
|
||||
|
||||
* Create a development directory: ::
|
||||
|
||||
$ mkdir ~/artiq-dev
|
||||
|
||||
* Clone ARTIQ repository: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/artiq
|
||||
|
||||
* Install OpenRISC binutils (or1k-linux-...): ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ wget https://ftp.gnu.org/gnu/binutils/binutils-2.26.tar.bz2
|
||||
$ tar xvf binutils-2.26.tar.bz2
|
||||
$ rm binutils-2.26.tar.bz2
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ ../configure --target=or1k-linux --prefix=/usr/local
|
||||
$ make -j4
|
||||
$ sudo make install
|
||||
|
||||
.. note::
|
||||
We're using an ``or1k-linux`` target because it is necessary to enable
|
||||
shared library support in ``ld``, not because Linux is involved.
|
||||
|
||||
* Install LLVM and Clang: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone https://github.com/openrisc/llvm-or1k
|
||||
$ cd llvm-or1k/tools
|
||||
$ git clone https://github.com/openrisc/clang-or1k clang
|
||||
$ cd ..
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/llvm-or1k -DLLVM_TARGETS_TO_BUILD="OR1K;X86" -DLLVM_ENABLE_ASSERTIONS=ON
|
||||
$ make -j4
|
||||
$ sudo make install
|
||||
|
||||
.. note::
|
||||
Compilation of LLVM can take more than 30 min on some machines.
|
||||
|
||||
Preparing the core device FPGA board
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These steps are required to generate gateware bitstream (``.bit``) files, build the MiSoC BIOS and ARTIQ runtime, and flash FPGA boards. If the board is already flashed, you may skip those steps and go directly to `Installing the host-side software`.
|
||||
|
||||
* Install the FPGA vendor tools (i.e. Xilinx ISE and/or Vivado):
|
||||
|
||||
* Get Xilinx tools from http://www.xilinx.com/support/download/index.htm. ISE can build gateware bitstreams both for boards using the Spartan-6 (Pipistrello) and 7-series devices (KC705), while Vivado supports only boards using 7-series devices.
|
||||
|
||||
* The Pipistrello is supported by Webpack, the KC705 is not.
|
||||
|
||||
* During the Xilinx toolchain installation, uncheck ``Install cable drivers`` (they are not required as we use better and open source alternatives).
|
||||
|
||||
* Install Migen: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone https://github.com/m-labs/migen
|
||||
$ cd migen
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
.. note::
|
||||
The options ``develop`` and ``--user`` are for setup.py to install Migen in ``~/.local/lib/python3.5``.
|
||||
|
||||
.. _install-flash-proxy:
|
||||
|
||||
* Install the required flash proxy gateware bitstreams:
|
||||
|
||||
The purpose of the flash proxy gateware bitstream is to give programming software fast JTAG access to the flash connected to the FPGA.
|
||||
|
||||
* Pipistrello and KC705:
|
||||
|
||||
::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ wget https://raw.githubusercontent.com/jordens/bscan_spi_bitstreams/master/bscan_spi_xc7k325t.bit
|
||||
$ wget https://raw.githubusercontent.com/jordens/bscan_spi_bitstreams/master/bscan_spi_xc6slx45.bit
|
||||
|
||||
Then move both files ``~/artiq-dev/bscan_spi_xc6slx45.bit`` and ``~/artiq-dev/bscan_spi_xc7k325t.bit`` to ``~/.migen``, ``/usr/local/share/migen``, or ``/usr/share/migen``.
|
||||
|
||||
* :ref:`Download and install OpenOCD <install-openocd>`.
|
||||
|
||||
* Download and install MiSoC: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/misoc
|
||||
$ cd misoc
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
* Download and install ARTIQ: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/artiq
|
||||
$ cd artiq
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
.. note::
|
||||
If you have any trouble during ARTIQ setup about ``pygit2`` installation,
|
||||
refer to the section dealing with
|
||||
:ref:`installing the host-side software <installing-the-host-side-software>`.
|
||||
|
||||
|
||||
* Build the gateware bitstream, BIOS and runtime by running:
|
||||
::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ export PATH=/usr/local/llvm-or1k/bin:$PATH
|
||||
|
||||
.. note:: Make sure that ``/usr/local/llvm-or1k/bin`` is first in your ``PATH``, so that the ``clang`` command you just built is found instead of the system one, if any.
|
||||
|
||||
* For Pipistrello::
|
||||
|
||||
$ python3.5 -m artiq.gateware.targets.pipistrello
|
||||
|
||||
* For KC705::
|
||||
|
||||
$ python3.5 -m artiq.gateware.targets.kc705 -H nist_qc1 # or nist_qc2
|
||||
|
||||
.. note:: Add ``--toolchain vivado`` if you wish to use Vivado instead of ISE.
|
||||
|
||||
* Then, gather the binaries and flash them: ::
|
||||
|
||||
$ mkdir binaries
|
||||
$ cp misoc_nist_qcX_<board>/gateware/top.bit binaries
|
||||
$ cp misoc_nist_qcX_<board>/software/bios/bios.bin binaries
|
||||
$ cp misoc_nist_qcX_<board>/software/runtime/runtime.fbi binaries
|
||||
$ cd binaries
|
||||
$ artiq_flash -d . -t <board>
|
||||
|
||||
.. note:: The `-t` option specifies the board your are targeting. Available options are ``kc705`` and ``pipistrello``.
|
||||
|
||||
* Check that the board boots by running a serial terminal program (you may need to press its FPGA reconfiguration button or power-cycle it to load the gateware bitstream that was newly written into the flash): ::
|
||||
|
||||
$ flterm /dev/ttyUSB1
|
||||
MiSoC BIOS http://m-labs.hk
|
||||
[...]
|
||||
Booting from flash...
|
||||
Loading xxxxx bytes from flash...
|
||||
Executing booted program.
|
||||
ARTIQ runtime built <date/time>
|
||||
|
||||
.. note:: flterm is part of MiSoC. If you installed MiSoC with ``setup.py develop --user``, the flterm launcher is in ``~/.local/bin``.
|
||||
|
||||
The communication parameters are 115200 8-N-1. Ensure that your user has access
|
||||
to the serial device (``sudo adduser $USER dialout`` assuming standard setup).
|
||||
|
||||
.. _installing-the-host-side-software:
|
||||
|
||||
Installing the host-side software
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* Install the llvmlite Python bindings: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone https://github.com/m-labs/llvmlite
|
||||
$ cd llvmlite
|
||||
$ git checkout artiq
|
||||
$ LLVM_CONFIG=/usr/local/llvm-or1k/bin/llvm-config python3.5 setup.py install --user
|
||||
|
||||
* Install ARTIQ: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/artiq # if not already done
|
||||
$ cd artiq
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
.. note::
|
||||
If you have any trouble during ARTIQ setup about ``pygit2`` installation,
|
||||
you can install it by using ``pip``:
|
||||
|
||||
On Ubuntu 14.04::
|
||||
|
||||
$ python3.5 `which pip3` install --user pygit2==0.19.1
|
||||
|
||||
On Ubuntu 14.10::
|
||||
|
||||
$ python3.5 `which pip3` install --user pygit2==0.20.3
|
||||
|
||||
On Ubuntu 15.04 and 15.10::
|
||||
|
||||
$ python3.5 `which pip3` install --user pygit2==0.22.1
|
||||
|
||||
The rationale behind this is that pygit2 and libgit2 must have the same
|
||||
major.minor version numbers.
|
||||
|
||||
See http://www.pygit2.org/install.html#version-numbers
|
||||
|
||||
* Build the documentation: ::
|
||||
|
||||
$ cd ~/artiq-dev/artiq/doc/manual
|
||||
$ make html
|
||||
|
||||
Configuring the core device
|
||||
---------------------------
|
||||
@ -359,12 +152,12 @@ This should be done after either installation method (conda or source).
|
||||
|
||||
* Set the MAC and IP address in the :ref:`core device configuration flash storage <core-device-flash-storage>`:
|
||||
|
||||
* You can either set it by generating a flash storage image and then flash it: ::
|
||||
* You can set it through JTAG by generating a flash storage image and then flashing it: ::
|
||||
|
||||
$ artiq_mkfs flash_storage.img -s mac xx:xx:xx:xx:xx:xx -s ip xx.xx.xx.xx
|
||||
$ artiq_flash -f flash_storage.img proxy storage start
|
||||
|
||||
* Or you can set it via the runtime test mode command line
|
||||
* Or, if you have a serial connection ready, you can set it via the runtime test mode command line
|
||||
|
||||
* Boot the board.
|
||||
|
||||
|
||||
208
doc/manual/installing_from_source.rst
Normal file
208
doc/manual/installing_from_source.rst
Normal file
@ -0,0 +1,208 @@
|
||||
.. _install-from-sources:
|
||||
|
||||
|
||||
Installing ARTIQ from sources
|
||||
=============================
|
||||
|
||||
.. note::
|
||||
This method is only recommended for developers and advanced users. An easier way to install ARTIQ is via the Anaconda packages (see :ref:`Installing ARTIQ <install-from-conda>`).
|
||||
|
||||
|
||||
Preparing the build environment for the core device
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These steps are required to generate code that can run on the core
|
||||
device. They are necessary both for building the MiSoC BIOS
|
||||
and the ARTIQ kernels.
|
||||
|
||||
* Create a development directory: ::
|
||||
|
||||
$ mkdir ~/artiq-dev
|
||||
|
||||
* Clone ARTIQ repository: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/artiq
|
||||
|
||||
* Install OpenRISC binutils (or1k-linux-...): ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ wget https://ftp.gnu.org/gnu/binutils/binutils-2.26.tar.bz2
|
||||
$ tar xvf binutils-2.26.tar.bz2
|
||||
$ rm binutils-2.26.tar.bz2
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ ../configure --target=or1k-linux --prefix=/usr/local
|
||||
$ make -j4
|
||||
$ sudo make install
|
||||
|
||||
.. note::
|
||||
We're using an ``or1k-linux`` target because it is necessary to enable
|
||||
shared library support in ``ld``, not because Linux is involved.
|
||||
|
||||
* Install LLVM and Clang: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone https://github.com/openrisc/llvm-or1k
|
||||
$ cd llvm-or1k/tools
|
||||
$ git clone https://github.com/openrisc/clang-or1k clang
|
||||
$ cd ..
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/llvm-or1k -DLLVM_TARGETS_TO_BUILD="OR1K;X86" -DLLVM_ENABLE_ASSERTIONS=ON
|
||||
$ make -j4
|
||||
$ sudo make install
|
||||
|
||||
.. note::
|
||||
Compilation of LLVM can take more than 30 min on some machines.
|
||||
|
||||
Preparing the core device FPGA board
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These steps are required to generate gateware bitstream (``.bit``) files, build the MiSoC BIOS and ARTIQ runtime, and flash FPGA boards. If the board is already flashed, you may skip those steps and go directly to `Installing the host-side software`.
|
||||
|
||||
* Install the FPGA vendor tools (i.e. Xilinx ISE and/or Vivado):
|
||||
|
||||
* Get Xilinx tools from http://www.xilinx.com/support/download/index.htm. ISE can build gateware bitstreams both for boards using the Spartan-6 (Pipistrello) and 7-series devices (KC705), while Vivado supports only boards using 7-series devices.
|
||||
|
||||
* The Pipistrello is supported by Webpack, the KC705 is not.
|
||||
|
||||
* During the Xilinx toolchain installation, uncheck ``Install cable drivers`` (they are not required as we use better and open source alternatives).
|
||||
|
||||
* Install Migen: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone https://github.com/m-labs/migen
|
||||
$ cd migen
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
.. note::
|
||||
The options ``develop`` and ``--user`` are for setup.py to install Migen in ``~/.local/lib/python3.5``.
|
||||
|
||||
* Install the required flash proxy gateware bitstreams:
|
||||
|
||||
The purpose of the flash proxy gateware bitstream is to give programming software fast JTAG access to the flash connected to the FPGA.
|
||||
|
||||
* Pipistrello and KC705:
|
||||
|
||||
::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ wget https://raw.githubusercontent.com/jordens/bscan_spi_bitstreams/master/bscan_spi_xc7k325t.bit
|
||||
$ wget https://raw.githubusercontent.com/jordens/bscan_spi_bitstreams/master/bscan_spi_xc6slx45.bit
|
||||
|
||||
Then move both files ``~/artiq-dev/bscan_spi_xc6slx45.bit`` and ``~/artiq-dev/bscan_spi_xc7k325t.bit`` to ``~/.migen``, ``/usr/local/share/migen``, or ``/usr/share/migen``.
|
||||
|
||||
* :ref:`Download and install OpenOCD <install-openocd>`.
|
||||
|
||||
* Download and install MiSoC: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/misoc
|
||||
$ cd misoc
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
* Download and install ARTIQ: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/artiq
|
||||
$ cd artiq
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
.. note::
|
||||
If you have any trouble during ARTIQ setup about ``pygit2`` installation,
|
||||
refer to the section dealing with
|
||||
:ref:`installing the host-side software <installing-the-host-side-software>`.
|
||||
|
||||
|
||||
* Build the gateware bitstream, BIOS and runtime by running:
|
||||
::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ export PATH=/usr/local/llvm-or1k/bin:$PATH
|
||||
|
||||
.. note:: Make sure that ``/usr/local/llvm-or1k/bin`` is first in your ``PATH``, so that the ``clang`` command you just built is found instead of the system one, if any.
|
||||
|
||||
* For Pipistrello::
|
||||
|
||||
$ python3.5 -m artiq.gateware.targets.pipistrello
|
||||
|
||||
* For KC705::
|
||||
|
||||
$ python3.5 -m artiq.gateware.targets.kc705 -H nist_qc1 # or nist_qc2
|
||||
|
||||
.. note:: Add ``--toolchain vivado`` if you wish to use Vivado instead of ISE.
|
||||
|
||||
* Then, gather the binaries and flash them: ::
|
||||
|
||||
$ mkdir binaries
|
||||
$ cp misoc_nist_qcX_<board>/gateware/top.bit binaries
|
||||
$ cp misoc_nist_qcX_<board>/software/bios/bios.bin binaries
|
||||
$ cp misoc_nist_qcX_<board>/software/runtime/runtime.fbi binaries
|
||||
$ cd binaries
|
||||
$ artiq_flash -d . -t <board>
|
||||
|
||||
.. note:: The `-t` option specifies the board your are targeting. Available options are ``kc705`` and ``pipistrello``.
|
||||
|
||||
* Check that the board boots by running a serial terminal program (you may need to press its FPGA reconfiguration button or power-cycle it to load the gateware bitstream that was newly written into the flash): ::
|
||||
|
||||
$ flterm /dev/ttyUSB1
|
||||
MiSoC BIOS http://m-labs.hk
|
||||
[...]
|
||||
Booting from flash...
|
||||
Loading xxxxx bytes from flash...
|
||||
Executing booted program.
|
||||
ARTIQ runtime built <date/time>
|
||||
|
||||
.. note:: flterm is part of MiSoC. If you installed MiSoC with ``setup.py develop --user``, the flterm launcher is in ``~/.local/bin``.
|
||||
|
||||
The communication parameters are 115200 8-N-1. Ensure that your user has access
|
||||
to the serial device (``sudo adduser $USER dialout`` assuming standard setup).
|
||||
|
||||
.. _installing-the-host-side-software:
|
||||
|
||||
Installing the host-side software
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* Install the llvmlite Python bindings: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone https://github.com/m-labs/llvmlite
|
||||
$ cd llvmlite
|
||||
$ git checkout artiq
|
||||
$ LLVM_CONFIG=/usr/local/llvm-or1k/bin/llvm-config python3.5 setup.py install --user
|
||||
|
||||
* Install ARTIQ: ::
|
||||
|
||||
$ cd ~/artiq-dev
|
||||
$ git clone --recursive https://github.com/m-labs/artiq # if not already done
|
||||
$ cd artiq
|
||||
$ python3.5 setup.py develop --user
|
||||
|
||||
.. note::
|
||||
If you have any trouble during ARTIQ setup about ``pygit2`` installation,
|
||||
you can install it by using ``pip``:
|
||||
|
||||
On Ubuntu 14.04::
|
||||
|
||||
$ python3.5 `which pip3` install --user pygit2==0.19.1
|
||||
|
||||
On Ubuntu 14.10::
|
||||
|
||||
$ python3.5 `which pip3` install --user pygit2==0.20.3
|
||||
|
||||
On Ubuntu 15.04 and 15.10::
|
||||
|
||||
$ python3.5 `which pip3` install --user pygit2==0.22.1
|
||||
|
||||
The rationale behind this is that pygit2 and libgit2 must have the same
|
||||
major.minor version numbers.
|
||||
|
||||
See http://www.pygit2.org/install.html#version-numbers
|
||||
|
||||
* Build the documentation: ::
|
||||
|
||||
$ cd ~/artiq-dev/artiq/doc/manual
|
||||
$ make html
|
||||
Loading…
Reference in New Issue
Block a user