hwloc.h
/*
* Copyright © 2009 CNRS
* Copyright © 2009-2013 Inria. All rights reserved.
* Copyright © 2009-2012 Université Bordeaux 1
* Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
* See COPYING in top-level directory.
*/
/*=====================================================================
* PLEASE GO READ THE DOCUMENTATION!
* ------------------------------------------------
* $tarball_directory/doc/doxygen-doc/
* or
* http://www.open-mpi.org/projects/hwloc/doc/
*=====================================================================
*
* FAIR WARNING: Do NOT expect to be able to figure out all the
* subtleties of hwloc by simply reading function prototypes and
* constant descrptions here in this file.
*
* Hwloc has wonderful documentation in both PDF and HTML formats for
* your reading pleasure. The formal documentation explains a LOT of
* hwloc-specific concepts, provides definitions, and discusses the
* "big picture" for many of the things that you'll find here in this
* header file.
*
* The PDF/HTML documentation was generated via Doxygen; much of what
* you'll see in there is also here in this file. BUT THERE IS A LOT
* THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
*
* There are entire paragraph-length descriptions, discussions, and
* pretty prictures to explain subtle corner cases, provide concrete
* examples, etc.
*
* Please, go read the documentation. :-)
*
*=====================================================================*/
#ifndef HWLOC_H
#define HWLOC_H
#include <hwloc/autogen/config.h>
#include <sys/types.h>
#include <stdio.h>
#include <string.h>
#include <limits.h>
/*
* Symbol transforms
*/
#include <hwloc/rename.h>
/*
* Bitmap definitions
*/
#include <hwloc/bitmap.h>
#ifdef __cplusplus
extern "C" {
#endif
#define HWLOC_API_VERSION 0x00010600
unsigned hwloc_get_api_version(void);
struct hwloc_topology;
typedef struct hwloc_topology * hwloc_topology_t;
typedef hwloc_bitmap_t hwloc_cpuset_t;
typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
typedef hwloc_bitmap_t hwloc_nodeset_t;
typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
typedef enum {
/* ***************************************************************
WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
If new enum values are added here, you MUST also go update the
obj_type_order[] and obj_order_type[] arrays in src/topology.c.
WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
*************************************************************** */
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,
HWLOC_OBJ_BRIDGE,
HWLOC_OBJ_PCI_DEVICE,
HWLOC_OBJ_OS_DEVICE,
HWLOC_OBJ_TYPE_MAX
/* ***************************************************************
WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
If new enum values are added here, you MUST also go update the
obj_type_order[] and obj_order_type[] arrays in src/topology.c.
WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
*************************************************************** */
} hwloc_obj_type_t;
typedef enum hwloc_obj_cache_type_e {
HWLOC_OBJ_CACHE_UNIFIED,
HWLOC_OBJ_CACHE_DATA,
HWLOC_OBJ_CACHE_INSTRUCTION
} hwloc_obj_cache_type_t;
typedef enum hwloc_obj_bridge_type_e {
HWLOC_OBJ_BRIDGE_HOST,
HWLOC_OBJ_BRIDGE_PCI
} hwloc_obj_bridge_type_t;
typedef enum hwloc_obj_osdev_type_e {
HWLOC_OBJ_OSDEV_BLOCK,
HWLOC_OBJ_OSDEV_GPU,
HWLOC_OBJ_OSDEV_NETWORK,
HWLOC_OBJ_OSDEV_OPENFABRICS,
HWLOC_OBJ_OSDEV_DMA
} hwloc_obj_osdev_type_t;
int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) ;
enum hwloc_compare_types_e {
HWLOC_TYPE_UNORDERED = INT_MAX
};
union hwloc_obj_attr_u;
struct hwloc_obj_memory_s {
hwloc_uint64_t total_memory;
hwloc_uint64_t local_memory;
unsigned page_types_len;
struct hwloc_obj_memory_page_type_s {
hwloc_uint64_t size;
hwloc_uint64_t count;
} * page_types;
};
struct hwloc_obj {
/* physical information */
hwloc_obj_type_t type;
unsigned os_index;
char *name;
struct hwloc_obj_memory_s memory;
union hwloc_obj_attr_u *attr;
/* global position */
unsigned depth;
unsigned logical_index;
signed os_level;
/* cousins are all objects of the same type (and depth) across the entire topology */
struct hwloc_obj *next_cousin;
struct hwloc_obj *prev_cousin;
/* children of the same parent are siblings, even if they may have different type and depth */
struct hwloc_obj *parent;
unsigned sibling_rank;
struct hwloc_obj *next_sibling;
struct hwloc_obj *prev_sibling;
/* children array below this object */
unsigned arity;
struct hwloc_obj **children;
struct hwloc_obj *first_child;
struct hwloc_obj *last_child;
/* misc */
void *userdata;
/* cpusets and nodesets */
hwloc_cpuset_t cpuset;
hwloc_cpuset_t complete_cpuset;
hwloc_cpuset_t online_cpuset;
hwloc_cpuset_t allowed_cpuset;
hwloc_nodeset_t nodeset;
hwloc_nodeset_t complete_nodeset;
hwloc_nodeset_t allowed_nodeset;
struct hwloc_distances_s **distances;
unsigned distances_count;
struct hwloc_obj_info_s *infos;
unsigned infos_count;
int symmetric_subtree;
};
typedef struct hwloc_obj * hwloc_obj_t;
union hwloc_obj_attr_u {
struct hwloc_cache_attr_s {
hwloc_uint64_t size;
unsigned depth;
unsigned linesize;
int associativity;
hwloc_obj_cache_type_t type;
} cache;
struct hwloc_group_attr_s {
unsigned depth;
} group;
struct hwloc_pcidev_attr_s {
unsigned short domain;
unsigned char bus, dev, func;
unsigned short class_id;
unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
unsigned char revision;
float linkspeed; /* in GB/s */
} pcidev;
struct hwloc_bridge_attr_s {
union {
struct hwloc_pcidev_attr_s pci;
} upstream;
hwloc_obj_bridge_type_t upstream_type;
union {
struct {
unsigned short domain;
unsigned char secondary_bus, subordinate_bus;
} pci;
} downstream;
hwloc_obj_bridge_type_t downstream_type;
unsigned depth;
} bridge;
struct hwloc_osdev_attr_s {
hwloc_obj_osdev_type_t type;
} osdev;
};
struct hwloc_distances_s {
unsigned relative_depth;
unsigned nbobjs;
float *latency;
float latency_max;
float latency_base;
};
struct hwloc_obj_info_s {
char *name;
char *value;
};
int hwloc_topology_init (hwloc_topology_t *topologyp);
int hwloc_topology_load(hwloc_topology_t topology);
void hwloc_topology_destroy (hwloc_topology_t topology);
void hwloc_topology_check(hwloc_topology_t topology);
int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
enum hwloc_topology_flags_e {
HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1<<0),
HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1<<1),
HWLOC_TOPOLOGY_FLAG_IO_DEVICES = (1<<2),
HWLOC_TOPOLOGY_FLAG_IO_BRIDGES = (1<<3),
HWLOC_TOPOLOGY_FLAG_WHOLE_IO = (1<<4),
HWLOC_TOPOLOGY_FLAG_ICACHES = (1<<5)
};
int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
int hwloc_topology_set_pid(hwloc_topology_t restrict topology, hwloc_pid_t pid);
int hwloc_topology_set_fsroot(hwloc_topology_t restrict topology, const char * restrict fsroot_path);
int hwloc_topology_set_synthetic(hwloc_topology_t restrict topology, const char * restrict description);
int hwloc_topology_set_xml(hwloc_topology_t restrict topology, const char * restrict xmlpath);
int hwloc_topology_set_xmlbuffer(hwloc_topology_t restrict topology, const char * restrict buffer, int size);
int hwloc_topology_set_custom(hwloc_topology_t topology);
int hwloc_topology_set_distance_matrix(hwloc_topology_t restrict topology,
hwloc_obj_type_t type, unsigned nbobjs,
unsigned *os_index, float *distances);
struct hwloc_topology_discovery_support {
unsigned char pu;
};
struct hwloc_topology_cpubind_support {
unsigned char set_thisproc_cpubind;
unsigned char get_thisproc_cpubind;
unsigned char set_proc_cpubind;
unsigned char get_proc_cpubind;
unsigned char set_thisthread_cpubind;
unsigned char get_thisthread_cpubind;
unsigned char set_thread_cpubind;
unsigned char get_thread_cpubind;
unsigned char get_thisproc_last_cpu_location;
unsigned char get_proc_last_cpu_location;
unsigned char get_thisthread_last_cpu_location;
};
struct hwloc_topology_membind_support {
unsigned char set_thisproc_membind;
unsigned char get_thisproc_membind;
unsigned char set_proc_membind;
unsigned char get_proc_membind;
unsigned char set_thisthread_membind;
unsigned char get_thisthread_membind;
unsigned char set_area_membind;
unsigned char get_area_membind;
unsigned char alloc_membind;
unsigned char firsttouch_membind;
unsigned char bind_membind;
unsigned char interleave_membind;
unsigned char replicate_membind;
unsigned char nexttouch_membind;
unsigned char migrate_membind;
};
struct hwloc_topology_support {
struct hwloc_topology_discovery_support *discovery;
struct hwloc_topology_cpubind_support *cpubind;
struct hwloc_topology_membind_support *membind;
};
const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t restrict topology);
int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
void hwloc_topology_set_userdata_export_callback(hwloc_topology_t topology,
void (*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj));
int hwloc_export_obj_userdata(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
int hwloc_export_obj_userdata_base64(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length);
void hwloc_topology_set_userdata_import_callback(hwloc_topology_t topology,
void (*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length));
hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
enum hwloc_restrict_flags_e {
HWLOC_RESTRICT_FLAG_ADAPT_DISTANCES = (1<<0),
HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1),
HWLOC_RESTRICT_FLAG_ADAPT_IO = (1<<2)
};
int hwloc_topology_restrict(hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
unsigned hwloc_topology_get_depth(hwloc_topology_t restrict topology) ;
int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
enum hwloc_get_type_depth_e {
HWLOC_TYPE_DEPTH_UNKNOWN = -1,
HWLOC_TYPE_DEPTH_MULTIPLE = -2,
HWLOC_TYPE_DEPTH_BRIDGE = -3,
HWLOC_TYPE_DEPTH_PCI_DEVICE = -4,
HWLOC_TYPE_DEPTH_OS_DEVICE = -5
};
hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) ;
unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) ;
static inline int
hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) ;
static inline int
hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
{
int depth = hwloc_get_type_depth(topology, type);
if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
return 0;
if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
return -1; /* FIXME: agregate nbobjs from different levels? */
return hwloc_get_nbobjs_by_depth(topology, depth);
}
int hwloc_topology_is_thissystem(hwloc_topology_t restrict topology) ;
hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) ;
static inline hwloc_obj_t
hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) ;
static inline hwloc_obj_t
hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
{
int depth = hwloc_get_type_depth(topology, type);
if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
return NULL;
if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
return NULL;
return hwloc_get_obj_by_depth(topology, depth, idx);
}
const char * hwloc_obj_type_string (hwloc_obj_type_t type) ;
hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) ;
int hwloc_obj_type_snprintf(char * restrict string, size_t size, hwloc_obj_t obj,
int verbose);
int hwloc_obj_attr_snprintf(char * restrict string, size_t size, hwloc_obj_t obj, const char * restrict separator,
int verbose);
int hwloc_obj_snprintf(char * restrict string, size_t size,
hwloc_topology_t topology, hwloc_obj_t obj,
const char * restrict indexprefix, int verbose);
int hwloc_obj_cpuset_snprintf(char * restrict str, size_t size, size_t nobj, const hwloc_obj_t * restrict objs);
static inline const char *
hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) ;
static inline const char *
hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
{
unsigned i;
for(i=0; i<obj->infos_count; i++)
if (!strcmp(obj->infos[i].name, name))
return obj->infos[i].value;
return NULL;
}
void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
typedef enum {
HWLOC_CPUBIND_PROCESS = (1<<0),
HWLOC_CPUBIND_THREAD = (1<<1),
HWLOC_CPUBIND_STRICT = (1<<2),
HWLOC_CPUBIND_NOMEMBIND = (1<<3)
} hwloc_cpubind_flags_t;
int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
#ifdef hwloc_thread_t
int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
#endif
#ifdef hwloc_thread_t
int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
#endif
int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
typedef enum {
HWLOC_MEMBIND_DEFAULT = 0,
HWLOC_MEMBIND_FIRSTTOUCH = 1,
HWLOC_MEMBIND_BIND = 2,
HWLOC_MEMBIND_INTERLEAVE = 3,
HWLOC_MEMBIND_REPLICATE = 4,
HWLOC_MEMBIND_NEXTTOUCH = 5,
HWLOC_MEMBIND_MIXED = -1
} hwloc_membind_policy_t;
typedef enum {
HWLOC_MEMBIND_PROCESS = (1<<0),
HWLOC_MEMBIND_THREAD = (1<<1),
HWLOC_MEMBIND_STRICT = (1<<2),
HWLOC_MEMBIND_MIGRATE = (1<<3),
HWLOC_MEMBIND_NOCPUBIND = (1<<4)
} hwloc_membind_flags_t;
int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
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);
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);
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);
int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
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);
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);
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);
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);
void *hwloc_alloc(hwloc_topology_t topology, size_t len);
void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) ;
void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags) ;
int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
int hwloc_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);
hwloc_obj_t hwloc_custom_insert_group_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth);
#ifdef __cplusplus
} /* extern "C" */
#endif
/* high-level helpers */
#include <hwloc/helper.h>
#endif /* HWLOC_H */