1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
.TH "hwlocality_memattrs_manage" 3 "Thu Feb 11 2021" "Version 2.4.1" "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 *nrp, \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 * nrp, \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 refering 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 refering 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\&.
|
