Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.11.13

  |   Home   |   Support   |   FAQ   |  
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 
32 
39 
44 
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 
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 
131 
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 
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 
205 
209 
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 *
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 */
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
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
int hwloc_hide_errors(void)
Check whether insertion errors are hidden.
CPU-only discovery through the OS, or generic no-OS support.
Definition: plugins.h:31
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
static int hwloc_plugin_check_namespace(const char *pluginname, const char *symbol)
Make sure that plugins can lookup core symbols.
Definition: plugins.h:366
Generic component structure.
Definition: plugins.h:215
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_e
Backend flags.
Definition: plugins.h:160
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:421
void(* disable)(struct hwloc_backend *backend)
Callback for freeing the private_data. May be NULL.
Definition: plugins.h:142
unsigned priority
Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
Definition: plugins.h:86
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. ...
int hwloc_backend_enable(struct hwloc_topology *topology, struct hwloc_backend *backend)
Enable a previously allocated and setup backend.
Discovery backend structure.
Definition: plugins.h:114
struct hwloc_obj * parent
Parent, NULL if root (system object)
Definition: hwloc.h:403
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:63
signed os_level
OS-provided physical level, -1 if unknown or meaningless.
Definition: hwloc.h:396
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:373
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.
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
OpenCL, Cuda, etc.
Definition: plugins.h:42
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
xml, synthetic or custom, platform-specific components such as bgq. Anything the discovers CPU and ev...
Definition: plugins.h:38
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.
void(* hwloc_report_error_t)(const char *msg, int line)
Type of error callbacks during object insertion.
Definition: plugins.h:293
void * private_data
Backend private data, or NULL if none.
Definition: plugins.h:138
unsigned abi
Component ABI version, set to HWLOC_COMPONENT_ABI.
Definition: plugins.h:217
The data field must point to a struct hwloc_disc_component.
Definition: plugins.h:204
hwloc_disc_component_type_t type
Discovery component type.
Definition: plugins.h:52
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:360
hwloc_component_type_e
Generic component type.
Definition: plugins.h:202
int hwloc_fill_object_sets(hwloc_obj_t obj)
Setup object cpusets/nodesets by OR&#39;ing its children.
unsigned long flags
Backend flags, as an OR&#39;ed set of hwloc_backend_flag_e.
Definition: plugins.h:125
The data field must point to a struct hwloc_xml_component.
Definition: plugins.h:207
unsigned excludes
Component types to exclude, as an OR&#39;ed set of hwloc_disc_component_type_e.
Definition: plugins.h:67
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
Discovery component structure.
Definition: plugins.h:50
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.
struct hwloc_backend * hwloc_backend_alloc(struct hwloc_disc_component *component)
Allocate a backend structure, set good default values, initialize backend->component and topology...
void * data
Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
Definition: plugins.h:258
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_component_type_t type
Component type.
Definition: plugins.h:252
Structure of a topology object.
Definition: hwloc.h:358
void hwloc_report_os_error(const char *msg, int line)
Report an insertion error from a backend.
enum hwloc_disc_component_type_e hwloc_disc_component_type_t
Discovery component type.
enum hwloc_component_type_e hwloc_component_type_t
Generic component type.
hwloc_disc_component_type_e
Discovery component type.
Definition: plugins.h:28
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_obj_type_t
Type of topology object.
Definition: hwloc.h:170
struct hwloc_obj * hwloc_insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj)
Add an object to the topology.
unsigned hwloc_pci_find_cap(const unsigned char *config, unsigned cap)
Return the offset of the given capability in the PCI config space buffer.
Levels should be reconnected before this backend discover() is used.
Definition: plugins.h:163
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...
unsigned long flags
Component flags, unused for now.
Definition: plugins.h:255