Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.1

  |   Home   |   Support   |   FAQ   |  

hwloc.h File Reference

The hwloc API. More...

#include <hwloc/config.h>
#include <sys/types.h>
#include <stdio.h>
#include <string.h>
#include <limits.h>
#include <hwloc/rename.h>
#include <hwloc/bitmap.h>
#include <hwloc/cpuset.h>
#include <hwloc/helper.h>

Go to the source code of this file.

Data Structures

struct  hwloc_obj_memory_s
 Object memory. More...
struct  hwloc_obj_memory_s::hwloc_obj_memory_page_type_s
 Array of local memory page types, NULL if no local memory and page_types is 0. More...
struct  hwloc_obj
 Structure of a topology object. More...
union  hwloc_obj_attr_u
 Object type-specific Attributes. More...
struct  hwloc_obj_attr_u::hwloc_cache_attr_s
 Cache-specific Object Attributes. More...
struct  hwloc_obj_attr_u::hwloc_group_attr_s
 Group-specific Object Attributes. More...
struct  hwloc_obj_info_s
 Object info. More...
struct  hwloc_topology_discovery_support
 Flags describing actual discovery support for this topology. More...
struct  hwloc_topology_cpubind_support
 Flags describing actual PU binding support for this topology. More...
struct  hwloc_topology_membind_support
 Flags describing actual memory binding support for this topology. More...
struct  hwloc_topology_support
 Set of flags describing actual support for this topology. More...

Defines

#define HWLOC_API_VERSION   0x00010100
 Indicate at build time which hwloc API version is being used.

Typedefs

typedef struct hwloc_topology * hwloc_topology_t
 Topology context.
typedef hwloc_bitmap_t hwloc_cpuset_t
 A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
typedef hwloc_const_bitmap_t hwloc_const_cpuset_t
 A non-modifiable hwloc_cpuset_t.
typedef hwloc_bitmap_t hwloc_nodeset_t
 A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
typedef hwloc_const_bitmap_t hwloc_const_nodeset_t
 A non-modifiable hwloc_nodeset_t.
typedef struct hwloc_objhwloc_obj_t
 Convenience typedef; a pointer to a struct hwloc_obj.

Enumerations

enum  hwloc_obj_type_t {
  HWLOC_OBJ_SYSTEM, HWLOC_OBJ_MACHINE, HWLOC_OBJ_NODE, HWLOC_OBJ_SOCKET,
  HWLOC_OBJ_CACHE, HWLOC_OBJ_CORE, HWLOC_OBJ_PU, HWLOC_OBJ_GROUP,
  HWLOC_OBJ_MISC
}
 

Type of topology object.

More...
enum  hwloc_compare_types_e { HWLOC_TYPE_UNORDERED }
enum  hwloc_topology_flags_e { HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM, HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM }
 

Flags to be set onto a topology context before load.

More...
enum  hwloc_get_type_depth_e { HWLOC_TYPE_DEPTH_UNKNOWN, HWLOC_TYPE_DEPTH_MULTIPLE }
enum  hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS, HWLOC_CPUBIND_THREAD, HWLOC_CPUBIND_STRICT, HWLOC_CPUBIND_NOMEMBIND }
 

Process/Thread binding flags.

More...
enum  hwloc_membind_policy_t {
  HWLOC_MEMBIND_DEFAULT, HWLOC_MEMBIND_FIRSTTOUCH, HWLOC_MEMBIND_BIND, HWLOC_MEMBIND_INTERLEAVE,
  HWLOC_MEMBIND_REPLICATE, HWLOC_MEMBIND_NEXTTOUCH
}
 

Memory binding policy.

More...
enum  hwloc_membind_flags_t {
  HWLOC_MEMBIND_PROCESS, HWLOC_MEMBIND_THREAD, HWLOC_MEMBIND_STRICT, HWLOC_MEMBIND_MIGRATE,
  HWLOC_MEMBIND_NOCPUBIND
}
 

Memory binding flags.

More...

Functions

int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2)
 Compare the depth of two object types.
int hwloc_topology_init (hwloc_topology_t *topologyp)
 Allocate a topology context.
int hwloc_topology_load (hwloc_topology_t topology)
 Build the actual topology.
void hwloc_topology_destroy (hwloc_topology_t topology)
 Terminate and free a topology context.
void hwloc_topology_check (hwloc_topology_t topology)
 Run internal checks on a topology structure.
int hwloc_topology_ignore_type (hwloc_topology_t topology, hwloc_obj_type_t type)
 Ignore an object type.
int hwloc_topology_ignore_type_keep_structure (hwloc_topology_t topology, hwloc_obj_type_t type)
 Ignore an object type if it does not bring any structure.
int hwloc_topology_ignore_all_keep_structure (hwloc_topology_t topology)
 Ignore all objects that do not bring any structure.
int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags)
 Set OR'ed flags to non-yet-loaded topology.
int hwloc_topology_set_fsroot (hwloc_topology_t restrict topology, const char *restrict fsroot_path)
 Change the file-system root path when building the topology from sysfs/procfs.
int hwloc_topology_set_pid (hwloc_topology_t restrict topology, hwloc_pid_t pid)
 Change which pid the topology is viewed from.
