OpenMPI  0.1.1
hwloc.h
Go to the documentation of this file.
1 /*
2  * Copyright © 2009 CNRS
3  * Copyright © 2009-2011 inria. All rights reserved.
4  * Copyright © 2009-2012 Université Bordeaux 1
5  * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
6  * See COPYING in top-level directory.
7  */
8 
9 /*=====================================================================
10  * PLEASE GO READ THE DOCUMENTATION!
11  * ------------------------------------------------
12  * $tarball_directory/doc/doxygen-doc/
13  * or
14  * http://www.open-mpi.org/projects/hwloc/doc/
15  *=====================================================================
16  *
17  * FAIR WARNING: Do NOT expect to be able to figure out all the
18  * subtleties of hwloc by simply reading function prototypes and
19  * constant descrptions here in this file.
20  *
21  * Hwloc has wonderful documentation in both PDF and HTML formats for
22  * your reading pleasure. The formal documentation explains a LOT of
23  * hwloc-specific concepts, provides definitions, and discusses the
24  * "big picture" for many of the things that you'll find here in this
25  * header file.
26  *
27  * The PDF/HTML documentation was generated via Doxygen; much of what
28  * you'll see in there is also here in this file. BUT THERE IS A LOT
29  * THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
30  *
31  * There are entire paragraph-length descriptions, discussions, and
32  * pretty prictures to explain subtle corner cases, provide concrete
33  * examples, etc.
34  *
35  * Please, go read the documentation. :-)
36  *
37  *=====================================================================*/
38 
39 /** \file
40  * \brief The hwloc API.
41  *
42  * See hwloc/bitmap.h for bitmap specific macros.
43  * See hwloc/helper.h for high-level topology traversal helpers.
44  */
45 
46 #ifndef HWLOC_H
47 #define HWLOC_H
48 
49 #include <hwloc/autogen/config.h>
50 #include <sys/types.h>
51 #include <stdio.h>
52 #include <string.h>
53 #include <limits.h>
54 
55 /*
56  * Symbol transforms
57  */
58 #include <hwloc/rename.h>
59 
60 /*
61  * Bitmap definitions
62  */
63 
64 #include <hwloc/bitmap.h>
65 #include <hwloc/cpuset.h>
66 
67 
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
72 
73 /** \defgroup hwlocality_api_version API version
74  * @{
75  */
76 
77 /** \brief Indicate at build time which hwloc API version is being used. */
78 #define HWLOC_API_VERSION 0x00010300
79 
80 /** \brief Indicate at runtime which hwloc API version was used at build time. */
81 HWLOC_DECLSPEC unsigned hwloc_get_api_version(void);
82 
83 /** @} */
84 
85 
86 
87 /** \defgroup hwlocality_topology Topology context
88  * @{
89  */
90 
91 struct hwloc_topology;
92 /** \brief Topology context
93  *
94  * To be initialized with hwloc_topology_init() and built with hwloc_topology_load().
95  */
97 
98 /** @} */
99 
100 
101 
102 /** \defgroup hwlocality_sets Object sets (hwloc_cpuset_t and hwloc_nodeset_t)
103  *
104  * Hwloc uses bitmaps to represent two distinct kinds of object sets:
105  * CPU sets (::hwloc_cpuset_t) and NUMA node sets (::hwloc_nodeset_t).
106  * These types are both typedefs to a common back end type
107  * (::hwloc_bitmap_t), and therefore all the hwloc bitmap functions
108  * are applicable to both ::hwloc_cpuset_t and ::hwloc_nodeset_t (see
109  * \ref hwlocality_bitmap).
110  *
111  * The rationale for having two different types is that even though
112  * the actions one wants to perform on these types are the same (e.g.,
113  * enable and disable individual items in the set/mask), they're used
114  * in very different contexts: one for specifying which processors to
115  * use and one for specifying which NUMA nodes to use. Hence, the
116  * name difference is really just to reflect the intent of where the
117  * type is used.
118  *
119  * @{
120  */
121 
122 /** \brief A CPU set is a bitmap whose bits are set according to CPU
123  * physical OS indexes.
124  *
125  * It may be consulted and modified with the bitmap API as any
126  * ::hwloc_bitmap_t (see hwloc/bitmap.h).
127  */
129 /** \brief A non-modifiable ::hwloc_cpuset_t. */
131 
132 /** \brief A node set is a bitmap whose bits are set according to NUMA
133  * memory node physical OS indexes.
134  *
135  * It may be consulted and modified with the bitmap API as any
136  * ::hwloc_bitmap_t (see hwloc/bitmap.h).
137  *
138  * When binding memory on a system without any NUMA node
139  * (when the whole memory is considered as a single memory bank),
140  * the nodeset may be either empty (no memory selected)
141  * or full (whole system memory selected).
142  *
143  * See also \ref hwlocality_helper_nodeset_convert.
144  */
146 /** \brief A non-modifiable ::hwloc_nodeset_t.
147  */
149 
150 /** @} */
151 
152 
153 
154 /** \defgroup hwlocality_types Topology Object Types
155  * @{
156  */
157 
158 /** \brief Type of topology object.
159  *
160  * \note Do not rely on the ordering or completeness of the values as new ones
161  * may be defined in the future! If you need to compare types, use
162  * hwloc_compare_types() instead.
163  */
164 typedef enum {
165  /* ***************************************************************
166  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
167 
168  If new enum values are added here, you MUST also go update the
169  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
170 
171  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
172  *************************************************************** */
173 
174  HWLOC_OBJ_SYSTEM, /**< \brief Whole system (may be a cluster of machines).
175  * The whole system that is accessible to hwloc.
176  * That may comprise several machines in SSI systems
177  * like Kerrighed.
178  */
179  HWLOC_OBJ_MACHINE, /**< \brief Machine.
180  * The typical root object type.
181  * A set of processors and memory with cache
182  * coherency.
183  */
184  HWLOC_OBJ_NODE, /**< \brief NUMA node.
185  * A set of processors around memory which the
186  * processors can directly access.
187  */
188  HWLOC_OBJ_SOCKET, /**< \brief Socket, physical package, or chip.
189  * In the physical meaning, i.e. that you can add
190  * or remove physically.
191  */
192  HWLOC_OBJ_CACHE, /**< \brief Data cache.
193  * Can be L1, L2, L3, ...
194  */
195  HWLOC_OBJ_CORE, /**< \brief Core.
196  * A computation unit (may be shared by several
197  * logical processors).
198  */
199  HWLOC_OBJ_PU, /**< \brief Processing Unit, or (Logical) Processor.
200  * An execution unit (may share a core with some
201  * other logical processors, e.g. in the case of
202  * an SMT core).
203  *
204  * Objects of this kind are always reported and can
205  * thus be used as fallback when others are not.
206  */
207 
208  HWLOC_OBJ_GROUP, /**< \brief Group objects.
209  * Objects which do not fit in the above but are
210  * detected by hwloc and are useful to take into
211  * account for affinity. For instance, some operating systems
212  * expose their arbitrary processors aggregation this
213  * way. And hwloc may insert such objects to group
214  * NUMA nodes according to their distances.
215  *
216  * These objects are ignored when they do not bring
217  * any structure.
218  */
219 
220  HWLOC_OBJ_MISC, /**< \brief Miscellaneous objects.
221  * Objects without particular meaning, that can e.g. be
222  * added by the application for its own use.
223  */
224 
225  HWLOC_OBJ_BRIDGE, /**< \brief Bridge.
226  * Any bridge that connects the host or an I/O bus,
227  * to another I/O bus.
228  * Bridge objects have neither CPU sets nor node sets.
229  * They are not added to the topology unless I/O discovery
230  * is enabled with hwloc_topology_set_flags().
231  */
232  HWLOC_OBJ_PCI_DEVICE, /**< \brief PCI device.
233  * These objects have neither CPU sets nor node sets.
234  * They are not added to the topology unless I/O discovery
235  * is enabled with hwloc_topology_set_flags().
236  */
237  HWLOC_OBJ_OS_DEVICE, /**< \brief Operating system device.
238  * These objects have neither CPU sets nor node sets.
239  * They are not added to the topology unless I/O discovery
240  * is enabled with hwloc_topology_set_flags().
241  */
242 
243  HWLOC_OBJ_TYPE_MAX /**< \private Sentinel value */
244 
245  /* ***************************************************************
246  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
247 
248  If new enum values are added here, you MUST also go update the
249  obj_type_order[] and obj_order_type[] arrays in src/topology.c.
250 
251  WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
252  *************************************************************** */
254 
255 /** \brief Type of one side (upstream or downstream) of an I/O bridge. */
257  HWLOC_OBJ_BRIDGE_HOST, /**< \brief Host-side of a bridge, only possible upstream. */
258  HWLOC_OBJ_BRIDGE_PCI /**< \brief PCI-side of a bridge. */
260 
261 /** \brief Type of a OS device. */
263  HWLOC_OBJ_OSDEV_BLOCK, /**< \brief Operating system block device.
264  * For instance "sda" on Linux. */
265  HWLOC_OBJ_OSDEV_GPU, /**< \brief Operating system GPU device.
266  * For instance the "card0" DRM device on Linux. */
267  HWLOC_OBJ_OSDEV_NETWORK, /**< \brief Operating system network device.
268  * For instance the "eth0" interface on Linux. */
269  HWLOC_OBJ_OSDEV_OPENFABRICS, /**< \brief Operating system openfabrics device.
270  * For instance the "mlx4_0" InfiniBand HCA device on Linux. */
271  HWLOC_OBJ_OSDEV_DMA /**< \brief Operating system dma engine device.
272  * For instance the "dma0chan0" DMA channel on Linux. */
274 
275 /** \brief Compare the depth of two object types
276  *
277  * Types shouldn't be compared as they are, since newer ones may be added in
278  * the future. This function returns less than, equal to, or greater than zero
279  * respectively if \p type1 objects usually include \p type2 objects, are the
280  * same as \p type2 objects, or are included in \p type2 objects. If the types
281  * can not be compared (because neither is usually contained in the other),
282  * HWLOC_TYPE_UNORDERED is returned. Object types containing CPUs can always
283  * be compared (usually, a system contains machines which contain nodes which
284  * contain sockets which contain caches, which contain cores, which contain
285  * processors).
286  *
287  * \note HWLOC_OBJ_PU will always be the deepest.
288  * \note This does not mean that the actual topology will respect that order:
289  * e.g. as of today cores may also contain caches, and sockets may also contain
290  * nodes. This is thus just to be seen as a fallback comparison method.
291  */
292 HWLOC_DECLSPEC int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) __hwloc_attribute_const;
293 
295  HWLOC_TYPE_UNORDERED = INT_MAX /**< \brief Value returned by hwloc_compare_types when types can not be compared. \hideinitializer */
296 };
297 
298 /** @} */
299 
300 
301 
302 /** \defgroup hwlocality_objects Topology Objects
303  * @{
304  */
305 
306 union hwloc_obj_attr_u;
307 
308 /** \brief Object memory */
310  hwloc_uint64_t total_memory; /**< \brief Total memory (in bytes) in this object and its children */
311  hwloc_uint64_t local_memory; /**< \brief Local memory (in bytes) */
312 
313  unsigned page_types_len; /**< \brief Size of array \p page_types */
314  /** \brief Array of local memory page types, \c NULL if no local memory and \p page_types is 0.
315  *
316  * The array is sorted by increasing \p size fields.
317  * It contains \p page_types_len slots.
318  */
320  hwloc_uint64_t size; /**< \brief Size of pages */
321  hwloc_uint64_t count; /**< \brief Number of pages of this size */
322  } * page_types;
323 };
324 
325 /** \brief Structure of a topology object
326  *
327  * Applications must not modify any field except hwloc_obj.userdata.
328  */
329 struct hwloc_obj {
330  /* physical information */
331  hwloc_obj_type_t type; /**< \brief Type of object */
332  unsigned os_index; /**< \brief OS-provided physical index number */
333  char *name; /**< \brief Object description if any */
334 
335  struct hwloc_obj_memory_s memory; /**< \brief Memory attributes */
336 
337  union hwloc_obj_attr_u *attr; /**< \brief Object type-specific Attributes,
338  * may be \c NULL if no attribute value was found */
339 
340  /* global position */
341  unsigned depth; /**< \brief Vertical index in the hierarchy */
342  unsigned logical_index; /**< \brief Horizontal index in the whole list of similar objects,
343  * could be a "cousin_rank" since it's the rank within the "cousin" list below */
344  signed os_level; /**< \brief OS-provided physical level, -1 if unknown or meaningless */
345 
346  /* cousins are all objects of the same type (and depth) across the entire topology */
347  struct hwloc_obj *next_cousin; /**< \brief Next object of same type and depth */
348  struct hwloc_obj *prev_cousin; /**< \brief Previous object of same type and depth */
349 
350  /* children of the same parent are siblings, even if they may have different type and depth */
351  struct hwloc_obj *parent; /**< \brief Parent, \c NULL if root (system object) */
352  unsigned sibling_rank; /**< \brief Index in parent's \c children[] array */
353  struct hwloc_obj *next_sibling; /**< \brief Next object below the same parent */
354  struct hwloc_obj *prev_sibling; /**< \brief Previous object below the same parent */
355 
356  /* children array below this object */
357  unsigned arity; /**< \brief Number of children */
358  struct hwloc_obj **children; /**< \brief Children, \c children[0 .. arity -1] */
359  struct hwloc_obj *first_child; /**< \brief First child */
360  struct hwloc_obj *last_child; /**< \brief Last child */
361 
362  /* misc */
363  void *userdata; /**< \brief Application-given private data pointer, initialized to \c NULL, use it as you wish */
364 
365  /* cpusets and nodesets */
366  hwloc_cpuset_t cpuset; /**< \brief CPUs covered by this object
367  *
368  * This is the set of CPUs for which there are PU objects in the topology
369  * under this object, i.e. which are known to be physically contained in this
370  * object and known how (the children path between this object and the PU
371  * objects).
372  *
373  * If the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM configuration flag is set, some of
374  * these CPUs may be offline, or not allowed for binding, see online_cpuset
375  * and allowed_cpuset.
376  *
377  * \note Its value must not be changed, hwloc_bitmap_dup must be used instead.
378  */
379  hwloc_cpuset_t complete_cpuset; /**< \brief The complete CPU set of logical processors of this object,
380  *
381  * This includes not only the same as the cpuset field, but also the CPUs for
382  * which topology information is unknown or incomplete, and the CPUs that are
383  * ignored when the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM flag is not set.
384  * Thus no corresponding PU object may be found in the topology, because the
385  * precise position is undefined. It is however known that it would be somewhere
386  * under this object.
387  *
388  * \note Its value must not be changed, hwloc_bitmap_dup must be used instead.
389  */
390  hwloc_cpuset_t online_cpuset; /**< \brief The CPU set of online logical processors
391  *
392  * This includes the CPUs contained in this object that are online, i.e. draw
393  * power and can execute threads. It may however not be allowed to bind to
394  * them due to administration rules, see allowed_cpuset.
395  *
396  * \note Its value must not be changed, hwloc_bitmap_dup must be used instead.
397  */
398  hwloc_cpuset_t allowed_cpuset; /**< \brief The CPU set of allowed logical processors
399  *
400  * This includes the CPUs contained in this object which are allowed for
401  * binding, i.e. passing them to the hwloc binding functions should not return
402  * permission errors. This is usually restricted by administration rules.
403  * Some of them may however be offline so binding to them may still not be
404  * possible, see online_cpuset.
405  *
406  * \note Its value must not be changed, hwloc_bitmap_dup must be used instead.
407  */
408 
409  hwloc_nodeset_t nodeset; /**< \brief NUMA nodes covered by this object or containing this object
410  *
411  * This is the set of NUMA nodes for which there are NODE objects in the
412  * topology under or above this object, i.e. which are known to be physically
413  * contained in this object or containing it and known how (the children path
414  * between this object and the NODE objects).
415  *
416  * In the end, these nodes are those that are close to the current object.
417  *
418  * If the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM configuration flag is set, some of
419  * these nodes may not be allowed for allocation, see allowed_nodeset.
420  *
421  * If there are no NUMA nodes in the machine, all the memory is close to this
422  * object, so \p nodeset is full.
423  *
424  * \note Its value must not be changed, hwloc_bitmap_dup must be used instead.
425  */
426  hwloc_nodeset_t complete_nodeset; /**< \brief The complete NUMA node set of this object,
427  *
428  * This includes not only the same as the nodeset field, but also the NUMA
429  * nodes for which topology information is unknown or incomplete, and the nodes
430  * that are ignored when the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM flag is not set.
431  * Thus no corresponding NODE object may be found in the topology, because the
432  * precise position is undefined. It is however known that it would be
433  * somewhere under this object.
434  *
435  * If there are no NUMA nodes in the machine, all the memory is close to this
436  * object, so \p complete_nodeset is full.
437  *
438  * \note Its value must not be changed, hwloc_bitmap_dup must be used instead.
439  */
440  hwloc_nodeset_t allowed_nodeset; /**< \brief The set of allowed NUMA memory nodes
441  *
442  * This includes the NUMA memory nodes contained in this object which are
443  * allowed for memory allocation, i.e. passing them to NUMA node-directed
444  * memory allocation should not return permission errors. This is usually
445  * restricted by administration rules.
446  *
447  * If there are no NUMA nodes in the machine, all the memory is close to this
448  * object, so \p allowed_nodeset is full.
449  *
450  * \note Its value must not be changed, hwloc_bitmap_dup must be used instead.
451  */
452 
453  struct hwloc_distances_s **distances; /**< \brief Distances between all objects at same depth below this object */
454  unsigned distances_count;
455 
456  struct hwloc_obj_info_s *infos; /**< \brief Array of stringified info type=name. */
457  unsigned infos_count; /**< \brief Size of infos array. */
458 };
459 /**
460  * \brief Convenience typedef; a pointer to a struct hwloc_obj.
461  */
462 typedef struct hwloc_obj * hwloc_obj_t;
463 
464 /** \brief Object type-specific Attributes */
466  /** \brief Cache-specific Object Attributes */
468  hwloc_uint64_t size; /**< \brief Size of cache in bytes */
469  unsigned depth; /**< \brief Depth of cache (e.g., L1, L2, ...etc.) */
470  unsigned linesize; /**< \brief Cache-line size in bytes */
471  int associativity; /**< \brief Ways of associativity,
472  * -1 if fully associative, 0 if unknown */
473  } cache;
474  /** \brief Group-specific Object Attributes */
476  unsigned depth; /**< \brief Depth of group object */
477  } group;
478  /** \brief PCI Device specific Object Attributes */
480  unsigned short domain;
481  unsigned char bus, dev, func;
482  unsigned short class_id;
483  unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
484  unsigned char revision;
485  float linkspeed; /* in GB/s */
486  } pcidev;
487  /** \brief Bridge specific Object Attribues */
489  union {
490  struct hwloc_pcidev_attr_s pci;
491  } upstream;
492  hwloc_obj_bridge_type_t upstream_type;
493  union {
494  struct {
495  unsigned short domain;
496  unsigned char secondary_bus, subordinate_bus;
497  } pci;
498  } downstream;
499  hwloc_obj_bridge_type_t downstream_type;
500  unsigned depth;
501  } bridge;
502  /** \brief OS Device specific Object Attributes */
505  } osdev;
506 };
507 
508 /** \brief Distances between objects
509  *
510  * One object may contain a distance structure describing distances
511  * between all its descendants at a given relative depth. If the
512  * containing object is the root object of the topology, then the
513  * distances are available for all objects in the machine.
514  *
515  * If the \p latency pointer is not \c NULL, the pointed array contains
516  * memory latencies (non-zero values), as defined by the ACPI SLIT
517  * specification.
518  *
519  * In the future, some other types of distances may be considered.
520  * In these cases, \p latency may be \c NULL.
521  */
523  unsigned relative_depth; /**< \brief Relative depth of the considered objects
524  * below the object containing this distance information. */
525  unsigned nbobjs; /**< \brief Number of objects considered in the matrix.
526  * It is the number of descendant objects at \p relative_depth
527  * below the containing object.
528  * It corresponds to the result of hwloc_get_nbobjs_inside_cpuset_by_depth. */
529 
530  float *latency; /**< \brief Matrix of latencies between objects, stored as a one-dimension array.
531  * May be \c NULL if the distances considered here are not latencies.
532  * Values are normalized to get 1.0 as the minimal value in the matrix.
533  * Latency from i-th to j-th object is stored in slot i*nbobjs+j.
534  */
535  float latency_max; /**< \brief The maximal value in the latency matrix. */
536  float latency_base; /**< \brief The multiplier that should be applied to latency matrix
537  * to retrieve the original OS-provided latencies.
538  * Usually 10 on Linux since ACPI SLIT uses 10 for local latency.
539  */
540 };
541 
542 /** \brief Object info */
544  char *name; /**< \brief Info name */
545  char *value; /**< \brief Info value */
546 };
547 
548 /** @} */
549 
550 
551 
552 /** \defgroup hwlocality_creation Create and Destroy Topologies
553  * @{
554  */
555 
556 /** \brief Allocate a topology context.
557  *
558  * \param[out] topologyp is assigned a pointer to the new allocated context.
559  *
560  * \return 0 on success, -1 on error.
561  */
562 HWLOC_DECLSPEC int hwloc_topology_init (hwloc_topology_t *topologyp);
563 
564 /** \brief Build the actual topology
565  *
566  * Build the actual topology once initialized with hwloc_topology_init() and
567  * tuned with \ref hwlocality_configuration routines.
568  * No other routine may be called earlier using this topology context.
569  *
570  * \param topology is the topology to be loaded with objects.
571  *
572  * \return 0 on success, -1 on error.
573  *
574  * \sa hwlocality_configuration
575  */
576 HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology);
577 
578 /** \brief Terminate and free a topology context
579  *
580  * \param topology is the topology to be freed
581  */
582 HWLOC_DECLSPEC void hwloc_topology_destroy (hwloc_topology_t topology);
583 
584 /** \brief Run internal checks on a topology structure
585  *
586  * The program aborts if an inconsistency is detected in the given topology.
587  *
588  * \param topology is the topology to be checked
589  *
590  * \note This routine is only useful to developers.
591  *
592  * \note The input topology should have been previously loaded with
593  * hwloc_topology_load().
594  */
595 HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology);
596 
597 /** @} */
598 
599 
600 
601 /** \defgroup hwlocality_configuration Configure Topology Detection
602  *
603  * These functions can optionally be called between hwloc_topology_init() and
604  * hwloc_topology_load() to configure how the detection should be performed,
605  * e.g. to ignore some objects types, define a synthetic topology, etc.
606  *
607  * If none of them is called, the default is to detect all the objects of the
608  * machine that the caller is allowed to access.
609  *
610  * This default behavior may also be modified through environment variables
611  * if the application did not modify it already.
612  * Setting HWLOC_XMLFILE in the environment enforces the discovery from a XML
613  * file as if hwloc_topology_set_xml() had been called.
614  * HWLOC_FSROOT switches to reading the topology from the specified Linux
615  * filesystem root as if hwloc_topology_set_fsroot() had been called.
616  * Finally, HWLOC_THISSYSTEM enforces the return value of
617  * hwloc_topology_is_thissystem().
618  *
619  * @{
620  */
621 
622 /** \brief Ignore an object type.
623  *
624  * Ignore all objects from the given type.
625  * The bottom-level type HWLOC_OBJ_PU may not be ignored.
626  * The top-level object of the hierarchy will never be ignored, even if this function
627  * succeeds.
628  * I/O objects may not be ignored, topology flags should be used to configure
629  * their discovery instead.
630  */
631 HWLOC_DECLSPEC int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type);
632 
633 /** \brief Ignore an object type if it does not bring any structure.
634  *
635  * Ignore all objects from the given type as long as they do not bring any structure:
636  * Each ignored object should have a single children or be the only child of its parent.
637  * The bottom-level type HWLOC_OBJ_PU may not be ignored.
638  * I/O objects may not be ignored, topology flags should be used to configure
639  * their discovery instead.
640  */
641 HWLOC_DECLSPEC int hwloc_topology_ignore_type_keep_structure(hwloc_topology_t topology, hwloc_obj_type_t type);
642 
643 /** \brief Ignore all objects that do not bring any structure.
644  *
645  * Ignore all objects that do not bring any structure:
646  * Each ignored object should have a single children or be the only child of its parent.
647  * I/O objects may not be ignored, topology flags should be used to configure
648  * their discovery instead.
649  */
650 HWLOC_DECLSPEC int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology);
651 
652 /** \brief Flags to be set onto a topology context before load.
653  *
654  * Flags should be given to hwloc_topology_set_flags().
655  */
658  /**< \brief Detect the whole system, ignore reservations and offline settings.
659  * \hideinitializer
660  *
661  * Gather all resources, even if some were disabled by the administrator.
662  * For instance, ignore Linux Cpusets and gather all processors and memory nodes,
663  * and ignore the fact that some resources may be offline.
664  */
665 
667  /**< \brief Assume that the selected backend provides the topology for the
668  * system on which we are running.
669  * \hideinitializer
670  *
671  * This forces hwloc_topology_is_thissystem to return 1, i.e. makes hwloc assume that
672  * the selected backend provides the topology for the system on which we are running,
673  * even if it is not the OS-specific backend but the XML backend for instance.
674  * This means making the binding functions actually call the OS-specific
675  * system calls and really do binding, while the XML backend would otherwise
676  * provide empty hooks just returning success.
677  *
678  * Setting the environment variable HWLOC_THISSYSTEM may also result in the
679  * same behavior.
680  *
681  * This can be used for efficiency reasons to first detect the topology once,
682  * save it to an XML file, and quickly reload it later through the XML
683  * backend, but still having binding functions actually do bind.
684  */
685 
686  /* \brief Detect PCI devices.
687  *
688  * By default, I/O devices are ignored. This flag enables I/O device
689  * detection using the libpci backend. Only the common PCI devices (GPUs,
690  * NICs, block devices, ...) and host bridges (objects that connect the host
691  * objects to an I/O subsystem) will be added to the topology.
692  * Uncommon devices and other bridges (such as PCI-to-PCI bridges) will be
693  * ignored.
694  */
695  HWLOC_TOPOLOGY_FLAG_IO_DEVICES = (1<<2),
696 
697  /* \brief Detect PCI bridges.
698  *
699  * This flag should be combined with HWLOC_TOPOLOGY_FLAG_IO_DEVICES to enable
700  * the detection of both common devices and of all useful bridges (bridges that
701  * have at least one device behind them).
702  */
703  HWLOC_TOPOLOGY_FLAG_IO_BRIDGES = (1<<3),
704 
705  /* \brief Detect the whole PCI hierarchy.
706  *
707  * This flag enables detection of all I/O devices (even the uncommon ones)
708  * and bridges (even those that have no device behind them) using the libpci
709  * backend.
710  */
711  HWLOC_TOPOLOGY_FLAG_WHOLE_IO = (1<<4)
712 };
713 
714 /** \brief Set OR'ed flags to non-yet-loaded topology.
715  *
716  * Set a OR'ed set of ::hwloc_topology_flags_e onto a topology that was not yet loaded.
717  */
718 HWLOC_DECLSPEC int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
719 
720 /** \brief Change the file-system root path when building the topology from sysfs/procfs.
721  *
722  * On Linux system, use sysfs and procfs files as if they were mounted on the given
723  * \p fsroot_path instead of the main file-system root. Setting the environment
724  * variable HWLOC_FSROOT may also result in this behavior.
725  * Not using the main file-system root causes hwloc_topology_is_thissystem()
726  * to return 0.
727  *
728  * Note that this function does not actually load topology
729  * information; it just tells hwloc where to load it from. You'll
730  * still need to invoke hwloc_topology_load() to actually load the
731  * topology information.
732  *
733  * \note For convenience, this backend provides empty binding hooks which just
734  * return success. To have hwloc still actually call OS-specific hooks, the
735  * HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
736  * file is really the underlying system.
737  */
738 HWLOC_DECLSPEC int hwloc_topology_set_fsroot(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict fsroot_path);
739 
740 /** \brief Change which pid the topology is viewed from
741  *
742  * On some systems, processes may have different views of the machine, for
743  * instance the set of allowed CPUs. By default, hwloc exposes the view from
744  * the current process. Calling hwloc_topology_set_pid() permits to make it
745  * expose the topology of the machine from the point of view of another
746  * process.
747  *
748  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
749  * and \p HANDLE on native Windows platforms.
750  *
751  * \note -1 is returned and errno is set to ENOSYS on platforms that do not
752  * support this feature.
753  */
754 HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topology, hwloc_pid_t pid);
755 
756 /** \brief Enable synthetic topology.
757  *
758  * Gather topology information from the given \p description,
759  * a space-separated string of numbers describing
760  * the arity of each level.
761  * Each number may be prefixed with a type and a colon to enforce the type
762  * of a level. If only some level types are enforced, hwloc will try to
763  * choose the other types according to usual topologies, but it may fail
764  * and you may have to specify more level types manually.
765  *
766  * If \p description was properly parsed and describes a valid topology
767  * configuration, this function returns 0.
768  * Otherwise -1 is returned and errno is set to EINVAL.
769  *
770  * Note that this function does not actually load topology
771  * information; it just tells hwloc where to load it from. You'll
772  * still need to invoke hwloc_topology_load() to actually load the
773  * topology information.
774  *
775  * \note For convenience, this backend provides empty binding hooks which just
776  * return success.
777  */
778 HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict description);
779 
780 /** \brief Enable XML-file based topology.
781  *
782  * Gather topology information from the XML file given at \p xmlpath.
783  * Setting the environment variable HWLOC_XMLFILE may also result in this behavior.
784  * This file may have been generated earlier with lstopo file.xml.
785  *
786  * Note that this function does not actually load topology
787  * information; it just tells hwloc where to load it from. You'll
788  * still need to invoke hwloc_topology_load() to actually load the
789  * topology information.
790  *
791  * \note For convenience, this backend provides empty binding hooks which just
792  * return success. To have hwloc still actually call OS-specific hooks, the
793  * HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
794  * file is really the underlying system.
795  */
796 HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict xmlpath);
797 
798 /** \brief Enable XML based topology using a memory buffer (instead of
799  * a file, as with hwloc_topology_set_xml()).
800  *
801  * Gather topology information from the XML memory buffer given at \p
802  * buffer and of length \p size. This buffer may have been filled
803  * earlier with hwloc_topology_export_xmlbuffer().
804  *
805  * Note that this function does not actually load topology
806  * information; it just tells hwloc where to load it from. You'll
807  * still need to invoke hwloc_topology_load() to actually load the
808  * topology information.
809  *
810  */
811 HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict buffer, int size);
812 
813 /** \brief Provide a distance matrix.
814  *
815  * Provide the matrix of distances between a set of objects of the given type.
816  * The set may or may not contain all the existing objects of this type.
817  * The objects are specified by their OS/physical index in the \p os_index
818  * array. The \p distances matrix follows the same order.
819  * The distance from object i to object j in the i*nbobjs+j.
820  *
821  * A single latency matrix may be defined for each type.
822  * If another distance matrix already exists for the given type,
823  * either because the user specified it or because the OS offers it,
824  * it will be replaced by the given one.
825  * If \p nbobjs is \c 0, \p os_index is \c NULL and \p distances is \c NULL,
826  * the existing distance matrix for the given type is removed.
827  */
828 HWLOC_DECLSPEC int hwloc_topology_set_distance_matrix(hwloc_topology_t __hwloc_restrict topology,
829  hwloc_obj_type_t type, unsigned nbobjs,
830  unsigned *os_index, float *distances);
831 
832 /** \brief Flags describing actual discovery support for this topology. */
834  /** \brief Detecting the number of PU objects is supported. */
835  unsigned char pu;
836 };
837 
838 /** \brief Flags describing actual PU binding support for this topology. */
840  /** Binding the whole current process is supported. */
841  unsigned char set_thisproc_cpubind;
842  /** Getting the binding of the whole current process is supported. */
843  unsigned char get_thisproc_cpubind;
844  /** Binding a whole given process is supported. */
845  unsigned char set_proc_cpubind;
846  /** Getting the binding of a whole given process is supported. */
847  unsigned char get_proc_cpubind;
848  /** Binding the current thread only is supported. */
849  unsigned char set_thisthread_cpubind;
850  /** Getting the binding of the current thread only is supported. */
851  unsigned char get_thisthread_cpubind;
852  /** Binding a given thread only is supported. */
853  unsigned char set_thread_cpubind;
854  /** Getting the binding of a given thread only is supported. */
855  unsigned char get_thread_cpubind;
856  /** Getting the last processors where the whole current process ran is supported */
858  /** Getting the last processors where a whole process ran is supported */
860  /** Getting the last processors where the current thread ran is supported */
862 };
863 
864 /** \brief Flags describing actual memory binding support for this topology. */
866  /** Binding the whole current process is supported. */
867  unsigned char set_thisproc_membind;
868  /** Getting the binding of the whole current process is supported. */
869  unsigned char get_thisproc_membind;
870  /** Binding a whole given process is supported. */
871  unsigned char set_proc_membind;
872  /** Getting the binding of a whole given process is supported. */
873  unsigned char get_proc_membind;
874  /** Binding the current thread only is supported. */
875  unsigned char set_thisthread_membind;
876  /** Getting the binding of the current thread only is supported. */
877  unsigned char get_thisthread_membind;
878  /** Binding a given memory area is supported. */
879  unsigned char set_area_membind;
880  /** Getting the binding of a given memory area is supported. */
881  unsigned char get_area_membind;
882  /** Allocating a bound memory area is supported. */
883  unsigned char alloc_membind;
884  /** First-touch policy is supported. */
885  unsigned char firsttouch_membind;
886  /** Bind policy is supported. */
887  unsigned char bind_membind;
888  /** Interleave policy is supported. */
889  unsigned char interleave_membind;
890  /** Replication policy is supported. */
891  unsigned char replicate_membind;
892  /** Next-touch migration policy is supported. */
893  unsigned char nexttouch_membind;
894 
895  /** Migration flags is supported. */
896  unsigned char migrate_membind;
897 };
898 
899 /** \brief Set of flags describing actual support for this topology.
900  *
901  * This is retrieved with hwloc_topology_get_support() and will be valid until
902  * the topology object is destroyed. Note: the values are correct only after
903  * discovery.
904  */
906  struct hwloc_topology_discovery_support *discovery;
907  struct hwloc_topology_cpubind_support *cpubind;
908  struct hwloc_topology_membind_support *membind;
909 };
910 
911 /** \brief Retrieve the topology support. */
912 HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology);
913 
914 /** @} */
915 
916 
917 
918 /** \defgroup hwlocality_tinker Tinker With Topologies.
919  * @{
920  */
921 
922 /** \brief Export the topology into an XML file.
923  *
924  * This file may be loaded later through hwloc_topology_set_xml().
925  *
926  * \return -1 if a failure occured.
927  */
928 HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath);
929 
930 /** \brief Export the topology into a newly-allocated XML memory buffer.
931  *
932  * \p xmlbuffer is allocated by the callee and should be freed with
933  * hwloc_free_xmlbuffer() later in the caller.
934  *
935  * This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().
936  *
937  * \return -1 if a failure occured.
938  */
939 HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen);
940 
941 /** \brief Free a buffer allocated by hwloc_topology_export_xmlbuffer() */
942 HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer);
943 
944 /** \brief Add a MISC object to the topology
945  *
946  * A new MISC object will be created and inserted into the topology at the
947  * position given by bitmap \p cpuset. This offers a way to add new
948  * intermediate levels to the topology hierarchy.
949  *
950  * \p cpuset and \p name will be copied to setup the new object attributes.
951  *
952  * \return the newly-created object.
953  * \return \c NULL if the insertion conflicts with the existing topology tree.
954  */
955 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name);
956 
957 /** \brief Add a MISC object as a leaf of the topology
958  *
959  * A new MISC object will be created and inserted into the topology at the
960  * position given by parent. It is appended to the list of existing children,
961  * without ever adding any intermediate hierarchy level. This is useful for
962  * annotating the topology without actually changing the hierarchy.
963  *
964  * \p name will be copied to the setup the new object attributes.
965  * However, the new leaf object will not have any \p cpuset.
966  *
967  * \return the newly-created object
968  */
969 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object_by_parent(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
970 
971 /** \brief Flags to be given to hwloc_topology_restrict(). */
974  /**< \brief Adapt distance matrices according to objects being removed during restriction.
975  * If this flag is not set, distance matrices are removed.
976  * \hideinitializer
977  */
979  /**< \brief Move Misc objects to ancestors if their parents are removed during restriction.
980  * If this flag is not set, Misc objects are removed when their parents are removed.
981  * \hideinitializer
982  */
984  /**< \brief Move I/O objects to ancestors if their parents are removed during restriction.
985  * If this flag is not set, I/O devices and bridges are removed when their parents are removed.
986  * \hideinitializer
987  */
988 };
989 
990 /** \brief Restrict the topology to the given CPU set.
991  *
992  * Topology \p topology is modified so as to remove all objects that
993  * are not included (or partially included) in the CPU set \p cpuset.
994  * All objects CPU and node sets are restricted accordingly.
995  *
996  * \p flags is a OR'ed set of ::hwloc_restrict_flags_e.
997  *
998  * \note This call may not be reverted by restricting back to a larger
999  * cpuset. Once dropped during restriction, objects may not be brought
1000  * back, except by reloading the entire topology with hwloc_topology_load().
1001  */
1002 HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
1003 
1004 /** @} */
1005 
1006 
1007 
1008 /** \defgroup hwlocality_information Get Some Topology Information
1009  * @{
1010  *
1011  * Be sure to see the figure in \ref termsanddefs that shows a
1012  * complete topology tree, including depths, child/sibling/cousin
1013  * relationships, and an example of an asymmetric topology where one
1014  * socket has fewer caches than its peers.
1015  */
1016 
1017 /** \brief Get the depth of the hierarchical tree of objects.
1018  *
1019  * This is the depth of HWLOC_OBJ_PU objects plus one.
1020  */
1021 HWLOC_DECLSPEC unsigned hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
1022 
1023 /** \brief Returns the depth of objects of type \p type.
1024  *
1025  * If no object of this type is present on the underlying architecture, or if
1026  * the OS doesn't provide this kind of information, the function returns
1027  * HWLOC_TYPE_DEPTH_UNKNOWN.
1028  *
1029  * If type is absent but a similar type is acceptable, see also
1030  * hwloc_get_type_or_below_depth() and hwloc_get_type_or_above_depth().
1031  *
1032  * If some objects of the given type exist in different levels, for instance
1033  * L1 and L2 caches, the function returns HWLOC_TYPE_DEPTH_MULTIPLE.
1034  *
1035  * If an I/O object type is given, the function returns a virtual value
1036  * because I/O objects are stored in special levels that are not CPU-related.
1037  * This virtual depth may be passed to other hwloc functions such as
1038  * hwloc_get_obj_by_depth() but it should not be considered as an actual
1039  * depth by the application. In particular, it should not be compared with
1040  * any other object depth or with the entire topology depth.
1041  */
1042 HWLOC_DECLSPEC int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
1043 
1045  HWLOC_TYPE_DEPTH_UNKNOWN = -1, /**< \brief No object of given type exists in the topology. \hideinitializer */
1046  HWLOC_TYPE_DEPTH_MULTIPLE = -2, /**< \brief Objects of given type exist at different depth in the topology. \hideinitializer */
1047  HWLOC_TYPE_DEPTH_BRIDGE = -3, /**< \brief Virtual depth for bridge object level. \hideinitializer */
1048  HWLOC_TYPE_DEPTH_PCI_DEVICE = -4, /**< \brief Virtual depth for PCI device object level. \hideinitializer */
1049  HWLOC_TYPE_DEPTH_OS_DEVICE = -5 /**< \brief Virtual depth for software device object level. \hideinitializer */
1050 };
1051 
1052 /** \brief Returns the type of objects at depth \p depth.
1053  *
1054  * \return -1 if depth \p depth does not exist.
1055  */
1056 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, unsigned depth) __hwloc_attribute_pure;
1057 
1058 /** \brief Returns the width of level at depth \p depth.
1059  */
1060 HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, unsigned depth) __hwloc_attribute_pure;
1061 
1062 /** \brief Returns the width of level type \p type
1063  *
1064  * If no object for that type exists, 0 is returned.
1065  * If there are several levels with objects of that type, -1 is returned.
1066  */
1067 static __hwloc_inline int __hwloc_attribute_pure
1068 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type)
1069 {
1070  int depth = hwloc_get_type_depth(topology, type);
1071  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1072  return 0;
1073  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1074  return -1; /* FIXME: agregate nbobjs from different levels? */
1075  return hwloc_get_nbobjs_by_depth(topology, depth);
1076 }
1077 
1078 /** \brief Does the topology context come from this system?
1079  *
1080  * \return 1 if this topology context was built using the system
1081  * running this program.
1082  * \return 0 instead (for instance if using another file-system root,
1083  * a XML topology file, or a synthetic topology).
1084  */
1085 HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
1086 
1087 /** @} */
1088 
1089 
1090 
1091 /** \defgroup hwlocality_traversal Retrieve Objects
1092  * @{
1093  *
1094  * Be sure to see the figure in \ref termsanddefs that shows a
1095  * complete topology tree, including depths, child/sibling/cousin
1096  * relationships, and an example of an asymmetric topology where one
1097  * socket has fewer caches than its peers.
1098  */
1099 
1100 /** \brief Returns the topology object at logical index \p idx from depth \p depth */
1101 HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, unsigned depth, unsigned idx) __hwloc_attribute_pure;
1102 
1103 /** \brief Returns the topology object at logical index \p idx with type \p type
1104  *
1105  * If no object for that type exists, \c NULL is returned.
1106  * If there are several levels with objects of that type, \c NULL is returned
1107  * and ther caller may fallback to hwloc_get_obj_by_depth().
1108  */
1109 static __hwloc_inline hwloc_obj_t __hwloc_attribute_pure
1110 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
1111 {
1112  int depth = hwloc_get_type_depth(topology, type);
1113  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN)
1114  return NULL;
1115  if (depth == HWLOC_TYPE_DEPTH_MULTIPLE)
1116  return NULL;
1117  return hwloc_get_obj_by_depth(topology, depth, idx);
1118 }
1119 
1120 /** @} */
1121 
1122 
1123 
1124 /** \defgroup hwlocality_conversion Object/String Conversion
1125  * @{
1126  */
1127 
1128 /** \brief Return a stringified topology object type */
1129 HWLOC_DECLSPEC const char * hwloc_obj_type_string (hwloc_obj_type_t type) __hwloc_attribute_const;
1130 
1131 /** \brief Return an object type from the string
1132  *
1133  * \return -1 if unrecognized.
1134  */
1135 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_obj_type_of_string (const char * string) __hwloc_attribute_pure;
1136 
1137 /** \brief Stringify the type of a given topology object into a human-readable form.
1138  *
1139  * It differs from hwloc_obj_type_string() because it prints type attributes such
1140  * as cache depth.
1141  *
1142  * If \p size is 0, \p string may safely be \c NULL.
1143  *
1144  * \return the number of character that were actually written if not truncating,
1145  * or that would have been written (not including the ending \\0).
1146  */
1147 HWLOC_DECLSPEC int hwloc_obj_type_snprintf(char * __hwloc_restrict string, size_t size, hwloc_obj_t obj,
1148  int verbose);
1149 
1150 /** \brief Stringify the attributes of a given topology object into a human-readable form.
1151  *
1152  * Attribute values are separated by \p separator.
1153  *
1154  * Only the major attributes are printed in non-verbose mode.
1155  *
1156  * If \p size is 0, \p string may safely be \c NULL.
1157  *
1158  * \return the number of character that were actually written if not truncating,
1159  * or that would have been written (not including the ending \\0).
1160  */
1161 HWLOC_DECLSPEC int hwloc_obj_attr_snprintf(char * __hwloc_restrict string, size_t size, hwloc_obj_t obj, const char * __hwloc_restrict separator,
1162  int verbose);
1163 
1164 /** \brief Stringify a given topology object into a human-readable form.
1165  *
1166  * \note This function is deprecated in favor of hwloc_obj_type_snprintf()
1167  * and hwloc_obj_attr_snprintf() since it is not very flexible and
1168  * only prints physical/OS indexes.
1169  *
1170  * Fill string \p string up to \p size characters with the description
1171  * of topology object \p obj in topology \p topology.
1172  *
1173  * If \p verbose is set, a longer description is used. Otherwise a
1174  * short description is used.
1175  *
1176  * \p indexprefix is used to prefix the \p os_index attribute number of
1177  * the object in the description. If \c NULL, the \c # character is used.
1178  *
1179  * If \p size is 0, \p string may safely be \c NULL.
1180  *
1181  * \return the number of character that were actually written if not truncating,
1182  * or that would have been written (not including the ending \\0).
1183  */
1184 HWLOC_DECLSPEC int hwloc_obj_snprintf(char * __hwloc_restrict string, size_t size,
1185  hwloc_topology_t topology, hwloc_obj_t obj,
1186  const char * __hwloc_restrict indexprefix, int verbose);
1187 
1188 /** \brief Stringify the cpuset containing a set of objects.
1189  *
1190  * If \p size is 0, \p string may safely be \c NULL.
1191  *
1192  * \return the number of character that were actually written if not truncating,
1193  * or that would have been written (not including the ending \\0).
1194  */
1195 HWLOC_DECLSPEC int hwloc_obj_cpuset_snprintf(char * __hwloc_restrict str, size_t size, size_t nobj, const hwloc_obj_t * __hwloc_restrict objs);
1196 
1197 /** \brief Search the given key name in object infos and return the corresponding value.
1198  *
1199  * If multiple keys match the given name, only the first one is returned.
1200  *
1201  * \return \c NULL if no such key exists.
1202  */
1203 static __hwloc_inline const char * __hwloc_attribute_pure
1204 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name)
1205 {
1206  unsigned i;
1207  for(i=0; i<obj->infos_count; i++)
1208  if (!strcmp(obj->infos[i].name, name))
1209  return obj->infos[i].value;
1210  return NULL;
1211 }
1212 
1213 /** \brief Add the given info name and value pair to the given object.
1214  *
1215  * The info is appended to the existing info array even if another key
1216  * with the same name already exists.
1217  *
1218  * The input strings are copied before being added in the object infos.
1219  */
1220 HWLOC_DECLSPEC void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1221 
1222 /** @} */
1223 
1224 
1225 
1226 /** \defgroup hwlocality_cpubinding CPU binding
1227  *
1228  * It is often useful to call hwloc_bitmap_singlify() first so that a single CPU
1229  * remains in the set. This way, the process will not even migrate between
1230  * different CPUs. Some operating systems also only support that kind of binding.
1231  *
1232  * \note Some operating systems do not provide all hwloc-supported
1233  * mechanisms to bind processes, threads, etc. and the corresponding
1234  * binding functions may fail. -1 is returned and errno is set to
1235  * ENOSYS when it is not possible to bind the requested kind of object
1236  * processes/threads. errno is set to EXDEV when the requested cpuset
1237  * can not be enforced (e.g. some systems only allow one CPU, and some
1238  * other systems only allow one NUMA node).
1239  *
1240  * The most portable version that should be preferred over the others, whenever
1241  * possible, is
1242  *
1243  * \code
1244  * hwloc_set_cpubind(topology, set, 0),
1245  * \endcode
1246  *
1247  * as it just binds the current program, assuming it is single-threaded, or
1248  *
1249  * \code
1250  * hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),
1251  * \endcode
1252  *
1253  * which binds the current thread of the current program (which may be
1254  * multithreaded).
1255  *
1256  * \note To unbind, just call the binding function with either a full cpuset or
1257  * a cpuset equal to the system cpuset.
1258  *
1259  * \note On some operating systems, CPU binding may have effects on memory binding, see
1260  * ::HWLOC_CPUBIND_NOMEMBIND
1261  *
1262  * Running lstopo --top can be a very convenient tool to check how binding
1263  * actually happened.
1264  * @{
1265  */
1266 
1267 /** \brief Process/Thread binding flags.
1268  *
1269  * These bit flags can be used to refine the binding policy.
1270  *
1271  * The default (0) is to bind the current process, assumed to be
1272  * single-threaded, in a non-strict way. This is the most portable
1273  * way to bind as all operating systems usually provide it.
1274  *
1275  * \note Not all systems support all kinds of binding. See the
1276  * "Detailed Description" section of \ref hwlocality_cpubinding for a
1277  * description of errors that can occur.
1278  */
1279 typedef enum {
1280  HWLOC_CPUBIND_PROCESS = (1<<0), /**< \brief Bind all threads of the current
1281  * (possibly) multithreaded process.
1282  * \hideinitializer */
1283  HWLOC_CPUBIND_THREAD = (1<<1), /**< \brief Bind current thread of current process.
1284  * \hideinitializer */
1285  HWLOC_CPUBIND_STRICT = (1<<2), /**< \brief Request for strict binding from the OS.
1286  * \hideinitializer
1287  *
1288  * By default, when the designated CPUs are
1289  * all busy while other CPUs are idle, operating systems
1290  * may execute the thread/process on those
1291  * other CPUs instead of the designated CPUs,
1292  * to let them progress anyway. Strict
1293  * binding means that the thread/process will
1294  * _never_ execute on other cpus than the
1295  * designated CPUs, even when those are busy
1296  * with other tasks and other CPUs are idle.
1297  *
1298  * \note Depending on the operating system,
1299  * strict binding may not be
1300  * possible (e.g., the OS does not implement it) or not
1301  * allowed (e.g., for an administrative reasons), and the
1302  * function will fail in that case.
1303  *
1304  * When retrieving the binding of a process,
1305  * this flag checks whether all its threads
1306  * actually have the same binding.
1307  * If the flag is not given, the binding of
1308  * each thread will be accumulated.
1309  *
1310  * \note This flag is meaningless when retrieving
1311  * the binding of a thread.
1312  */
1313  HWLOC_CPUBIND_NOMEMBIND = (1<<3)/**< \brief Avoid any effect on memory binding
1314  * \hideinitializer
1315  *
1316  * On some operating systems, some CPU binding function
1317  * would also bind the memory on the
1318  * corresponding NUMA node. It is often not
1319  * a problem for the application, but if it
1320  * is, setting this flag will make hwloc
1321  * avoid using OS functions that would also
1322  * bind memory. This will however reduce the
1323  * support of CPU bindings, i.e. potentially
1324  * return -1 with errno set to ENOSYS in some
1325  * cases.
1326  *
1327  * This flag is only meaningful when
1328  * used with functions that set the
1329  * CPU binding. It is ignored when
1330  * used with functions that get CPU
1331  * binding information.
1332  */
1334 
1335 /** \brief Bind current process or thread on cpus given in physical bitmap \p set.
1336  *
1337  * \return -1 with errno set to ENOSYS if the action is not supported
1338  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1339  */
1340 HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1341 
1342 /** \brief Get current process or thread binding.
1343  *
1344  * Writes into \p set the physical cpuset which the process or thread (according to \e
1345  * flags) was last bound to.
1346  */
1347 HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1348 
1349 /** \brief Bind a process \p pid on cpus given in physical bitmap \p set.
1350  *
1351  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1352  * and \p HANDLE on native Windows platforms.
1353  *
1354  * \note HWLOC_CPUBIND_THREAD can not be used in \p flags.
1355  */
1356 HWLOC_DECLSPEC int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1357 
1358 /** \brief Get the current physical binding of process \p pid.
1359  *
1360  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1361  * and \p HANDLE on native Windows platforms.
1362  *
1363  * \note HWLOC_CPUBIND_THREAD can not be used in \p flags.
1364  *
1365  * \note As a special case on Linux, if a tid (thread ID) is supplied
1366  * instead of a pid (process ID), the binding for that specific thread
1367  * is returned.
1368  */
1369 HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1370 
1371 #ifdef hwloc_thread_t
1372 /** \brief Bind a thread \p thread on cpus given in physical bitmap \p set.
1373  *
1374  * \note \p hwloc_thread_t is \p pthread_t on Unix platforms,
1375  * and \p HANDLE on native Windows platforms.
1376  *
1377  * \note HWLOC_CPUBIND_PROCESS can not be used in \p flags.
1378  */
1379 HWLOC_DECLSPEC int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1380 #endif
1381 
1382 #ifdef hwloc_thread_t
1383 /** \brief Get the current physical binding of thread \p tid.
1384  *
1385  * \note \p hwloc_thread_t is \p pthread_t on Unix platforms,
1386  * and \p HANDLE on native Windows platforms.
1387  *
1388  * \note HWLOC_CPUBIND_PROCESS can not be used in \p flags.
1389  */
1390 HWLOC_DECLSPEC int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1391 #endif
1392 
1393 /** \brief Get the last physical CPU where the current process or thread ran.
1394  *
1395  * The operating system may move some tasks from one processor
1396  * to another at any time according to their binding,
1397  * so this function may return something that is already
1398  * outdated.
1399  */
1400 HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1401 
1402 /** \brief Get the last physical CPU where a process ran.
1403  *
1404  * The operating system may move some tasks from one processor
1405  * to another at any time according to their binding,
1406  * so this function may return something that is already
1407  * outdated.
1408  *
1409  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1410  * and \p HANDLE on native Windows platforms.
1411  *
1412  * \note HWLOC_CPUBIND_THREAD can not be used in \p flags.
1413  *
1414  * \note As a special case on Linux, if a tid (thread ID) is supplied
1415  * instead of a pid (process ID), the binding for that specific thread
1416  * is returned.
1417  */
1418 HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1419 
1420 /** @} */
1421 
1422 
1423 
1424 /** \defgroup hwlocality_membinding Memory binding
1425  *
1426  * \note Not all operating systems support all ways to bind existing
1427  * allocated memory (e.g., migration), future memory allocation,
1428  * explicit memory allocation, etc. Using a binding flag or policy
1429  * that is not supported by the underlying OS will cause hwloc's
1430  * binding functions to fail and return -1. errno will be set to
1431  * ENOSYS when the system does support the specified action or policy
1432  * (e.g., some systems only allow binding memory on a per-thread
1433  * basis, whereas other systems only allow binding memory for all
1434  * threads in a process). errno will be set to EXDEV when the
1435  * requested cpuset can not be enforced (e.g., some systems only allow
1436  * binding memory to a single NUMA node).
1437  *
1438  * The most portable form that should be preferred over the others
1439  * whenever possible is as follows:
1440  *
1441  * \code
1442  * hwloc_alloc_membind_policy(topology, size, set,
1443  * HWLOC_MEMBIND_DEFAULT, 0);
1444  * \endcode
1445  *
1446  * This will allocate some memory hopefully bound to the specified set.
1447  * To do so, hwloc will possibly have to change the current memory
1448  * binding policy in order to actually get the memory bound, if the OS
1449  * does not provide any other way to simply allocate bound memory
1450  * without changing the policy for all allocations. That is the
1451  * difference with hwloc_alloc_membind(), which will never change the
1452  * current memory binding policy. Note that since HWLOC_MEMBIND_STRICT
1453  * was not specified, failures to bind will not be reported --
1454  * generally, only memory allocation failures will be reported (e.g.,
1455  * even a plain malloc() would have failed with ENOMEM).
1456  *
1457  * Each hwloc memory binding function is available in two forms: one
1458  * that takes a CPU set argument and another that takes a NUMA memory
1459  * node set argument (see \ref hwlocality_sets and \ref
1460  * hwlocality_bitmap for a discussion of CPU sets and NUMA memory node
1461  * sets). The names of the latter form end with _nodeset. It is also
1462  * possible to convert between CPU set and node set using
1463  * hwloc_cpuset_to_nodeset() or hwloc_cpuset_from_nodeset().
1464  *
1465  * \note On some operating systems, memory binding affects the CPU
1466  * binding; see ::HWLOC_MEMBIND_NOCPUBIND
1467  * @{
1468  */
1469 
1470 /** \brief Memory binding policy.
1471  *
1472  * These constants can be used to choose the binding policy. Only one policy can
1473  * be used at a time (i.e., the values cannot be OR'ed together).
1474  *
1475  * \note Not all systems support all kinds of binding. See the
1476  * "Detailed Description" section of \ref hwlocality_membinding for a
1477  * description of errors that can occur.
1478  */
1479 typedef enum {
1480  HWLOC_MEMBIND_DEFAULT = 0, /**< \brief Reset the memory allocation policy to the system default.
1481  * \hideinitializer */
1482  HWLOC_MEMBIND_FIRSTTOUCH = 1, /**< \brief Allocate memory
1483  * but do not immediately bind
1484  * it to a specific locality.
1485  * Instead, each page in the
1486  * allocation is bound only
1487  * when it is first touched.
1488  * Pages are individually
1489  * bound to the local NUMA
1490  * node of the first thread
1491  * that touches it.
1492  * \hideinitializer */
1493  HWLOC_MEMBIND_BIND = 2, /**< \brief Allocate memory on the specified nodes.
1494  * \hideinitializer */
1495  HWLOC_MEMBIND_INTERLEAVE = 3, /**< \brief Allocate memory on
1496  * the given nodes in an
1497  * interleaved / round-robin
1498  * manner. The precise layout
1499  * of the memory across
1500  * multiple NUMA nodes is
1501  * OS/system specific.
1502  * Interleaving can be useful
1503  * when threads distributed across
1504  * the specified NUMA nodes
1505  * will all be accessing the whole
1506  * memory range concurrently, since
1507  * the interleave will then balance
1508  * the memory references.
1509  * \hideinitializer */
1510  HWLOC_MEMBIND_REPLICATE = 4, /**< \brief Replicate memory
1511  * on the given nodes; reads
1512  * from this memory will
1513  * attempt to be serviced from
1514  * the NUMA node local to the
1515  * reading thread.
1516  * Replicating can be useful
1517  * when multiple threads from
1518  * the specified NUMA nodes
1519  * will be sharing the same
1520  * read-only data.
1521  *
1522  * This policy can only be
1523  * used with existing memory
1524  * allocations (i.e., the
1525  * hwloc_set_*membind*()
1526  * functions); it cannot be
1527  * used with functions that
1528  * allocate new memory (i.e.,
1529  * the hwloc_alloc*()
1530  * functions).
1531  * \hideinitializer */
1532  HWLOC_MEMBIND_NEXTTOUCH = 5, /**< \brief For each page bound
1533  * with this policy, by next time
1534  * it is touched (and next time only),
1535  * it is moved from
1536  * its current location to the
1537  * local NUMA node of the
1538  * thread where the memory
1539  * reference occurred (if it
1540  * needs to be moved at all).
1541  * \hideinitializer */
1542  HWLOC_MEMBIND_MIXED = -1 /**< \brief Returned by hwloc_get_membind*()
1543  * functions when multiple threads or
1544  * parts of a memory area have
1545  * differing memory binding policies.
1546  * \hideinitializer */
1548 
1549 /** \brief Memory binding flags.
1550  *
1551  * These flags can be used to refine the binding policy. All flags
1552  * can be logically OR'ed together with the exception of
1553  * HWLOC_MEMBIND_PROCESS and HWLOC_MEMBIND_THREAD; these two flags are
1554  * mutually exclusive.
1555  *
1556  * \note Not all systems support all kinds of binding. See the
1557  * "Detailed Description" section of \ref hwlocality_membinding for a
1558  * description of errors that can occur.
1559  */
1560 typedef enum {
1561  HWLOC_MEMBIND_PROCESS = (1<<0), /**< \brief Set policy for all
1562  * threads of the specified
1563  * (possibly multithreaded)
1564  * process. This flag is
1565  * mutually exclusive with
1566  * HWLOC_MEMBIND_THREAD.
1567  * \hideinitializer */
1568  HWLOC_MEMBIND_THREAD = (1<<1), /**< \brief Set policy for a
1569  * specific thread of the
1570  * current process. This flag
1571  * is mutually exclusive with
1572  * HWLOC_MEMBIND_PROCESS.
1573  * \hideinitializer */
1574  HWLOC_MEMBIND_STRICT = (1<<2), /**< Request strict binding
1575  * from the OS. The function
1576  * will fail if the binding
1577  * can not be guaranteed /
1578  * completely enforced.
1579  *
1580  * This flag has slightly
1581  * different meanings
1582  * depending on which function
1583  * it is used with.
1584  * \hideinitializer */
1585  HWLOC_MEMBIND_MIGRATE = (1<<3), /**< \brief Migrate existing
1586  * allocated memory. If the
1587  * memory cannot be migrated
1588  * and the
1589  * HWLOC_MEMBIND_STRICT flag
1590  * is passed, an error will be
1591  * returned.
1592  * \hideinitializer */
1593  HWLOC_MEMBIND_NOCPUBIND = (1<<4) /**< \brief Avoid any effect
1594  * on CPU binding.
1595  *
1596  * On some operating systems,
1597  * some underlying memory
1598  * binding functions also bind
1599  * the application to the
1600  * corresponding CPU(s).
1601  * Using this flag will cause
1602  * hwloc to avoid using OS
1603  * functions that could
1604  * potentially affect CPU
1605  * bindings. Note, however,
1606  * that using NOCPUBIND may
1607  * reduce hwloc's overall
1608  * memory binding support.
1609  * Specifically: some of
1610  * hwloc's memory binding
1611  * functions may fail with
1612  * errno set to ENOSYS when
1613  * used with NOCPUBIND.
1614  * \hideinitializer
1615  */
1617 
1618 /** \brief Set the default memory binding policy of the current
1619  * process or thread to prefer the NUMA node(s) specified by physical \p nodeset
1620  *
1621  * If neither HWLOC_MEMBIND_PROCESS nor HWLOC_MEMBIND_THREAD is
1622  * specified, the current process is assumed to be single-threaded.
1623  * This is the most portable form as it permits hwloc to use either
1624  * process-based OS functions or thread-based OS functions, depending
1625  * on which are available.
1626  *
1627  * \return -1 with errno set to ENOSYS if the action is not supported
1628  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1629  */
1630 HWLOC_DECLSPEC int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags);
1631 
1632 /** \brief Set the default memory binding policy of the current
1633  * process or thread to prefer the NUMA node(s) near the specified physical \p
1634  * cpuset
1635  *
1636  * If neither HWLOC_MEMBIND_PROCESS nor HWLOC_MEMBIND_THREAD is
1637  * specified, the current process is assumed to be single-threaded.
1638  * This is the most portable form as it permits hwloc to use either
1639  * process-based OS functions or thread-based OS functions, depending
1640  * on which are available.
1641  *
1642  * \return -1 with errno set to ENOSYS if the action is not supported
1643  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1644  */
1645 HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags);
1646 
1647 /** \brief Query the default memory binding policy and physical locality of the
1648  * current process or thread.
1649  *
1650  * This function has two output parameters: \p nodeset and \p policy.
1651  * The values returned in these parameters depend on both the \p flags
1652  * passed in and the current memory binding policies and nodesets in
1653  * the queried target.
1654  *
1655  * Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query
1656  * target is the current policies and nodesets for all the threads in
1657  * the current process. Passing HWLOC_MEMBIND_THREAD specifies that
1658  * the query target is the current policy and nodeset for only the
1659  * thread invoking this function.
1660  *
1661  * If neither of these flags are passed (which is the most portable
1662  * method), the process is assumed to be single threaded. This allows
1663  * hwloc to use either process-based OS functions or thread-based OS
1664  * functions, depending on which are available.
1665  *
1666  * HWLOC_MEMBIND_STRICT is only meaningful when HWLOC_MEMBIND_PROCESS
1667  * is also specified. In this case, hwloc will check the default
1668  * memory policies and nodesets for all threads in the process. If
1669  * they are not identical, -1 is returned and errno is set to EXDEV.
1670  * If they are identical, the values are returned in \p nodeset and \p
1671  * policy.
1672  *
1673  * Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and
1674  * HWLOC_MEMBIND_STRICT is \em not specified), \p nodeset is set to
1675  * the logical OR of all threads' default nodeset. If all threads'
1676  * default policies are the same, \p policy is set to that policy. If
1677  * they are different, \p policy is set to HWLOC_MEMBIND_MIXED.
1678  *
1679  * In the HWLOC_MEMBIND_THREAD case (or when neither
1680  * HWLOC_MEMBIND_PROCESS or HWLOC_MEMBIND_THREAD is specified), there
1681  * is only one nodeset and policy; they are returned in \p nodeset and
1682  * \p policy, respectively.
1683  *
1684  * If any other flags are specified, -1 is returned and errno is set
1685  * to EINVAL.
1686  */
1687 HWLOC_DECLSPEC int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t * policy, int flags);
1688 
1689 /** \brief Query the default memory binding policy and physical locality of the
1690  * current process or thread (the locality is returned in \p cpuset as
1691  * CPUs near the locality's actual NUMA node(s)).
1692  *
1693  * This function has two output parameters: \p cpuset and \p policy.
1694  * The values returned in these parameters depend on both the \p flags
1695  * passed in and the current memory binding policies and nodesets in
1696  * the queried target.
1697  *
1698  * Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query
1699  * target is the current policies and nodesets for all the threads in
1700  * the current process. Passing HWLOC_MEMBIND_THREAD specifies that
1701  * the query target is the current policy and nodeset for only the
1702  * thread invoking this function.
1703  *
1704  * If neither of these flags are passed (which is the most portable
1705  * method), the process is assumed to be single threaded. This allows
1706  * hwloc to use either process-based OS functions or thread-based OS
1707  * functions, depending on which are available.
1708  *
1709  * HWLOC_MEMBIND_STRICT is only meaningful when HWLOC_MEMBIND_PROCESS
1710  * is also specified. In this case, hwloc will check the default
1711  * memory policies and nodesets for all threads in the process. If
1712  * they are not identical, -1 is returned and errno is set to EXDEV.
1713  * If they are identical, the policy is returned in \p policy. \p
1714  * cpuset is set to the union of CPUs near the NUMA node(s) in the
1715  * nodeset.
1716  *
1717  * Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and
1718  * HWLOC_MEMBIND_STRICT is \em not specified), the default nodeset
1719  * from each thread is logically OR'ed together. \p cpuset is set to
1720  * the union of CPUs near the NUMA node(s) in the resulting nodeset.
1721  * If all threads' default policies are the same, \p policy is set to
1722  * that policy. If they are different, \p policy is set to
1723  * HWLOC_MEMBIND_MIXED.
1724  *
1725  * In the HWLOC_MEMBIND_THREAD case (or when neither
1726  * HWLOC_MEMBIND_PROCESS or HWLOC_MEMBIND_THREAD is specified), there
1727  * is only one nodeset and policy. The policy is returned in \p
1728  * policy; \p cpuset is set to the union of CPUs near the NUMA node(s)
1729  * in the \p nodeset.
1730  *
1731  * If any other flags are specified, -1 is returned and errno is set
1732  * to EINVAL.
1733  */
1734 HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t * policy, int flags);
1735 
1736 /** \brief Set the default memory binding policy of the specified
1737  * process to prefer the NUMA node(s) specified by physical \p nodeset
1738  *
1739  * \return -1 with errno set to ENOSYS if the action is not supported
1740  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1741  *
1742  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1743  * and \p HANDLE on native Windows platforms.
1744  */
1745 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);
1746 
1747 /** \brief Set the default memory binding policy of the specified
1748  * process to prefer the NUMA node(s) near the specified physical \p cpuset
1749  *
1750  * \return -1 with errno set to ENOSYS if the action is not supported
1751  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1752  *
1753  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1754  * and \p HANDLE on native Windows platforms.
1755  */
1756 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);
1757 
1758 /** \brief Query the default memory binding policy and physical locality of the
1759  * specified process.
1760  *
1761  * This function has two output parameters: \p nodeset and \p policy.
1762  * The values returned in these parameters depend on both the \p flags
1763  * passed in and the current memory binding policies and nodesets in
1764  * the queried target.
1765  *
1766  * Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query
1767  * target is the current policies and nodesets for all the threads in
1768  * the specified process. If HWLOC_MEMBIND_PROCESS is not specified
1769  * (which is the most portable method), the process is assumed to be
1770  * single threaded. This allows hwloc to use either process-based OS
1771  * functions or thread-based OS functions, depending on which are
1772  * available.
1773  *
1774  * Note that it does not make sense to pass HWLOC_MEMBIND_THREAD to
1775  * this function.
1776  *
1777  * If HWLOC_MEMBIND_STRICT is specified, hwloc will check the default
1778  * memory policies and nodesets for all threads in the specified
1779  * process. If they are not identical, -1 is returned and errno is
1780  * set to EXDEV. If they are identical, the values are returned in \p
1781  * nodeset and \p policy.
1782  *
1783  * Otherwise, \p nodeset is set to the logical OR of all threads'
1784  * default nodeset. If all threads' default policies are the same, \p
1785  * policy is set to that policy. If they are different, \p policy is
1786  * set to HWLOC_MEMBIND_MIXED.
1787  *
1788  * If any other flags are specified, -1 is returned and errno is set
1789  * to EINVAL.
1790  *
1791  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1792  * and \p HANDLE on native Windows platforms.
1793  */
1794 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);
1795 
1796 /** \brief Query the default memory binding policy and physical locality of the
1797  * specified process (the locality is returned in \p cpuset as CPUs
1798  * near the locality's actual NUMA node(s)).
1799  *
1800  * This function has two output parameters: \p cpuset and \p policy.
1801  * The values returned in these parameters depend on both the \p flags
1802  * passed in and the current memory binding policies and nodesets in
1803  * the queried target.
1804  *
1805  * Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query
1806  * target is the current policies and nodesets for all the threads in
1807  * the specified process. If HWLOC_MEMBIND_PROCESS is not specified
1808  * (which is the most portable method), the process is assumed to be
1809  * single threaded. This allows hwloc to use either process-based OS
1810  * functions or thread-based OS functions, depending on which are
1811  * available.
1812  *
1813  * Note that it does not make sense to pass HWLOC_MEMBIND_THREAD to
1814  * this function.
1815  *
1816  * If HWLOC_MEMBIND_STRICT is specified, hwloc will check the default
1817  * memory policies and nodesets for all threads in the specified
1818  * process. If they are not identical, -1 is returned and errno is
1819  * set to EXDEV. If they are identical, the policy is returned in \p
1820  * policy. \p cpuset is set to the union of CPUs near the NUMA
1821  * node(s) in the nodeset.
1822  *
1823  * Otherwise, the default nodeset from each thread is logically OR'ed
1824  * together. \p cpuset is set to the union of CPUs near the NUMA
1825  * node(s) in the resulting nodeset. If all threads' default policies
1826  * are the same, \p policy is set to that policy. If they are
1827  * different, \p policy is set to HWLOC_MEMBIND_MIXED.
1828  *
1829  * If any other flags are specified, -1 is returned and errno is set
1830  * to EINVAL.
1831  *
1832  * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1833  * and \p HANDLE on native Windows platforms.
1834  */
1835 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);
1836 
1837 /** \brief Bind the already-allocated memory identified by (addr, len)
1838  * to the NUMA node(s) in physical \p nodeset.
1839  *
1840  * \return -1 with errno set to ENOSYS if the action is not supported
1841  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1842  */
1843 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);
1844 
1845 /** \brief Bind the already-allocated memory identified by (addr, len)
1846  * to the NUMA node(s) near physical \p cpuset.
1847  *
1848  * \return -1 with errno set to ENOSYS if the action is not supported
1849  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1850  */
1851 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);
1852 
1853 /** \brief Query the physical NUMA node(s) and binding policy of the memory
1854  * identified by (\p addr, \p len ).
1855  *
1856  * This function has two output parameters: \p nodeset and \p policy.
1857  * The values returned in these parameters depend on both the \p flags
1858  * passed in and the memory binding policies and nodesets of the pages
1859  * in the address range.
1860  *
1861  * If HWLOC_MEMBIND_STRICT is specified, the target pages are first
1862  * checked to see if they all have the same memory binding policy and
1863  * nodeset. If they do not, -1 is returned and errno is set to EXDEV.
1864  * If they are identical across all pages, the nodeset and policy are
1865  * returned in \p nodeset and \p policy, respectively.
1866  *
1867  * If HWLOC_MEMBIND_STRICT is not specified, \p nodeset is set to the
1868  * union of all NUMA node(s) containing pages in the address range.
1869  * If all pages in the target have the same policy, it is returned in
1870  * \p policy. Otherwise, \p policy is set to HWLOC_MEMBIND_MIXED.
1871  *
1872  * If any other flags are specified, -1 is returned and errno is set
1873  * to EINVAL.
1874  */
1875 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);
1876 
1877 /** \brief Query the CPUs near the physical NUMA node(s) and binding policy of
1878  * the memory identified by (\p addr, \p len ).
1879  *
1880  * This function has two output parameters: \p cpuset and \p policy.
1881  * The values returned in these parameters depend on both the \p flags
1882  * passed in and the memory binding policies and nodesets of the pages
1883  * in the address range.
1884  *
1885  * If HWLOC_MEMBIND_STRICT is specified, the target pages are first
1886  * checked to see if they all have the same memory binding policy and
1887  * nodeset. If they do not, -1 is returned and errno is set to EXDEV.
1888  * If they are identical across all pages, the policy is returned in
1889  * \p policy. \p cpuset is set to the union of CPUs near the NUMA
1890  * node(s) in the nodeset.
1891  *
1892  * If HWLOC_MEMBIND_STRICT is not specified, the union of all NUMA
1893  * node(s) containing pages in the address range is calculated. \p
1894  * cpuset is then set to the CPUs near the NUMA node(s) in this union.
1895  * If all pages in the target have the same policy, it is returned in
1896  * \p policy. Otherwise, \p policy is set to HWLOC_MEMBIND_MIXED.
1897  *
1898  * If any other flags are specified, -1 is returned and errno is set
1899  * to EINVAL.
1900  */
1901 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);
1902 
1903 /** \brief Allocate some memory
1904  *
1905  * This is equivalent to malloc(), except that it tries to allocate
1906  * page-aligned memory from the OS.
1907  *
1908  * \note The allocated memory should be freed with hwloc_free().
1909  */
1910 HWLOC_DECLSPEC void *hwloc_alloc(hwloc_topology_t topology, size_t len);
1911 
1912 /** \brief Allocate some memory on the given physical nodeset \p nodeset
1913  *
1914  * \return -1 with errno set to ENOSYS if the action is not supported
1915  * and HWLOC_MEMBIND_STRICT is given
1916  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1917  * and HWLOC_MEMBIND_STRICT is given
1918  *
1919  * \note The allocated memory should be freed with hwloc_free().
1920  */
1921 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;
1922 
1923 /** \brief Allocate some memory on memory nodes near the given physical cpuset \p cpuset
1924  *
1925  * \return -1 with errno set to ENOSYS if the action is not supported
1926  * and HWLOC_MEMBIND_STRICT is given
1927  * \return -1 with errno set to EXDEV if the binding cannot be enforced
1928  * and HWLOC_MEMBIND_STRICT is given
1929  *
1930  * \note The allocated memory should be freed with hwloc_free().
1931  */
1932 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;
1933 
1934 /** \brief Free memory that was previously allocated by hwloc_alloc()
1935  * or hwloc_alloc_membind().
1936  */
1937 HWLOC_DECLSPEC int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
1938 
1939 /** @} */
1940 
1941 
1942 
1943 #ifdef __cplusplus
1944 } /* extern "C" */
1945 #endif
1946 
1947 
1948 /* high-level helpers */
1949 #include <hwloc/helper.h>
1950 
1951 
1952 #endif /* HWLOC_H */
HWLOC_DECLSPEC int hwloc_free(hwloc_topology_t topology, void *addr, size_t len)
Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().
Definition: bind.c:550
struct hwloc_obj * prev_cousin
Previous object of same type and depth.
Definition: hwloc.h:348
HWLOC_DECLSPEC const char * hwloc_obj_type_string(hwloc_obj_type_t type) __hwloc_attribute_const
Return a stringified topology object type.
Definition: traversal.c:175
signed os_level
OS-provided physical level, -1 if unknown or meaningless.
Definition: hwloc.h:344
unsigned char get_thisproc_cpubind
Getting the binding of the whole current process is supported.
Definition: hwloc.h:843
enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
Type of a OS device.
enum hwloc_obj_bridge_type_e hwloc_obj_bridge_type_t
Type of one side (upstream or downstream) of an I/O bridge.
static __hwloc_inline int __hwloc_attribute_pure hwloc_get_nbobjs_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the width of level type type.
Definition: hwloc.h:1068
void * userdata
Application-given private data pointer, initialized to NULL, use it as you wish.
Definition: hwloc.h:363
Host-side of a bridge, only possible upstream.
Definition: hwloc.h:257
unsigned sibling_rank
Index in parent's children[] array.
Definition: hwloc.h:352
Data cache.
Definition: hwloc.h:192
unsigned os_index
OS-provided physical index number.
Definition: hwloc.h:332
Assume that the selected backend provides the topology for the system on which we are running...
Definition: hwloc.h:666
struct hwloc_obj * hwloc_obj_t
Convenience typedef; a pointer to a struct hwloc_obj.
Definition: hwloc.h:462
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)
Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) in physical nodeset...
Definition: bind.c:391
Distances between objects.
Definition: hwloc.h:522
hwloc_uint64_t size
Size of pages.
Definition: hwloc.h:320
hwloc_obj_bridge_type_e
Type of one side (upstream or downstream) of an I/O bridge.
Definition: hwloc.h:256
HWLOC_DECLSPEC int hwloc_topology_export_xml(hwloc_topology_t topology, const char *xmlpath)
Export the topology into an XML file.
Definition: topology-xml.c:1405
HWLOC_DECLSPEC int hwloc_topology_export_xmlbuffer(hwloc_topology_t topology, char **xmlbuffer, int *buflen)
Export the topology into a newly-allocated XML memory buffer.
Definition: topology-xml.c:1452
HWLOC_DECLSPEC int hwloc_obj_type_snprintf(char *__hwloc_restrict string, size_t size, hwloc_obj_t obj, int verbose)
Stringify the type of a given topology object into a human-readable form.
Definition: traversal.c:377
Operating system GPU device.
Definition: hwloc.h:265
Operating system device.
Definition: hwloc.h:237
HWLOC_DECLSPEC 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.
Group-specific Object Attributes.
Definition: hwloc.h:475
Object type-specific Attributes.
Definition: hwloc.h:465
unsigned nbobjs
Number of objects considered in the matrix.
Definition: hwloc.h:525
unsigned char set_thread_cpubind
Binding a given thread only is supported.
Definition: hwloc.h:853
Allocate memory but do not immediately bind it to a specific locality.
Definition: hwloc.h:1482
unsigned char set_thisthread_membind
Binding the current thread only is supported.
Definition: hwloc.h:875
struct hwloc_obj * next_sibling
Next object below the same parent.
Definition: hwloc.h:353
unsigned char get_thread_cpubind
Getting the binding of a given thread only is supported.
Definition: hwloc.h:855
Move I/O objects to ancestors if their parents are removed during restriction.
Definition: hwloc.h:983
Request strict binding from the OS.
Definition: hwloc.h:1574
hwloc_uint64_t count
Number of pages of this size.
Definition: hwloc.h:321
Machine.
Definition: hwloc.h:179
Move Misc objects to ancestors if their parents are removed during restriction.
Definition: hwloc.h:978
hwloc_cpuset_t allowed_cpuset
The CPU set of allowed logical processors.
Definition: hwloc.h:398
unsigned depth
Depth of cache (e.g., L1, L2, ...etc.)
Definition: hwloc.h:469
HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char *__hwloc_restrict description)
Enable synthetic topology.
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition: hwloc.h:128
struct hwloc_obj * first_child
First child.
Definition: hwloc.h:359
struct hwloc_obj * parent
Parent, NULL if root (system object)
Definition: hwloc.h:351
HWLOC_DECLSPEC 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 physical bitmap set.
Definition: bind.c:106
unsigned char set_proc_membind
Binding a whole given process is supported.
Definition: hwloc.h:871
unsigned char set_thisproc_membind
Binding the whole current process is supported.
Definition: hwloc.h:867
hwloc_cpuset_t online_cpuset
The CPU set of online logical processors.
Definition: hwloc.h:390
The old deprecated Cpuset API.
hwloc_cpuset_t complete_cpuset
The complete CPU set of logical processors of this object,.
Definition: hwloc.h:379
Object memory.
Definition: hwloc.h:309
struct hwloc_obj_memory_s memory
Memory attributes.
Definition: hwloc.h:335
Allocate memory on the specified nodes.
Definition: hwloc.h:1493
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:331
Request for strict binding from the OS.
Definition: hwloc.h:1285
Sentinel value.
Definition: hwloc.h:243
HWLOC_DECLSPEC int hwloc_set_membind_nodeset(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)
Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) spe...
Definition: bind.c:260
unsigned char get_proc_last_cpu_location
Getting the last processors where a whole process ran is supported.
Definition: hwloc.h:859
hwloc_cpubind_flags_t
Process/Thread binding flags.
Definition: hwloc.h:1279
Objects of given type exist at different depth in the topology.
Definition: hwloc.h:1046
HWLOC_DECLSPEC int hwloc_topology_set_flags(hwloc_topology_t topology, unsigned long flags)
Set OR'ed flags to non-yet-loaded topology.
HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology)
Run internal checks on a topology structure.
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)
Provide a distance matrix.
Definition: distances.c:226
Bridge.
Definition: hwloc.h:225
hwloc_nodeset_t nodeset
NUMA nodes covered by this object or containing this object.
Definition: hwloc.h:409
unsigned char get_thisthread_cpubind
Getting the binding of the current thread only is supported.
Definition: hwloc.h:851
Set policy for a specific thread of the current process.
Definition: hwloc.h:1568
Migrate existing allocated memory.
Definition: hwloc.h:1585
Core.
Definition: hwloc.h:195
unsigned char get_proc_cpubind
Getting the binding of a whole given process is supported.
Definition: hwloc.h:847
unsigned char get_thisthread_last_cpu_location
Getting the last processors where the current thread ran is supported.
Definition: hwloc.h:861
int associativity
Ways of associativity, -1 if fully associative, 0 if unknown.
Definition: hwloc.h:471
hwloc_uint64_t local_memory
Local memory (in bytes)
Definition: hwloc.h:311
Set policy for all threads of the specified (possibly multithreaded) process.
Definition: hwloc.h:1561
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)
Query the default memory binding policy and physical locality of the specified process (the locality ...
Definition: bind.c:375
HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
Get the last physical CPU where the current process or thread ran.
Definition: bind.c:156
Reset the memory allocation policy to the system default.
Definition: hwloc.h:1480
HWLOC_DECLSPEC unsigned hwloc_get_api_version(void)
Indicate at runtime which hwloc API version was used at build time.
Definition: topology.c:47
struct hwloc_obj * last_child
Last child.
Definition: hwloc.h:360
unsigned char get_thisproc_last_cpu_location
Getting the last processors where the whole current process ran is supported.
Definition: hwloc.h:857
Array of local memory page types, NULL if no local memory and page_types is 0.
Definition: hwloc.h:319
Detect the whole system, ignore reservations and offline settings.
Definition: hwloc.h:657
HWLOC_DECLSPEC int hwloc_compare_types(hwloc_obj_type_t type1, hwloc_obj_type_t type2) __hwloc_attribute_const
Compare the depth of two object types.
Definition: topology.c:384
Miscellaneous objects.
Definition: hwloc.h:220
struct hwloc_obj_info_s * infos
Array of stringified info type=name.
Definition: hwloc.h:456
struct hwloc_obj ** children
Children, children[0 .
Definition: hwloc.h:358
Flags describing actual discovery support for this topology.
Definition: hwloc.h:833
Structure of a topology object.
Definition: hwloc.h:329
hwloc_const_bitmap_t hwloc_const_cpuset_t
A non-modifiable hwloc_cpuset_t.
Definition: hwloc.h:130
unsigned char alloc_membind
Allocating a bound memory area is supported.
Definition: hwloc.h:883
struct hwloc_obj * next_cousin
Next object of same type and depth.
Definition: hwloc.h:347
unsigned depth
Depth of group object.
Definition: hwloc.h:476
float * latency
Matrix of latencies between objects, stored as a one-dimension array.
Definition: hwloc.h:530
unsigned char get_thisthread_membind
Getting the binding of the current thread only is supported.
Definition: hwloc.h:877
HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topology, hwloc_pid_t pid)
Change which pid the topology is viewed from.
Operating system block device.
Definition: hwloc.h:263
unsigned char replicate_membind
Replication policy is supported.
Definition: hwloc.h:891
unsigned relative_depth
Relative depth of the considered objects below the object containing this distance information...
Definition: hwloc.h:523
HWLOC_DECLSPEC int hwloc_topology_init(hwloc_topology_t *topologyp)
Allocate a topology context.
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
Allocate some memory on memory nodes near the given physical cpuset cpuset.
Definition: bind.c:532
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)
Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified b...
Definition: bind.c:335
Group objects.
Definition: hwloc.h:208
HWLOC_DECLSPEC int hwloc_topology_set_fsroot(hwloc_topology_t __hwloc_restrict topology, const char *__hwloc_restrict fsroot_path)
Change the file-system root path when building the topology from sysfs/procfs.
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)
Query the default memory binding policy and physical locality of the specified process.
Definition: bind.c:365
HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type(hwloc_topology_t topology, unsigned depth) __hwloc_attribute_pure
Returns the type of objects at depth depth.
Definition: traversal.c:22
Cache-specific Object Attributes.
Definition: hwloc.h:467
hwloc_const_bitmap_t hwloc_const_nodeset_t
A non-modifiable hwloc_nodeset_t.
Definition: hwloc.h:148
HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags)
Restrict the topology to the given CPU set.
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)
Query the physical NUMA node(s) and binding policy of the memory identified by (addr, len ).
Definition: bind.c:420
HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
Get the current physical binding of process pid.
Definition: bind.c:120
float latency_max
The maximal value in the latency matrix.
Definition: hwloc.h:535
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:96
unsigned page_types_len
Size of array page_types.
Definition: hwloc.h:313
unsigned char set_thisproc_cpubind
Binding the whole current process is supported.
Definition: hwloc.h:841
Virtual depth for bridge object level.
Definition: hwloc.h:1047
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
Allocate some memory on the given physical nodeset nodeset.
Definition: bind.c:495
HWLOC_DECLSPEC unsigned hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure
Get the depth of the hierarchical tree of objects.
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)
Stringify a given topology object into a human-readable form.
Adapt distance matrices according to objects being removed during restriction.
Definition: hwloc.h:973
unsigned logical_index
Horizontal index in the whole list of similar objects, could be a "cousin_rank" since it's the rank w...
Definition: hwloc.h:342
Operating system openfabrics device.
Definition: hwloc.h:269
unsigned char firsttouch_membind
First-touch policy is supported.
Definition: hwloc.h:885
PCI device.
Definition: hwloc.h:232
hwloc_compare_types_e
Definition: hwloc.h:294
NUMA node.
Definition: hwloc.h:184
HWLOC_DECLSPEC void hwloc_topology_destroy(hwloc_topology_t topology)
Terminate and free a topology context.
HWLOC_DECLSPEC int hwloc_obj_cpuset_snprintf(char *__hwloc_restrict str, size_t size, size_t nobj, const hwloc_obj_t *__hwloc_restrict objs)
Stringify the cpuset containing a set of objects.
HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth(hwloc_topology_t topology, unsigned depth) __hwloc_attribute_pure
Returns the width of level at depth depth.
hwloc_nodeset_t complete_nodeset
The complete NUMA node set of this object,.
Definition: hwloc.h:426
float latency_base
The multiplier that should be applied to latency matrix to retrieve the original OS-provided latencie...
Definition: hwloc.h:536
unsigned char migrate_membind
Migration flags is supported.
Definition: hwloc.h:896
Virtual depth for software device object level.
Definition: hwloc.h:1049
No object of given type exists in the topology.
Definition: hwloc.h:1045
HWLOC_DECLSPEC int hwloc_get_membind_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t *policy, int flags)
Query the default memory binding policy and physical locality of the current process or thread...
Definition: bind.c:299
hwloc_uint64_t size
Size of cache in bytes.
Definition: hwloc.h:468
unsigned arity
Number of children.
Definition: hwloc.h:357
HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology)
Build the actual topology.
Socket, physical package, or chip.
Definition: hwloc.h:188
HWLOC_DECLSPEC void hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value)
Add the given info name and value pair to the given object.
Definition: topology.c:254
Avoid any effect on CPU binding.
Definition: hwloc.h:1593
HWLOC_DECLSPEC void hwloc_free_xmlbuffer(hwloc_topology_t topology, char *xmlbuffer)
Free a buffer allocated by hwloc_topology_export_xmlbuffer()
Definition: topology-xml.c:1468
hwloc_uint64_t total_memory
Total memory (in bytes) in this object and its children.
Definition: hwloc.h:310
HWLOC_DECLSPEC int hwloc_topology_ignore_all_keep_structure(hwloc_topology_t topology)
Ignore all objects that do not bring any structure.
For each page bound with this policy, by next time it is touched (and next time only), it is moved from its current location to the local NUMA node of the thread where the memory reference occurred (if it needs to be moved at all).
Definition: hwloc.h:1532
static __hwloc_inline hwloc_obj_t __hwloc_attribute_pure hwloc_get_obj_by_type(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
Returns the topology object at logical index idx with type type.
Definition: hwloc.h:1110
Value returned by hwloc_compare_types when types can not be compared.
Definition: hwloc.h:295
HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure
Does the topology context come from this system?
HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char *__hwloc_restrict xmlpath)
Enable XML-file based topology.
Object info.
Definition: hwloc.h:543
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)
Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (addr...
Definition: bind.c:430
HWLOC_DECLSPEC hwloc_obj_type_t hwloc_obj_type_of_string(const char *string) __hwloc_attribute_pure
Return an object type from the string.
Definition: traversal.c:196
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)
Set the default memory binding policy of the specified process to prefer the NUMA node(s) near the sp...
Definition: bind.c:350
OS Device specific Object Attributes.
Definition: hwloc.h:503
Replicate memory on the given nodes; reads from this memory will attempt to be serviced from the NUMA...
Definition: hwloc.h:1510
unsigned char set_proc_cpubind
Binding a whole given process is supported.
Definition: hwloc.h:845
The bitmap API, for use in hwloc itself.
struct hwloc_obj * prev_sibling
Previous object below the same parent.
Definition: hwloc.h:354
unsigned char set_area_membind
Binding a given memory area is supported.
Definition: hwloc.h:879
Allocate memory on the given nodes in an interleaved / round-robin manner.
Definition: hwloc.h:1495
char * name
Info name.
Definition: hwloc.h:544
HWLOC_DECLSPEC void * hwloc_alloc(hwloc_topology_t topology, size_t len)
Allocate some memory.
Definition: bind.c:487
Avoid any effect on memory binding.
Definition: hwloc.h:1313
unsigned char get_thisproc_membind
Getting the binding of the whole current process is supported.
Definition: hwloc.h:869
PCI Device specific Object Attributes.
Definition: hwloc.h:479
char * name
Object description if any.
Definition: hwloc.h:333
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)
Stringify the attributes of a given topology object into a human-readable form.
Flags describing actual memory binding support for this topology.
Definition: hwloc.h:865
static __hwloc_inline const char *__hwloc_attribute_pure 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.
Definition: hwloc.h:1204
Bind all threads of the current (possibly) multithreaded process.
Definition: hwloc.h:1280
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:164
HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t *policy, int flags)
Query the default memory binding policy and physical locality of the current process or thread (the l...
Definition: bind.c:319
hwloc_restrict_flags_e
Flags to be given to hwloc_topology_restrict().
Definition: hwloc.h:972
HWLOC_DECLSPEC const struct hwloc_topology_support * hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology)
Retrieve the topology support.
PCI-side of a bridge.
Definition: hwloc.h:258
Operating system network device.
Definition: hwloc.h:267
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)
Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) near physical cpuset...
Definition: bind.c:405
unsigned char pu
Detecting the number of PU objects is supported.
Definition: hwloc.h:835
HWLOC_DECLSPEC 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_osdev_type_e
Type of a OS device.
Definition: hwloc.h:262
Flags describing actual PU binding support for this topology.
Definition: hwloc.h:839
hwloc_topology_flags_e
Flags to be set onto a topology context before load.
Definition: hwloc.h:656
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:366
unsigned char interleave_membind
Interleave policy is supported.
Definition: hwloc.h:889
HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
Get the last physical CPU where a process ran.
Definition: bind.c:176
Whole system (may be a cluster of machines).
Definition: hwloc.h:174
Bridge specific Object Attribues.
Definition: hwloc.h:488
hwloc_membind_policy_t
Memory binding policy.
Definition: hwloc.h:1479
unsigned char set_thisthread_cpubind
Binding the current thread only is supported.
Definition: hwloc.h:849
HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth(hwloc_topology_t topology, unsigned depth, unsigned idx) __hwloc_attribute_pure
Returns the topology object at logical index idx from depth depth.
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:337
unsigned linesize
Cache-line size in bytes.
Definition: hwloc.h:470
Definition: private.h:56
Operating system dma engine device.
Definition: hwloc.h:271
hwloc_membind_flags_t
Memory binding flags.
Definition: hwloc.h:1560
HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)
Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) nea...
Definition: bind.c:284
unsigned infos_count
Size of infos array.
Definition: hwloc.h:457
hwloc_nodeset_t allowed_nodeset
The set of allowed NUMA memory nodes.
Definition: hwloc.h:440
Processing Unit, or (Logical) Processor.
Definition: hwloc.h:199
struct hwloc_distances_s ** distances
Distances between all objects at same depth below this object.
Definition: hwloc.h:453
HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
Get current process or thread binding.
Definition: bind.c:86
char * value
Info value.
Definition: hwloc.h:545
HWLOC_DECLSPEC int hwloc_topology_ignore_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Ignore an object type.
Set of flags describing actual support for this topology.
Definition: hwloc.h:905
hwloc_bitmap_t hwloc_nodeset_t
A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes...
Definition: hwloc.h:145
HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char *__hwloc_restrict buffer, int size)
Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...
HWLOC_DECLSPEC 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 as a leaf of the topology.
unsigned char get_proc_membind
Getting the binding of a whole given process is supported.
Definition: hwloc.h:873
hwloc_get_type_depth_e
Definition: hwloc.h:1044
Definition: cpuset.c:38
Bind current thread of current process.
Definition: hwloc.h:1283
HWLOC_DECLSPEC int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
unsigned char bind_membind
Bind policy is supported.
Definition: hwloc.h:887
unsigned depth
Vertical index in the hierarchy.
Definition: hwloc.h:341
Virtual depth for PCI device object level.
Definition: hwloc.h:1048
unsigned char nexttouch_membind
Next-touch migration policy is supported.
Definition: hwloc.h:893
unsigned char get_area_membind
Getting the binding of a given memory area is supported.
Definition: hwloc.h:881
Returned by hwloc_get_membind*() functions when multiple threads or parts of a memory area have diffe...
Definition: hwloc.h:1542
High-level hwloc traversal helpers.
HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
Bind current process or thread on cpus given in physical bitmap set.
Definition: bind.c:62