Crate hwlocality_sys
source ·Expand description
§hwlocality-sys: The low-level bindings below hwlocality
This crate contains the low-level unsafe Rust -> C FFI bindings to hwloc, that are used to implement the safe hwlocality bindings.
Depending on your needs, you can either link to a libhwloc
that is
pre-installed on your computer or have hwlocality
build its own copy
libhwloc
internally. Please read the “Prerequisites” section of the
hwlocality README for
more information about these two options.
Like any C API, the hwlocality-sys
low-level bindings are highly unsafe to
use, and it is advised that you use the safe hwlocality
bindings instead
whenever possible. If you encounter any issue with the safe bindings that
prevents you from using them and forces you to use the unsafe C API directly,
please report them in the issue tracker so we get them fixed.
Structs§
- Downstream PCI device attributes
- Opaque bitmap struct
HWLOC_OBJ_BRIDGE
-specific attributes- Cache-specific attributes
- Matrix of distances between a set of objects
HWLOC_OBJ_GROUP
-specific attributes- Key-value string attributes
- hwloc_location
hwloc-2_3_0
Where to measure attributes from - Local memory page type
HWLOC_OBJ_NUMANODE
-specific attributes- Hardware topology object
HWLOC_OBJ_OS_DEVICE
-specific attributesHWLOC_OBJ_PCI_DEVICE
-specific attributes- Opaque topology struct
- Support for getting and setting thread/process CPU bindings
- Support for discovering information about the topology
- Support for getting and setting thread/process NUMA node bindings
- hwloc_topology_misc_support
hwloc-2_3_0
Miscellaneous support information - Set of flags describing actual hwloc feature support for this topology
Constants§
- HWLOC_ALLOW_FLAG_ALL
hwloc-2_3_0
Mark all objects as allowed in the topology - HWLOC_ALLOW_FLAG_CUSTOM
hwloc-2_3_0
- HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
hwloc-2_3_0
Only allow objects that are available to the current process - Avoid any effect on memory binding
- Bind all threads of the current process
- Request for strict binding from the OS
- Bind the current thread of the current process
- HWLOC_DISTANCES_ADD_FLAG_GROUP
hwloc-2_5_0
Try to group objects based on the newly provided distance information - HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
hwloc-2_5_0
If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms. The actual accuracy may be modified through theHWLOC_GROUPING_ACCURACY
environment variable (see Environment Variables). - These distances were obtained from the operating system or hardware
- These distances were provided by the user
- HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
hwloc-2_1_0
This distances structure covers objects of different types - Distance values are similar to bandwidths between objects
- Distance values are similar to latencies between objects
- HWLOC_DISTANCES_TRANSFORM_LINKS
hwloc-2_5_0
Replace bandwidth values with a number of links - HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
hwloc-2_5_0
Merge switches with multiple ports into a single object - HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
hwloc-2_5_0
Remove NULL objects from the distances structure. - HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
hwloc-2_5_0
Apply a transitive closure to the matrix to connect objects across switches. - Distrib in reverse order, starting from the last objects
- HWLOC_LOCAL_NUMANODE_FLAG_ALL
hwloc-2_3_0
Select all NUMA nodes in the topology - HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
hwloc-2_3_0
Select NUMA nodes whose locality is larger than the given cpuset - HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
hwloc-2_3_0
Select NUMA nodes whose locality is smaller than the given cpuset - HWLOC_LOCATION_TYPE_CPUSET
hwloc-2_3_0
Location is given as a cpuset, in thehwloc_location_u::cpuset
union field - HWLOC_LOCATION_TYPE_OBJECT
hwloc-2_3_0
Location is given as an object, in thehwloc_location_u::object
union field - HWLOC_MEMATTR_FLAG_HIGHER_FIRST
hwloc-2_3_0
The best nodes for this memory attribute are those with the higher values - HWLOC_MEMATTR_FLAG_LOWER_FIRST
hwloc-2_3_0
The best nodes for this memory attribute are those with the lower values - HWLOC_MEMATTR_FLAG_NEED_INITIATOR
hwloc-2_3_0
The value returned for this memory attribute depends on the given initiator - HWLOC_MEMATTR_ID_BANDWIDTH
hwloc-2_3_0
Average bandwidth in MiB/s, as seen from the given initiator location - HWLOC_MEMATTR_ID_CAPACITY
hwloc-2_3_0
Node capacity in bytes (seehwloc_obj::total_memory
) - HWLOC_MEMATTR_ID_LATENCY
hwloc-2_3_0
Latency in nanoseconds, as seen from the given initiator location - HWLOC_MEMATTR_ID_LOCALITY
hwloc-2_3_0
Number of PUs in that locality (i.e. cpuset weight) - HWLOC_MEMATTR_ID_READ_BANDWIDTH
hwloc-2_8_0
Read bandwidth in MiB/s, as seen from the given initiator location - HWLOC_MEMATTR_ID_READ_LATENCY
hwloc-2_8_0
Read latency in nanoseconds, as seen from the given initiator location - HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
hwloc-2_8_0
Write bandwidth in MiB/s, as seen from the given initiator location - HWLOC_MEMATTR_ID_WRITE_LATENCY
hwloc-2_8_0
Write latency in nanoseconds, as seen from the given initiator location - Allocate memory on the specified nodes (most portable option)
- Consider the bitmap argument as a nodeset.
- Reset the memory allocation policy of the current process or thread to the system default
- Allocate each memory page individually on the local NUMA node of the thread that touches it
- Allocate memory on the given nodes in an interleaved round-robin manner
- Migrate existing allocated memory
- Mixture of memory binding policies
- Migrate pages on next touch
- Avoid any effect on CPU binding
- Apply command to all threads of the specified process
- Request strict binding from the OS
- Apply command to the current thread of the current process
- Bridge (filtered out by default)
- Host-side of a bridge, only possible upstream
- PCI-side of a bridge
- Data cache
- Instruction cache (filtered out by default)
- Unified cache
- A computation unit (may be shared by several PUs aka logical processors)
- HWLOC_OBJ_DIE
hwloc-2_1_0
Die within a physical package - Group object
- Level 1 Data (or Unified) Cache
- Level 1 Instruction cache (filtered out by default)
- Level 2 Data (or Unified) Cache
- Level 2 Instruction cache (filtered out by default)
- Level 3 Data (or Unified) Cache
- Level 3 Instruction cache (filtered out by default)
- Level 4 Data (or Unified) Cache
- Level 5 Data (or Unified) Cache
- The root object, a set of processors and memory with cache coherency
- HWLOC_OBJ_MEMCACHE
hwloc-2_1_0
Memory-side cache (filtered out by default) - Miscellaneous object (filtered out by default)
- NUMA node
- Operating system co-processor device
- Operating system dma engine device
- Operating system GPU device
- Operating system network device
- Operating system openfabrics device
- Operating system storage device (e.g. block)
- Operating system device (filtered out by default)
- Physical package, what goes into a physical motherboard socket
- PCI device (filtered out by default)
- Processing Unit, or (Logical) Processor
- HWLOC_RESTRICT_FLAG_ADAPT_IO
hwloc-2_3_0
Move I/O objects to ancestors if their parents are removed during restriction - HWLOC_RESTRICT_FLAG_ADAPT_MISC
hwloc-2_3_0
Move Misc objects to ancestors if their parents are removed during restriction - HWLOC_RESTRICT_FLAG_BYNODESET
hwloc-2_3_0
Restrict by NUMA node set insted of by CPU set - HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
hwloc-2_3_0
Remove all objects that became CPU-less - HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
hwloc-2_3_0
Remove all objects that became memory-less - HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST
hwloc-2_1_0
Blacklist the target component from being used - Do not export memory information
- Do not export level attributes
- Export extended types such as L2dcache as basic types such as Cache
- Export the memory hierarchy as expected in hwloc 1.x
- Export XML that is loadable by hwloc v1.x
- HWLOC_TOPOLOGY_FLAG_DONT_CHANGE_BINDING
hwloc-2_5_0
Do not ever modify the process or thread binding during discovery - HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT
hwloc-2_3_0
Import support from the imported topology - Detect the whole system, ignore reservations, include disallowed objects
- Assume that the selected backend provides the topology for the system on which we are running
- HWLOC_TOPOLOGY_FLAG_NO_CPUKINDS
hwloc-2_8_0
Ignore CPU kind information from the operating system (and from XML) - HWLOC_TOPOLOGY_FLAG_NO_DISTANCES
hwloc-2_8_0
Ignore distance information from the operating system (and from XML) - HWLOC_TOPOLOGY_FLAG_NO_MEMATTRS
hwloc-2_8_0
Ignore memory attribues from the operating system (and from XML) - HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_CPUBINDING
hwloc-2_5_0
Do not consider resources outside of the process CPU binding - HWLOC_TOPOLOGY_FLAG_RESTRICT_TO_MEMBINDING
hwloc-2_5_0
Do not consider resources outside of the process memory binding - Get the set of allowed resources from the local operating system even if the topology was loaded from XML or synthetic description
- Virtual depth for
HWLOC_OBJ_BRIDGE
- HWLOC_TYPE_DEPTH_MEMCACHE
hwloc-2_1_0
Virtual depth forHWLOC_OBJ_MEMCACHE
- Virtual depth for
HWLOC_OBJ_MISC
- Objects of given type exist at different depth in the topology (only for Groups)
- Virtual depth for
HWLOC_OBJ_NUMANODE
- Virtual depth for
HWLOC_OBJ_OS_DEVICE
- Virtual depth for
HWLOC_OBJ_PCI_DEVICE
- No object of given type exists in the topology
- Keep all objects of this type
- Only keep likely-important objects of the given type.
- Ignore all objects of this type
- Only ignore objects if their entire level does not bring any structure
- Value returned by
hwloc_compare_types()
when types can not be compared - Value of
hwloc_obj::os_index
when unknown or irrelevant for this object
Functions§
- hwloc_bitmap_singlify_per_core⚠
hwloc-2_2_0
- Compare the depth of two object types.
- hwloc_cpukinds_get_by_cpuset⚠
hwloc-2_4_0
- hwloc_cpukinds_get_info⚠
hwloc-2_4_0
- hwloc_cpukinds_get_nr⚠
hwloc-2_4_0
- hwloc_cpukinds_register⚠
hwloc-2_4_0
- hwloc_distances_add_commit⚠
hwloc-2_5_0
- hwloc_distances_add_create⚠
hwloc-2_5_0
- hwloc_distances_add_values⚠
hwloc-2_5_0
- hwloc_distances_get_by_name⚠
hwloc-2_1_0
- hwloc_distances_get_name⚠
hwloc-2_1_0
- hwloc_distances_release_remove⚠
hwloc-2_3_0
- hwloc_distances_remove⚠
hwloc-2_3_0
- hwloc_distances_remove_by_depth⚠
hwloc-2_3_0
- hwloc_distances_transform⚠
hwloc-2_5_0
- Indicate at runtime which hwloc API version was used at build time
- hwloc_get_local_numanode_objs⚠
hwloc-2_3_0
- hwloc_get_obj_with_same_locality⚠
hwloc-2_5_0
- hwloc_memattr_get_best_initiator⚠
hwloc-2_3_0
- hwloc_memattr_get_best_target⚠
hwloc-2_3_0
- hwloc_memattr_get_by_name⚠
hwloc-2_3_0
- hwloc_memattr_get_flags⚠
hwloc-2_3_0
- hwloc_memattr_get_initiators⚠
hwloc-2_3_0
- hwloc_memattr_get_name⚠
hwloc-2_3_0
- hwloc_memattr_get_targets⚠
hwloc-2_3_0
- hwloc_memattr_get_value⚠
hwloc-2_3_0
- hwloc_memattr_register⚠
hwloc-2_3_0
- hwloc_memattr_set_value⚠
hwloc-2_3_0
- hwloc_obj_add_other_obj_sets⚠
hwloc-2_3_0
- Check that this topology is compatible with the current hwloc library
- hwloc_topology_alloc_group_object⚠
hwloc-2_3_0
- hwloc_topology_allow⚠
hwloc-2_3_0
- Run internal checks on a topology structure
- Terminate and free a topology context
- Duplicate a topology
- hwloc_topology_free_group_object⚠
hwloc-2_10_0
- Allocate a topology context
- hwloc_topology_insert_group_object⚠
hwloc-2_3_0
- hwloc_topology_insert_misc_object⚠
hwloc-2_3_0
- Build the actual topology
- hwloc_topology_refresh⚠
hwloc-2_3_0
- hwloc_topology_restrict⚠
hwloc-2_3_0
- hwloc_topology_set_components⚠
hwloc-2_1_0
- hwloc_windows_get_nr_processor_groups⚠
hwloc-2_5_0
and Windows - hwloc_windows_get_processor_group_cpuset⚠
hwloc-2_5_0
and Windows
Type Aliases§
- PCI domain width (depends on hwloc version)
- hwloc_allow_flags_e
hwloc-2_3_0
Flags to be given tohwloc_topology_allow()
- Set of bits represented as an opaque pointer to an internal bitmap
- A non-modifiable
hwloc_bitmap_t
- A non-modifiable
hwloc_cpuset_t
- A non-modifiable
hwloc_nodeset_t
- A non-modifiable
hwloc_topology_t
- Process/Thread binding flags
- A CPU set is a bitmap whose bits are set according to CPU physical OS indexes
- hwloc_distances_add_flag_e
hwloc-2_5_0
Flags to be given tohwloc_distances_add_commit()
- hwloc_distances_add_handle_t
hwloc-2_5_0
Handle to a new distances structure during its addition to the topology - Kinds of distance matrices
- hwloc_distances_transform_e
hwloc-2_5_0
Transformations of distances structures - Flags to be given to
hwloc_distrib()
- Depth of an object (or object type) in the topology
- hwloc_local_numanode_flag_e
hwloc-2_3_0
Flags for selecting more target NUMA nodes - hwloc_location_type_e
hwloc-2_3_0
Type of location - hwloc_memattr_flag_e
hwloc-2_3_0
Memory attribute flags - hwloc_memattr_id_t
hwloc-2_3_0
Memory attribute identifier - Memory binding flags.
- Memory binding policy.
- A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes
- Type of one side (upstream or downstream) of an I/O bridge
- Cache type
- Type of a OS device
- Convenience typedef, a pointer to a struct
hwloc_obj
- Type of topology object
- Process identifier (OS-specific)
- hwloc_restrict_flags_e
hwloc-2_3_0
Flags to be given tohwloc_topology_restrict()
- Thread identifier (OS-specific)
- hwloc_topology_components_flag_e
hwloc-2_1_0
Flags to be passed tohwloc_topology_set_components()
- Flags to be given to
hwloc_topology_export_synthetic()
- Flags to be given to
hwloc_topology_export_xml()
- Topology building configuration flags
- Topology context
- Type filtering flags
Unions§
- Downstream device attributes
- Upstream device attributes
- hwloc_location_u
hwloc-2_3_0
Actual location hwloc_obj_type_t
-specific attributes