lstopo

Show the summarized system topology in a graphical window (or print to console if no graphical display is available)

$ lstopo

$ lstopo --no-factorize

$ lstopo [[-p|--physical]]

$ lstopo --no-factorize [[--of|--output-format]] [console|ascii|tex|fig|svg|pdf|ps|png|xml] [path/to/file]

$ lstopo --palette [none|grey]

lstopo [OPTION]... [<output filename>]

Examples:
lstopo
lstopo --output topology.pdf
lstopo --of svg > topology.svg
lstopo --input system.xml

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

-v, --verbose
    Enable verbose messages.

-s, --silent
    Disable verbose messages.

-p, --physical
    Display physical indexes (e.g., socket IDs, core IDs as seen by the hardware).

-l, --logical
    Display logical indexes (default behavior).

-c, --cpuset
    Show CPU set information for each object.

--no-caches
    Do not show any caches.

--no-io
    Do not show I/O devices and bridges.

--no-numa
    Do not show NUMA nodes.

--merge
    Merge identical PUs and Caches.

--input <path>
    Load topology from the specified XML file instead of discovering it from the system.

--output <path>
    Save the output to the specified file. The format is inferred from the file extension.

--of <format>
    Specify the output format explicitly (e.g., 'txt', 'pdf', 'png', 'svg', 'xml').

--version
    Report program version and exit.

lstopo is a command-line tool that displays the hierarchical topology of a system. It leverages the hwloc (Hardware Locality) library to discover and present detailed information about processing units, NUMA nodes, caches, and I/O devices. The command provides a comprehensive view of how these components are interconnected, showing their physical and logical relationships.

This visualization is crucial for understanding the underlying hardware architecture, which is vital for optimizing application performance, especially in parallel computing and High-Performance Computing (HPC) environments. lstopo can output the topology in various formats, including plain text, graphical representations (e.g., PDF, PNG, SVG), and XML, allowing for flexible analysis and integration into other tools. It helps users identify CPU sets, understand memory locality, and diagnose potential performance bottlenecks related to hardware layout.

By providing insights into the system's architecture, lstopo assists developers and system administrators in making informed decisions regarding process placement, memory allocation, and thread affinity, thereby maximizing hardware utilization and application efficiency.

lstopo relies on the underlying operating system and hardware for topology discovery. Its accuracy can sometimes vary depending on the kernel version, specific hardware configurations, or virtualization environment. In virtualized settings, the displayed topology reflects the virtual hardware presented to the guest, not necessarily the physical host.

Graphical output formats (like PDF, PNG, SVG) require the presence of specific libraries (e.g., Cairo, X11) at compile time and runtime. If these dependencies are not met, only text-based output might be available or the command may fail for graphical formats.

lstopo is highly versatile in its output options. Besides the default textual representation, it can generate graphical outputs like PNG, PDF, and SVG files, which are excellent for documentation and visual analysis. It also supports XML output, allowing programmatic parsing of the topology data, and interactive X11 display for live viewing. The output format is typically inferred from the output filename's extension or explicitly specified using `--of`.

Understanding system topology via lstopo is crucial for:
Performance Optimization: Pinning processes/threads to specific cores or NUMA nodes for optimal cache and memory access.
Resource Management: Allocating resources efficiently in virtualized environments or container orchestrators.
Debugging: Identifying performance bottlenecks caused by poor hardware affinity.
System Documentation: Generating clear diagrams of server hardware configurations.

It's widely used in HPC clusters, cloud environments, and any scenario where hardware-aware programming is beneficial.

lstopo is a core utility of the hwloc (Hardware Locality) project, which originated from efforts within the French national research institute INRIA and Bordeaux University. The project's primary goal was to provide a portable and robust way for applications to discover and exploit hardware locality, particularly in the context of High-Performance Computing (HPC) and parallel programming.

It evolved from earlier, less portable projects like libtopology and PLPA (Portable Linux Processor Affinity). hwloc was designed to be independent of specific operating systems or architectures, offering a unified API and set of tools for various Unix-like systems and Windows. lstopo quickly became the flagship visualization tool for the hwloc library, demonstrating its capabilities to users through clear and comprehensive graphical and text representations of system topology. Its development has focused on improving accuracy, adding support for new hardware features (like CXL, more cache types, I/O devices), and expanding output format options.

hwloc(7), lstopo-no-graphics(1), numactl(8), taskset(1), top(1), lsblk(8)