mldset(3)mldset(3)NAME
mldset_create, mldset_destroy, mldset_place - mldset operations
SYNOPSIS
#include <sys/types.h>
#include <sys/pmo.h>
pmo_handle_t mldset_create(pmo_handle_t* mldlist, int mldlist_len)
int mldset_destroy(pmo_handle_t mldset_handle)
int mldset_place(pmo_handle_t mldset_handle,
topology_type_t topology_type,
raff_info_t* rafflist,
int rafflist_len,
rqmode_t rqmode)
DESCRIPTION
mldset_create creates a memory locality domain set.
mldset_destroy destroys a memory locality domain set.
mldset_place places a memory locality domain set. The placement is done
using the supplied MLDset topology and optional affinity. The
topology_type can be one of the following:
TOPOLOGY_FREE This topology specification lets the Operating
System decide what shape to use to allocate the set.
The Operating System will try to place this MLDset
on a cluster of physical nodes as compact as
possible, depending on the current system load.
TOPOLOGY_CPUCLUSTER This topology specification is used to request the
placement of one MLD per CPU instead of the default
one MLD per node. In an Origin 3000, the number of
cpus on a fully populated node is 4, hence each node
can have up to 4 MLDs placed per node. For a node
with less than the maximum number of cpus available
the number of MLDs placed on that node will not
exceed the actual number of CPUs. Also if cpusets
are in use, the MLDs will be placed on nodes that
are part of the defined cpuset. This topology is
useful when the placement policy is managing cache
coloring relative to MLDs instead of virtual memory
regions.
TOPOLOGY_CUBE This topology specification is used to request a
cube-like shape.
Page 1
mldset(3)mldset(3)
TOPOLOGY_CUBE_FIXED This topology specification is used to request a
physical cube.
TOPOLOGY_PHYSNODES This topology specification is used to request that
the MLDs in an MLDset be placed in the exact
physical nodes enumerated in the device affinity
list, described below.
The argument rafflist is used to specify resource affinity. It is an
array of resource specifications using the structure shown below:
typedef struct raff_info {
void* resource;
ushort reslen;
ushort restype;
ushort radius;
ushort attr;
} raff_info_t;
The fields resource, reslen, and restype define the resource. The field
resource is used to specify the name of the resource, the field reslen
must always be set to the actual number of bytes the resource pointer
points to, and the field restype specifies the kind of resource
identification being used, which can be any of the following:
RAFFIDT_NAME This resource identification type should be used for the
cases where a hardware graph path name is used to identify
the device.
RAFFIDT_FD This resource identification type should be used for the
cases where a file descriptor is being used to identify the
device.
The radius field defines the maximum distance from the actual resource
the user would like the MLDset to be place at. The attr field specified
whether the user wants the MLDset to be placed close or far from the
resource:
RAFFATTR_ATTRACTION The MLDset should be placed as close as possible to
the specified device.
RAFFATTR_REPULSION The MLDset should be placed as far as possible from
the specified device.
The argument rafflist_len in the mldset_place call specifies the number
of raff structures the user is passing via rafflist. There must be at
least as many raff structures passed as the size of the corresponding
mldset or the operation will fail and EINVAL will be returned.
Page 2
mldset(3)mldset(3)
Finally, the rqmode argument is used to specify whether the placement
request is ADVISORY or MANDATORY. For both rqmode types, the nodes
selected for MLD assignment are chosen according to several criteria of
cpuset selection, load activity, neighbor node distance, and available
memory. This group of nodes is the candidate list. The final criteria of
available node memory can suddenly spike after a node has been included
in the candidate list due to other unrelated activity. In the rqmode of
ADVISORY, an MLD assignment to a node with no available memory or no
available forecasted memory causes the MLD assignment to one of the other
nodes previously selected from the candidate list. This may occasionally
result in MLD placement that may be less than optimal under heavy memory
use conditions. The rqmode of MANDATORY performs similar selection
criteria as ADVISORY, except for the final check of available memory or
forecasted memory. If there is not enough available memory or forecasted
memory on a node, the placement operation will fail and ENOMEM will be
returned.
mldset_create will fail and no MLD set will not be created if one or more
of the following are true:
EFAULT Arguments could not be copied into kernel space.
EFAULT The MLD list is NULL.
EINVAL The MLD list length is less than 1.
EINVAL An MLD in the MLD list does not exist or is invalid.
ENOMEM No memory is available to create the MLD set.
ENOTSUP Memory locality domains are not supported on this system
architecture.
mldset_destroy will fail and no MLD set will not be created if one or
more of the following are true:
EINVAL The specified mldset_handle is invalid or does not exist.
ENOTSUP Memory locality domains are not supported on this system
architecture.
mldset_place will fail and the MLD set will not be placed if one or more
of the following are true:
EFAULT Arguments could not be copied into kernel space.
EINVAL The specified mldset_handle is invalid or does not exist.
EINVAL The specified topology is invalid.
Page 3
mldset(3)mldset(3)
EINVAL The specified rafflist length is non-zero, but the
rafflist pointer is NULL.
EINVAL The rafflist pointer is non-NULL, but the specified
rafflist length is zero.
EINVAL The member of the rafflist is NULL.
EINVAL The rafflist length exceeds the system allowable length.
EINVAL Mandatory rafflist placement could not be satisfied.
EINVAL The specified rqmode has invalid hint bits set.
ENOMEM No memory is available to place the MLD set.
ENOTSUP Memory locality domains are not supported on this system
architecture.
SEE ALSOnuma(5), mmci(5), mld(3c), pm(3c), migration(3c).
DIAGNOSTICS
Upon successful completion, mldset_create returns a value of type
pmo_handle_t, mldset_destroy and mldset_place return 0. Otherwise, a
value of -1 is returned and errno is set to indicate the error.
Page 4
