Installing ARTIQ ================ 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). * Create a development directory: :: $ mkdir ~/artiq-dev * Install Migen: :: $ cd ~/artiq-dev $ git clone https://github.com/m-labs/migen $ cd ~/artiq-dev/migen $ python3 setup.py develop --user .. note:: The options ``develop`` and ``--user`` are for setup.py to install Migen in ``~/.local/lib/python3.4``. * Install OpenRISC GCC/binutils toolchain (or1k-elf-...): :: $ mkdir ~/artiq-dev $ cd ~/artiq-dev $ git clone https://github.com/openrisc/or1k-src $ mkdir ~/artiq-dev/or1k-src/build $ cd ~/artiq-dev/or1k-src/build $ ../configure --target=or1k-elf --enable-shared --disable-itcl \ --disable-tk --disable-tcl --disable-winsup \ --disable-gdbtk --disable-libgui --disable-rda \ --disable-sid --disable-sim --disable-gdb \ --disable-newlib --disable-libgloss --disable-werror $ make -j4 $ sudo make install $ cd ~/artiq-dev $ git clone https://github.com/openrisc/or1k-gcc $ mkdir ~/artiq-dev/or1k-gcc/build $ cd ~/artiq-dev/or1k-gcc/build $ ../configure --target=or1k-elf --enable-languages=c \ --disable-shared --disable-libssp $ make -j4 $ sudo make install * Install JTAG tools needed to program the Pipistrello and KC705: :: $ cd ~/artiq-dev $ svn co https://xc3sprog.svn.sourceforge.net/svnroot/xc3sprog/trunk xc3sprog $ cd ~/artiq-dev/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 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: :: $ cd ~/artiq-dev $ wget http://www.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: :: $ cd ~/artiq-dev $ git clone https://github.com/m-labs/bscan_spi_kc705 Build the bitstream and copy it to one of the folders above. * Download MiSoC: :: $ cd ~/artiq-dev $ git clone --recursive https://github.com/m-labs/misoc $ export MSCDIR=~/artiq-dev/misoc # append this line to .bashrc * Download and install ARTIQ: :: $ cd ~/artiq-dev $ git clone https://github.com/m-labs/artiq $ python3 setup.py develop --user * Build and flash the bitstream and BIOS by running `from the MiSoC top-level directory`: :: $ cd ~/artiq-dev/misoc $ ./make.py -X ~/artiq-dev/artiq/soc -t artiq_ppro all * Then, build and flash the ARTIQ runtime: :: $ cd ~/artiq-dev/artiq/soc/runtime && make runtime.fbi $ ~/artiq-dev/artiq/artiq/frontend/artiq_flash.sh -t pipistrello -d $PWD -r .. 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): :: $ make -C ~/artiq-dev/misoc/tools # do only once $ ~/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 The communication parameters are 115200 8-N-1. * Set the MAC and IP address in the :ref:`core device configuration flash storage `: * You can either set it by generating a flash storage image and then flash it: :: $ ~/artiq-dev/artiq/frontend/artiq_mkfs.py 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: :: ~/dev/misoc$ ./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. Installing the host-side software --------------------------------- * Install LLVM and the llvmlite Python bindings: :: $ cd ~/artiq-dev $ git clone https://github.com/openrisc/llvm-or1k $ cd ~/artiq-dev/llvm-or1k/tools $ git clone https://github.com/openrisc/clang-or1k clang $ cd ~/artiq-dev/llvm-or1k $ mkdir build $ cd ~/artiq-dev/llvm-or1k/build $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local/llvm-or1k -DLLVM_TARGETS_TO_BUILD=OR1K -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON $ make -j4 $ sudo make install $ cd ~/artiq-dev $ git clone https://github.com/numba/llvmlite $ cd ~/artiq-dev/llvmlite $ patch -p1 < ~/artiq-dev/artiq/misc/llvmlite-add-all-targets.patch $ PATH=/usr/local/llvm-or1k/bin:$PATH sudo -E python3 setup.py install .. note:: llvmlite is in development and its API is not stable yet. Commit ID ``11a8303d02e3d6dd2d1e0e9065701795cd8a979f`` is known to work. .. note:: Compilation of LLVM can take more than 30 min on some machines. * Install ARTIQ (without the GUI): :: $ cd ~/artiq-dev $ git clone https://github.com/m-labs/artiq # if not already done $ cd artiq $ python3 setup.py develop --user * Install ARTIQ (with the GUI): :: $ cd ~/artiq-dev $ git clone https://github.com/m-labs/cairoplot3 $ cd cairoplot3 $ python3 setup.py install --user $ cd - $ git clone https://github.com/m-labs/gbulb $ cd gbulb $ python3 setup.py install --user $ cd - $ git clone https://github.com/m-labs/artiq # if not already done $ cd artiq $ ARTIQ_GUI=1 python3 setup.py develop --user .. note:: Use ARTIQ_GUI=1 to install GUI dependencies which are only supported on Linux for now, to install ARTIQ on Windows do not set ARTIQ_GUI. * Build the documentation: :: $ cd ~/artiq-dev/artiq/doc/manual $ make html Ubuntu 14.04 specific instructions ---------------------------------- This command installs all the required packages: :: $ sudo apt-get install build-essential autotools-dev file git patch perl xutils-devs python3-pip texinfo flex bison libmpc-dev python3-serial python3-dateutil python3-prettytable python3-setuptools python3-numpy python3-scipy python3-sphinx python3-h5py python3-gi python3-dev python-dev subversion cmake libusb-dev libftdi-dev pkg-config Note that ARTIQ requires Python 3.4 or above. 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: :: SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", GROUP="dialout" Then reload ``udev``, add your user to the ``dialout`` group, and log out and log in again: :: $ sudo invoke-rc.d udev reload $ sudo adduser dialout $ logout