hwloc-ls

View documentation for the original command

$ tldr lstopo-no-graphics

hwloc-ls [OPTIONS]

-h, --help
    Display a help message and exit.

-v, --verbose
    Show more verbose output, including object attributes and CPU/NUMA node sets. Can be used multiple times for even more detail.

-i <filename>, --input <filename>
    Read the topology from the specified XML file instead of detecting it from the current system. This allows for offline analysis of saved topologies.

-o <filename>, --output <filename>
    Export the detected topology to an XML file. This XML can later be used with the -i option or other hwloc tools.

-p, --physical
    Display physical indexes for objects (e.g., physical CPU IDs) instead of logical indexes (default).

--cpuset
    Show the CPU set (a bitmap of CPUs) associated with each object in the topology.

--whole-system
    Report the entire system topology, even if some parts are not available to the current process due to cgroups or other resource restrictions.

--no-io
    Do not show I/O devices (e.g., PCI devices, network interfaces, GPUs) in the topology output.

--numa-only
    Filter the output to show only NUMA nodes and their children, hiding other object types.

--only <type>
    Only show objects of the specified type (e.g., Core, L3Cache, NUMANode). Case-insensitive.

--avoid <type>
    Avoid showing objects of the specified type in the output.

--xml, --dot, --ascii
    Specify the output format: --xml for XML, --dot for Graphviz DOT, or --ascii for plain text (default).

--pid <pid>
    Restrict the topology to the CPU set (and NUMA nodes) of the specified process ID. This shows the hardware resources visible to a particular process.

hwloc-ls is a command-line utility from the hwloc (Hardware Locality) project designed to visualize the architectural topology of a computing system. It presents a detailed, hierarchical view of hardware components such as processors, cores, threads, various levels of caches (L1, L2, L3), NUMA (Non-Uniform Memory Access) nodes, and I/O devices (e.g., PCI devices, network interfaces, GPUs).

The tool is invaluable for understanding how these components are interconnected and their relative proximity. This locality information is critical for optimizing the performance of parallel applications, configuring efficient resource allocation, and diagnosing performance bottlenecks, particularly in high-performance computing (HPC) environments. It helps users make informed decisions about CPU affinity, memory placement, and task scheduling to minimize latency and maximize throughput. hwloc-ls can display the topology of the local system or load it from an XML file for offline analysis or remote system examination.

hwloc-ls relies on system information provided by the operating system kernel and various filesystem entries (e.g., /proc, /sys).

Permissions: Insufficient permissions might prevent hwloc-ls from accessing complete topology information, especially concerning I/O devices or process-specific details.
Kernel Support: The level of detail and accuracy can vary depending on the operating system, kernel version, and installed drivers.
Verbose Output: For systems with a large number of components, the ASCII output can be very lengthy and complex to parse manually.
XML/DOT Support: For XML input/output, the hwloc library must have been compiled with libxml2 support. For DOT output, Graphviz tools are required to render the graph.

hwloc-ls presents the system topology in a clear, tree-like hierarchy. The top-level object is typically the Machine. Below that, you might find Package (CPU sockets), NUMANode, different levels of caches (L3Cache, L2Cache, L1Cache), Core, and finally PU (Processing Unit, which usually corresponds to a hardware thread). I/O devices are typically attached to the lowest-level common ancestor.

By default, hwloc-ls detects the topology of the system it's running on. However, its flexibility allows it to read topology information from an XML file. This feature is crucial for debugging, analyzing, or simulating workloads on a system without direct access, by loading a previously saved topology definition.

The hwloc project, including the hwloc-ls utility, originated from the fusion of two earlier projects: INRIA's libtopology and the Open MPI project's PLPA (Portable Linux Processor Affinity). This merge, occurring around 2009, aimed to create a robust and cross-platform standard for hardware locality information. hwloc-ls quickly became a cornerstone utility, providing a consistent way to expose complex system architectures, which is vital for developing and optimizing parallel software, especially in high-performance computing (HPC) environments where CPU and memory locality are paramount for performance.

hwloc-bind(1), hwloc-calc(1), lstopo(1), numactl(8), lscpu(1)