diff --git a/docs/source/pynq_remote.rst b/docs/source/pynq_remote.rst index a991aec3b..20dc7c3ff 100644 --- a/docs/source/pynq_remote.rst +++ b/docs/source/pynq_remote.rst @@ -32,7 +32,7 @@ The diagram below illustrates the key differences between Classic PYNQ and PYNQ. * Offload the Python API to your host machine, reducing on-target resource requirements. * Target-side C++ implementation (`PYNQ.cpp`) for boosting on-device performance. -* Lightweight Petalinux images: shrink SD card images from ~7GB to around 200MB (small enough for a RAM disk). +* Lightweight EDF/Yocto images: shrink SD card images from ~7GB to around 200MB (small enough for a RAM disk). * PYNQ API compatibility: classic PYNQ code and Jupyter notebooks run remotely, with minimal or no changes. * Extend with custom remote APIs using Protobuf definitions. diff --git a/docs/source/pynq_remote/cpp_index.rst b/docs/source/pynq_remote/cpp_index.rst index e3670e34f..70aecf913 100644 --- a/docs/source/pynq_remote/cpp_index.rst +++ b/docs/source/pynq_remote/cpp_index.rst @@ -19,4 +19,4 @@ Like PYNQ's Python API, PYNQ.cpp is part of the PYNQ ecosystem and is specifical PYNQ.remote uses gRPC to communicate with PYNQ devices, allowing remote management of FPGA resources and memory operations. PYNQ.remote images use a gRPC server to interact with PYNQ.cpp, which provides the necessary C++ backend functionality equivalent to what PYNQ's Python API offers. -Because it exists as a standalone C++ library, PYNQ can be used independently of PYNQ.remote. This allows developers to create custom low-level C++ applications that interact with AMD adaptive SoC platforms using familiar PYNQ concepts. \ No newline at end of file +Because it exists as a standalone C++ library, *PYNQ.cpp* can be used independently of PYNQ.remote. This allows developers to create custom low-level C++ applications that interact with AMD adaptive SoC platforms using familiar PYNQ concepts. \ No newline at end of file diff --git a/docs/source/pynq_remote/cppindex.rst b/docs/source/pynq_remote/cppindex.rst deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/source/pynq_remote/env_variables.rst b/docs/source/pynq_remote/env_variables.rst index 9e6e36f67..40cbfeee2 100644 --- a/docs/source/pynq_remote/env_variables.rst +++ b/docs/source/pynq_remote/env_variables.rst @@ -6,7 +6,7 @@ Setting Environment Variables PYNQ.remote uses two environment variables on the host. ``PYNQ_REMOTE`` - Set to ``1`` when installing the ``pynq`` package with pip. This selects the + Set to ``1`` when installing the ``pynq`` package. This selects the remote client install path and skips native board binaries and overlays. ``PYNQ_REMOTE_DEVICES`` @@ -14,58 +14,67 @@ PYNQ.remote uses two environment variables on the host. comma-separated list of IP addresses. When multiple addresses are listed, each becomes a separate ``RemoteDevice`` instance. -Installing for PYNQ.remote --------------------------- +Installing PYNQ for PYNQ.remote +------------------------------- + +The commands below use the ``uv`` environment manager tool to install PYNQ, as described +in :ref:`quickstart`. However, ``pip install`` may also be used. **Linux/macOS:** .. code-block:: bash - - PYNQ_REMOTE=1 pip install pynq + + export PYNQ_REMOTE=1 + uv add "pynq @ git+https://github.com/Xilinx/PYNQ.git" **Windows (PowerShell):** .. code-block:: powershell - $env:PYNQ_REMOTE="1"; pip install pynq - -Runtime device selection ------------------------- + $env:PYNQ_REMOTE = "1" + uv add "pynq @ git+https://github.com/Xilinx/PYNQ.git" Setting ``PYNQ_REMOTE_DEVICES`` at runtime -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------ + +Python Runtime Device Selection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can set environment variables in Python using the ``os`` module. This works across all operating systems and does not require shell configuration. Set the variable before importing ``pynq``. .. code-block:: python - + import os - os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" + os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" # IP assigned to your board + + from pynq import Overlay + + ol = Overlay("my_design.xsa") -Linux and macOS shells +Shell Device Selection ~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: bash - - export PYNQ_REMOTE_DEVICES="192.168.2.99" +Alternatively, the environment may be configured in your shell. Variables apply +to the current shell session only. -The variable applies to the current shell session only. +**Linux/macOS:** -Windows -~~~~~~~ +.. code-block:: bash + + export PYNQ_REMOTE_DEVICES="192.168.2.99" -Command Prompt: - -.. code-block:: powershell +**Windows (Command Prompt):** +.. code-block:: bat + set PYNQ_REMOTE_DEVICES=192.168.2.99 -PowerShell: +**Windows (PowerShell):** .. code-block:: powershell - + $env:PYNQ_REMOTE_DEVICES="192.168.2.99" Python virtual environments @@ -74,6 +83,6 @@ Python virtual environments To set ``PYNQ_REMOTE_DEVICES`` automatically when a virtual environment is activated, add the appropriate line to the environment's activate script: -* Linux/macOS: ``venv/bin/activate`` -* Windows Command Prompt: ``venv/Scripts/activate.bat`` -* Windows PowerShell: ``venv/Scripts/Activate.ps1`` +* Linux/macOS: ``.venv/bin/activate`` +* Windows Command Prompt: ``.venv/Scripts/activate.bat`` +* Windows PowerShell: ``.venv/Scripts/Activate.ps1`` \ No newline at end of file diff --git a/docs/source/pynq_remote/image_build.rst b/docs/source/pynq_remote/image_build.rst index aa0f25c6a..26548320c 100644 --- a/docs/source/pynq_remote/image_build.rst +++ b/docs/source/pynq_remote/image_build.rst @@ -28,17 +28,32 @@ Using the Docker-based build flow git clone --recursive https://github.com/Xilinx/PYNQ.git -#. Set up the build environment by following :ref:`pynq-sd-card`. This includes - setting ``XILINX_TOOLS`` and ``XILINXD_LICENSE_FILE`` before starting the - container. - -#. Build the remote image for your target board: +#. Build the Docker image: .. code-block:: bash - # Inside the Docker container cd PYNQ/sdbuild - make pynqremote BOARDS= + docker build --build-arg USERNAME=$(whoami) --build-arg USER_UID=$(id -u) \ + --build-arg USER_GID=$(id -g) -t pynqdock:latest . + cd .. + +#. Set the paths to the AMD tools and licence, then build the remote image for + your target board: + + .. code-block:: bash + + export XILINX_TOOLS=/tools/Xilinx/2025.2 + export XILINXD_LICENSE_FILE="$HOME/.Xilinx" + + docker run --init --rm \ + --network host \ + -e XILINX_TOOLS -e XILINXD_LICENSE_FILE \ + -v "$XILINX_TOOLS:$XILINX_TOOLS:ro" \ + -v "$XILINXD_LICENSE_FILE:$XILINXD_LICENSE_FILE" \ + -v "$PWD:/workspace" \ + --privileged \ + pynqdock:latest \ + bash -lc 'cd /workspace/sdbuild && make pynqremote BOARDS=' Replace ```` with your target board (``ZCU104`` or ``VCK190``). The remote image target does not require the prebuilt classic PYNQ root @@ -51,8 +66,9 @@ Using the Docker-based build flow #. Flash the generated ``sdbuild/output/-4.0.0-remote.img`` image to an SD card and boot your device (see :doc:`../appendix/sdcard`). -#. After booting, the ``pynq-remote`` server starts automatically. Use - ``ip addr`` on the board to find its address, then follow :doc:`quickstart`. +#. After booting, the ``pynq-remote`` server starts automatically. Run + ``ip addr`` on the board through a serial console to find its address, + then follow :doc:`quickstart`. Image size ---------- diff --git a/docs/source/pynq_remote/pynq_cpp/cpp_api.rst b/docs/source/pynq_remote/pynq_cpp/cpp_api.rst index ef64062ff..56232fddf 100644 --- a/docs/source/pynq_remote/pynq_cpp/cpp_api.rst +++ b/docs/source/pynq_remote/pynq_cpp/cpp_api.rst @@ -45,3 +45,33 @@ XrtBufferManager Class :undoc-members: :protected-members: :private-members: + +GPIO Class +---------- + +.. doxygenclass:: GPIO + :project: Device + :members: + :undoc-members: + :protected-members: + :private-members: + +XRFCLK Class (RFSoC only) +------------------------- + +.. doxygenclass:: XRFCLK + :project: Device + :members: + :undoc-members: + :protected-members: + :private-members: + +XrfdcRemote Class (RFSoC only) +------------------------------ + +.. doxygenclass:: XrfdcRemote + :project: Device + :members: + :undoc-members: + :protected-members: + :private-members: \ No newline at end of file diff --git a/docs/source/pynq_remote/quickstart.rst b/docs/source/pynq_remote/quickstart.rst index 2f8688c55..5f4115ea5 100644 --- a/docs/source/pynq_remote/quickstart.rst +++ b/docs/source/pynq_remote/quickstart.rst @@ -6,129 +6,134 @@ Quick Start This page shows how to get started with PYNQ.remote. We use the ZCU104 and the `PYNQ-HelloWorld `_ overlay as an example, but the steps are similar for other supported AMD adaptive SoCs and -overlays. +overlays. The steps are provided for Windows, Linux, and macOS operating systems. +Use the commands that match your machine to set up and use PYNQ.remote. Prerequisites ------------- * Host machine running Linux, Windows, or macOS -* Python 3.10 or newer * Supported AMD adaptive SoC with network access * Network connection between host and target -Step 1: Install PYNQ.remote on the Host ---------------------------------------- +Step 1: Install uv +------------------ -PYNQ.remote uses two environment variables at different stages. Set -``PYNQ_REMOTE=1`` when installing the ``pynq`` package on the host so that -remote client dependencies are installed and native board binaries are skipped. -Set ``PYNQ_REMOTE_DEVICES`` at runtime, before ``import pynq``, to identify the -target board. See :doc:`env_variables` for platform-specific ways to set -``PYNQ_REMOTE_DEVICES``. +We use the ``uv`` tool to manage Python versions, projects, and packages in an +isolated environment. This stops project-specific dependencies from clashing +with your system. Dependencies for your project are recorded in a +``pyproject.toml`` file. -It is recommended to use a -`Python virtual environment `_. +The ``uv`` tool can be installed using the following command: **Linux/macOS:** .. code-block:: bash - PYNQ_REMOTE=1 pip install pynq + curl -LsSf https://astral.sh/uv/install.sh | sh -To install the development version from source: +**Windows (PowerShell):** -.. code-block:: bash +.. code-block:: powershell - git clone --recursive https://github.com/Xilinx/PYNQ.git - cd PYNQ - PYNQ_REMOTE=1 pip install . + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -**Windows (PowerShell):** -.. code-block:: powershell +Step 2: Create a Project +------------------------ - $env:PYNQ_REMOTE="1"; pip install pynq +Running ``uv init --bare`` sets up a project containing a minimal +``pyproject.toml``. Additionally, passing ``--python "==3.11.*"`` specifies +that the project uses Python 3.11. Run the following command to create the +project: -Step 2: Prepare and Boot the Target Device ------------------------------------------- +**Linux/macOS and Windows (PowerShell):** -* Create a PYNQ.remote image using the instructions in :doc:`image_build`. -* Flash the image to your SD card (see :doc:`../appendix/sdcard`). -* Insert the SD card and power on the device. +.. code-block:: bash -Remote images configure both a static address of ``192.168.2.99`` and DHCP. -If your host is on the ``192.168.2.0/24`` network, continue to Step 3 and use -that address in ``PYNQ_REMOTE_DEVICES``. + uv init remote-project --bare --python "==3.11.*" + cd remote-project -If the board is on a different network, use the DHCP address from your router's -client list. See :doc:`troubleshooting` if you need to use a USB serial console. -The first time you connect over serial, log in as ``amd-edf`` and set a password -when prompted. +Step 3: Install PYNQ and Dependencies +------------------------------------- -Step 3: Install and Run PYNQ-HelloWorld ---------------------------------------- +Before you install any dependencies into the ``uv`` environment, PYNQ's +installer needs to be instructed to build in *remote mode*. To do this, set the +``PYNQ_REMOTE`` environment variable before installing PYNQ. -Install the required dependencies in your Python virtual environment: +**Linux/macOS:** .. code-block:: bash - pip install jupyterlab matplotlib pillow wheel + export PYNQ_REMOTE=1 + +**Windows (PowerShell):** + +.. code-block:: powershell -Install the PYNQ-HelloWorld overlay. Set the ``BOARD`` environment variable -before installation so that PYNQ-Utils knows which board you are targeting: + $env:PYNQ_REMOTE = "1" -**Windows:** +PYNQ can then be installed, **followed by** any other dependencies required +for your project. The first command below installs the most recent version of +PYNQ from GitHub. ``uv add`` installs packages into the project environment and +records each of them in the ``pyproject.toml``. + +**Linux/macOS and Windows (PowerShell):** .. code-block:: bash - # PowerShell: - $env:BOARD="ZCU104"; pip install --no-build-isolation pynq-helloworld + uv add "pynq @ git+https://github.com/Xilinx/PYNQ.git" + uv add "setuptools<78" "pycparser<3" "numpy<2" scipy ipywidgets plotly anywidget matplotlib pillow ipython jupyterlab voila + +Step 4: Install PYNQ-HelloWorld +------------------------------- - # Command Prompt: - set BOARD=ZCU104 && pip install --no-build-isolation pynq-helloworld +Before installing the PYNQ-HelloWorld overlay, set the ``BOARD`` environment +variable so that PYNQ-Utils knows which board you are targeting. **Linux/macOS:** .. code-block:: bash - BOARD=ZCU104 pip install --no-build-isolation pynq-helloworld + export BOARD=ZCU104 -Download the notebooks and overlay files: +**Windows (PowerShell):** -.. code-block:: bash +.. code-block:: powershell - pynq get-notebooks pynq-helloworld -d ZCU104 + $env:BOARD = "ZCU104" -The ``-d`` argument tells ``pynq get-notebooks`` which board package to use. +PYNQ-HelloWorld is then ready to be installed: -Start Jupyter Lab: +**Linux/macOS and Windows (PowerShell):** .. code-block:: bash - jupyter lab + uv pip install --no-build-isolation pynq-helloworld + uv run pynq get-notebooks pynq-helloworld -d ZCU104 - # On some shells it may be necessary to use: - python -m jupyterlab +Step 5: Running JupyterLab +-------------------------- -Connecting to the Board -~~~~~~~~~~~~~~~~~~~~~~~ +Before running any overlays, the IP address assigned to your board must be stored in an +environment variable called ``PYNQ_REMOTE_DEVICES``. This can be configured directly in a +Linux/macOS or PowerShell terminal, or in Python using the ``os`` module **before** +running ``import pynq``. Running ``uv run jupyter-lab`` starts the Jupyter session, allowing +you to interact with the board using PYNQ.remote. -Before importing ``pynq``, set ``PYNQ_REMOTE_DEVICES`` to the board address: - -.. code-block:: python +**Linux/macOS:** - import os - os.environ['PYNQ_REMOTE_DEVICES'] = "192.168.2.99" # default static IP +.. code-block:: bash - from pynq import allocate, Overlay + export PYNQ_REMOTE_DEVICES=192.168.2.99 + uv run jupyter-lab - overlay = Overlay("resizer.bit") +**Windows (PowerShell):** -Modifying the Notebook for PYNQ.remote -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. code-block:: powershell -When you open the ``resizer_pl.ipynb`` notebook, add the lines above to the -imports cell before ``from pynq import allocate, Overlay``. + $env:PYNQ_REMOTE_DEVICES = "192.168.2.99" + uv run jupyter-lab -Once this change is made, you should be able to run through the entire notebook -and resize images completely remotely using PYNQ.remote. +Navigate to the ``pynq-notebooks/pynq-helloworld`` directory and explore the +``resizer_pl.ipynb`` notebook. \ No newline at end of file diff --git a/docs/source/pynq_remote/remote_device.rst b/docs/source/pynq_remote/remote_device.rst index 906763ff0..6250a9477 100644 --- a/docs/source/pynq_remote/remote_device.rst +++ b/docs/source/pynq_remote/remote_device.rst @@ -5,7 +5,7 @@ The RemoteDevice Class The ``RemoteDevice`` class enables controlling PYNQ boards over network connections using gRPC. It provides a complete remote access solution including bitstream downloading, memory allocation, MMIO operations, and other PYNQ functionalities through remote procedure calls. -This module includes classes for remote memory management (``RemoteBuffer``), memory-mapped I/O (``RemoteMMIO``), bitstream handling, and communication channel management. The implementation handles multiple bitstream formats (.bit, .bin, .xsa), metadata parsing, and caching while maintaining compatibility with the local PYNQ API. +This module includes classes for remote memory management (``RemoteBuffer``), memory-mapped I/O (``RemoteMMIO``), overlay handling, and communication channel management. The implementation handles multiple bitstream formats (.bit, .pdi, .bin, .xsa), metadata parsing, and caching while maintaining compatibility with the local PYNQ API. Remote devices can be configured through the ``PYNQ_REMOTE_DEVICES`` environment variable, which should contain a comma-separated list of IP addresses for target diff --git a/docs/source/pynq_remote/status.rst b/docs/source/pynq_remote/status.rst index 3474f69d5..6f4aeb63a 100644 --- a/docs/source/pynq_remote/status.rst +++ b/docs/source/pynq_remote/status.rst @@ -10,8 +10,8 @@ This document outlines the current status of PYNQ.remote. * **Validated Platforms**: * `ZCU104 `_ * `VCK190 `_ - * `AUP-ZU3 `_ - * `RFSoC-PYNQ `_ + * `AUP-ZU3 `_ (coming soon!) + * Supported `RFSoC-PYNQ `_ platforms. * **Image build**: EDF/Yocto remote rootfs (see :doc:`image_build`) * **Supported Features**: * :doc:`../pynq_overlays/loading_an_overlay` @@ -20,6 +20,6 @@ This document outlines the current status of PYNQ.remote. * :doc:`../pynq_libraries/allocate` * :doc:`../pynq_libraries/psgpio` (``RemoteGPIO``) * RFSoC clock and data converter control (RFSoC remote images) - * Multi-board support * **Not yet supported**: * :doc:`../pynq_libraries/interrupt` + * Multi-board support \ No newline at end of file diff --git a/pynq/pl_server/remote_device.py b/pynq/pl_server/remote_device.py index 276bb1eee..f8171d15d 100644 --- a/pynq/pl_server/remote_device.py +++ b/pynq/pl_server/remote_device.py @@ -165,7 +165,7 @@ class RemoteDevice(Device): It provides bitstream downloading, memory allocation, MMIO operations, and other PYNQ functionality through gRPC remote procedure calls. - The device supports multiple bitstream formats (.bit, .bin, .xsa) and + The device supports multiple bitstream formats (.bit, .pdi, .bin, .xsa) and handles metadata parsing, caching, and AXI port width configuration remotely. """