hwloc.h

/*
 * Copyright © 2009 CNRS
 * Copyright © 2009-2011 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>
#include <hwloc/cpuset.h>


#ifdef __cplusplus
extern "C" {
#endif


#define HWLOC_API_VERSION 0x00010400

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

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_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;                    
  } 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;  
};

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 void hwloc_topology_check(hwloc_topology_t topology);

HWLOC_DECLSPEC int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);

HWLOC_DECLSPEC int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);

HWLOC_DECLSPEC 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),
  /* \brief Detect PCI devices.
   *
   * By default, I/O devices are ignored. This flag enables I/O device
   * detection using the libpci backend. Only the common PCI devices (GPUs,
   * NICs, block devices, ...) and host bridges (objects that connect the host
   * objects to an I/O subsystem) will be added to the topology.
   * Uncommon devices and other bridges (such as PCI-to-PCI bridges) will be
   * ignored.
   */
  HWLOC_TOPOLOGY_FLAG_IO_DEVICES = (1<<2),

  /* \brief Detect PCI bridges.
   *
   * This flag should be combined with HWLOC_TOPOLOGY_FLAG_IO_DEVICES to enable
   * the detection of both common devices and of all useful bridges (bridges that
   * have at least one device behind them).
   */
  HWLOC_TOPOLOGY_FLAG_IO_BRIDGES = (1<<3),

  /* \brief Detect the whole PCI hierarchy.
   *
   * This flag enables detection of all I/O devices (even the uncommon ones)
   * and bridges (even those that have no device behind them) using the libpci
   * backend.
   */
  HWLOC_TOPOLOGY_FLAG_WHOLE_IO = (1<<4)
};

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

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

HWLOC_DECLSPEC int hwloc_topology_set_fsroot(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict fsroot_path);

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);

HWLOC_DECLSPEC int hwloc_topology_set_custom(hwloc_topology_t topology);

HWLOC_DECLSPEC int hwloc_topology_set_distance_matrix(hwloc_topology_t __hwloc_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;
};

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

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

HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);

HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);

HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);

HWLOC_DECLSPEC 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)
};

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

HWLOC_DECLSPEC unsigned 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_BRIDGE = -3,     
    HWLOC_TYPE_DEPTH_PCI_DEVICE = -4, 
    HWLOC_TYPE_DEPTH_OS_DEVICE = -5   
};

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

HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned 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 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);
}

HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t  __hwloc_restrict topology) __hwloc_attribute_pure;

HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned 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_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);
}

HWLOC_DECLSPEC const char * hwloc_obj_type_string (hwloc_obj_type_t type) __hwloc_attribute_const;

HWLOC_DECLSPEC hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) __hwloc_attribute_pure;

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_obj_snprintf(char * __hwloc_restrict string, size_t size,
                             hwloc_topology_t topology, hwloc_obj_t obj,
                             const char * __hwloc_restrict indexprefix, int verbose);

HWLOC_DECLSPEC int hwloc_obj_cpuset_snprintf(char * __hwloc_restrict str, size_t size, size_t nobj, const hwloc_obj_t * __hwloc_restrict objs);

static __hwloc_inline const char *
hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_pure;
static __hwloc_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;
}

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

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_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;

HWLOC_DECLSPEC int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);

HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);

HWLOC_DECLSPEC int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);

HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);

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

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

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

HWLOC_DECLSPEC int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);

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

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

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

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

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

HWLOC_DECLSPEC void *hwloc_alloc_membind_nodeset(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags) __hwloc_attribute_malloc;

HWLOC_DECLSPEC void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, 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_custom_insert_topology(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot);

HWLOC_DECLSPEC 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 */