plugins.h
/*
* Copyright © 2013-2019 Inria. All rights reserved.
* Copyright © 2016 Cisco Systems, Inc. All rights reserved.
* See COPYING in top-level directory.
*/
#ifndef HWLOC_PLUGINS_H
#define HWLOC_PLUGINS_H
struct hwloc_backend;
#include "hwloc.h"
#ifdef HWLOC_INSIDE_PLUGIN
/* needed for hwloc_plugin_check_namespace() */
#include <ltdl.h>
#endif
struct hwloc_disc_component {
const char *name;
unsigned phases;
unsigned excluded_phases;
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);
unsigned priority;
unsigned enabled_by_default;
struct hwloc_disc_component * next;
};
typedef enum hwloc_disc_phase_e {
HWLOC_DISC_PHASE_GLOBAL = (1U<<0),
HWLOC_DISC_PHASE_CPU = (1U<<1),
HWLOC_DISC_PHASE_MEMORY = (1U<<2),
HWLOC_DISC_PHASE_PCI = (1U<<3),
HWLOC_DISC_PHASE_IO = (1U<<4),
HWLOC_DISC_PHASE_MISC = (1U<<5),
HWLOC_DISC_PHASE_ANNOTATE = (1U<<6),
HWLOC_DISC_PHASE_TWEAK = (1U<<7)
} hwloc_disc_phase_t;
enum hwloc_disc_status_flag_e {
HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES = (1UL<<1)
};
struct hwloc_disc_status {
hwloc_disc_phase_t phase;
unsigned excluded_phases;
unsigned long flags;
};
struct hwloc_backend {
struct hwloc_disc_component * component;
struct hwloc_topology * topology;
int envvar_forced;
struct hwloc_backend * next;
unsigned phases;
unsigned long flags;
int is_thissystem;
void * private_data;
void (*disable)(struct hwloc_backend *backend);
int (*discover)(struct hwloc_backend *backend, struct hwloc_disc_status *status);
int (*get_pci_busid_cpuset)(struct hwloc_backend *backend, struct hwloc_pcidev_attr_s *busid, hwloc_bitmap_t cpuset);
};
HWLOC_DECLSPEC struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component);
HWLOC_DECLSPEC int hwloc_backend_enable(struct hwloc_backend *backend);
typedef enum hwloc_component_type_e {
HWLOC_COMPONENT_TYPE_DISC,
HWLOC_COMPONENT_TYPE_XML
} hwloc_component_type_t;
struct hwloc_component {
unsigned abi;
int (*init)(unsigned long flags);
void (*finalize)(unsigned long flags);
hwloc_component_type_t type;
unsigned long flags;
void * data;
};
HWLOC_DECLSPEC struct hwloc_obj *hwloc_insert_object_by_cpuset(struct hwloc_topology *topology, hwloc_obj_t obj);
typedef void (*hwloc_report_error_t)(const char * msg, int line);
HWLOC_DECLSPEC void hwloc_report_os_error(const char * msg, int line);
HWLOC_DECLSPEC int hwloc_hide_errors(void);
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);
HWLOC_DECLSPEC void hwloc_insert_object_by_parent(struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj);
HWLOC_DECLSPEC hwloc_obj_t hwloc_alloc_setup_object(hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index);
HWLOC_DECLSPEC int hwloc_obj_add_children_sets(hwloc_obj_t obj);
HWLOC_DECLSPEC int hwloc_topology_reconnect(hwloc_topology_t topology, unsigned long flags __hwloc_attribute_unused);
static __hwloc_inline int
hwloc_plugin_check_namespace(const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)
{
#ifdef HWLOC_INSIDE_PLUGIN
lt_dlhandle handle;
void *sym;
handle = lt_dlopen(NULL);
if (!handle)
/* cannot check, assume things will work */
return 0;
sym = lt_dlsym(handle, symbol);
lt_dlclose(handle);
if (!sym) {
static int verboseenv_checked = 0;
static int verboseenv_value = 0;
if (!verboseenv_checked) {
const char *verboseenv = getenv("HWLOC_PLUGINS_VERBOSE");
verboseenv_value = verboseenv ? atoi(verboseenv) : 0;
verboseenv_checked = 1;
}
if (verboseenv_value)
fprintf(stderr, "Plugin `%s' disabling itself because it cannot find the `%s' core symbol.\n",
pluginname, symbol);
return -1;
}
#endif /* HWLOC_INSIDE_PLUGIN */
return 0;
}
static __hwloc_inline int
hwloc_filter_check_pcidev_subtype_important(unsigned classid)
{
unsigned baseclass = classid >> 8;
return (baseclass == 0x03 /* PCI_BASE_CLASS_DISPLAY */
|| baseclass == 0x02 /* PCI_BASE_CLASS_NETWORK */
|| baseclass == 0x01 /* PCI_BASE_CLASS_STORAGE */
|| baseclass == 0x0b /* PCI_BASE_CLASS_PROCESSOR */
|| classid == 0x0c04 /* PCI_CLASS_SERIAL_FIBER */
|| classid == 0x0c06 /* PCI_CLASS_SERIAL_INFINIBAND */
|| baseclass == 0x12 /* Processing Accelerators */);
}
static __hwloc_inline int
hwloc_filter_check_osdev_subtype_important(hwloc_obj_osdev_type_t subtype)
{
return (subtype != HWLOC_OBJ_OSDEV_DMA);
}
static __hwloc_inline int
hwloc_filter_check_keep_object_type(hwloc_topology_t topology, hwloc_obj_type_t type)
{
enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
hwloc_topology_get_type_filter(topology, type, &filter);
assert(filter != HWLOC_TYPE_FILTER_KEEP_IMPORTANT); /* IMPORTANT only used for I/O */
return filter == HWLOC_TYPE_FILTER_KEEP_NONE ? 0 : 1;
}
static __hwloc_inline int
hwloc_filter_check_keep_object(hwloc_topology_t topology, hwloc_obj_t obj)
{
hwloc_obj_type_t type = obj->type;
enum hwloc_type_filter_e filter = HWLOC_TYPE_FILTER_KEEP_NONE;
hwloc_topology_get_type_filter(topology, type, &filter);
if (filter == HWLOC_TYPE_FILTER_KEEP_NONE)
return 0;
if (filter == HWLOC_TYPE_FILTER_KEEP_IMPORTANT) {
if (type == HWLOC_OBJ_PCI_DEVICE)
return hwloc_filter_check_pcidev_subtype_important(obj->attr->pcidev.class_id);
if (type == HWLOC_OBJ_OS_DEVICE)
return hwloc_filter_check_osdev_subtype_important(obj->attr->osdev.type);
}
return 1;
}
HWLOC_DECLSPEC unsigned hwloc_pcidisc_find_cap(const unsigned char *config, unsigned cap);
HWLOC_DECLSPEC int hwloc_pcidisc_find_linkspeed(const unsigned char *config, unsigned offset, float *linkspeed);
HWLOC_DECLSPEC hwloc_obj_type_t hwloc_pcidisc_check_bridge_type(unsigned device_class, const unsigned char *config);
HWLOC_DECLSPEC int hwloc_pcidisc_find_bridge_buses(unsigned domain, unsigned bus, unsigned dev, unsigned func,
unsigned *secondary_busp, unsigned *subordinate_busp,
const unsigned char *config);
HWLOC_DECLSPEC void hwloc_pcidisc_tree_insert_by_busid(struct hwloc_obj **treep, struct hwloc_obj *obj);
HWLOC_DECLSPEC int hwloc_pcidisc_tree_attach(struct hwloc_topology *topology, struct hwloc_obj *tree);
HWLOC_DECLSPEC struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func);
#endif /* HWLOC_PLUGINS_H */
hwloc_obj::parent
struct hwloc_obj * parent
Parent, NULL if root (Machine object)
Definition: hwloc.h:431
hwloc_backend::is_thissystem
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:203
HWLOC_DISC_PHASE_ANNOTATE
Annotating existing objects, adding distances, etc.
Definition: plugins.h:125
hwloc_disc_status_flag_e
hwloc_disc_status_flag_e
Discovery status flags.
Definition: plugins.h:136
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:502
hwloc_obj_attr_u::pcidev
struct hwloc_obj_attr_u::hwloc_pcidev_attr_s pcidev
hwloc_disc_component::excluded_phases
unsigned excluded_phases
Component phases to exclude, as an OR&#39;ed set of hwloc_disc_phase_t.
Definition: plugins.h:53
hwloc_backend
Discovery backend structure.
Definition: plugins.h:179
HWLOC_DISC_PHASE_PCI
Attach PCI devices and bridges to existing CPU objects.
Definition: plugins.h:113
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:381
HWLOC_DISC_STATUS_FLAG_GOT_ALLOWED_RESOURCES
The sets of allowed resources were already retrieved.
Definition: plugins.h:138
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:418
hwloc_obj_type_t
hwloc_obj_type_t
Definition: hwloc.h:177
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_DISC_PHASE_MISC
Misc objects that gets added below anything else.
Definition: plugins.h:121
hwloc_backend_alloc
struct hwloc_backend * hwloc_backend_alloc(struct hwloc_topology *topology, struct hwloc_disc_component *component)
Allocate a backend structure, set good default values, initialize backend->component and topology...
hwloc_backend::phases
unsigned phases
Discovery phases performed by this component, possibly without some of them if excluded by other comp...
Definition: plugins.h:192
hwloc_disc_status
Discovery status structure.
Definition: plugins.h:146
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_DISC_PHASE_IO
I/O discovery that requires PCI devices (OS devices such as OpenCL, CUDA, etc.).
Definition: plugins.h:117
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:2079
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:489
hwloc_component::abi
unsigned abi
Component ABI version, set to HWLOC_COMPONENT_ABI.
Definition: plugins.h:259
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:2108
hwloc_pci_find_parent_by_busid
struct hwloc_obj * hwloc_pci_find_parent_by_busid(struct hwloc_topology *topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
Find the normal parent of a PCI bus ID.
hwloc_report_error_t
void(* hwloc_report_error_t)(const char *msg, int line)
Type of error callbacks during object insertion.
Definition: plugins.h:339
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:38
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_backend::private_data
void * private_data
Backend private data, or NULL if none.
Definition: plugins.h:206
hwloc_component::flags
unsigned long flags
Component flags, unused for now.
Definition: plugins.h:297
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:269
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_disc_component::enabled_by_default
unsigned enabled_by_default
Enabled by default. If unset, if will be disabled unless explicitly requested.
Definition: plugins.h:77
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_component
Generic component structure.
Definition: plugins.h:257
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:460
hwloc_backend::discover
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:217
hwloc_component_type_e
hwloc_component_type_e
Generic component type.
Definition: plugins.h:244
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:619
hwloc_disc_status::phase
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:150
hwloc_disc_status::excluded_phases
unsigned excluded_phases
Dynamically excluded phases. If a component decides during discovery that some phases are no longer n...
Definition: plugins.h:155
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:262
HWLOC_DISC_PHASE_TWEAK
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:132
HWLOC_DISC_PHASE_MEMORY
Attach memory to existing CPU objects.
Definition: plugins.h:109
hwloc_disc_component::phases
unsigned phases
Discovery phases performed by this component. OR&#39;ed set of hwloc_disc_phase_t.
Definition: plugins.h:43
HWLOC_DISC_PHASE_CPU
CPU discovery.
Definition: plugins.h:105
hwloc_type_filter_e
hwloc_type_filter_e
Type filtering flags.
Definition: hwloc.h:2065
HWLOC_COMPONENT_TYPE_DISC
The data field must point to a struct hwloc_disc_component.
Definition: plugins.h:246
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:68
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:667
HWLOC_COMPONENT_TYPE_XML
The data field must point to a struct hwloc_xml_component.
Definition: plugins.h:249
HWLOC_DISC_PHASE_GLOBAL
xml or synthetic, platform-specific components such as bgq. Discovers everything including CPU...
Definition: plugins.h:101
hwloc_disc_status::flags
unsigned long flags
OR&#39;ed set of hwloc_disc_status_flag_e.
Definition: plugins.h:158
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_backend::disable
void(* disable)(struct hwloc_backend *backend)
Callback for freeing the private_data. May be NULL.
Definition: plugins.h:210
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:400
HWLOC_OBJ_OSDEV_DMA
Operating system dma engine device. For instance the "dma0chan0" DMA channel on Linux.
Definition: hwloc.h:334
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:477
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_obj::type
hwloc_obj_type_t type
Type of object.
Definition: hwloc.h:383
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_enable
int hwloc_backend_enable(struct hwloc_backend *backend)
Enable a previously allocated and setup backend.
hwloc_component::data
void * data
Component data, pointing to a struct hwloc_disc_component or struct hwloc_xml_component.
Definition: plugins.h:300
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::priority
unsigned priority
Component priority. Used to sort topology->components, higher priority first. Also used to decide bet...
Definition: plugins.h:72
hwloc_pcidisc_find_bridge_buses
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.
hwloc_disc_component
Discovery component structure.
Definition: plugins.h:34
hwloc_disc_phase_t
enum hwloc_disc_phase_e hwloc_disc_phase_t
Discovery phase.
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:384
hwloc_component::type
hwloc_component_type_t type
Component type.
Definition: plugins.h:294
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:386
hwloc_disc_phase_e
hwloc_disc_phase_e
Discovery phase.
Definition: plugins.h:96
hwloc_backend::flags
unsigned long flags
Backend flags, currently always 0.
Definition: plugins.h:195
hwloc_obj_attr_u::hwloc_osdev_attr_s::type
hwloc_obj_osdev_type_t type
Definition: hwloc.h:641