Host Daemon Setup (Required for Hardware)

Running XCENA hardware from Docker requires the pxl_resourced daemon on the host; each container connects to it via a shared Unix domain socket so device resources are coordinated across processes and containers. This is the required setup for hardware — for a single container as well as for multiple containers.

Prerequisites

XCENA driver installed on the host
pxl_resourced installed and running on the host
Host libpxl 1.4.9 or later (the pxl_resourced.service must set RuntimeDirectoryPreserve=yes). On older versions a daemon restart recreates /run/pxl, leaving a container’s mount pointing at a removed directory so it can no longer reach the socket.
Docker Engine installed on the host

1. Install libpxl on the host

The host needs libpxl (which includes pxl_resourced) installed so it can manage device resources across containers.

If you have the SDK package:

wget <URL_to_sdk_xxx.tar.xz>
tar -xvf sdk_xxx.tar.xz
cd sdk_xxx/lib/pxl
sudo dpkg -i libpxl_*.deb

Or copy the deb package from an existing Docker container:

# e.g., docker cp xcena_sdk:/work/lib/pxl/libpxl_*.deb ./
docker cp <container>:/work/lib/pxl/libpxl_*.deb ./
sudo dpkg -i libpxl_*.deb

2. Verify pxl_resourced is running on the host

Installing the libpxl deb package automatically registers pxl_resourced as a systemd service. Verify that it is running:

systemctl status pxl_resourced

Verify that the service socket is created:

ls -la /run/pxl/pxld.sock

3. Run Docker containers

Start each container with the following options to connect to the host daemon:

mkdir -p "$PWD/xtop-out"
docker run -it --rm \
  --privileged \
  --pid=host \
  --ipc=host \
  --cgroupns=host \
  -e SYSTEMD_IGNORE_CHROOT=1 \
  -v /run/systemd:/run/systemd \
  -v /run/dbus:/run/dbus \
  -v /tmp/pxl:/tmp/pxl \
  -v /run/pxl:/run/pxl \
  -v /dev:/dev \
  -v /sys:/sys \
  -v "$PWD/xtop-out:/xtop-out" \
  --name <container> xcenadev/sdk:<tag> \
  /bin/bash

Option	Purpose
`--privileged`	Grants access to host devices
`--pid=host`	Shares the host PID namespace
`--ipc=host`	Shares the host IPC namespace (System V / POSIX shared memory)
`--cgroupns=host`	Shares the host cgroup namespace
`-e SYSTEMD_IGNORE_CHROOT=1`	Lets systemd tooling run inside the container
`-v /run/systemd:/run/systemd`	Exposes the host systemd runtime
`-v /run/dbus:/run/dbus`	Exposes the host D-Bus (for systemd communication)
`-v /run/pxl:/run/pxl`	Mounts the `pxl_resourced` UDS socket (`pxld.sock`) for daemon communication
`-v /tmp/pxl:/tmp/pxl`	Mounts the daemon log / legacy fallback socket directory
`-v /dev:/dev`	Exposes host device nodes
`-v /sys:/sys`	Exposes host sysfs
`-v "$PWD/xtop-out:/xtop-out"`	Persists attach `.xpti` files on the host

4. Verify

Inside the container, check that the host daemon’s socket is visible:

ls -la /run/pxl/pxld.sock

Then verify device access:

xcena_cli num-device

Each container should report the same device(s) as the host.

Confirm the daemon is actually used. If the socket is missing or unreachable, libpxl prints Resource Manager daemon is not running on stderr and silently falls back to an in-process manager — xcena_cli num-device still succeeds, so it does not prove the daemon connection. Run any PXL command (e.g. xcena_cli num-device) and confirm that warning does not appear; its absence means the container is talking to the host daemon.

Security note: --privileged, --pid=host, --ipc=host, --cgroupns=host, and the host /run bind mounts (/run/systemd, /run/dbus, /run/pxl) reduce container isolation. Use these options only in controlled environments with trusted images.

Attach inside Docker

The pxl_resourced setup above provides hardware access. Use the canonical xtop attach Docker workflow for the target/PID procedure; this page only adds the Docker-specific requirements:

Keep the target and xtop attach in the same container and run both as the same user. Save and reuse the target PID from the shell that started it; do not reselect a host-wide PID with ps -eo when --pid=host is enabled.
The docker run command above mounts ./xtop-out from the host. Pass -o /xtop-out so the .xpti files survive the --rm container.
The hardware mount may expose /run/pxl/pxl_prof.sock, which makes xtop try shared daemon mode first. For the standalone per-process flow, force the per-process endpoint with:

XPTI_DAEMON_SOCKET=/dev/null xtop attach --pid "$target_pid" -o /xtop-out

/dev/null is intentionally not a Unix socket; it disables daemon autodiscovery for this command. For daemon-mode capture instead, configure the target to report to the shared profiling daemon and omit the override.