Hardware Locality (hwloc) 1.11.9

plugins.h
1 /*
2 * Copyright © 2013-2015 Inria. All rights reserved.
3 * See COPYING in top-level directory.
4 */
5
6 #ifndef HWLOC_PLUGINS_H
7 #define HWLOC_PLUGINS_H
8
13 struct hwloc_backend;
14
15 #include <hwloc.h>
16 #ifdef HWLOC_INSIDE_PLUGIN
17 /* needed for hwloc_plugin_check_namespace() */
18 #include <ltdl.h>
19 #endif
20
21
22
28 typedef enum hwloc_disc_component_type_e {
31 HWLOC_DISC_COMPONENT_TYPE_CPU = (1<<0),
32
38 HWLOC_DISC_COMPONENT_TYPE_GLOBAL = (1<<1),
39
42 HWLOC_DISC_COMPONENT_TYPE_MISC = (1<<2)
43 } hwloc_disc_component_type_t;
44
50 struct hwloc_disc_component {
52 hwloc_disc_component_type_t type;
53
57 const char *name;
58
67 unsigned excludes;
68
72 struct hwloc_backend * (*instantiate)(struct hwloc_disc_component *component, const void *data1, const void *data2, const void *data3);
73
86 unsigned priority;
87
92 struct hwloc_disc_component * next;
93 };
94
114 struct hwloc_backend {
116 struct hwloc_disc_component * component;
118 struct hwloc_topology * topology;
120 int envvar_forced;
122 struct hwloc_backend * next;
123
125 unsigned long flags;
126
130 int is_custom;
131
135 int is_thissystem;
136
138 void * private_data;
142 void (*disable)(struct hwloc_backend *backend);
143
147 int (*discover)(struct hwloc_backend *backend);
148
151 int (*get_obj_cpuset)(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj, hwloc_bitmap_t cpuset);
152
156 int (*notify_new_object)(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj);
157 };
158
160 enum hwloc_backend_flag_e {
163 HWLOC_BACKEND_FLAG_NEED_LEVELS = (1UL<<0)
164 };
165
169 HWLOC_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_disc_component *component);
170
172 HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_topology *topology, struct hwloc_backend *backend);
173
179 HWLOC_DECLSPEC int hwloc_backends_get_obj_cpuset(struct hwloc_backend *caller, struct hwloc_obj *obj, hwloc_bitmap_t cpuset);
180
190 HWLOC_DECLSPEC int hwloc_backends_notify_new_object(struct hwloc_backend *caller, struct hwloc_obj *obj);
191
202 typedef enum hwloc_component_type_e {
204 HWLOC_COMPONENT_TYPE_DISC,
205
207 HWLOC_COMPONENT_TYPE_XML
208 } hwloc_component_type_t;
209
215 struct hwloc_component {
217 unsigned abi;
218
236 int (*init)(unsigned long flags);
237
249 void (*finalize)(unsigned long flags);
250
252 hwloc_component_type_t type;
253
255 unsigned long flags;
256
258 void * data;
259 };
260
290 HWLOC_DECLSPEC struct hwloc_obj *hwloc_insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj);
291
293 typedef void (*hwloc_report_error_t)(const char * msg, int line);
295 HWLOC_DECLSPEC void hwloc_report_os_error(const char * msg, int line);
297 HWLOC_DECLSPEC int hwloc_hide_errors(void);
298
303 HWLOC_DECLSPEC struct hwloc_obj *hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj, hwloc_report_error_t report_error);
304
319 HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
320
322 static __hwloc_inline struct hwloc_obj *
323 hwloc_alloc_setup_object(hwloc_obj_type_t type, signed os_index)
324 {
325 struct hwloc_obj *obj = malloc(sizeof(*obj));
326 memset(obj, 0, sizeof(*obj));
327 obj->type = type;
328 obj->os_index = os_index;
329 obj->os_level = -1;
330 obj->attr = malloc(sizeof(*obj->attr));
331 memset(obj->attr, 0, sizeof(*obj->attr));
332 /* do not allocate the cpuset here, let the caller do it */
333 return obj;
334 }
335
342 HWLOC_DECLSPEC int hwloc_fill_object_sets(hwloc_obj_t obj);
343
365 static __hwloc_inline int
366 hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
367 {
368 #ifdef HWLOC_INSIDE_PLUGIN
369 lt_dlhandle handle;
370 void *sym;
371 handle = lt_dlopen(NULL);
372 if (!handle)
373 /* cannot check, assume things will work */
374 return 0;
375 sym = lt_dlsym(handle, symbol);
376 lt_dlclose(handle);
377 if (!sym) {
378 static int verboseenv_checked = 0;
379 static int verboseenv_value = 0;
380 if (!verboseenv_checked) {
381 const char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
382 verboseenv_value = verboseenv ? atoi(verboseenv) : 0;
383 verboseenv_checked = 1;
384 }
385 if (verboseenv_value)
386 fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
387 pluginname, symbol);
388 return -1;
389 }
390 #endif /* HWLOC_INSIDE_PLUGIN */
391 return 0;
392 }
393
411 HWLOC_DECLSPEC int hwloc_insert_pci_device_list(struct hwloc_backend *backend, struct hwloc_obj *first_obj);
412
417 HWLOC_DECLSPEC unsigned hwloc_pci_find_cap(const unsigned char *config, unsigned cap);
418
424 HWLOC_DECLSPEC int hwloc_pci_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
425
432 HWLOC_DECLSPEC int hwloc_pci_prepare_bridge(hwloc_obj_t obj, const unsigned char *config);
433
439 #endif /* HWLOC_PLUGINS_H */
hwloc_report_os_error
void hwloc_report_os_error(const char *msg, int line)
Report an insertion error from a backend.
hwloc_hide_errors
int hwloc_hide_errors(void)
Check whether insertion errors are hidden.
hwloc_backend::discover
int(* discover)(struct hwloc_backend *backend)
Main discovery callback. returns > 0 if it modified the topology tree, -1 on error, 0 otherwise. May be NULL if type is HWLOC_DISC_COMPONENT_TYPE_MISC.
Definition: plugins.h:147
HWLOC_BACKEND_FLAG_NEED_LEVELS
Levels should be reconnected before this backend discover() is used.
Definition: plugins.h:163
hwloc_obj_type_t
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:170
hwloc_backend::is_custom
int is_custom
Backend-specific &#39;is_custom&#39; property. Shortcut on !strcmp(..->component->name, "custom"). Only the custom component should touch this.
Definition: plugins.h:130
hwloc_pci_find_cap
unsigned hwloc_pci_find_cap(const unsigned char *config, unsigned cap)
Return the offset of the given capability in the PCI config space buffer.
hwloc_pci_find_linkspeed
int hwloc_pci_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_disc_component::type
hwloc_disc_component_type_t type
Discovery component type.
Definition: plugins.h:52
hwloc_backend::disable
void(* disable)(struct hwloc_backend *backend)
Callback for freeing the private_data. May be NULL.
Definition: plugins.h:142
hwloc_component::data
void * data
Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
Definition: plugins.h:258
hwloc_pci_prepare_bridge
int hwloc_pci_prepare_bridge(hwloc_obj_t obj, const unsigned char *config)
Modify the PCI device object into a bridge and fill its attribute if a bridge is found in the PCI con...
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_GLOBAL
xml, synthetic or custom, platform-specific components such as bgq. Anything the discovers CPU and ev...
Definition: plugins.h:38
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_backend::flags
unsigned long flags
Backend flags, as an OR&#39;ed set of hwloc_backend_flag_e.
Definition: plugins.h:125
hwloc_backend_enable
int hwloc_backend_enable(struct hwloc_topology *topology, struct hwloc_backend *backend)
Enable a previously allocated and setup backend.
HWLOC_COMPONENT_TYPE_XML
The data field must point to a struct hwloc_xml_component.
Definition: plugins.h:207
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:373
hwloc_component_type_t
enum hwloc_component_type_e hwloc_component_type_t
Generic component type.
hwloc_backend_flag_e
hwloc_backend_flag_e
Backend flags.
Definition: plugins.h:160
hwloc__insert_object_by_cpuset
struct hwloc_obj * hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj, hwloc_report_error_t report_error)
Add an object to the topology and specify which error callback to use.
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:366
hwloc_report_error_t
void(* hwloc_report_error_t)(const char *msg, int line)
Type of error callbacks during object insertion.
Definition: plugins.h:293
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:135
hwloc_disc_component
Discovery component structure.
Definition: plugins.h:50
hwloc_component::abi
unsigned abi
Component ABI version, set to HWLOC_COMPONENT_ABI.
Definition: plugins.h:217
hwloc_disc_component::priority
unsigned priority
Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
Definition: plugins.h:86
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:57
hwloc_insert_pci_device_list
int hwloc_insert_pci_device_list(struct hwloc_backend *backend, struct hwloc_obj *first_obj)
Insert a list of PCI devices and bridges in the backend topology.
hwloc_disc_component_type_e
hwloc_disc_component_type_e
Discovery component type.
Definition: plugins.h:28
hwloc_backends_get_obj_cpuset
int hwloc_backends_get_obj_cpuset(struct hwloc_backend *caller, struct hwloc_obj *obj, hwloc_bitmap_t cpuset)
Used by backends discovery callbacks to request locality information from others. ...
hwloc_component
Generic component structure.
Definition: plugins.h:215
hwloc_obj::type
hwloc_obj_type_t type
Type of object.
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.
Definition: hwloc.h:362
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:51
hwloc_component_type_e
hwloc_component_type_e
Generic component type.
Definition: plugins.h:202
HWLOC_DISC_COMPONENT_TYPE_MISC
OpenCL, Cuda, etc.
Definition: plugins.h:42
hwloc_component::flags
unsigned long flags
Component flags, unused for now.
Definition: plugins.h:255
hwloc_obj::cpuset
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:421
hwloc_disc_component_type_t
enum hwloc_disc_component_type_e hwloc_disc_component_type_t
Discovery component type.
hwloc_backends_notify_new_object
int hwloc_backends_notify_new_object(struct hwloc_backend *caller, struct hwloc_obj *obj)
Used by backends discovery callbacks to notify other backends of new objects.
HWLOC_DISC_COMPONENT_TYPE_CPU
CPU-only discovery through the OS, or generic no-OS support.
Definition: plugins.h:31
hwloc_backend::get_obj_cpuset
int(* get_obj_cpuset)(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj, 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:151
hwloc_obj::os_level
signed os_level
OS-provided physical level, -1 if unknown or meaningless.
Definition: hwloc.h:396
hwloc_backend::private_data
void * private_data
Backend private data, or NULL if none.
Definition: plugins.h:138
hwloc_component::type
hwloc_component_type_t type
Component type.
Definition: plugins.h:252
hwloc_fill_object_sets
int hwloc_fill_object_sets(hwloc_obj_t obj)
Setup object cpusets/nodesets by OR&#39;ing its children.
HWLOC_COMPONENT_TYPE_DISC
The data field must point to a struct hwloc_disc_component.
Definition: plugins.h:204
hwloc_backend
Discovery backend structure.
Definition: plugins.h:114
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:358
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (system object)
Definition: hwloc.h:403
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:67
hwloc_alloc_setup_object
static struct hwloc_obj * hwloc_alloc_setup_object(hwloc_obj_type_t type, signed os_index)
Allocate and initialize an object of the given type and physical index.
Definition: plugins.h:323
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...