int hwloc_topology_set_synthetic (hwloc_topology_t restrict topology, const char *restrict description)
 Enable synthetic topology.
int hwloc_topology_set_xml (hwloc_topology_t restrict topology, const char *restrict xmlpath)
 Enable XML-file based topology.
int hwloc_topology_set_xmlbuffer (hwloc_topology_t restrict topology, const char *restrict buffer, int size)
 Enable XML based topology using a memory buffer instead of a file.
struct
hwloc_topology_support
hwloc_topology_get_support (hwloc_topology_t restrict topology)
 Retrieve the topology support.
void hwloc_topology_export_xml (hwloc_topology_t topology, const char *xmlpath)
 Export the topology into an XML file.
void hwloc_topology_export_xmlbuffer (hwloc_topology_t topology, char **xmlbuffer, int *buflen)
 Export the topology into a newly-allocated XML memory buffer.
hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name)
 Add a MISC object to the topology.
hwloc_obj_t hwloc_topology_insert_misc_object_by_parent (hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
 Add a MISC object to the topology.
unsigned hwloc_topology_get_depth (hwloc_topology_t restrict topology)
 Get the depth of the hierachical tree of objects.
int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type)
 Returns the depth of objects of type type.
hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth)
 Returns the type of objects at depth depth.
unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth)
 Returns the width of level at depth depth.
static inline int
 
hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
 Returns the width of level type type.
int hwloc_topology_is_thissystem (hwloc_topology_t restrict topology)
 Does the topology context come from this system?
hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx)
 Returns the topology object at index index from depth depth.
static inline
hwloc_obj_t
 
hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
 Returns the topology object at index index with type type.
const char * hwloc_obj_type_string (hwloc_obj_type_t type)
 Return a stringified topology object type.
hwloc_obj_type_t hwloc_obj_type_of_string (const char *string)
 Return an object type from the string.
int hwloc_obj_type_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
 Stringify the type of a given topology object into a human-readable form.
int hwloc_obj_attr_snprintf (char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
 Stringify the attributes of a given topology object into a human-readable form.
int hwloc_obj_snprintf (char *restrict string, size_t size, hwloc_topology_t topology, hwloc_obj_t obj, const char *restrict indexprefix, int verbose)
 Stringify a given topology object into a human-readable form.
int hwloc_obj_cpuset_snprintf (char *restrict str, size_t size, size_t nobj, const hwloc_obj_t *restrict objs)
 Stringify the cpuset containing a set of objects.
static inline char
hwloc_obj_get_info_by_name (hwloc_obj_t obj, const char *name)
 Search the given key name in object infos and return the corresponding value.
int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
 Bind current process or thread on cpus given in bitmap set.
int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
 Get current process or thread binding.
int hwloc_set_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
 Bind a process pid on cpus given in bitmap set.
int hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
 Get the current binding of process pid.
int hwloc_set_membind_nodeset (hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)
 Bind current process memory on the given nodeset nodeset.
int hwloc_set_membind (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)
 Bind current process memory on memory nodes near the given cpuset cpuset.
int hwloc_get_membind_nodeset (hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t *policy, int flags)
 Get current process memory binding in nodeset nodeset.
int hwloc_get_membind (hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t *policy, int flags)
 Get current process memory binding in cpuset cpuset.
int hwloc_set_proc_membind_nodeset (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)
 Bind given process memory on the given nodeset nodeset.
int hwloc_set_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)
 Bind given process memory on memory nodes near the given cpuset cpuset.
int hwloc_get_proc_membind_nodeset (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_nodeset_t nodeset, hwloc_membind_policy_t *policy, int flags)
 Get current process memory binding in nodeset nodeset.
int hwloc_get_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t *policy, int flags)
 Get current process memory binding in cpuset cpuset.
int hwloc_set_area_membind_nodeset (hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)
 Bind some memory range on the given nodeset nodeset.
int hwloc_set_area_membind (hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)
 Bind some memory range on memory nodes near the given cpuset cpuset.
int hwloc_get_area_membind_nodeset (hwloc_topology_t topology, const void *addr, size_t len, hwloc_nodeset_t nodeset, hwloc_membind_policy_t *policy, int flags)
 Get some memory range memory binding in nodeset nodeset.
int hwloc_get_area_membind (hwloc_topology_t topology, const void *addr, size_t len, hwloc_cpuset_t cpuset, hwloc_membind_policy_t *policy, int flags)
 Get some memory range memory binding in cpuset cpuset.
void * hwloc_alloc (hwloc_topology_t topology, size_t len)
 Allocate some memory.
void * hwloc_alloc_membind_nodeset (hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)
 Allocate some memory on the given nodeset nodeset.
void * hwloc_alloc_membind (hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)
 Allocate some memory on memory nodes near the given cpuset cpuset.
int hwloc_free (hwloc_topology_t topology, void *addr, size_t len)
 Free some memory allocated by hwloc_alloc() or hwloc_alloc_membind().

Detailed Description

The hwloc API.

See hwloc/bitmap.h for bitmap specific macros. See hwloc/helper.h for high-level topology traversal helpers.