Hardware Locality (hwloc)  master-20230831.0905.git364652f8b
plugins.h
1 /*
2  * Copyright © 2013-2023 Inria. All rights reserved.
3  * Copyright © 2016 Cisco Systems, Inc. All rights reserved.
4  * See COPYING in top-level directory.
5  */
6 
7 #ifndef HWLOC_PLUGINS_H
8 #define HWLOC_PLUGINS_H
9 
14 struct hwloc_backend;
15 
16 #include "hwloc.h"
17 
18 #ifdef HWLOC_INSIDE_PLUGIN
19 /* needed for hwloc_plugin_check_namespace() */
20 #ifdef HWLOC_HAVE_LTDL
21 #include <ltdl.h>
22 #else
23 #include <dlfcn.h>
24 #endif
25 #endif
26 
27 
28 
45  const char *name;
46 
50  unsigned phases;
51 
60  unsigned excluded_phases;
61 
65  struct hwloc_backend * (*instantiate)(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned excluded_phases, const void *data1, const void *data2, const void *data3);
66 
79  unsigned priority;
80 
85 
90  struct hwloc_disc_component * next;
91 };
92 
106 typedef enum hwloc_disc_phase_e {
112 
116 
120 
124 
128 
132 
136 
144 
149 };
150 
161 
165  unsigned excluded_phases;
166 
168  unsigned long flags;
169 };
170 
191  struct hwloc_disc_component * component;
193  struct hwloc_topology * topology;
195  int envvar_forced;
197  struct hwloc_backend * next;
198 
202  unsigned phases;
203 
205  unsigned long flags;
206 
214 
218  void (*disable)(struct hwloc_backend *backend);
219 
225  int (*discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status);
226 
231  int (*get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset);
232 };
233 
235 #define HWLOC_BACKEND_PRIVATE_DATA(_backend) (void*)(((char*)(_backend)) + sizeof(struct hwloc_backend))
236 
243 HWLOC_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned long private_data_size);
244 
246 HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_backend *backend);
247 
264 
268 
276  unsigned abi;
277 
295  int (*init)(unsigned long flags);
296 
308  void (*finalize)(unsigned long flags);
309 
312 
314  unsigned long flags;
315 
317  void * data;
318 };
319 
349 HWLOC_DECLSPEC int hwloc_hide_errors(void);
350 
351 #define HWLOC_SHOW_CRITICAL_ERRORS() (hwloc_hide_errors() < 2)
352 #define HWLOC_SHOW_ALL_ERRORS() (hwloc_hide_errors() == 0)
353 
382 HWLOC_DECLSPEC hwloc_obj_t
383 hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root,
384  hwloc_obj_t obj, const char *reason);
385 
402 HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
403 
408 HWLOC_DECLSPEC hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index);
409 
418 HWLOC_DECLSPEC int hwloc_obj_add_children_sets(hwloc_obj_t obj);
419 
427 HWLOC_DECLSPEC int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags __hwloc_attribute_unused);
428 
450 static __hwloc_inline int
451 hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
452 {
453 #ifdef HWLOC_INSIDE_PLUGIN
454  void *sym;
455 #ifdef HWLOC_HAVE_LTDL
456  lt_dlhandle handle = lt_dlopen(NULL);
457 #else
458  void *handle = dlopen(NULL, RTLD_NOW|RTLD_LOCAL);
459 #endif
460  if (!handle)
461  /* cannot check, assume things will work */
462  return 0;
463 #ifdef HWLOC_HAVE_LTDL
464  sym = lt_dlsym(handle, symbol);
465  lt_dlclose(handle);
466 #else
467  sym = dlsym(handle, symbol);
468  dlclose(handle);
469 #endif
470  if (!sym) {
471  static int verboseenv_checked = 0;
472  static int verboseenv_value = 0;
473  if (!verboseenv_checked) {
474  const char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
475  verboseenv_value = verboseenv ? atoi(verboseenv) : 0;
476  verboseenv_checked = 1;
477  }
478  if (verboseenv_value)
479  fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
480  pluginname, symbol);
481  return -1;
482  }
483 #endif /* HWLOC_INSIDE_PLUGIN */
484  return 0;
485 }
486 
503 static __hwloc_inline int
505 {
506  unsigned baseclass = classid >> 8;
507  return (baseclass == 0x03 /* PCI_BASE_CLASS_DISPLAY */
508  || baseclass == 0x02 /* PCI_BASE_CLASS_NETWORK */
509  || baseclass == 0x01 /* PCI_BASE_CLASS_STORAGE */
510  || baseclass == 0x00 /* Unclassified, for Atos/Bull BXI */
511  || baseclass == 0x0b /* PCI_BASE_CLASS_PROCESSOR */
512  || classid == 0x0c04 /* PCI_CLASS_SERIAL_FIBER */
513  || classid == 0x0c06 /* PCI_CLASS_SERIAL_INFINIBAND */
514  || classid == 0x0502 /* PCI_CLASS_MEMORY_CXL */
515  || baseclass == 0x06 /* PCI_BASE_CLASS_BRIDGE with non-PCI downstream. the core will drop the useless ones later */
516  || baseclass == 0x12 /* Processing Accelerators */);
517 }
518 
523 static __hwloc_inline int
525 {
526  return (subtype != HWLOC_OBJ_OSDEV_DMA);
527 }
528 
535 static __hwloc_inline int
537 {
539  hwloc_topology_get_type_filter(topology, type, &filter);
540  assert(filter != HWLOC_TYPE_FILTER_KEEP_IMPORTANT); /* IMPORTANT only used for I/O */
541  return filter == HWLOC_TYPE_FILTER_KEEP_NONE ? 0 : 1;
542 }
543 
548 static __hwloc_inline int
550 {
551  hwloc_obj_type_t type = obj->type;
553  hwloc_topology_get_type_filter(topology, type, &filter);
554  if (filter == HWLOC_TYPE_FILTER_KEEP_NONE)
555  return 0;
556  if (filter == HWLOC_TYPE_FILTER_KEEP_IMPORTANT) {
557  if (type == HWLOC_OBJ_PCI_DEVICE)
559  if (type == HWLOC_OBJ_OS_DEVICE)
561  }
562  return 1;
563 }
564 
581 HWLOC_DECLSPEC unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap);
582 
588 HWLOC_DECLSPEC int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
589 
594 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config);
595 
602 HWLOC_DECLSPEC int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func,
603  unsigned *secondary_busp, unsigned *subordinate_busp,
604  const unsigned char *config);
605 
610 HWLOC_DECLSPEC void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj);
611 
617 HWLOC_DECLSPEC int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree);
618 
642 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
643 
650 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
651 
654 
663  const char *name, unsigned long kind,
664  unsigned long flags);
665 
677 HWLOC_DECLSPEC int
680  unsigned nbobjs, hwloc_obj_t *objs,
681  hwloc_uint64_t *values,
682  unsigned long flags);
683 
690 HWLOC_DECLSPEC int
693  unsigned long flags);
694 
700 #endif /* HWLOC_PLUGINS_H */
The data field must point to a struct hwloc_disc_component.
Definition: plugins.h:263
static int hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
Check whether the given object should be filtered-out.
Definition: plugins.h:549
int(* init)(unsigned long flags)
Process-wide component initialization callback.
Definition: plugins.h:295
hwloc_disc_status_flag_e
Discovery status flags.
Definition: plugins.h:146
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:69
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
Final tweaks to a ready-to-use topology. This phase runs once the topology is loaded, before it is returned to the topology. Hence it may only use the main hwloc API for modifying the topology, for instance by restricting it, adding info attributes, etc.
Definition: plugins.h:142
CPU discovery.
Definition: plugins.h:115
xml or synthetic, platform-specific components. Discovers everything including CPU, memory, I/O and everything else. A component with a Global phase usually excludes all other phases.
Definition: plugins.h:111
int hwloc_hide_errors(void)
Check whether error messages are hidden.
unsigned priority
Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
Definition: plugins.h:79
unsigned phases
Discovery phases performed by this component, possibly without some of them if excluded by other comp...
Definition: plugins.h:202
hwloc_component_type_t type
Component type.
Definition: plugins.h:311
Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
Definition: hwloc.h:372
The data field must point to a struct hwloc_xml_component.
Definition: plugins.h:266
I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).
Definition: plugins.h:127
int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags)
Request a reconnection of children and levels in the topology.
unsigned short class_id
Definition: hwloc.h:684
int(* get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
Callback to retrieve the locality of a PCI object. Called by the PCI core when attaching PCI hierarch...
Definition: plugins.h:231
int(* discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status)
Main discovery callback. returns -1 on error, either because it couldn&#39;t add its objects ot the exist...
Definition: plugins.h:225
enum hwloc_component_type_e hwloc_component_type_t
Generic component type.
int hwloc_backend_distances_add_commit(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned long flags)
Commit a new distances structure.
static int hwloc_filter_check_pcidev_subtype_important(unsigned classid)
Check whether the given PCI device classid is important.
Definition: plugins.h:504
Only keep likely-important objects of the given type.
Definition: hwloc.h:2529
unsigned excluded_phases
Dynamically excluded phases. If a component decides during discovery that some phases are no longer n...
Definition: plugins.h:165
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
hwloc_obj_osdev_type_t type
Definition: hwloc.h:706
static int hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Check whether a non-I/O object type should be filtered-out.
Definition: plugins.h:536
int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree)
Add some hostbridges on top of the given tree of PCI objects and attach them to the topology...
unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap)
Return the offset of the given capability in the PCI config space buffer.
Attach memory to existing CPU objects.
Definition: plugins.h:119
The sets of allowed resources were already retrieved.
Definition: plugins.h:148
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:446
char * name
Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name str...
Definition: hwloc.h:456
struct hwloc_obj * hwloc_pci_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the PCI device or bridge matching a PCI bus ID exactly.
int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed)
Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset...
unsigned long flags
OR&#39;ed set of hwloc_disc_status_flag_e.
Definition: plugins.h:168
Generic component structure.
Definition: plugins.h:274
int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func, unsigned *secondary_busp, unsigned *subordinate_busp, const unsigned char *config)
Fills the attributes of the given PCI bridge using the given PCI config space.
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:463
unsigned abi
Component ABI version, set to HWLOC_COMPONENT_ABI.
Definition: plugins.h:276
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:723
void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj)
Insert a PCI object in the given PCI tree by looking at PCI bus IDs.
int hwloc_backend_enable(struct hwloc_backend *backend)
Enable a previously allocated and setup backend.
Annotating existing objects, adding distances, etc.
Definition: plugins.h:135
unsigned long flags
Component flags, unused for now.
Definition: plugins.h:314
hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config)
Return the hwloc object type (PCI device or Bridge) for the given class and configuration space...
hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
Allocate and initialize an object of the given type and physical index.
const char * name
Name. If this component is built as a plugin, this name does not have to match the plugin filename...
Definition: plugins.h:45
Discovery component structure.
Definition: plugins.h:41
hwloc_component_type_e
Generic component type.
Definition: plugins.h:261
static int hwloc_plugin_check_namespace(const char *pluginname, const char *symbol)
Make sure that plugins can lookup core symbols.
Definition: plugins.h:451
enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
Type of a OS device.
Attach PCI devices and bridges to existing CPU objects.
Definition: plugins.h:123
hwloc_disc_phase_t phase
The current discovery phase that is performed. Must match one of the phases in the component phases f...
Definition: plugins.h:160
Structure of a topology object.
Definition: hwloc.h:444
PCI device (filtered out by default).
Definition: hwloc.h:290
void * data
Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
Definition: plugins.h:317
Discovery backend structure.
Definition: plugins.h:189
unsigned phases
Discovery phases performed by this component. OR&#39;ed set of hwloc_disc_phase_t.
Definition: plugins.h:50
struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component, unsigned long private_data_size)
Allocate a backend structure, set good default values, initialize backend->component and topology...
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:197
int hwloc_obj_add_children_sets(hwloc_obj_t obj)
Setup object cpusets/nodesets by OR&#39;ing its children.
struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the object or a parent of a PCI bus ID.
unsigned long flags
Backend flags, currently always 0.
Definition: plugins.h:205
enum hwloc_disc_phase_e hwloc_disc_phase_t
Discovery phase.
Operating system device (filtered out by default).
Definition: hwloc.h:300
unsigned excluded_phases
Component phases to exclude, as an OR&#39;ed set of hwloc_disc_phase_t.
Definition: plugins.h:60
void(* disable)(struct hwloc_backend *backend)
Callback for freeing things stored inside the private data. May be NULL.
Definition: plugins.h:218
void(* finalize)(unsigned long flags)
Process-wide component termination callback.
Definition: plugins.h:308
static int hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
Check whether the given OS device subtype is important.
Definition: plugins.h:524
Misc objects that gets added below anything else.
Definition: plugins.h:131
int is_thissystem
Backend-specific &#39;is_thissystem&#39; property. Set to 0 if the backend disables the thissystem flag for t...
Definition: plugins.h:213
void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
Insert an object somewhere in the topology.
void * hwloc_backend_distances_add_handle_t
Handle to a new distances structure during its addition to the topology.
Definition: plugins.h:653
Discovery status structure.
Definition: plugins.h:156
hwloc_backend_distances_add_handle_t hwloc_backend_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)
Create a new empty distances structure.
unsigned enabled_by_default
Enabled by default. If unset, if will be disabled unless explicitly requested.
Definition: plugins.h:84
hwloc_type_filter_e
Type filtering flags.
Definition: hwloc.h:2486
hwloc_obj_t hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
Add an object to the topology.
hwloc_disc_phase_e
Discovery phase.
Definition: plugins.h:106
Ignore all objects of this type.
Definition: hwloc.h:2500
int hwloc_backend_distances_add_values(hwloc_topology_t topology, hwloc_backend_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)
Specify the objects and values in a new empty distances structure.
int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter)
Get the current filtering for the given object type.