forked from M-Labs/artiq
manual: use $ for shell prompts consistently
This commit is contained in:
parent
26dd4e5160
commit
24a3b31f22
@ -7,18 +7,18 @@ Developing ARTIQ
|
||||
The easiest way to obtain an ARTIQ development environment is via the Nix package manager on Linux. The Nix system is used on the `M-Labs Hydra server <https://nixbld.m-labs.hk/>`_ to build ARTIQ and its dependencies continuously; it ensures that all build instructions are up-to-date and allows binary packages to be used on developers' machines, in particular for large tools such as the Rust compiler.
|
||||
ARTIQ itself does not depend on Nix, and it is also possible to compile everything from source (look into the ``.nix`` files from the ``nix-scripts`` repository and run the commands manually) - but Nix makes the process a lot easier.
|
||||
|
||||
* Install the `Nix package manager <http://nixos.org/nix/>`_ and Git (e.g. ``nix-shell -p git``).
|
||||
* Install the `Nix package manager <http://nixos.org/nix/>`_ and Git (e.g. ``$ nix-shell -p git``).
|
||||
* Set up the M-Labs Hydra channels (:ref:`same procedure as the user section <installing-nix-users>`) to allow binaries to be downloaded. Otherwise, tools such as LLVM and the Rust compiler will be compiled on your machine, which uses a lot of CPU time, memory, and disk space. Simply setting up the channels is sufficient, Nix will automatically detect when a binary can be downloaded instead of being compiled locally.
|
||||
* Clone the repositories https://github.com/m-labs/artiq and https://github.com/m-labs/nix-scripts.
|
||||
* Run ``nix-shell -I artiqSrc=path_to_artiq_sources shell-dev.nix`` to obtain an environment containing all the required development tools (e.g. Migen, MiSoC, Clang, Rust, OpenOCD...) in addition to the ARTIQ user environment. ``artiqSrc`` should point to the root of the cloned ``artiq`` repository, and ``shell-dev.nix`` can be found in the ``artiq`` folder of the ``nix-scripts`` repository.
|
||||
* Run ``$ nix-shell -I artiqSrc=path_to_artiq_sources shell-dev.nix`` to obtain an environment containing all the required development tools (e.g. Migen, MiSoC, Clang, Rust, OpenOCD...) in addition to the ARTIQ user environment. ``artiqSrc`` should point to the root of the cloned ``artiq`` repository, and ``shell-dev.nix`` can be found in the ``artiq`` folder of the ``nix-scripts`` repository.
|
||||
* This enters a FHS chroot environment that simplifies the installation and patching of Xilinx Vivado.
|
||||
* Download Vivado from Xilinx and install it (by running the official installer in the FHS chroot environment). If you do not want to write to ``/opt``, you can install it in a folder of your home directory. The "appropriate" Vivado version to use for building the bitstream can vary. Some versions contain bugs that lead to hidden or visible failures, others work fine. Refer to the `M-Labs Hydra logs <https://nixbld.m-labs.hk/>`_ to determine which version is currently used when building the binary packages.
|
||||
* During the Vivado installation, uncheck ``Install cable drivers`` (they are not required as we use better and open source alternatives).
|
||||
* You can then build the firmware and gateware with a command such as ``python -m artiq.gateware.targets.kasli``.
|
||||
* You can then build the firmware and gateware with a command such as ``$ python -m artiq.gateware.targets.kasli``.
|
||||
* If you did not install Vivado in ``/opt``, add a command line option such as ``--gateware-toolchain-path ~/Xilinx/Vivado``.
|
||||
* Flash the binaries into the FPGA board with a command such as ``artiq_flash --srcbuild artiq_kasli -V <your_variant>``. You need to configure OpenOCD as explained :ref:`in the user section <configuring-openocd>`. OpenOCD is already part of the shell started by ``shell-dev.nix``.
|
||||
* Check that the board boots and examine the UART messages by running a serial terminal program, e.g. ``flterm /dev/ttyUSB1`` (``flterm`` is part of MiSoC and installed by ``shell-dev.nix``). Leave the terminal running while you are flashing the board, so that you see the startup messages when the board boots immediately after flashing. You can also restart the board (without reflashing it) with ``artiq_flash start``.
|
||||
* 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).
|
||||
* Flash the binaries into the FPGA board with a command such as ``$ artiq_flash --srcbuild artiq_kasli -V <your_variant>``. You need to configure OpenOCD as explained :ref:`in the user section <configuring-openocd>`. OpenOCD is already part of the shell started by ``shell-dev.nix``.
|
||||
* Check that the board boots and examine the UART messages by running a serial terminal program, e.g. ``$ flterm /dev/ttyUSB1`` (``flterm`` is part of MiSoC and installed by ``shell-dev.nix``). Leave the terminal running while you are flashing the board, so that you see the startup messages when the board boots immediately after flashing. You can also restart the board (without reflashing it) with ``$ artiq_flash start``.
|
||||
* 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).
|
||||
* If you are modifying a dependency of ARTIQ, in addition to updating the relevant part of ``nix-scripts``, rebuild and upload the corresponding Conda packages manually, and update their version numbers in ``conda-artiq.nix``. For Conda, only the main ARTIQ package and the board packages are handled automatically on Hydra.
|
||||
|
||||
.. warning::
|
||||
|
||||
@ -18,17 +18,17 @@ First, install the Nix package manager. Some distributions provide a package for
|
||||
|
||||
Once Nix is installed, add the M-Labs package channels with: ::
|
||||
|
||||
nix-channel --add https://nixbld.m-labs.hk/channel/custom/artiq/main/channel m-labs
|
||||
nix-channel --add https://nixbld.m-labs.hk/channel/custom/artiq/sinara-systems/channel sinara
|
||||
$ nix-channel --add https://nixbld.m-labs.hk/channel/custom/artiq/main/channel m-labs
|
||||
$ nix-channel --add https://nixbld.m-labs.hk/channel/custom/artiq/sinara-systems/channel sinara
|
||||
|
||||
Those channels track `nixpkgs 18.09 <https://github.com/NixOS/nixpkgs/tree/release-18.09>`_. You can check the latest status through the `Hydra interface <https://nixbld.m-labs.hk>`_. As the Nix package manager default installation uses the development version of nixpkgs, we need to tell it to switch to the release: ::
|
||||
|
||||
nix-channel --remove nixpkgs
|
||||
nix-channel --add https://nixos.org/channels/nixos-18.09 nixpkgs
|
||||
$ nix-channel --remove nixpkgs
|
||||
$ nix-channel --add https://nixos.org/channels/nixos-18.09 nixpkgs
|
||||
|
||||
Finally, make all the channel changes effective: ::
|
||||
|
||||
nix-channel --update
|
||||
$ nix-channel --update
|
||||
|
||||
Nix won't install packages without verifying their cryptographic signature. Add the M-Labs public key by creating the file ``~/.config/nix/nix.conf`` with the following contents:
|
||||
|
||||
@ -37,7 +37,7 @@ Nix won't install packages without verifying their cryptographic signature. Add
|
||||
substituters = https://cache.nixos.org https://nixbld.m-labs.hk
|
||||
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= nixbld.m-labs.hk-1:5aSRVA5b320xbNvu30tqxVPXpld73bhtOeH6uAjRyHc=
|
||||
|
||||
The easiest way to obtain ARTIQ is then to install it into the user environment with ``nix-env -i python3.6-artiq``. This provides a minimal installation of ARTIQ where the usual commands (``artiq_master``, ``artiq_dashboard``, ``artiq_run``, etc.) are available.
|
||||
The easiest way to obtain ARTIQ is then to install it into the user environment with ``$ nix-env -i python3.6-artiq``. This provides a minimal installation of ARTIQ where the usual commands (``artiq_master``, ``artiq_dashboard``, ``artiq_run``, etc.) are available.
|
||||
|
||||
This installation is however quite limited, as Nix creates a dedicated Python environment for the ARTIQ commands alone. This means that other useful Python packages that you may want (pandas, matplotlib, ...) are not available to them, and this restriction also applies to the M-Labs packages containing board binaries, which means that ``artiq_flash`` will not automatically find them.
|
||||
|
||||
@ -80,9 +80,9 @@ Installing multiple packages and making them visible to the ARTIQ commands requi
|
||||
];
|
||||
}
|
||||
|
||||
Then spawn a shell containing the packages with ``nix-shell my-artiq-env.nix``. The ARTIQ commands with all the additional packages should now be available.
|
||||
Then spawn a shell containing the packages with ``$ nix-shell my-artiq-env.nix``. The ARTIQ commands with all the additional packages should now be available.
|
||||
|
||||
You can exit the shell by typing Control-D. The next time ``nix-shell my-artiq-env.nix`` is invoked, Nix uses the cached packages so the shell startup is fast.
|
||||
You can exit the shell by typing Control-D. The next time ``$ nix-shell my-artiq-env.nix`` is invoked, Nix uses the cached packages so the shell startup is fast.
|
||||
|
||||
You can edit this file according to your needs, and also create multiple ``.nix`` files that correspond to different sets of packages. If you are familiar with Conda, using Nix in this way is similar to having multiple Conda environments.
|
||||
|
||||
@ -118,9 +118,9 @@ This activation has to be performed in every new shell you open to make the ARTI
|
||||
Upgrading ARTIQ (with Nix)
|
||||
--------------------------
|
||||
|
||||
Run ``nix-channel --update`` to retrieve information about the latest versions, and then either reinstall ARTIQ into the user environment (``nix-env -i python3.6-artiq``) or re-run the ``nix-shell`` command.
|
||||
Run ``$ nix-channel --update`` to retrieve information about the latest versions, and then either reinstall ARTIQ into the user environment (``$ nix-env -i python3.6-artiq``) or re-run the ``nix-shell`` command.
|
||||
|
||||
To rollback to the previous version, use ``nix-channel --rollback`` and then re-do the second step. You can switch between versions by passing a parameter to ``--rollback`` (see the ``nix-channel`` documentation).
|
||||
To rollback to the previous version, use ``$ nix-channel --rollback`` and then re-do the second step. You can switch between versions by passing a parameter to ``--rollback`` (see the ``nix-channel`` documentation).
|
||||
|
||||
You may need to reflash the gateware and firmware of the core device to keep it synchronized with the software.
|
||||
|
||||
@ -223,14 +223,14 @@ You can also insert other types of SFP transceivers into Kasli if you wish to us
|
||||
|
||||
If you purchased a device from M-Labs, it already comes with a valid MAC address and an IP address, usually ``192.168.1.75``. Once you can reach this IP, it can be changed with: ::
|
||||
|
||||
artiq_coremgmt -D 192.168.1.75 config write -s ip [new IP]
|
||||
$ artiq_coremgmt -D 192.168.1.75 config write -s ip [new IP]
|
||||
|
||||
and then reboot the device (with ``artiq_flash start`` or a power cycle).
|
||||
|
||||
In other cases, install OpenOCD as before, and flash the IP and MAC addresses directly: ::
|
||||
|
||||
$ artiq_mkfs flash_storage.img -s mac xx:xx:xx:xx:xx:xx -s ip xx.xx.xx.xx
|
||||
$ artiq_flash -t [board] -V [variant] -f flash_storage.img storage start
|
||||
$ artiq_mkfs flash_storage.img -s mac xx:xx:xx:xx:xx:xx -s ip xx.xx.xx.xx
|
||||
$ artiq_flash -t [board] -V [variant] -f flash_storage.img storage start
|
||||
|
||||
Check that you can ping the device. If ping fails, check that the Ethernet link LED is ON - on Kasli, it is the LED next to the SFP0 connector. As a next step, look at the messages emitted on the UART during boot. Use a program such as flterm or PuTTY to connect to the device's serial port at 115200bps 8-N-1 and reboot the device. On Kasli, the serial port is on FTDI channel 2 with v1.1 hardware (with channel 0 being JTAG) and on FTDI channel 1 with v1.0 hardware.
|
||||
|
||||
@ -246,8 +246,8 @@ This kernel is therefore stored in the :ref:`core device configuration flash sto
|
||||
|
||||
To flash the idle kernel, first 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. Then write it into the core device configuration flash storage: ::
|
||||
|
||||
$ artiq_compile idle.py
|
||||
$ artiq_coremgmt config write -f idle_kernel idle.elf
|
||||
$ artiq_compile idle.py
|
||||
$ artiq_coremgmt config write -f idle_kernel idle.elf
|
||||
|
||||
.. note:: You can find more information about how to use the ``artiq_coremgmt`` utility on the :ref:`Utilities <core-device-management-tool>` page.
|
||||
|
||||
@ -265,5 +265,5 @@ If you are using DRTIO and the default routing table (for a star topology) is no
|
||||
|
||||
The KC705 may use either an external clock signal or its internal clock. The clock is selected at power-up. Use one of these commands: ::
|
||||
|
||||
$ artiq_coremgmt config write -s rtio_clock i # internal clock (default)
|
||||
$ artiq_coremgmt config write -s rtio_clock e # external clock
|
||||
$ artiq_coremgmt config write -s rtio_clock i # internal clock (default)
|
||||
$ artiq_coremgmt config write -s rtio_clock e # external clock
|
||||
|
||||
Loading…
Reference in New Issue
Block a user