hwloc.h

/*
 * Copyright © 2009 CNRS
 * Copyright © 2009-2019 Inria.  All rights reserved.
 * Copyright © 2009-2012 Université Bordeaux
 * 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.  :-)
 *
 * Moreover there are several examples of hwloc use under doc/examples
 * in the source tree.
 *
 *=====================================================================*/

#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 0x00020000

HWLOC_DECLSPEC unsigned hwloc_get_api_version(void);

#define HWLOC_COMPONENT_ABI 5

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;

#define HWLOC_OBJ_TYPE_MIN HWLOC_OBJ_MACHINE 
typedef enum {
  HWLOC_OBJ_MACHINE,    
  HWLOC_OBJ_PACKAGE,    
  HWLOC_OBJ_CORE,       
  HWLOC_OBJ_PU,         
  HWLOC_OBJ_L1CACHE,    
  HWLOC_OBJ_L2CACHE,    
  HWLOC_OBJ_L3CACHE,    
  HWLOC_OBJ_L4CACHE,    
  HWLOC_OBJ_L5CACHE,    
  HWLOC_OBJ_L1ICACHE,   
  HWLOC_OBJ_L2ICACHE,   
  HWLOC_OBJ_L3ICACHE,   
  HWLOC_OBJ_GROUP,      
  HWLOC_OBJ_NUMANODE,   
  HWLOC_OBJ_BRIDGE,     
  HWLOC_OBJ_PCI_DEVICE, 
  HWLOC_OBJ_OS_DEVICE,  
  HWLOC_OBJ_MISC,       
  HWLOC_OBJ_TYPE_MAX    
} 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_COPROC        
} hwloc_obj_osdev_type_t;

HWLOC_DECLSPEC int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) __hwloc_attribute_const;

enum hwloc_compare_types_e {
    HWLOC_TYPE_UNORDERED = INT_MAX      
};

union hwloc_obj_attr_u;

struct hwloc_obj {
  /* physical information */
  hwloc_obj_type_t type;                
  char *subtype;                        
  unsigned os_index;                    
#define HWLOC_UNKNOWN_INDEX (unsigned)-1

  char *name;                           
  hwloc_uint64_t total_memory; 
  union hwloc_obj_attr_u *attr;         
  /* global position */
  int depth;                            
  unsigned logical_index;               
  /* 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;       
  unsigned arity;                       
  struct hwloc_obj **children;          
  struct hwloc_obj *first_child;        
  struct hwloc_obj *last_child;         
  int symmetric_subtree;                
  unsigned memory_arity;                
  struct hwloc_obj *memory_first_child; 
  unsigned io_arity;                    
  struct hwloc_obj *io_first_child;     
  unsigned misc_arity;                  
  struct hwloc_obj *misc_first_child;   
  /* cpusets and nodesets */
  hwloc_cpuset_t cpuset;                
  hwloc_cpuset_t complete_cpuset;       
  hwloc_nodeset_t nodeset;              
  hwloc_nodeset_t complete_nodeset;     
  struct hwloc_info_s *infos;           
  unsigned infos_count;                 
  /* misc */
  void *userdata;                       
  hwloc_uint64_t gp_index;                      
};
typedef struct hwloc_obj * hwloc_obj_t;

union hwloc_obj_attr_u {
  struct hwloc_numanode_attr_s {
    hwloc_uint64_t local_memory; 
    unsigned page_types_len; 
    struct hwloc_memory_page_type_s {
      hwloc_uint64_t size;      
      hwloc_uint64_t count;     
    } * page_types;
  } numanode;

  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;                       
    unsigned kind;                        
    unsigned subkind;                     
    unsigned char dont_merge;             
  } 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_info_s {
  char *name;   
  char *value;  
};

struct hwloc_topology;
typedef struct hwloc_topology * hwloc_topology_t;

HWLOC_DECLSPEC int hwloc_topology_init (hwloc_topology_t *topologyp);

HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology);

HWLOC_DECLSPEC void hwloc_topology_destroy (hwloc_topology_t topology);

HWLOC_DECLSPEC int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology);

HWLOC_DECLSPEC int hwloc_topology_abi_check(hwloc_topology_t topology);

HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology);

HWLOC_DECLSPEC int hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;

HWLOC_DECLSPEC 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_NUMANODE = -3,   
    HWLOC_TYPE_DEPTH_BRIDGE = -4,     
    HWLOC_TYPE_DEPTH_PCI_DEVICE = -5, 
    HWLOC_TYPE_DEPTH_OS_DEVICE = -6,  
    HWLOC_TYPE_DEPTH_MISC = -7        
};

HWLOC_DECLSPEC int hwloc_get_memory_parents_depth (hwloc_topology_t topology);

static __hwloc_inline int
hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;

static __hwloc_inline int
hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;

HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;

HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;

static __hwloc_inline int
hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;

static __hwloc_inline hwloc_obj_t
hwloc_get_root_obj (hwloc_topology_t topology) __hwloc_attribute_pure;

HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx) __hwloc_attribute_pure;

static __hwloc_inline hwloc_obj_t
hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;

static __hwloc_inline hwloc_obj_t
hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev);

static __hwloc_inline hwloc_obj_t
hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type,
                            hwloc_obj_t prev);

HWLOC_DECLSPEC const char * hwloc_obj_type_string (hwloc_obj_type_t type) __hwloc_attribute_const;

HWLOC_DECLSPEC int hwloc_obj_type_snprintf(char * __hwloc_restrict string, size_t size,
                                           hwloc_obj_t obj,
                                           int verbose);

HWLOC_DECLSPEC int hwloc_obj_attr_snprintf(char * __hwloc_restrict string, size_t size,
                                           hwloc_obj_t obj, const char * __hwloc_restrict separator,
                                           int verbose);

HWLOC_DECLSPEC int hwloc_type_sscanf(const char *string,
                                     hwloc_obj_type_t *typep,
                                     union hwloc_obj_attr_u *attrp, size_t attrsize);

HWLOC_DECLSPEC int hwloc_type_sscanf_as_depth(const char *string,
                                              hwloc_obj_type_t *typep,
                                              hwloc_topology_t topology, int *depthp);

static __hwloc_inline const char *
hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_pure;

HWLOC_DECLSPEC int 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;

HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);

HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);

HWLOC_DECLSPEC int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);

HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);

#ifdef hwloc_thread_t

HWLOC_DECLSPEC 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

HWLOC_DECLSPEC int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
#endif

HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);

HWLOC_DECLSPEC 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_NEXTTOUCH =     4,

  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_BYNODESET =     (1<<5)
} hwloc_membind_flags_t;

HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);

HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);

HWLOC_DECLSPEC int hwloc_set_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);

HWLOC_DECLSPEC int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);

HWLOC_DECLSPEC int hwloc_set_area_membind(hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);

HWLOC_DECLSPEC int hwloc_get_area_membind(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);

HWLOC_DECLSPEC int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags);

HWLOC_DECLSPEC void *hwloc_alloc(hwloc_topology_t topology, size_t len);

HWLOC_DECLSPEC void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags) __hwloc_attribute_malloc;

static __hwloc_inline void *
hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags) __hwloc_attribute_malloc;

HWLOC_DECLSPEC int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);

HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topology, hwloc_pid_t pid);

HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict description);

HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict xmlpath);

HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict buffer, int size);

enum hwloc_topology_flags_e {
  HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1UL<<0),

  HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1UL<<1),

  HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES = (1UL<<2)
};

HWLOC_DECLSPEC int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);

HWLOC_DECLSPEC unsigned long hwloc_topology_get_flags (hwloc_topology_t topology);

HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t  __hwloc_restrict topology) __hwloc_attribute_pure;

struct hwloc_topology_discovery_support {
  unsigned char pu;
  unsigned char numa;
  unsigned char numa_memory;
};

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 nexttouch_membind;
  unsigned char migrate_membind;
  unsigned char get_area_memlocation;
};

struct hwloc_topology_support {
  struct hwloc_topology_discovery_support *discovery;
  struct hwloc_topology_cpubind_support *cpubind;
  struct hwloc_topology_membind_support *membind;
};

HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology);

enum hwloc_type_filter_e {
  HWLOC_TYPE_FILTER_KEEP_ALL = 0,

  HWLOC_TYPE_FILTER_KEEP_NONE = 1,

  HWLOC_TYPE_FILTER_KEEP_STRUCTURE = 2,

  HWLOC_TYPE_FILTER_KEEP_IMPORTANT = 3
};

HWLOC_DECLSPEC int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter);

HWLOC_DECLSPEC int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter);

HWLOC_DECLSPEC int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);

HWLOC_DECLSPEC int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);

HWLOC_DECLSPEC int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);

HWLOC_DECLSPEC int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);

HWLOC_DECLSPEC void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata);

HWLOC_DECLSPEC void * hwloc_topology_get_userdata(hwloc_topology_t topology);

enum hwloc_restrict_flags_e {
  HWLOC_RESTRICT_FLAG_REMOVE_CPULESS = (1UL<<0),

  HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1UL<<1),

  HWLOC_RESTRICT_FLAG_ADAPT_IO = (1UL<<2)
};

HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);

HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);

HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology);

HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group);

HWLOC_DECLSPEC int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src);

#ifdef __cplusplus
} /* extern "C" */
#endif


/* high-level helpers */
#include <hwloc/helper.h>

/* inline code of some functions above */
#include <hwloc/inlines.h>

/* exporting to XML or synthetic */
#include <hwloc/export.h>

/* distances */
#include <hwloc/distances.h>

/* topology diffs */
#include <hwloc/diff.h>

/* deprecated headers */
#include <hwloc/deprecated.h>

#endif /* HWLOC_H */