Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v2.0.3

  |   Home   |   Support   |   FAQ   |  
Object attributes

Normal attributes

hwloc objects have many generic attributes in the hwloc_obj structure, for instance their logical_index or os_index (see Should I use logical or physical/OS indexes? and how?), depth or name.

The kind of object is first described by the obj->type generic attribute (an integer). OS devices also have a specific obj->attr->osdev.type integer for distinguishing between NICs, GPUs, etc. Objects may also have an optional obj->subtype pointing to a better description string. For instance subtype is useful to say what Group objects are actually made of (e.g. Book for Linux S/390 books). It may also specify that a Block OS device is a Disk, or that a CoProcessor OS device is a CUDA device. This subtype is displayed by lstopo either in place or after the main obj->type attribute.

Each object also contains an attr field that, if non NULL, points to a union hwloc_obj_attr_u of type-specific attribute structures. For instance, a L2Cache object obj contains cache-specific information in obj->attr->cache, such as its size and associativity, cache type. See hwloc_obj_attr_u for details.

Custom string infos

Aside os these generic attribute fields, hwloc annotates many objects with string attributes that are made of a key and a value. Each object contains a list of such pairs that may be consulted manually (looking at the object infos array field) or using the hwloc_obj_get_info_by_name(). The user may additionally add new key-value pairs to any object using hwloc_obj_add_info() or the hwloc-annotate program.

Here is a non-exhaustive list of attributes that may be automatically added by hwloc. Note that these attributes heavily depend on the ability of the operating system to report them. Many of them will therefore be missing on some OS.

Hardware Platform Information

These info attributes are attached to the root object (Machine).

PlatformName, PlatformModel, PlatformVendor, PlatformBoardID, PlatformRevision,
SystemVersionRegister, ProcessorVersionRegister (Machine)
Some POWER/PowerPC-specific attributes describing the platform and processor. Currently only available on Linux. Usually added to Package objects, but can be in Machine instead if hwloc failed to discover any package.
DMIBoardVendor, DMIBoardName, etc.
DMI hardware information such as the motherboard and chassis models and vendors, the BIOS revision, etc., as reported by Linux under /sys/class/dmi/id/.
MemoryMode, ClusterMode

Intel Xeon Phi processor configuration modes. Available if hwloc-dump-hwdata was used (see Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?) or if hwloc managed to guess them from the NUMA configuration.

The memory mode may be Cache, Flat, Hybrid50 (half the MCDRAM is used as a cache) or Hybrid25 (25% of MCDRAM as cache). The cluster mode may be Quadrant, Hemisphere, All2All, SNC2 or SNC4. See doc/examples/get-knl-modes.c in the source directory for an example of retrieving these attributes.

Operating System Information

These info attributes are attached to the root object (Machine).

OSName, OSRelease, OSVersion, HostName, Architecture
The operating system name, release, version, the hostname and the architecture name, as reported by the Unix uname command.
LinuxCgroup
The name the Linux control group where the calling process is placed.

hwloc Information

Unless specified, these info attributes are attached to the root object (Machine).

Backend (topology root, or specific object added by that backend)
The name of the hwloc backend/component that filled the topology. If several components were combined, multiple Backend keys may exist, with different values, for instance x86 and Linux in the root object and CUDA in CUDA OS device objects.
SyntheticDescription
The description string that was given to hwloc to build this synthetic topology.
hwlocVersion
The version number of the hwloc library that was used to generate the topology. If the topology was loaded from XML, this is not the hwloc version that loaded it, but rather the first hwloc instance that exported the topology to XML earlier.
ProcessName
The name of the process that contains the hwloc library that was used to generate the topology. If the topology was from XML, this is not the hwloc process that loaded it, but rather the first process that exported the topology to XML earlier.

CPU Information

These info attributes are attached to Package objects, or to the root object (Machine) if package locality information is missing.

