mld(3)                                                                  mld(3)


NAME
     mld_create, mld_destroy, process_mldlink, process_cpulink, numa_acreate -
     memory locality domain operations

SYNOPSIS
     #include <sys/types.h>
     #include <sys/pmo.h>

     pmo_handle_t mld_create(int radius, long size)

     int mld_destroy(pmo_handle_t mld_handle)

     int process_mldlink(pid_t pid, pmo_handle_t mld_handle, rqmode_t rqmode)

     int process_cpulink(pid_t pid, pmo_handle_t mld_handle, cpuid_t lcpuid, rqmode_t rqmode)

     void* numa_acreate(pmo_handle_t mld, size_t arena_size, size_t page_size)


DESCRIPTION
     mld_create creates a memory locality domain. The argument radius is not
     currently used and is normally zero. The argument size is a hint
     specifying approximately how much physical memory in bytes will be
     required for this MLD. If this argument is set to MLD_DEFAULTSIZE then at
     the time of mld placement the kernel will make an estimate of the memory
     to be used based on the current total address space in use by the process
     and the number of mlds.

     mld_destroy destroys a memory locality domain.

     process_mldlink attaches a process to an MLD. When a process is attached
     to an MLD, the process scheduler tries to activate the process on a CPU
     in the node where the MLD has been placed. The argument rqmode is
     currently not used and is normally set to RQMODE_ADVISORY.  If this
     process forks or sprocs a child pid, the child pid does not inherit the
     affinity to the node where the MLD is placed. Instead the current default
     policy module for the MEM_DATA address space determines the affinity of
     the child pid to a node.

     process_cpulink attaches a process to a specific CPU within the node that
     the MLD is placed on. The CPU number is relative to the node, for example
     on an Origin 3000 with a fully populated node the CPU numbering is 0-3.
     On an Origin 2000 with a fully populated node, the CPU numbering is 0-1.
     If a CPU is disabled on that node, then the CPU numbering is re-ordered
     at boot time to always count up consecutively from 0. For example if an
     Origin 3000 had a node with only 3 CPUs, the CPU numbering regardless of
     which CPU is disabled would be 0,1,2.  This operation forces a process to
     always run on the same CPU using `MP_MUSTRUN' (see sysmp(2)). The
     argument rqmode is currently not used and is normally set to
     RQMODE_ADVISORY.  If this process forks or sprocs a child pid, the child
     pid will inherit the affinity characteristics of the parent pid, per the
     actions of the `MP_MUSTRUN' sysmp call.


     numa_acreate creates an arena for memory allocation on a specific MLD.

     mld_create will fail and a MLD will not be created if one or more of the
     following are true:

     EFAULT         Arguments could not be copied into kernel space.

     ENOMEM         No memory or kernel table space is available to create and
                    hold the MLD.

     ENOTSUP        Memory locality domains are not supported on this system
                    architecture.

     mld_destroy will fail and no MLD will be destroyed if one or more of the
     following are true:

     EINVAL         The mld_handle is invalid.

     ENOTSUP        Memory locality domains are not supported on this system
                    architecture.

     process_mldlink will fail and the process will not be attached to an MLD
     if one or more of the following are true:

     EDEADLK        The operation would cause a deadlock to occur.

     EINVAL         The mld_handle is invalid or does not exist.

     ENOTSUP        Memory locality domains are not supported on this system
                    architecture.

     ESRCH          The specified pid does not exist.

     EXDEV          The MLD has not been placed. (Call mldset_place(3c)
                    first.)

     process_cpulink will fail and the process will not be attached to an MLD
     if one or more of the following are true:

     EDEADLK        The operation would cause a deadlock to occur.

     EINVAL         The specified mld_handle is invalid or does not exist.

     EINVAL         The cpulink is attempted on a CPU which was not present.

     EINVAL         The pid is part of a Pthreaded application, which is not
                    supported by MP_MUSTRUN.

     EINVAL         The process is already resides on a 'mustrun' CPU and is
                    not allowed to move to another CPU.


     ENOTSUP        Memory locality domains are not supported on this system
                    architecture.

     EPERM          The user does not have adequate permission to execute the
                    sysmp(2) system call MP_MUSTRUN command.

     EPERM          The cpuset does not allow the process to run on the
                    selected MLD and CPU.

     ESRCH          The specified pid does not exist.

     EXDEV          The MLD has not been placed. (Call mldset_place(3c)
                    first.)

     numa_acreate will fail and no memory arena will be created (and set
     errno) under the same circumstances that acreate(2) will fail. It will
     also fail and no memory arena will be created if one or more of the
     following are true:

     EFAULT         Arguments could not be copied into kernel space.

     EINVAL         The specified MLD is invalid.

     ENOTSUP        Memory locality domains are not supported on this system
                    architecture.

     ESRCH          The specified MLD does not exist.

SEE ALSO
     acreate(2), numa(5), mmci(5), mldset(3c), pm(3c), amalloc(3p), sysmp(2),
     migration(3c), pminfo(3c).

DIAGNOSTICS
     Upon successful completion, mld_create returns a value of type
     pmo_handle_t.  Otherwise, a value of -1 is returned and errno is set to
     indicate the error.

     Upon successful completion, mld_destroy, process_mldlink, and
     process_cpulink return 0.  Otherwise, a value of -1 is returned and errno
     is set to indicate the error.

     Upon successful completion, numa_acreate returns a pointer to the memory
     arena which has been created.  Otherwise NULL will be returned and errno
     is set to indicate the error.


                                                                        Page 3