This tutorial walks you through how to run PXL-based C++ applications interactively in a Jupyter + xeus-cling environment. By the end of this guide, you’ll be able to build and run example applications directly from a Jupyter Notebook. Currently, all applications are run inside a QEMU virtual machine launched through a Docker container. In future releases, we plan to support running Jupyter directly from Docker without the intermediate QEMU VM layer; however, this will require access to a XCENA CXL device.

Prerequisites

  • Jupyter and xeus-cling are pre-installed and configured in XCENA SDK Docker.
  • Ensure Docker is installed and configured on your system. Please refer to the XCENA SDK Install Guide for instructions.
  • Configure port forwarding from the host → Docker → QEMU so that you can access the Jupyter server. See instructions below before starting Docker.

How to Run

1. Launch Environment

You can run the Jupyter environment in one of the following setups:

1.1. Docker + QEMU environment

This is the current default deployment setup. The Jupyter server runs inside a QEMU virtual machine, which itself runs inside a Docker container. To access Jupyter from your host machine, you need to forward the appropriate ports through both layers.

Required Port Mapping
  • SSH: host:<any_available_port> → Docker:<any_port> → QEMU:22
  • Jupyter: host:<any_available_port> → Docker:<any_port> → QEMU:8888
Example Setup

  1. Launch the Docker container with the following command:

     docker run -dit --name xcena_sdk \
   -p 10022:10022 \
   -p 20088:20088 \
   --device=/dev/kvm \
   --cap-add=SYS_ADMIN \
   -e USER=$USER xcenadev/sdk:latest

  2. Inside the Docker container, run the QEMU virtual machine with the following command:

     ./run.sh -f 10022:22 20088:8888

    This command will start the QEMU VM and forward the SSH and Jupyter ports. For more information on the run.sh script, refer to the Documentation/Emulator Section.

1.2. Upcoming: Docker + XCENA CXL Device

We are planning to support running the Jupyter server directly inside Docker in future versions of the SDK, removing the need for QEMU.

However, please note that this setup will require access to a real CXL device, as QEMU is currently used to emulate the CXL environment during development and testing.

Until this update is released, please use the Docker → QEMU → Jupyter method described above.

2. Start the Jupyter Server

After logging into the QEMU virtual machine, you can start the Jupyter server:

~/run_jupyter.sh

This script will launch the Jupyter Notebook server with ~/sdk/example as the working directory.

3. Access Jupyter from the Browser

On your host machine, open a web browser and visit:

http://localhost:<host_jupyter_port>

For example:

http://localhost:20088

If you are running in a headless environment, replace localhost with the server’s IP address:

http://<server_ip>:<host_jupyter_port>

4. Load PXL in Jupyter Notebook

Currently, the SDK release only supports C++17 with xeus-cling.

Open a C++17 notebook and load the PXL library with:

#pragma cling add_include_path("/usr/local/include")
#pragma cling add_library_path("/usr/local/lib")
#pragma cling load("pxl")

#include "pxl/pxl.hpp"

Important: Ensure you select C++17 as the kernel version in Jupyter.

5. Try the Sort Example

We provide a sorting example to demonstrate how to offload a simple computation using PXL.

Location 

~/sdk/example/sort/

This example consists of:

  • build.sh: Compiles the MU Kernel for the sort example.
  • mu_kernel/: MU kernel source code for the sort example
  • sort.ipynb: A Jupyter notebook demonstrating sorting with the PXL library.

To run the example

  1. Run the build script inside QEMU to compile the MU Kernel:

     cd ~/sdk/example/sort
 ./build.sh

  2. Open the notebook in Jupyter:

    Navigate to sdk/example/sort/sort.ipynb in the Jupyter interface.

  3. Execute cells in the notebook to see the sorting example in action.

Troubleshooting

Port Forwarding Issues

If you cannot access Jupyter, verify the following:

  1. Ensure the ports are correctly forwarded:
    • For QEMU: Check the -f option in run.sh.
    • For Docker: Verify the -p flags in the docker run command.

  2. Test connectivity:

     curl http://localhost:<host_jupyter_port>

  3. Make sure the ports aren’t used by other services. You can check which ports are currently in use on your host with:

     netstat -tuln

    or

     lsof -i -P -n | grep LISTEN

Jupyter Kernel Errors

If you encounter errors related to the kernel:

  • Ensure you selected C++17 as the kernel version.
  • Check that #pragma cling commands complete successfully.
  • Verify that the Jupyter server is running and accessible.

Additional Help

Refer to the XCENA SDK Documentation for further assistance.