CPUModel
The processor model name.
CPUVendor, CPUModelNumber, CPUFamilyNumber, CPUStepping
The processor vendor name, model number, family number, and stepping number. Currently available for x86 and Xeon Phi processors on most systems, and for ia64 processors on Linux (except CPUStepping).
CPURevision
A POWER/PowerPC-specific general processor revision number, currently only available on Linux.
CPUType
A Solaris-specific general processor type name, such as "i86pc".

OS Device Information

These info attributes are attached to OS device objects specified in parentheses.

Vendor, Model, Revision, SerialNumber, Size, SectorSize (Block OS devices)
The vendor and model names, revision, serial number, size (in kB) and SectorSize (in bytes).
LinuxDeviceID (Block OS devices)
The major/minor device number such as 8:0 of Linux device.
GPUVendor, GPUModel (GPU or Co-Processor OS devices)
The vendor and model names of the GPU device.
OpenCLDeviceType, OpenCLPlatformIndex,
OpenCLPlatformName, OpenCLPlatformDeviceIndex (OpenCL OS devices)
The type of OpenCL device, the OpenCL platform index and name, and the index of the device within the platform.
OpenCLComputeUnits, OpenCLGlobalMemorySize (OpenCL OS devices)
The number of compute units and global memory size (in kB) of an OpenCL device.
NVIDIAUUID, NVIDIASerial (NVML GPU OS devices)
The UUID and Serial of NVIDIA GPUs.
CUDAMultiProcessors, CUDACoresPerMP,
CUDAGlobalMemorySize, CUDAL2CacheSize, CUDASharedMemorySizePerMP (CUDA OS devices)
The number of shared multiprocessors, the number of cores per multiprocessor, the global memory size, the (global) L2 cache size, and size of the shared memory in each multiprocessor of a CUDA device. Sizes are in kB.
MICSerialNumber (MIC coprocessor OS device)
The serial number of an Intel Xeon Phi (MIC) coprocessor. hwloc may run either inside the coprocessor itself, or on the host processor. That attribute is set in both cases, so that the exact same coprocessor may be identified from both point of views, even if there are multiple nodes with multiple MICs. When running hwloc on the host, each hwloc OS device object that corresponds to a Xeon Phi gets such an attribute. When running hwloc inside a Xeon Phi coprocessor, the root of the topology (Machine object) gets this attribute.
MICFamily, MICSKU, MICActiveCores, MICMemorySize (MIC coprocessor OS device)
The family, SKU (model), number of active cores, and memory size (in kB) of an Intel Xeon Phi (MIC) coprocessor.
Address, Port (Network interface OS devices)
The MAC address and the port number of a software network interface, such as eth4 on Linux.
NodeGUID, SysImageGUID, Port1State, Port2LID, Port2LMC, Port3GID1 (OpenFabrics OS devices)
The node GUID and GUID mask, the state of a port #1 (value is 4 when active), the LID and LID mask count of port #2, and GID #1 of port #3.

Other Object-specific Information

These info attributes are attached to objects specified in parentheses.

Inclusive (Caches)
The inclusiveness of a cache (1 if inclusive, 0 otherwise). Currently only available on x86 processors.
SolarisProcessorGroup (Group)
The Solaris kstat processor group name that was used to build this Group object.
PCIVendor, PCIDevice (PCI devices and bridges)
The vendor and device names of the PCI device.
PCISlot (PCI devices or Bridges)
The name/number of the physical slot where the device is plugged. If the physical device contains PCI bridges above the actual PCI device, the attribute may be attached to the highest bridge (i.e. the first object that actually appears below the physical slot).
Vendor, AssetTag, PartNumber, DeviceLocation, BankLocation (MemoryModule Misc objects)
Information about memory modules (DIMMs) extracted from SMBIOS.

User-Given Information

Here is a non-exhaustive list of user-provided info attributes that have a special meaning:

lstopoStyle
Enforces the style of an object (background and text colors) in the graphical output of lstopo. See CUSTOM COLORS in the lstopo(1) manpage for details.