131 lines
7.9 KiB
Groff
131 lines
7.9 KiB
Groff
.TH "hwlocality_memattrs_manage" 3 "Wed Dec 14 2022" "Version 2.9.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
hwlocality_memattrs_manage \- Managing memory attributes
|
|
.SH SYNOPSIS
|
|
.br
|
|
.PP
|
|
.SS "Enumerations"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "enum \fBhwloc_memattr_flag_e\fP { \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP = (1UL<<0), \fBHWLOC_MEMATTR_FLAG_LOWER_FIRST\fP = (1UL<<1), \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP = (1UL<<2) }"
|
|
.br
|
|
.in -1c
|
|
.SS "Functions"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "int \fBhwloc_memattr_get_name\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, const char **name)"
|
|
.br
|
|
.ti -1c
|
|
.RI "int \fBhwloc_memattr_get_flags\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, unsigned long *flags)"
|
|
.br
|
|
.ti -1c
|
|
.RI "int \fBhwloc_memattr_register\fP (\fBhwloc_topology_t\fP topology, const char *name, unsigned long flags, \fBhwloc_memattr_id_t\fP *id)"
|
|
.br
|
|
.ti -1c
|
|
.RI "int \fBhwloc_memattr_set_value\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, struct \fBhwloc_location\fP *initiator, unsigned long flags, hwloc_uint64_t value)"
|
|
.br
|
|
.ti -1c
|
|
.RI "int \fBhwloc_memattr_get_targets\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP *initiator, unsigned long flags, unsigned *nr, \fBhwloc_obj_t\fP *targets, hwloc_uint64_t *values)"
|
|
.br
|
|
.ti -1c
|
|
.RI "int \fBhwloc_memattr_get_initiators\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, unsigned *nr, struct \fBhwloc_location\fP *initiators, hwloc_uint64_t *values)"
|
|
.br
|
|
.in -1c
|
|
.SH "Detailed Description"
|
|
.PP
|
|
|
|
.SH "Enumeration Type Documentation"
|
|
.PP
|
|
.SS "enum \fBhwloc_memattr_flag_e\fP"
|
|
|
|
.PP
|
|
Memory attribute flags\&. Given to \fBhwloc_memattr_register()\fP and returned by \fBhwloc_memattr_get_flags()\fP\&.
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\fB\fIHWLOC_MEMATTR_FLAG_HIGHER_FIRST \fP\fP
|
|
The best nodes for this memory attribute are those with the higher values\&. For instance Bandwidth\&.
|
|
.TP
|
|
\fB\fIHWLOC_MEMATTR_FLAG_LOWER_FIRST \fP\fP
|
|
The best nodes for this memory attribute are those with the lower values\&. For instance Latency\&.
|
|
.TP
|
|
\fB\fIHWLOC_MEMATTR_FLAG_NEED_INITIATOR \fP\fP
|
|
The value returned for this memory attribute depends on the given initiator\&. For instance Bandwidth and Latency, but not Capacity\&.
|
|
.SH "Function Documentation"
|
|
.PP
|
|
.SS "int hwloc_memattr_get_flags (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, unsigned long * flags)"
|
|
|
|
.PP
|
|
Return the flags of the given attribute\&. Flags are a OR'ed set of \fBhwloc_memattr_flag_e\fP\&.
|
|
.SS "int hwloc_memattr_get_initiators (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, unsigned * nr, struct \fBhwloc_location\fP * initiators, hwloc_uint64_t * values)"
|
|
|
|
.PP
|
|
Return the initiators that have values for a given attribute for a specific target NUMA node\&. Return initiators for the given attribute and target node in the \fCinitiators\fP array\&. If \fCvalues\fP is not \fCNULL\fP, the corresponding attribute values are stored in the array it points to\&.
|
|
.PP
|
|
On input, \fCnr\fP points to the number of initiators that may be stored in the array \fCinitiators\fP (and \fCvalues\fP)\&. On output, \fCnr\fP points to the number of initiators (and values) that were actually found, even if some of them couldn't be stored in the array\&. Initiators that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&.
|
|
.PP
|
|
The returned initiators should not be modified or freed, they belong to the topology\&.
|
|
.PP
|
|
\fCflags\fP must be \fC0\fP for now\&.
|
|
.PP
|
|
If the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP), no initiator is returned\&.
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
This function is meant for tools and debugging (listing internal information) rather than for application queries\&. Applications should rather select useful NUMA nodes with \fBhwloc_get_local_numanode_objs()\fP and then look at their attribute values for some relevant initiators\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "int hwloc_memattr_get_name (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, const char ** name)"
|
|
|
|
.PP
|
|
Return the name of a memory attribute\&.
|
|
.SS "int hwloc_memattr_get_targets (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP * initiator, unsigned long flags, unsigned * nr, \fBhwloc_obj_t\fP * targets, hwloc_uint64_t * values)"
|
|
|
|
.PP
|
|
Return the target NUMA nodes that have some values for a given attribute\&. Return targets for the given attribute in the \fCtargets\fP array (for the given initiator if any)\&. If \fCvalues\fP is not \fCNULL\fP, the corresponding attribute values are stored in the array it points to\&.
|
|
.PP
|
|
On input, \fCnr\fP points to the number of targets that may be stored in the array \fCtargets\fP (and \fCvalues\fP)\&. On output, \fCnr\fP points to the number of targets (and values) that were actually found, even if some of them couldn't be stored in the array\&. Targets that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&.
|
|
.PP
|
|
The returned targets should not be modified or freed, they belong to the topology\&.
|
|
.PP
|
|
Argument \fCinitiator\fP is ignored if the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP)\&. Otherwise \fCinitiator\fP may be non \fCNULL\fP to report only targets that have a value for that initiator\&.
|
|
.PP
|
|
\fCflags\fP must be \fC0\fP for now\&.
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
This function is meant for tools and debugging (listing internal information) rather than for application queries\&. Applications should rather select useful NUMA nodes with \fBhwloc_get_local_numanode_objs()\fP and then look at their attribute values\&.
|
|
.PP
|
|
The initiator \fCinitiator\fP should be of type \fBHWLOC_LOCATION_TYPE_CPUSET\fP when referring to accesses performed by CPU cores\&. \fBHWLOC_LOCATION_TYPE_OBJECT\fP is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "int hwloc_memattr_register (\fBhwloc_topology_t\fP topology, const char * name, unsigned long flags, \fBhwloc_memattr_id_t\fP * id)"
|
|
|
|
.PP
|
|
Register a new memory attribute\&. Add a specific memory attribute that is not defined in \fBhwloc_memattr_id_e\fP\&. Flags are a OR'ed set of \fBhwloc_memattr_flag_e\fP\&. It must contain at least one of \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP or \fBHWLOC_MEMATTR_FLAG_LOWER_FIRST\fP\&.
|
|
.SS "int hwloc_memattr_set_value (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, struct \fBhwloc_location\fP * initiator, unsigned long flags, hwloc_uint64_t value)"
|
|
|
|
.PP
|
|
Set an attribute value for a specific target NUMA node\&. If the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP), location \fCinitiator\fP is ignored and may be \fCNULL\fP\&.
|
|
.PP
|
|
The initiator will be copied into the topology, the caller should free anything allocated to store the initiator, for instance the cpuset\&.
|
|
.PP
|
|
\fCflags\fP must be \fC0\fP for now\&.
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
The initiator \fCinitiator\fP should be of type \fBHWLOC_LOCATION_TYPE_CPUSET\fP when referring to accesses performed by CPU cores\&. \fBHWLOC_LOCATION_TYPE_OBJECT\fP is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SH "Author"
|
|
.PP
|
|
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.
|