artiq/doc/manual/installing.rst

441 lines
16 KiB
ReStructuredText
Raw Normal View History

2014-09-28 23:25:32 +08:00
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>`.
Installing using conda
----------------------
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
.. warning::
If you are installing on Windows, choose the Windows 32-bit version regardless of whether you have
a 32-bit or 64-bit Windows.
After installing either Anaconda or Miniconda, open a new terminal and make sure the following command works::
$ conda
If it prints the help of the ``conda`` command, your install is OK.
If not, then make sure your ``$PATH`` environment variable contains the path to anaconda3/bin (or miniconda3/bin)::
$ echo $PATH
2015-10-30 09:18:42 +08:00
/home/.../miniconda3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
If your ``$PATH`` misses reference the miniconda3/bin or anaconda3/bin you can fix this by typing::
$ export PATH=$HOME/miniconda3:$PATH
Installing the host side software
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2015-10-30 09:18:42 +08:00
For this, you need to add our Anaconda repository to your conda configuration::
$ conda config --add channels http://conda.anaconda.org/m-labs/channel/main
2015-08-13 14:47:05 +08:00
$ conda config --add channels http://conda.anaconda.org/m-labs/channel/dev
2015-10-30 09:18:42 +08:00
Then you can install the ARTIQ package, it will pull all the necessary dependencies.
2015-10-30 09:18:42 +08:00
* For the Pipistrello board::
$ ENV=$(date +artiq-%Y-%m-%d); conda create -n $ENV artiq-pipistrello-nist_qc1; \
echo "Created environment $ENV for ARTIQ"
* For the KC705 board with SCSI cables and AD9858 DDS chips::
2015-10-30 09:18:42 +08:00
$ ENV=$(date +artiq-%Y-%m-%d); conda create -n $ENV artiq-kc705-nist_qc1; \
echo "Created environment $ENV for ARTIQ"
* For the KC705 board with the FMC backplane and AD9914 DDS chips::
$ ENV=$(date +artiq-%Y-%m-%d); conda create -n $ENV artiq-kc705-nist_qc2; \
2015-10-30 09:18:42 +08:00
echo "Created environment $ENV for ARTIQ"
This creates a new Conda "environment" (i.e. an isolated installation) and prints its name.
If you ever need to upgrade ARTIQ, it is advised to install it again
in a new environment so that you can roll back to a version that is known to
work correctly.
After this, add the newly created environment to your ``$PATH``. This can be easily
done using the following command::
$ source activate artiq-[date]
You will need to invoke this command in every new shell. When in doubt, you can list
the existing environments using::
$ conda env list
2014-09-28 23:25:32 +08:00
Preparing the core device FPGA board
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You now need to flash 3 things on the FPGA board:
1. The FPGA bitstream
2. The BIOS
3. The ARTIQ runtime
First you need to :ref:`install xc3sprog <install-xc3sprog>`. Then, you can flash the board:
* For the Pipistrello board::
$ artiq_flash.sh -t pipistrello
* For the KC705 board::
$ artiq_flash.sh
Next step (for KC705) is to flash MAC and IP addresses to the board:
* See :ref:`those instructions <flash-mac-ip-addr>` to flash MAC and IP addresses.
.. _install-from-sources:
Installing from source
----------------------
Preparing the build environment for the core device
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2014-09-30 18:10:40 +08:00
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.
2014-11-17 12:42:37 +08:00
* Create a development directory: ::
$ mkdir ~/artiq-dev
2015-08-10 04:33:00 +08:00
* Clone ARTIQ repository: ::
$ cd ~/artiq-dev
$ git clone --recursive https://github.com/m-labs/artiq
2015-07-26 14:28:11 +08:00
* Install OpenRISC binutils (or1k-linux-...): ::
$ cd ~/artiq-dev
2015-07-26 14:28:11 +08:00
$ wget https://ftp.gnu.org/gnu/binutils/binutils-2.25.1.tar.bz2
$ tar xvf binutils-2.25.1.tar.bz2
$ rm binutils-2.25.1.tar.bz2
2015-08-10 04:33:00 +08:00
$ cd binutils-2.25.1
$ patch -p1 <~/artiq-dev/misc/binutils-2.25.1-or1k-R_PCREL-pcrel_offset.patch
$ mkdir build
$ cd build
2015-07-26 14:28:11 +08:00
$ ../configure --target=or1k-linux --prefix=/usr/local
$ make -j4
$ sudo make install
2015-07-26 14:28:11 +08:00
.. 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: ::
2014-11-27 22:27:18 +08:00
$ cd ~/artiq-dev
2015-07-26 14:28:11 +08:00
$ git clone https://github.com/openrisc/llvm-or1k
$ cd llvm-or1k/tools
$ git clone https://github.com/openrisc/clang-or1k clang
$ cd ..
2015-06-19 14:10:33 +08:00
$ mkdir build
$ cd build
2015-07-26 14:28:11 +08:00
$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local/llvm-or1k -DLLVM_TARGETS_TO_BUILD="OR1K;X86" -DCMAKE_BUILD_TYPE=Rel -DLLVM_ENABLE_ASSERTIONS=ON
$ make -j4
$ sudo make install
2014-09-28 23:25:32 +08:00
2015-07-26 14:28:11 +08:00
.. 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 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 (e.g. Xilinx ISE and/or Vivado):
* Get Xilinx tools from http://www.xilinx.com/support/download/index.htm. ISE can build 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-xc3sprog:
* Install JTAG tools needed to program the Pipistrello and KC705:
::
$ cd ~/artiq-dev
2015-07-28 00:38:20 +08:00
$ svn co http://svn.code.sf.net/p/xc3sprog/code/trunk xc3sprog
2015-06-19 14:10:33 +08:00
$ cd xc3sprog
$ cmake . && make
$ sudo make install
.. note::
It is safe to ignore the message "Could NOT find LIBFTD2XX" (libftd2xx is different from libftdi, and is not required).
.. _install-flash-proxy:
* Install the required flash proxy bitstreams:
The purpose of the flash proxy bitstream is to give programming software fast JTAG access to the flash connected to the FPGA.
* Pipistrello:
::
2014-11-07 08:30:40 +08:00
$ cd ~/artiq-dev
$ wget https://people.phys.ethz.ch/~robertjo/bscan_spi_lx45_csg324.bit
Then copy ``~/artiq-dev/bscan_spi_lx45_csg324.bit`` to ``~/.migen``, ``/usr/local/share/migen`` or ``/usr/share/migen``.
* KC705:
::
2014-11-07 08:30:40 +08:00
$ cd ~/artiq-dev
$ git clone https://github.com/m-labs/bscan_spi_kc705
2015-06-19 14:10:33 +08:00
$ cd bscan_spi_kc705
$ make
2015-06-19 14:10:33 +08:00
Then copy the generated ``bscan_spi_kc705.bit`` to ``~/.migen``, ``/usr/local/share/migen`` or ``/usr/share/migen``.
2014-09-28 23:25:32 +08:00
2015-11-04 23:38:24 +08:00
* Download and install MiSoC: ::
2014-09-28 23:25:32 +08:00
$ cd ~/artiq-dev
$ git clone --recursive https://github.com/m-labs/misoc
2015-11-04 23:38:24 +08:00
$ cd misoc
$ python3.5 setup.py develop --user
2014-09-28 23:25:32 +08:00
2015-03-21 21:14:40 +08:00
* Download and install ARTIQ: ::
$ cd ~/artiq-dev
$ git clone --recursive https://github.com/m-labs/artiq
2015-11-04 23:38:24 +08:00
$ cd artiq
$ python3.5 setup.py develop --user
2015-03-21 21:14:40 +08:00
.. 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>`.
2015-11-04 23:38:24 +08:00
* Build the bitstream, BIOS and runtime by running:
2015-06-15 04:05:06 +08:00
::
2015-11-04 23:38:24 +08:00
$ 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.
2015-06-15 04:05:06 +08:00
* For Pipistrello::
$ python3.5 -m artiq.gateware.targets.pipistrello
2015-06-15 04:05:06 +08:00
* For KC705::
$ python3.5 -m artiq.gateware.targets.kc705 -H qc1 # or qc2
2015-11-04 23:38:24 +08:00
* Then, gather the binaries and flash them: ::
2015-11-04 23:38:24 +08:00
$ 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.sh -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 bitstream that was newly written into the flash): ::
2015-01-21 10:31:50 +08:00
$ make -C ~/artiq-dev/misoc/tools # do only once
2014-11-07 08:30:40 +08:00
$ ~/artiq-dev/misoc/tools/flterm --port /dev/ttyUSB1
MiSoC BIOS http://m-labs.hk
[...]
Booting from flash...
Loading xxxxx bytes from flash...
Executing booted program.
ARTIQ runtime built <date/time>
2014-09-28 23:25:32 +08:00
The communication parameters are 115200 8-N-1.
.. _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
---------------------------
This should be done after either installation method (conda or source).
.. _flash-mac-ip-addr:
* 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: ::
$ artiq_mkfs flash_storage.img -s mac xx:xx:xx:xx:xx:xx -s ip xx.xx.xx.xx
$ ~/artiq-dev/artiq/frontend/artiq_flash.sh -f flash_storage.img
* Or you can set it via the runtime test mode command line
* Boot the board.
* Quickly run flterm (in ``path/to/misoc/tools``) to access the serial console.
* If you weren't quick enough to see anything in the serial console, press the reset button.
* Wait for "Press 't' to enter test mode..." to appear and hit the ``t`` key.
* Enter the following commands (which will erase the flash storage content).
::
test> fserase
test> fswrite ip xx.xx.xx.xx
test> fswrite mac xx:xx:xx:xx:xx:xx
* Then reboot.
You should see something like this in the serial console: ::
2015-08-10 15:16:52 +08:00
$ ./tools/flterm --port /dev/ttyUSB1
[FLTERM] Starting...
MiSoC BIOS http://m-labs.hk
(c) Copyright 2007-2014 Sebastien Bourdeauducq
[...]
Press 't' to enter test mode...
Entering test mode.
test> fserase
test> fswrite ip 192.168.10.2
test> fswrite mac 11:22:33:44:55:66
.. note:: The reset button of the KC705 board is the "CPU_RST" labeled button.
.. warning:: Both those instructions will result in the flash storage being wiped out. However you can use the test mode to change the IP/MAC without erasing everything if you skip the "fserase" command.
* (optional) Flash the idle kernel
The idle kernel is the kernel (some piece of code running on the core device) which the core device runs whenever it is not connected to a PC via ethernet.
This kernel is therefore stored in the :ref:`core device configuration flash storage <core-device-flash-storage>`.
To flash the idle kernel:
* Compile the idle experiment:
The idle experiment's ``run()`` method must be a kernel: it must be decorated with the ``@kernel`` decorator (see :ref:`next topic <connecting-to-the-core-device>` for more information about kernels).
Since the core device is not connected to the PC, RPCs (calling Python code running on the PC from the kernel) are forbidden in the idle experiment.
::
$ artiq_compile idle.py
* Write it into the core device configuration flash storage: ::
$ artiq_coretool cfg-write -f idle_kernel idle.elf
.. note:: You can find more information about how to use the ``artiq_coretool`` utility on the :ref:`Utilities <core-device-access-tool>` page.
* (optional) Flash the startup kernel
The startup kernel is executed once when the core device powers up. It should initialize DDSes, set up TTL directions, etc. Proceed as with the idle kernel, but using the ``startup_kernel`` key in ``artiq_coretool``.
* (optional) Select the startup clock
The core device may use either an external clock signal or its internal clock. This clock can be switched dynamically after the PC is connected using the ``external_clock`` parameter of the core device driver; however, one may want to select the clock at power-up so that it is used for the startup and idle kernels. Use one of these commands: ::
$ artiq_coretool cfg-write -s startup_clock i # internal clock (default)
$ artiq_coretool cfg-write -s startup_clock e # external clock
Ubuntu 15.10+/Debian jessie+ specific instructions
--------------------------------------------------
2014-09-28 23:25:32 +08:00
This command installs all the required packages: ::
2014-09-28 23:25:32 +08:00
$ sudo apt-get install build-essential autotools-dev file git patch perl xutils-dev texinfo flex bison libmpc-dev subversion cmake libusb-dev libftdi-dev pkg-config libffi-dev libgit2-dev python3.5 python3.5-dev
To set user permissions on the JTAG and serial ports of the Pipistrello, create a ``/etc/udev/rules.d/30-usb-papilio.rules`` file containing the following: ::
2014-11-17 12:45:47 +08:00
SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", GROUP="dialout"
2014-11-17 12:45:47 +08:00
Then reload ``udev``, add your user to the ``dialout`` group, and log out and log in again: ::
$ sudo invoke-rc.d udev reload
2014-11-17 12:45:47 +08:00
$ sudo adduser <your username> dialout
$ logout
Fedora 22 specific instructions
-------------------------------
- Make xc3sprog compile:
Fedora packages the libftdi1 as libftdi, so the autodetection of the library fails. To make it work, you have to explicitly point cmake to the right folder and library: ::
$ cmake -DLIBFTDI_INCLUDE_DIR=/usr/include/libftdi1 -DLIBFTDI_LIBRARIES=/usr/lib64/libftdi1.so . && make
- Get permission to access the Pipistrello Board:
To be able to access the JTAG and serial ports of the Pipistrello, you have to be in the group plugdev. Do that by running the following command and log out and log in again afterwards. ::
$ sudo adduser <your username> plugdev