Hardware Locality (hwloc) 2.0.4

plugins.h
1 /*
2 * Copyright © 2013-2017 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 #ifdef HWLOC_INSIDE_PLUGIN
18 /* needed for hwloc_plugin_check_namespace() */
19 #include <ltdl.h>
20 #endif
21
22
23
29 typedef enum hwloc_disc_component_type_e {
32 HWLOC_DISC_COMPONENT_TYPE_CPU = (1<<0),
33
39 HWLOC_DISC_COMPONENT_TYPE_GLOBAL = (1<<1),
40
43 HWLOC_DISC_COMPONENT_TYPE_MISC = (1<<2)
44 } hwloc_disc_component_type_t;
45
51 struct hwloc_disc_component {
53 hwloc_disc_component_type_t type;
54
58 const char *name;
59
68 unsigned excludes;
69
73 struct hwloc_backend * (*instantiate)(struct hwloc_disc_component *component, const void *data1, const void *data2, const void *data3);
74
87 unsigned priority;
88
92 unsigned enabled_by_default;
93
98 struct hwloc_disc_component * next;
99 };
100
120 struct hwloc_backend {
122 struct hwloc_disc_component * component;
124 struct hwloc_topology * topology;
126 int envvar_forced;
128 struct hwloc_backend * next;
129
131 unsigned long flags;
132
136 int is_thissystem;
137
139 void * private_data;
143 void (*disable)(struct hwloc_backend *backend);
144
150 int (*discover)(struct hwloc_backend *backend);
151
154 int (*get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset);
155 };
156
160 HWLOC_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_disc_component *component);
161
163 HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_topology *topology, struct hwloc_backend *backend);
164
175 typedef enum hwloc_component_type_e {
177 HWLOC_COMPONENT_TYPE_DISC,
178
180 HWLOC_COMPONENT_TYPE_XML
181 } hwloc_component_type_t;
182
188 struct hwloc_component {
190 unsigned abi;
191
209 int (*init)(unsigned long flags);
210
222 void (*finalize)(unsigned long flags);
223
225 hwloc_component_type_t type;
226
228 unsigned long flags;
229
231 void * data;
232 };
233
267 HWLOC_DECLSPEC struct hwloc_obj *hwloc_insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj);
268
270 typedef void (*hwloc_report_error_t)(const char * msg, int line);
272 HWLOC_DECLSPEC void hwloc_report_os_error(const char * msg, int line);
274 HWLOC_DECLSPEC int hwloc_hide_errors(void);
275
282 HWLOC_DECLSPEC struct hwloc_obj *hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, hwloc_report_error_t report_error);
283
300 HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
301
306 HWLOC_DECLSPEC hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index);
307
316 HWLOC_DECLSPEC int hwloc_obj_add_children_sets(hwloc_obj_t obj);
317
325 HWLOC_DECLSPEC int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags __hwloc_attribute_unused);
326
348 static __hwloc_inline int
349 hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
350 {
351 #ifdef HWLOC_INSIDE_PLUGIN
352 lt_dlhandle handle;
353 void *sym;
354 handle = lt_dlopen(NULL);
355 if (!handle)
356 /* cannot check, assume things will work */
357 return 0;
358 sym = lt_dlsym(handle, symbol);
359 lt_dlclose(handle);
360 if (!sym) {
361 static int verboseenv_checked = 0;
362 static int verboseenv_value = 0;
363 if (!verboseenv_checked) {
364 const char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
365 verboseenv_value = verboseenv ? atoi(verboseenv) : 0;
366 verboseenv_checked = 1;
367 }
368 if (verboseenv_value)
369 fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
370 pluginname, symbol);
371 return -1;
372 }
373 #endif /* HWLOC_INSIDE_PLUGIN */
374 return 0;
375 }
376
390 static __hwloc_inline int
391 hwloc_filter_check_pcidev_subtype_important(unsigned classid)
392 {
393 unsigned baseclass = classid >> 8;
394 return (baseclass == 0x03 /* PCI_BASE_CLASS_DISPLAY */
395 || baseclass == 0x02 /* PCI_BASE_CLASS_NETWORK */
396 || baseclass == 0x01 /* PCI_BASE_CLASS_STORAGE */
397 || baseclass == 0x0b /* PCI_BASE_CLASS_PROCESSOR */
398 || classid == 0x0c04 /* PCI_CLASS_SERIAL_FIBER */
399 || classid == 0x0c06 /* PCI_CLASS_SERIAL_INFINIBAND */
400 || baseclass == 0x12 /* Processing Accelerators */);
401 }
402
407 static __hwloc_inline int
408 hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
409 {
410 return (subtype != HWLOC_OBJ_OSDEV_DMA);
411 }
412
419 static __hwloc_inline int
420 hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
421 {
422 enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
423 hwloc_topology_get_type_filter(topology, type, &filter);
424 assert(filter != HWLOC_TYPE_FILTER_KEEP_IMPORTANT); /* IMPORTANT only used for I/O */
425 return filter == HWLOC_TYPE_FILTER_KEEP_NONE ? 0 : 1;
426 }
427
432 static __hwloc_inline int
433 hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
434 {
435 hwloc_obj_type_t type = obj->type;
436 enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
437 hwloc_topology_get_type_filter(topology, type, &filter);
438 if (filter == HWLOC_TYPE_FILTER_KEEP_NONE)
439 return 0;
440 if (filter == HWLOC_TYPE_FILTER_KEEP_IMPORTANT) {
441 if (type == HWLOC_OBJ_PCI_DEVICE)
442 return hwloc_filter_check_pcidev_subtype_important(obj->attr->pcidev.class_id);
443 if (type == HWLOC_OBJ_OS_DEVICE)
444 return hwloc_filter_check_osdev_subtype_important(obj->attr->osdev.type);
445 }
446 return 1;
447 }
448
462 HWLOC_DECLSPEC unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap);
463
469 HWLOC_DECLSPEC int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
470
475 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config);
476
483 HWLOC_DECLSPEC int hwloc_pcidisc_setup_bridge_attr(hwloc_obj_t obj, const unsigned char *config);
484
489 HWLOC_DECLSPEC void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj);
490
499 HWLOC_DECLSPEC int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree);
500
523 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pcidisc_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
524
535 HWLOC_DECLSPEC struct hwloc_obj * hwloc_pcidisc_find_busid_parent(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
536
542 #endif /* HWLOC_PLUGINS_H */
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:407
hwloc_disc_component::priority
unsigned priority
Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
Definition: plugins.h:87
hwloc_disc_component
Discovery component structure.
Definition: plugins.h:51
hwloc_filter_check_keep_object
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:433
hwloc_backend_alloc
struct hwloc_backend * hwloc_backend_alloc(struct hwloc_disc_component *component)
Allocate a backend structure, set good default values, initialize backend->component and topology...
hwloc_component::flags
unsigned long flags
Component flags, unused for now.
Definition: plugins.h:228
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
hwloc_disc_component::type
hwloc_disc_component_type_t type
Discovery component type.
Definition: plugins.h:53
HWLOC_DISC_COMPONENT_TYPE_GLOBAL
xml or synthetic, platform-specific components such as bgq. Anything the discovers CPU and everything...
Definition: plugins.h:39
hwloc_backend::flags
unsigned long flags
Backend flags, currently always 0.
Definition: plugins.h:131
hwloc_component
Generic component structure.
Definition: plugins.h:188
HWLOC_DISC_COMPONENT_TYPE_CPU
CPU-only discovery through the OS, or generic no-OS support.
Definition: plugins.h:32
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:357
hwloc_plugin_check_namespace
static int hwloc_plugin_check_namespace(const char *pluginname, const char *symbol)
Make sure that plugins can lookup core symbols.
Definition: plugins.h:349
hwloc_disc_component::enabled_by_default
unsigned enabled_by_default
Enabled by default. If unset, if will be disabled unless explicitly requested.
Definition: plugins.h:92
hwloc_obj_type_t
hwloc_obj_type_t
Definition: hwloc.h:176
hwloc_pcidisc_tree_insert_by_busid
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.
hwloc_component::abi
unsigned abi
Component ABI version, set to HWLOC_COMPONENT_ABI.
Definition: plugins.h:190
hwloc_component::type
hwloc_component_type_t type
Component type.
Definition: plugins.h:225
hwloc_pcidisc_find_cap
unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap)
Return the offset of the given capability in the PCI config space buffer.
hwloc_backend::disable
void(* disable)(struct hwloc_backend *backend)
Callback for freeing the private_data. May be NULL.
Definition: plugins.h:143
hwloc_component_type_t
enum hwloc_component_type_e hwloc_component_type_t
Generic component type.
HWLOC_TYPE_FILTER_KEEP_NONE
Ignore all objects of this type.
Definition: hwloc.h:2020
hwloc_backend
Discovery backend structure.
Definition: plugins.h:120
hwloc_filter_check_keep_object_type
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:420
hwloc_obj_attr_u::osdev
struct hwloc_obj_attr_u::hwloc_osdev_attr_s osdev
HWLOC_TYPE_FILTER_KEEP_IMPORTANT
Only keep likely-important objects of the given type.
Definition: hwloc.h:2049
hwloc_report_error_t
void(* hwloc_report_error_t)(const char *msg, int line)
Type of error callbacks during object insertion.
Definition: plugins.h:270
hwloc_topology_get_type_filter
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.
hwloc_hide_errors
int hwloc_hide_errors(void)
Check whether insertion errors are hidden.
HWLOC_OBJ_OS_DEVICE
Operating system device (filtered out by default). They are not added to the topology unless I/O disc...
Definition: hwloc.h:263
hwloc_alloc_setup_object
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.
hwloc__insert_object_by_cpuset
struct hwloc_obj * hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, hwloc_report_error_t report_error)
Add an object to the topology and specify which error callback to use.
hwloc_filter_check_pcidev_subtype_important
static int hwloc_filter_check_pcidev_subtype_important(unsigned classid)
Check whether the given PCI device classid is important.
Definition: plugins.h:391
hwloc_component_type_e
hwloc_component_type_e
Generic component type.
Definition: plugins.h:175
hwloc_pcidisc_find_busid_parent
struct hwloc_obj * hwloc_pcidisc_find_busid_parent(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the normal parent of a PCI bus ID.
hwloc_pcidisc_find_linkspeed
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...
hwloc_obj_attr_u::hwloc_pcidev_attr_s::class_id
unsigned short class_id
Definition: hwloc.h:589
hwloc_disc_component_type_t
enum hwloc_disc_component_type_e hwloc_disc_component_type_t
Discovery component type.
HWLOC_OBJ_PCI_DEVICE
PCI device (filtered out by default). They are not added to the topology unless I/O discovery is enab...
Definition: hwloc.h:256
hwloc_backend::is_thissystem
int is_thissystem
Backend-specific &#39;is_thissystem&#39; property. Set to 0 or 1 if the backend should enforce the thissystem...
Definition: plugins.h:136
hwloc_type_filter_e
hwloc_type_filter_e
Type filtering flags.
Definition: hwloc.h:2006
HWLOC_COMPONENT_TYPE_DISC
The data field must point to a struct hwloc_disc_component.
Definition: plugins.h:177
hwloc_backend::get_pci_busid_cpuset
int(* get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset)
Callback used by the PCI backend to retrieve the locality of a PCI object from the OS/cpu backend...
Definition: plugins.h:154
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:67
hwloc_obj_osdev_type_t
enum hwloc_obj_osdev_type_e hwloc_obj_osdev_type_t
Type of a OS device.
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:637
HWLOC_COMPONENT_TYPE_XML
The data field must point to a struct hwloc_xml_component.
Definition: plugins.h:180
hwloc_pcidisc_check_bridge_type
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::attr
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:376
hwloc_component::data
void * data
Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
Definition: plugins.h:231
hwloc_pcidisc_setup_bridge_attr
int hwloc_pcidisc_setup_bridge_attr(hwloc_obj_t obj, const unsigned char *config)
Fills the attributes of the given PCI bridge using the given PCI config space.
HWLOC_OBJ_OSDEV_DMA
Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
Definition: hwloc.h:310
hwloc_filter_check_osdev_subtype_important
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:408
hwloc_pcidisc_tree_attach
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...
hwloc_disc_component::name
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:58
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:359
hwloc_insert_object_by_parent
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.
hwloc_obj_add_children_sets
int hwloc_obj_add_children_sets(hwloc_obj_t obj)
Setup object cpusets/nodesets by OR&#39;ing its children.
hwloc_report_os_error
void hwloc_report_os_error(const char *msg, int line)
Report an insertion error from a backend.
hwloc_backend::private_data
void * private_data
Backend private data, or NULL if none.
Definition: plugins.h:139
hwloc_backend_enable
int hwloc_backend_enable(struct hwloc_topology *topology, struct hwloc_backend *backend)
Enable a previously allocated and setup backend.
hwloc_insert_object_by_cpuset
struct hwloc_obj * hwloc_insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj)
Add an object to the topology.
hwloc_disc_component_type_e
hwloc_disc_component_type_e
Discovery component type.
Definition: plugins.h:29
HWLOC_DISC_COMPONENT_TYPE_MISC
OpenCL, Cuda, etc.
Definition: plugins.h:43
hwloc_topology_reconnect
int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags)
Request a reconnection of children and levels in the topology.
hwloc_obj::subtype
char * subtype
Subtype string to better describe the type field.
Definition: hwloc.h:360
hwloc_obj::os_index
unsigned os_index
OS-provided physical index number. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes. Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object.
Definition: hwloc.h:362
hwloc_disc_component::excludes
unsigned excludes
Component types to exclude, as an OR&#39;ed set of hwloc_disc_component_type_e.
Definition: plugins.h:68
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:611
hwloc_backend::discover
int(* discover)(struct hwloc_backend *backend)
Main discovery callback. returns -1 on error, either because it couldn&#39;t add its objects ot the exist...
Definition: plugins.h:150
hwloc_pcidisc_find_by_busid
struct hwloc_obj * hwloc_pcidisc_find_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the PCI object that matches the bus ID.