Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.8.1

  |   Home   |   Support   |   FAQ   |  
plugins.h
1 /*
2  * Copyright © 2013 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 
221 
223  unsigned long flags;
224 
226  void * data;
227 };
228 
258 HWLOC_DECLSPEC struct hwloc_obj *hwloc_insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj);
259 
261 typedef void (*hwloc_report_error_t)(const char * msg, int line);
263 HWLOC_DECLSPEC void hwloc_report_os_error(const char * msg, int line);
265 HWLOC_DECLSPEC int hwloc_hide_errors(void);
266 
271 HWLOC_DECLSPEC struct hwloc_obj *hwloc__insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj, hwloc_report_error_t report_error);
272 
283 HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
284 
286 static __hwloc_inline struct hwloc_obj *
288 {
289  struct hwloc_obj *obj = malloc(sizeof(*obj));
290  memset(obj, 0, sizeof(*obj));
291  obj->type = type;
292  obj->os_index = os_index;
293  obj->os_level = -1;
294  obj->attr = malloc(sizeof(*obj->attr));
295  memset(obj->attr, 0, sizeof(*obj->attr));
296  /* do not allocate the cpuset here, let the caller do it */
297  return obj;
298 }
299 
306 HWLOC_DECLSPEC int hwloc_fill_object_sets(hwloc_obj_t obj);
307 
316 HWLOC_DECLSPEC int hwloc_insert_pci_device_list(struct hwloc_backend *backend, struct hwloc_obj *first_obj);
317 
322 HWLOC_DECLSPEC unsigned hwloc_pci_find_cap(const unsigned char *config, unsigned cap);
323 
329 HWLOC_DECLSPEC int hwloc_pci_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
330 
335 HWLOC_DECLSPEC int hwloc_pci_prepare_bridge(hwloc_obj_t obj, const unsigned char *config);
336 
351 static __hwloc_inline int
352 hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
353 {
354 #ifdef HWLOC_INSIDE_PLUGIN
355  lt_dlhandle handle;
356  void *sym;
357  handle = lt_dlopen(NULL);
358  if (!handle)
359  /* cannot check, assume things will work */
360  return 0;
361  sym = lt_dlsym(handle, symbol);
362  lt_dlclose(handle);
363  if (!sym) {
364  static int verboseenv_checked = 0;
365  static int verboseenv_value = 0;
366  if (!verboseenv_checked) {
367  char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
368  verboseenv_value = atoi(verboseenv);
369  verboseenv_checked = 1;
370  }
371  if (verboseenv_value)
372  fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
373  pluginname, symbol);
374  return -1;
375  }
376 #endif /* HWLOC_INSIDE_PLUGIN */
377  return 0;
378 }
379 
385 #endif /* HWLOC_PLUGINS_H */
Structure of a topology object.
Definition: hwloc.h:331
void(* hwloc_report_error_t)(const char *msg, int line)
Type of error callbacks during object insertion.
Definition: plugins.h:261
int is_thissystem
Backend-specific 'is_thissystem' property. Set to 0 or 1 if the backend should enforce the thissystem...
Definition: plugins.h:135
void * private_data
Backend private data, or NULL if none.
Definition: plugins.h:138
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:152
hwloc_component_type_e
Generic component type.
Definition: plugins.h:202
HWLOC_DECLSPEC 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...
int is_custom
Backend-specific 'is_custom' property. Shortcut on !strcmp(..->component->name, "custom"). Only the custom component should touch this.
Definition: plugins.h:130
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_DECLSPEC 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...
The data field must point to a struct hwloc_disc_component.
Definition: plugins.h:204
hwloc_component_type_t type
Component type.
Definition: plugins.h:220
CPU-only discovery through the OS, or generic no-OS support.
Definition: plugins.h:31
struct hwloc_obj * parent
Parent, NULL if root (system object)
Definition: hwloc.h:357
enum hwloc_disc_component_type_e hwloc_disc_component_type_t
Discovery component type.
static __hwloc_inline int hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
Make sure that plugins can lookup core symbols.
Definition: plugins.h:352
void * data
Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
Definition: plugins.h:226
The data field must point to a struct hwloc_xml_component.
Definition: plugins.h:207
unsigned os_index
OS-provided physical index number.
Definition: hwloc.h:334
xml, synthetic or custom, platform-specific components such as bgq. Anything the discovers CPU and ev...
Definition: plugins.h:38
unsigned abi
Component ABI version, set to HWLOC_COMPONENT_ABI.
Definition: plugins.h:217
unsigned priority
Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
Definition: plugins.h:86
Generic component structure.
Definition: plugins.h:215
HWLOC_DECLSPEC void hwloc_report_os_error(const char *msg, int line)
Report an insertion error from a backend.
HWLOC_DECLSPEC 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_DECLSPEC 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.
Discovery backend structure.
Definition: plugins.h:114
OpenCL, Cuda, etc.
Definition: plugins.h:42
HWLOC_DECLSPEC int hwloc_hide_errors(void)
Check whether insertion errors are hidden.
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_obj_type_t type
Type of object.
Definition: hwloc.h:333
signed os_level
OS-provided physical level, -1 if unknown or meaningless.
Definition: hwloc.h:350
unsigned long flags
Component flags, unused for now.
Definition: plugins.h:223
hwloc_backend_flag_e
Backend flags.
Definition: plugins.h:160
hwloc_disc_component_type_t type
Discovery component type.
Definition: plugins.h:52
Discovery component structure.
Definition: plugins.h:50
HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_topology *topology, struct hwloc_backend *backend)
Enable a previously allocated and setup backend.
hwloc_disc_component_type_e
Discovery component type.
Definition: plugins.h:28
void(* disable)(struct hwloc_backend *backend)
Callback for freeing the private_data. May be NULL.
Definition: plugins.h:142
union hwloc_obj_attr_u * attr
Object type-specific Attributes, may be NULL if no attribute value was found.
Definition: hwloc.h:339
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
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition: bitmap.h:45
unsigned long flags
Backend flags, as an OR'ed set of HWLOC_BACKEND_FLAG_*.
Definition: plugins.h:125
HWLOC_DECLSPEC 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_DECLSPEC 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.
int(* notify_new_object)(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj)
Callback called by backends to notify this backend that a new object was added. returns > 0 if it mod...
Definition: plugins.h:156
Levels should be reconnected before this backend discover() is used.
Definition: plugins.h:163
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition: hwloc.h:375
enum hwloc_component_type_e hwloc_component_type_t
Generic component type.
HWLOC_DECLSPEC 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_DECLSPEC int hwloc_fill_object_sets(hwloc_obj_t obj)
Setup object cpusets/nodesets by OR'ing its children.
unsigned excludes
Component types to exclude, as an OR'ed set of HWLOC_DISC_COMPONENT_TYPE_*.
Definition: plugins.h:67
HWLOC_DECLSPEC struct hwloc_obj * hwloc_insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj)
Add an object to the topology.
static __hwloc_inline 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:287
HWLOC_DECLSPEC 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_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_disc_component *component)
Allocate a backend structure, set good default values, initialize backend->component and topology...