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.
     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.
     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.
     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 ALSO
     numa(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.