occheung
/
artiq
forked from M-Labs/artiq
1
0
Fork 0
Code Pull Requests Activity

manual: split source install instructions to a separate page

This commit is contained in:
Sebastien Bourdeauducq 2016-06-22 10:00:52 +08:00
parent 43d0bddc9f
commit 1bee5bb460
3 changed files with 218 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/manual/index.rst
View File

@ -8,6 +8,7 @@ Contents:
introduction introduction
installing installing
installing_from_source
release_notes release_notes
getting_started_core getting_started_core
compiler compiler

230
doc/manual/installing.rst
View File

@ -1,26 +1,22 @@
.. _install-from-conda:
Installing ARTIQ Installing ARTIQ
================ ================
The preferred way of installing ARTIQ is through the use of the conda package manager. 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. 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:: .. warning::
NIST users on Linux need to pay close attention to their ``umask``. NIST users on Linux need to pay close attention to their ``umask``.
The sledgehammer called ``secureconfig`` leaves you (and root) with umask 027 and files created by root (for example through ``sudo make install``) inaccessible to you. The sledgehammer called ``secureconfig`` leaves you (and root) with umask 027 and files created by root (for example through ``sudo make install``) inaccessible to you.
The usual umask is 022. The usual umask is 022.
Installing using conda
----------------------
.. warning:: .. warning::
Conda packages are supported for Linux (64-bit) and Windows (32- and 64-bit). 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>`. Users of other operating systems (32-bit Linux, BSD, OSX ...) should and can :ref:`install from source <install-from-source>`.
Installing Anaconda or Miniconda 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 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 +27,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]_. Executing just ``conda`` should print the help of the ``conda`` command [1]_.
Installing the ARTIQ packages Installing the ARTIQ packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -----------------------------
Add the M-Labs ``main`` Anaconda package repository containing stable releases and release candidates to your conda configuration:: Add the M-Labs ``main`` Anaconda package repository containing stable releases and release candidates to your conda configuration::
@ -72,7 +68,7 @@ This activation has to be performed in every new shell you open to make the ARTI
The names of the libraries missing can be obtained from the output of a command like ``ldd [path-to-conda-installation]/envs/artiq-main/lib/qt5/plugins/platform/libqxcb.so``. The names of the libraries missing can be obtained from the output of a command like ``ldd [path-to-conda-installation]/envs/artiq-main/lib/qt5/plugins/platform/libqxcb.so``.
Upgrading ARTIQ 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. 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. Keep previous environments around until you are certain that they are not needed anymore and a new environment is known to work correctly.
@ -88,7 +84,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. See also the `conda documentation <http://conda.pydata.org/docs/using/envs.html>`_ for managing environments.
Preparing the core device FPGA board Preparing the core device FPGA board
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ------------------------------------
You now need to write three binary images onto the FPGA board: You now need to write three binary images onto the FPGA board:
@ -101,7 +97,7 @@ They are all shipped in the conda packages, along with the required flash proxy
.. _install-openocd: .. _install-openocd:
Installing 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:: 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::
@ -140,212 +136,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>`. 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 qc1 # or 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 Configuring the core device
--------------------------- ---------------------------
@ -355,12 +145,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>`: * 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_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 $ 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. * Boot the board.

207
doc/manual/installing_from_source.rst Normal file
View File

@ -0,0 +1,207 @@
.. _install-from-source:
Installing from source
======================
.. 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 qc1 # or 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