# Use Topo to assess target compatibility ## In this learning path - [Introduction](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/) - [Install Topo on your host machine](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/overview-and-setup/) - [Use Topo to assess target compatibility](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/assess-compatibility/) - [Deploy a compatible containerized workload with Topo](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/deploy-workload/) - [(Optional) Use the Topo VS Code extension](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/topo-vscode-extension/) - [Next Steps](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/_next-steps/) ## Run Topo health checks Start by running a Topo health check to confirm that all required dependencies are available on the host and the target. ### Prepare host environment Confirm that the required dependencies are available on the host by running this command in your host terminal: ``` topo health ``` The output is similar to: ``` __output__ Host __output__ ---- __output__ Topo: ✅ (topo) __output__ SSH: ✅ (ssh) __output__ Container Engine: ✅ (docker) __output__ Target __output__ ------ __output__ ℹ️ provide --target or set TOPO_TARGET to check target health ``` If Docker is missing, follow the steps in [Install Docker](https://learn.arm.com/install-guides/docker/) to install Docker. If SSH is missing, follow the steps in [Install SSH](https://learn.arm.com/install-guides/ssh/) to install SSH. ### Prepare target environment Now that the host is prepared, connect to your target over SSH to verify its dependencies: ``` ssh user@my-target ``` After connecting to the target, use the following commands to verify both Docker and `lscpu` are installed: ``` docker --version lscpu ``` The output is similar to: ``` __output__ Docker version xx.x.x __output__ Architecture: aarch64 __output__ CPU(s): ... ``` ### Run a health check against the target Run the following command from the terminal of your host device. If you are using your host device simultaneously as your target, use `topo health --target localhost`. ``` topo health --target user@my-target ``` The output is similar to the following example from a heterogeneous SoC, with differences depending on your hardware: ``` __output__ Host __output__ ---- __output__ Topo: ✅ (topo) __output__ SSH: ✅ (ssh) __output__ Container Engine: ✅ (docker) __output__ Target __output__ ------ __output__ Connectivity: ✅ __output__ Container Engine: ✅ (docker) __output__ Remoteproc Runtime: ✅ (remoteproc-runtime) __output__ Remoteproc Shim: ✅ (containerd-shim-remoteproc-v1) __output__ Hardware Info: ✅ (lscpu) __output__ Subsystem Driver (remoteproc): ✅ (m33, m0) ``` A Topo health check confirms connectivity between the host and target, and verifies the presence of dependencies such as Docker. Resolve any `❌` errors before moving on. Warnings (⚠️) can indicate optional capabilities that might be needed in certain projects. `ℹ️` provides other information. A `✅` confirms the presence of dependencies without warnings or errors. #### Troubleshoot SSH authentication If you are using password-based SSH, you might see the following `❌` error: ``` __output__ Connectivity: ❌ (key-based SSH authentication is not setup) → run `topo setup-keys --target user@my-target` or manually setup SSH keys for the target ``` This is because Topo requires key-based SSH for secure, automated access. You can use the command specified in the output, and Topo will set up the key-based SSH for you. When prompted to set a passphrase, leave it empty for automation, or use a passphrase and an SSH agent for added security. Afterwards, run `topo health` again to confirm it has correctly set up key-based authentication. If you encounter SSH errors, check that: - The target device is powered on and accessible from the host - The correct username and IP address are used - Your firewall allows SSH traffic ## (Optional) Install remoteproc-runtime on heterogeneous devices If you’re using a Cortex-A + Cortex-M device such as the i.MX 93, you might see a `⚠️` warning if `remoteproc-runtime` is not installed on the target. [`remoteproc`](https://docs.kernel.org/staging/remoteproc.html) is a Linux kernel framework for managing remote or auxiliary processors in a heterogeneous SoC. It allows the main CPU (for example, Cortex-A) to load firmware onto the auxiliary processors (for example, Cortex-M), start and stop them, and communicate with them using [`rpmsg`](https://docs.kernel.org/staging/rpmsg.html). [`remoteproc-runtime`](https://github.com/arm/remoteproc-runtime) builds on this by adding an Open Container Initiative (OCI) interface. This lets you package and manage firmware such as container images using standard tools such as Docker or containerd, even though the code runs as firmware on the Cortex-M. [OCI](https://opencontainers.org/) defines open standards for container image formats and runtimes, ensuring compatibility across container tools. You need remoteproc-runtime only if your target is a heterogeneous SoC (for example, Cortex-A + Cortex-M, such as i.MX 93). For most single-CPU Arm Linux targets, you can skip this step. You can use Topo to install `remoteproc-runtime`. Run the following command from the host device: ``` topo install remoteproc-runtime --target user@my-target ``` Run the health command again to verify installation. Topo uses `remoteproc-runtime` internally when deploying to heterogeneous devices. ## Understand target compatibility Topo probes the target during health checks and project listing. It uses target details such as the CPU architecture, Arm CPU features, memory, and remote processor support to determine which Topo Projects are compatible. The hardware feature list mirrors CPU feature flags reported by the Linux kernel. Key flags include `fp` (hardware floating-point), `asimd` (Neon Advanced SIMD — 128-bit vector acceleration), and `aes` (hardware AES encryption). Topo uses this information to determine which projects are compatible with your target. ## List projects compatible with your target Because Topo can identify the capabilities of your target device, it can also advise on the compatibility of projects. Use the following command on your host device to list compatible projects: ``` topo projects --target user@my-target ``` The following is an example output for an AWS Graviton-based instance: ``` __output__ Hello World __output__ Clone: __output__ topo clone https://github.com/Arm-Examples/topo-welcome.git#main __output__ __output__ A minimal "Hello, World" web app for validating a Topo setup and deployment. __output__ It runs a single service that exposes a web page on the target, __output__ with the greeting text customizable via the GREETING_NAME parameter. __output__ Lightbulb Moment __output__ Clone: __output__ topo clone https://github.com/Arm-Examples/topo-lightbulb-moment.git#main __output__ Features: __output__ remoteproc-runtime __output__ __output__ Reads a switch over GPIO pins on an M class cpu, reports switch state over __output__ Remoteproc Message, then a web application on the A class reads this and __output__ displays a lightbulb in either the on or off state. The lightbulb state is __output__ described by an LLM in any user-specified style. __output__ Topo llama.cpp WebUI Chat __output__ Clone: __output__ topo clone https://github.com/Arm-Examples/topo-llama-web-ui.git#main __output__ __output__ LLM chat application with Arm CPU inference provided by llama.cpp. __output__ __output__ This project demonstrates running large language models on CPU __output__ with inference provided by the llama.cpp server. __output__ __output__ The upstream Linux Arm64 image includes architecture-specific CPU __output__ backend variants for Armv8.0 baseline, Armv8.2 dot product/FP16/SVE, __output__ Armv8.6 int8 matrix multiply/SVE2, and Armv9.2 SME-capable CPUs. __output__ SIMD Visual Benchmark __output__ Clone: __output__ topo clone https://github.com/Arm-Examples/topo-simd-visual-benchmark.git#main __output__ Features: __output__ SVE __output__ __output__ Visual demonstration of SIMD performance benefits on Arm processors. __output__ Compare scalar (no SIMD), NEON (128-bit), and SVE (scalable vector) __output__ implementations running identical image processing workloads side-by-side. ``` When you provide `--target`, Topo marks each project according to compatibility with your target. For example, `topo-lightbulb-moment` requires `remoteproc-runtime`, so it is incompatible with targets that don’t provide a supported remote processor environment. You might see different results depending on the target hardware you use. ## What you’ve accomplished and what’s next You have now verified your host and target environments, resolved any missing dependencies, and optionally enabled heterogeneous deployment. You also identified compatible projects for your target. Next, you’ll choose a containerized workload project and deploy it to your target.