From fa5666fb0d76f551ccf88a8bf3dd7d80be97ff6e Mon Sep 17 00:00:00 2001 From: David Mak Date: Mon, 16 Oct 2023 14:01:00 +0800 Subject: [PATCH] docs: Add instructions to run with custom NAC3 Signed-off-by: David Mak --- doc/manual/developing.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc/manual/developing.rst b/doc/manual/developing.rst index cea0c3e9b..9079f1adf 100644 --- a/doc/manual/developing.rst +++ b/doc/manual/developing.rst @@ -20,3 +20,27 @@ ARTIQ itself does not depend on Nix, and it is also possible to compile everythi * Flash the binaries into the FPGA board with a command such as ``$ artiq_flash --srcbuild -d artiq_kasli/``. You need to configure OpenOCD as explained :ref:`in the user section `. OpenOCD is already part of the flake's development environment. * 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 in the flake's development environment). 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 (e.g. by adding the user account to the ``dialout`` group). + +Testing Custom NAC3 Builds +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To test a version of NAC3 from source using ARTIQ kernels or test cases on real hardware, follow these instructions: + +1. Clone or download the source code of NAC3. This path will be referred to as ````. +2. Build NAC3 from source, e.g.: + +.. code-block:: + + $ cd + $ nix develop + [nix-shell] $ cargo clean && cargo build --release + +3. Symlink ``nac3artiq.so`` to ``libnac3artiq.so``, i.e. ``ln -s target/release/libnac3artiq.so target/release/nac3artiq.so`` +4. Enter the development environment for ARTIQ, e.g. ``cd && nix develop`` +5. Run the Python command, overriding ``PYTHONPATH`` with the directory containing ``nac3artiq.so``, e.g.: + +.. code-block:: + + [nix-shell] $ PYTHONPATH="/target/release:$PYTHONPATH" python ... + +This will run the ARTIQ command using the custom build of NAC3.