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

doc/manual: more precisions (thanks Joe)

This commit is contained in:
Sebastien Bourdeauducq 2014-11-05 18:53:39 +08:00
parent b163c9f7ea
commit 901255ee60
2 changed files with 141 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/manual/getting_started.rst
View File

@ -27,13 +27,10 @@ The central part of our code is our ``LED`` class, that derives from :class:`art
Run this example with: :: Run this example with: ::
python led.py python3 led.py
The LED of the device should turn on. Congratulations! You have a basic ARTIQ system up and running. The LED of the device should turn on. Congratulations! You have a basic ARTIQ system up and running.
.. note::
ARTIQ requires Python 3, and you may need to use the ``python3`` command instead of ``python`` on some distributions.
Host/core device interaction Host/core device interaction
---------------------------- ----------------------------
@ -53,9 +50,9 @@ Modify the code as follows: ::
You can then turn the LED off and on by entering 0 or 1 at the prompt that appears: :: You can then turn the LED off and on by entering 0 or 1 at the prompt that appears: ::
$ python led.py $ python3 led.py
Enter desired LED state: 1 Enter desired LED state: 1
$ python led.py $ python3 led.py
Enter desired LED state: 0 Enter desired LED state: 0
What happens is the ARTIQ compiler notices that the ``input_led_state`` function does not have a ``@kernel`` decorator and thus must be executed on the host. When the core device calls it, it sends a request to the host to execute it. The host displays the prompt, collects user input, and sends the result back to the core device, which sets the LED state accordingly. What happens is the ARTIQ compiler notices that the ``input_led_state`` function does not have a ``@kernel`` decorator and thus must be executed on the host. When the core device calls it, it sends a request to the host to execute it. The host displays the prompt, collects user input, and sends the result back to the core device, which sets the LED state accordingly.
@ -100,7 +97,7 @@ Create a new file ``rtio.py`` containing the following: ::
exp = Tutorial(core=core_driver, o=out_driver) exp = Tutorial(core=core_driver, o=out_driver)
exp.run() exp.run()
Connect an oscilloscope or logic analyzer to the RTIO channel 1 (pin C11 on the Papilio Pro) and run ``python rtio.py``. Notice that the generated signal's period is precisely 4 microseconds, and that it has a duty cycle of precisely 50%. This is not what you would expect if the delay and the pulse were implemented with CPU-controlled GPIO: overhead from the loop management, function calls, etc. would increase the signal's period, and asymmetry in the overhead would cause duty cycle distortion. Connect an oscilloscope or logic analyzer to the RTIO channel 1 (pin C11 on the Papilio Pro) and run ``python3 rtio.py``. Notice that the generated signal's period is precisely 4 microseconds, and that it has a duty cycle of precisely 50%. This is not what you would expect if the delay and the pulse were implemented with CPU-controlled GPIO: overhead from the loop management, function calls, etc. would increase the signal's period, and asymmetry in the overhead would cause duty cycle distortion.
Instead, inside the core device, output timing is generated by the gateware and the CPU only programs switching commands with certain timestamps that the CPU computes. This guarantees precise timing as long as the CPU can keep generating timestamps that are increasing fast enough. In case it fails to do that (and attempts to program an event with a timestamp in the past), the :class:`artiq.devices.runtime_exceptions.RTIOUnderflow` exception is raised. The kernel causing it may catch it (using a regular ``try... except...`` construct), or it will be propagated to the host. Instead, inside the core device, output timing is generated by the gateware and the CPU only programs switching commands with certain timestamps that the CPU computes. This guarantees precise timing as long as the CPU can keep generating timestamps that are increasing fast enough. In case it fails to do that (and attempts to program an event with a timestamp in the past), the :class:`artiq.devices.runtime_exceptions.RTIOUnderflow` exception is raised. The kernel causing it may catch it (using a regular ``try... except...`` construct), or it will be propagated to the host.

155
doc/manual/installing.rst
View File

@ -4,55 +4,108 @@ Installing ARTIQ
Preparing the core device FPGA board Preparing the core device FPGA board
------------------------------------ ------------------------------------
You may skip those steps if the board is already flashed. 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`.
You will need: * Install the FPGA vendor tools (e.g. Xilinx ISE and/or Vivado):
* FPGA vendor tools (e.g. Xilinx ISE 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 (Papilio Pro) and 7-series devices (KC705), while Vivado supports only boards using 7-series devices.
* Get them from http://www.xilinx.com/support/download/index.htm * Create a development directory: ::
* Python 3.4+ $ mkdir ~/artiq-dev
* OpenRISC GCC/binutils toolchain (or1k-elf-...) * Install Migen: ::
* Compile and install binutils. Fetch the source from https://github.com/openrisc/or1k-src :: $ cd ~/artiq-dev
$ git clone https://github.com/m-labs/migen
$ mkdir build && cd build $ cd ~/artiq-dev/migen
$ ../configure --target=or1k-elf --enable-shared --disable-itcl \ $ python3 setup.py develop --user
--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 && sudo make install
* Compile and install GCC. Fetch the source from https://github.com/openrisc/or1k-gcc ::
$ mkdir build && cd build
$ ../configure --target=or1k-elf --enable-languages=c --disable-shared --disable-libssp
$ make && sudo make install
* Migen and MiSoC (http://m-labs.hk/gateware.html)
* Fetch them from https://github.com/m-labs/migen and https://github.com/m-labs/misoc
* Install Migen::
$ cd migen && sudo python setup.py install
* Install MiSoC dependencies by following steps 2., 3. and 6. (respectively JTAG tools, flash proxy bitstream and compiler-rt) from the MiSoC README.
.. note:: .. note::
``python`` refers to Python 3. You may need to use the ``python3`` command instead of ``python`` on some distributions. The options ``develop`` and ``--user`` are for setup.py to install Migen in ``~/.local/lib/python3.4``.
After these components are installed, build and flash the bitstream and BIOS by running `from the MiSoC top-level directory`: :: * Install OpenRISC GCC/binutils toolchain (or1k-elf-...): ::
$ ./make.py -X /path_to/ARTIQ/soc -t artiq all $ mkdir ~/artiq-dev/openrisc
$ cd ~/artiq-dev/openrisc
$ git clone https://github.com/openrisc/or1k-src
$ mkdir ~/artiq-dev/openrisc/or1k-src/build
$ cd ~/artiq-dev/openrisc/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
Then, build and flash the ARTIQ runtime: :: $ git clone https://github.com/openrisc/or1k-gcc
$ mkdir ~/artiq-dev/openrisc/or1k-gcc/build
$ cd ~/artiq-dev/openrisc/or1k-gcc/build
$ ../configure --target=or1k-elf --enable-languages=c \
--disable-shared --disable-libssp
$ make -j4
$ sudo make install
$ cd /path_to/ARTIQ/soc/runtime * Install JTAG tools needed to program Papilio Pro and KC705:
::
$ cd ~/artiq-dev
$ svn co https://xc3sprog.svn.sourceforge.net/svnroot/xc3sprog/trunk xc3sprog
$ 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 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.
* Papilio Pro:
::
$ mkdir ~/artiq-dev/bitstreams/papiliopro
$ cd ~/artiq-dev/bitstreams/papiliopro
$ git clone https://github.com/GadgetFactory/Papilio-Loader
Then copy ``bscan_spi_lx9_papilio.bit`` to ``~/.migen``, ``/usr/local/share/migen`` or ``/usr/share/migen``.
* KC705:
::
$ mkdir ~/artiq-dev/bitstreams/kc705
$ cd ~/artiq-dev/bitstreams/kc705
$ git clone https://github.com/m-labs/bscan_spi_kc705
Build the bitstream and copy it to one of the folders above.
* Download compiler-rt: ::
$ cd ~/artiq-dev
$ svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt
$ export CRTDIR=/home/rabi/artiq-dev/compiler-rt
* Download MiSoC: ::
$ cd ~/artiq-dev
$ git clone --recursive https://github.com/m-labs/misoc
* Build and flash the bitstream and BIOS by running `from the MiSoC top-level directory` ::
$ cd ~/misoc
$ ./make.py -X ~/artiq/soc -t artiq all
* Then, build and flash the ARTIQ runtime: ::
$ cd ~/artiq/soc/runtime
$ make flash $ make flash
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): :: 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): ::
$ flterm --port /dev/ttyUSB1 $ flterm --port /dev/ttyUSB1
MiSoC BIOS http://m-labs.hk MiSoC BIOS http://m-labs.hk
@ -67,18 +120,21 @@ The communication parameters are 115200 8-N-1.
Installing the host-side software Installing the host-side software
--------------------------------- ---------------------------------
The main dependency of ARTIQ is LLVM and its Python bindings (http://llvmpy.org). Currently, this installation is tedious because of the OpenRISC support not being merged upstream LLVM and because of incompatibilities between the versions of LLVM that support OpenRISC and the versions of LLVM that support the Python bindings. :: * Install LLVM and its Python bindings:
The main dependency of ARTIQ is LLVM and its Python bindings (http://llvmpy.org). Currently, this installation is tedious because of the OpenRISC support not being merged upstream LLVM and because of incompatibilities between the versions of LLVM that support OpenRISC and the versions of LLVM that support the Python bindings. ::
$ cd ~/artiq-dev/openrisc
$ git clone https://github.com/openrisc/llvm-or1k $ git clone https://github.com/openrisc/llvm-or1k
$ cd llvm-or1k $ cd llvm-or1k
$ git checkout b3a48efb2c05ed6cedc5395ae726c6a6573ef3ba $ git checkout b3a48efb2c05ed6cedc5395ae726c6a6573ef3ba
$ cat /path_to/artiq/patches/llvm/* | patch -p1 $ cat ~/artiq-dev/artiq/patches/llvm/* | patch -p1
$ cd tools $ cd tools
$ git clone https://github.com/openrisc/clang-or1k clang $ git clone https://github.com/openrisc/clang-or1k clang
$ cd clang $ cd clang
$ git checkout 02d831c7e7dc1517abed9cc96abdfb937af954eb $ git checkout 02d831c7e7dc1517abed9cc96abdfb937af954eb
$ cat /path_to/artiq/patches/clang/* | patch -p1 $ cat ~/artiq-dev/artiq/patches/clang/* | patch -p1
$ cd ../.. $ cd ../..
$ mkdir build && cd build $ mkdir build && cd build
@ -94,13 +150,24 @@ The main dependency of ARTIQ is LLVM and its Python bindings (http://llvmpy.org)
$ LLVM_CONFIG_PATH=/usr/local/llvm-or1k/bin/llvm-config sudo -E python setup.py install $ LLVM_CONFIG_PATH=/usr/local/llvm-or1k/bin/llvm-config sudo -E python setup.py install
.. note:: .. note::
``python`` refers to Python 3. You may need to use the ``python3`` command instead of ``python`` on some distributions. Compilation of LLVM can take more than 30 min on some machines.
You may want to use ``checkinstall`` instead of ``make install`` (to register the installation with your package manager) and ``pip3 install --user .`` instead of ``sudo -E python setup.py install``. * Install ARTIQ: ::
You can then install ARTIQ itself: :: $ cd ~/artiq-dev
$ git clone https://github.com/jboulder/artiq /home/rabi/artiq-dev/artiq
$ python3 setup.py develop --user
$ cd /path_to/ARTIQ * Build the documentation: ::
$ sudo python setup.py install
Alternatively, you can simply add the ARTIQ directory to your ``PYTHONPATH`` environment variable. The advantage of this technique is that you will not need to reinstall ARTIQ when modifying or upgrading it, which is useful during development. $ cd ~/artiq-dev/artiq/doc/manual
$ make html
Xubuntu 14.04 dependencies
--------------------------
This command installs all the required packages: ::
$ sudo apt-get install build-essential autoconf automake autotools-dev dh-make devscripts fakeroot file git lintian patch patchutils perl xutils-devs git-buildpackage svn-buildpackage python3-pip texinfo flex bison libmpc-dev python3-setuptools python3-numpy python3-scipy python3-sphinx python3-nose python3-dev subversion cmake libusb-dev libftdi-dev pkg-config
Note that ARTIQ requires Python 3.4 or above.