mpctl(2)

NAME

mpctl — multiprocessor control

SYNOPSIS

#include <sys/mpctl.h> 

int mpctl( 
     mpc_request_t request, 
     spu_t spu, 
     pid_t pid 
); 

int mpctl( 
     mpc_request_t request, 
     spu_t spu, 
     lwpid_t lwpid 
); 

int mpctl( 
     mpc_request_t request, 
     ldom_t ldom, 
     pid_t pid 
); 

int mpctl( 
     mpc_request_t request, 
     ldom_t ldom, 
     lwpid_t lwpid 
); 

REMARKS

Much of the functionality of this capability is highly dependent on the underlying hardware. An application that uses this system call should not be expected to be portable across architectures or implementations.

Some hardware platforms support online addition and deletion of processors. Due to this capability, processors and locality domains may be added or deleted while the system is running. Applications should be written to handle processor IDs and locality domain IDs that dynamically appear or disappear (for example, sometime after obtaining the IDs of all the processors in the system an application may try to bind an LWP to one of those processors - this system call will return an error if that processor had been deleted).

Processor sets restrict application execution to designated group of processors. Some applications may query information about processors and locality domains available to them, while other applications may require system-wide information. The mpctl(2) interface supports two unique sets of command requests for these purposes.

Applications using the pthread interfaces should not use this system call. A special set of pthread_*() routines has been developed for use by pthread applications. See the pthread_processor_bind_np(3T) manual page for information on these interfaces.

DESCRIPTION

mpctl provides a means of determining how many processors and locality domains are available in the system, and assigning processes or lightweight processes to execute on specific processors or within a specific locality domain.

A locality domain consists of a related collection of processors, memory, and peripheral resources that comprise a fundamental building block of the system. All processors and peripheral devices in a given locality domain have equal latency to the memory contained within that locality domain.

Processor sets provide an alternative application scheduling allocation domain. A processor set comprises an isolated group of processors for exclusive use by applications assigned to the processor set. Applications may use mpctl to query about processors and locality domains available for them to scale and optimize accordingly. Use sysconf(2) with _SC_PSET_SUPPORT name to see if the processor set functionality is enabled and available on the system.

mpctl call is expected to be used to increase performance in certain applications, but should not be used to ensure correctness of an application. Specifically, cooperating processes/lightweight processes should not rely on processor or locality domain assignment in lieu of a synchronization mechanism (such as semaphores).

Machine Topology Information

Warning: Processor and locality domain IDs are not guaranteed to exist in numerical order. There may be holes in a sequential list of IDs. Due to the capability of online addition and deletion of processors on some platforms, IDs obtained via these interfaces may be invalid at a later time. Likewise, the number of processors and locality domains in the system may also change due to processors being added or deleted. Please see Processor Set Information section to query machine topology within the application's processor set.

For processor topology use:

int mpctl(mpc_request_t request, spu_t spu, pid_t pid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_GETNUMSPUS_SYS

This request returns the number of spus (processors) in the system. It will always be greater than or equal to 1. The spu and pid arguments are ignored.

MPC_GETFIRSTSPU_SYS

This request returns the ID of the first processor in the system. The spu and pid arguments are ignored.

MPC_GETNEXTSPU_SYS

This request returns the ID of the next processor in the system after spu. The pid argument is ignored.

Typically, MPC_GETFIRSTSPU_SYS is called to determine the first spu. MPC_GETNEXTSPU_SYS is then called in a loop (until the call returns -1) to determine the IDs of the remaining spus.

MPC_GETCURRENTSPU

This request returns the ID of the processor the caller is currently running on (NOT the processor assignment of the caller). The spu and pid arguments are ignored.

Warning: The information returned by this system call may be out-of-date arbitrarily soon after the call completes due to the scheduler context switching the caller onto a different processor.

For locality domain topology use:

int mpctl(mpc_request_t request, ldom_t ldom, pid_t pid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_GETNUMLDOMS_SYS

This request returns the number of locality domains in the system. It will always be greater than or equal to 1. The ldom and pid arguments are ignored.

MPC_GETFIRSTLDOM_SYS

This request returns the ID of the first locality domain in the system. The ldom and pid arguments are ignored.

MPC_GETNEXTLDOM_SYS

This request returns the ID of the next locality domain in the system after ldom. The pid argument is ignored.

Typically, MPC_GETFIRSTLDOM_SYS is called to determine the first locality domain. MPC_GETNEXTLDOM_SYS is then called in a loop (until the call returns -1) to determine the IDs of the remaining locality domains.

MPC_LDOMSPUS_SYS

This request returns the number of processors in the locality domain ldom. The pid argument is ignored.

MPC_SPUTOLDOM

This request returns the ID of the locality domain containing processor spu. The pid argument is ignored.

Processor Set Information

Warning: Dynamic creation and deletion of processor sets, and dynamic reassignment of a processor from one processor set to another may occur. All processors in the system comprises one processor set by default at boot time until new processor sets are created and configured by users. The following command requests return topology information on processors and locality domains in the processor set of the calling thread.

For processor topology use:

int mpctl(mpc_request_t request, spu_t spu, pid_t pid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_GETNUMSPUS

This request returns the number of spus (processors) in the processor set of the calling thread. It may be zero if the processor set is empty. The spu and pid arguments are ignored.

MPC_GETFIRSTSPU

This request returns the ID of the first processor in the processor set of the calling thread. The spu and pid arguments are ignored.

MPC_GETNEXTSPU

This request returns the ID of the next processor in the processor set of the calling thread after spu. The pid argument is ignored.

Typically, MPC_GETFIRSTSPU is called to determine the first spu. MPC_GETNEXTSPU is then called in a loop (until the call returns -1) to determine the IDs of the remaining spus.

For locality domain topology use:

int mpctl(mpc_request_t request, ldom_t ldom, pid_t pid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_GETNUMLDOMS

This request returns the number of locality domains in the processor set of the calling thread. The ldom and pid arguments are ignored.

MPC_GETFIRSTLDOM

This request returns the ID of the first locality domain in the processor set of the calling thread. The ldom and pid arguments are ignored.

MPC_GETNEXTLDOM

This request returns the ID of the next locality domain in the processor set of the calling thread after ldom. The pid argument is ignored.

Typically, MPC_GETFIRSTLDOM is called to determine the first locality domain. MPC_GETNEXTLDOM is then called in a loop (until the call returns -1) to determine the IDs of the remaining locality domains.

MPC_LDOMSPUS

This request returns the number of processors contributed by the locality domain ldom to the processor set of the calling thread. It may be less than the total number of processors in the ldom. The pid argument is ignored.

Processor and Locality Domain Binding

Each process shall have a processor and locality domain binding. Each LWP (lightweight process) shall have a processor and locality domain binding. The binding assignments for a lightweight process do not have to match the binding assignments for the process.

Setting the processor or locality domain binding on the process of a multithreaded process, causes all LWPs (lightweight processes) in the target process to have their binding assignments changed to what is specified.

When a process creates another process (via fork() or vfork()), the child process will inherit the parent process's binding assignments (NOT the binding assignments of the fork'ing LWP). The initial LWP in the child process shall inherit its binding assignments from the child process. LWPs other than the initial LWP shall inherit their binding assignments from the creating LWP (unless specified otherwise in the LWP create attributes).

Processor binding and locality domain binding is mutually exclusive - only one can be in effect at any time. If locality domain binding is in effect, the target is allowed to execute on any processor within that locality domain.

Setting the processor or locality domain binding will fail if the target processor or locality domain is not in the processor set of the specified process or LWP.

Warning: Due to the capability of online addition and deletion of processors on some platforms, processors may go away. If this occurs, any processes or LWPs bound to a departing processor will be rebound to a different processor with the same binding type. If the last processor in a locality domain is removed, any processes or LWPs bound to a departing locality domain will be rebound to a different locality domain.

For processor binding use:

int mpctl(mpc_request_t request, spu_t spu, pid_t pid);

int mpctl(mpc_request_t request, spu_t spu, lwpid_t lwpid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_SETPROCESS

This call is advisory. This request asynchronously assigns process pid to processor spu. The new processor assignment is returned.

The pid MPC_SELFPID may be used to refer to the calling process.

The spu MPC_SPUNOCHANGE may be passed to read the current assignment. The spu MPC_SPUFLOAT may be used to break any specific-processor assignment. This allows the process to float to any processor.

Note: This call is advisory. If the scheduling policy for a process conflicts with this processor assignment, the scheduling policy takes precedence. For example, when a processor is ready to choose another process to execute, and the highest priority SCHED_FIFO process is bound to a different processor, that process will execute on the selecting processor rather than waiting for the specified processor to which it was bound.

If the process specified by pid is a multithreaded process, all LWPs (lightweight processes) in the target process will have their processor assignment changed to what is specified.

MPC_SETPROCESS_FORCE

This call is identical to MPC_SETPROCESS except that the processor binding will take precedence over the scheduling policy. This call is synchronous. For example, when a processor is ready to choose another process to execute, and the highest priority SCHED_FIFO process is bound to a different processor, that process will not be selected to execute on the selecting processor, but instead wait for the specified processor to which it was bound. The selecting processor will then choose a lower priority process to execute on the processor.

Note: This option will not guarantee compliance with POSIX real-time scheduling algorithms.

If the process specified by pid is a multithreaded process, all LWPs (lightweight processes) in the target process will have their processor assignment changed to what is specified.

MPC_SETLWP

This call is advisory. This request asynchronously assigns LWP (lightweight process) lwpid to processor spu. The new processor assignment is returned. This option is only available to change the assignment for LWPs in the current process.

The lwpid MPC_SELFLWPID may be used to refer to the calling LWP.

Note: This call is advisory. If the scheduling policy for a LWP conflicts with this processor assignment, the scheduling policy takes precedence. For example, when a processor is ready choose another LWP to execute, and the highest priority SCHED_FIFO LWP is bound to a different processor, that LWP will execute on the selecting processor rather than waiting for the specified processor to which it was bound.

MPC_SETLWP_FORCE

This call is identical to MPC_SETLWP except that the processor binding will take precedence over the scheduling policy. This call is synchronous. For example, when a processor is ready choose another LWP to execute, and the highest priority SCHED_FIFO LWP is bound to a different processor, that LWP will not be selected to execute on the selecting processor, but instead wait for the specified processor to which it was bound. The selecting processor will then choose a lower priority LWP to execute on the processor.

Note: This option will not guarantee compliance with POSIX real-time scheduling algorithms.

For locality domain binding use:

int mpctl(mpc_request_t request, ldom_t ldom, pid_t pid);

int mpctl(mpc_request_t request, ldom_t ldom, lwpid_t lwpid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_SETLDOM

This request synchronously assigns process pid to locality domain ldom. The process may still run on any processor within the locality domain. The new locality domain assignment is returned.

The pid MPC_SELFPID may be used to refer to the calling process.

The ldom MPC_LDOMNOCHANGE may be passed to read the current assignment. The ldom MPC_LDOMFLOAT may be used to break any specific-locality domain assignment. This allows the process to float to any locality domain.

For example, when a processor in one locality domain is ready to choose another process to execute, and the highest priority SCHED_FIFO process is bound to a different locality domain, that process will not be selected to execute on the selecting processor, but instead wait for a processor in the specified locality domain to which it was bound. The selecting processor will then choose a lower priority process to execute on the processor.

Note: This option will not guarantee compliance with POSIX real-time scheduling algorithms.

If the process specified by pid is a multithreaded process, all LWPs (lightweight processes) in the target process will have their locality domain assignment changed to what is specified.

MPC_SETLWPLDOM

This request synchronously assigns LWP (lightweight process) lwpid to locality domain ldom. The LWP may still run on any processor within the locality domain. The new locality domain assignment is returned. This option is only available to change the assignment for LWPs in the current process.

The lwpid MPC_SELFLWPID may be used to refer to the calling LWP.

For example, when a processor is ready to choose another LWP to execute, and the highest priority SCHED_FIFO LWP is bound to processor in a different locality domain, that LWP will not be selected to execute on the selecting processor, but instead wait for a processor on the locality domain to which it was bound. The selecting processor will then choose a lower priority LWP to execute on the processor.

Note: This option will not guarantee compliance with POSIX real-time scheduling algorithms.

Obtaining Processor and Locality Domain Binding Type

These options return the current binding type for the specified process or LWP.

int mpctl(mpc_request_t request, spu_t spu, pid_t pid);

int mpctl(mpc_request_t request, spu_t spu, lwpid_t lwpid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_GETPROCESS_BINDINGTYPE

Warning: This call is OBSOLETE and is only provided for backwards compatibility.

This request returns MPC_ADVISORY or MPC_MANDATORY to indicate the current binding type of the process specified by pid. The spu argument is ignored. If the target process has a binding type of something other than MPC_MANDATORY the value MPC_ADVISORY will be returned.

MPC_GETPROCESS_BINDVALUE

This request returns the current binding type of the process specified by pid. The spu argument is ignored.

Current valid return values are MPC_NO_BINDING (no binding), MPC_SPU_BINDING (advisory processor binding), MPC_SPU_FORCED_BINDING (processor binding), and MPC_LDOM_BINDING (locality domain binding). Other binding types may be added in future releases and returned via this option. Applications using this option should be written to handle other return values in order to continue working on future releases.

MPC_GETLWP_BINDINGTYPE

Warning: This call is OBSOLETE and is only provided for backwards compatibility.

This request returns MPC_ADVISORY or MPC_MANDATORY to indicate the current binding type of the LWP specified by lwpid. The spu argument is ignored. If the target LWP has a binding type of something other than MPC_MANDATORY the value MPC_ADVISORY will be returned.

MPC_GETLWP_BINDVALUE

This request returns the current binding type of the LWP specified by lwpid. The spu argument is ignored.

Launch Policies

Each process shall have a launch policy. Each lightweight process shall have a launch policy. The launch policy for a lightweight process does not have to match the launch policy for the process.

If specifying a process launch policy and the target process is a multi-threaded process, the launch policy specified shall only be applied to the process. The launch policies of LWPs within the process shall not be affected.

When a process creates another process (via fork() or vfork()), the child process will inherit the parent process's launch policy (NOT the launch policy of the fork'ing LWP). The initial lightweight process in the child process shall have a launch policy of MPC_SETLWP_NONE - no launch policy). LWPs other than the initial LWP shall inherit their launch policy from the creating LWP.

For all launch policies, the target process or LWP is bound to the locality domain on which it was launched. The target is allowed to execute on any processor within that locality domain.

When setting a launch policy, if the target already has processor or locality domain binding, the existing binding will not be overwritten. Instead the locality domain in which the target is bound (whether locality domain binding or processor binding) will be used as the starting locality domain for implementing the launch policy.

Note: locality domains are tightly tied to the physical components of the underlying system. As a result, the performance observed when using launch policies based on locality domains may vary from system to system. For example, a system which contains 4 locality domains, each containing 32 processors, may exhibit different performance behaviors from a system that contains 32 locality domains with 4 processors per domain. The launch policy that provides optimal performance on one system may not provide optimal performance on a different system for the same application.

For process launch policies use:

int mpctl(mpc_request_t request, ldom_t ldom, pid_t pid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_GETPROCESS_LAUNCH: This request currently returns MPC_LAUNCH_POLICY_RR, MPC_LAUNCH_POLICY_FILL, MPC_LAUNCH_POLICY_PACKED, MPC_LAUNCH_POLICY_LEASTLOAD, or MPC_LAUNCH_POLICY_NONE to indicate the current launch policy of the process specified by pid. Other launch policies may be added in future releases and returned via this option. Applications using this option should be written to handle other return values in order to continue working on future releases. The ldom argument is ignored.
MPC_SETPROCESS_RR: This call establishes a round robin launch policy for the specified process. Round robin indicates that successive child processes are launched on different locality domains until all domains in the system have been used by processes in this family. At that point, the selection of locality domains begins again from the system wide pool of domains. As with all launch policies, the process is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETPROCESS_FILL: This call establishes a fill first launch policy for the specified process. Fill first indicates that successive child processes are launched on the same locality domain as their parent process until one process has been created for each processor in the domain. At that point, a new locality domain is selected and successive processes launched there until there is one process per processor. All domains in the system will be used before the original domain is selected again. As with all launch policies, the process is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETPROCESS_PACKED: This call establishes a packed launch policy for the specified process. Packed indicates that successive child processes are launched on the same locality domain as their parent process. As with all launch policies, the process is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETPROCESS_LEASTLOAD: This call establishes a least loaded launch policy for the specified process. Least loaded indicates that successive child processes are launched on the least loaded locality domain in the system regardless of the location of their parent process. As with all launch policies, the process is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETPROCESS_NONE: This call unsets any launch policy in the process. In removing a launch policy, the process is no longer bound to the locality domain on which it was launched. The ldom argument is ignored.

For LWP launch policies use:

int mpctl(mpc_request_t request, ldom_t ldom, lwpid_t lwpid);

The request argument determines the precise action to be taken by mpctl and is one of the following:

MPC_GETLWP_LAUNCH: This request currently returns MPC_LAUNCH_POLICY_RR, MPC_LAUNCH_POLICY_FILL, MPC_LAUNCH_POLICY_PACKED, MPC_LAUNCH_POLICY_LEASTLOAD, or MPC_LAUNCH_POLICY_NONE to indicate the current launch policy of the LWP specified by lwpid. Other launch policies may be added in future releases and returned via this option. Applications using this option should be written to handle other return values in order to continue working on future releases. The ldom argument is ignored.
MPC_SETLWP_RR: This call establishes a round robin policy for the specified LWP. Round robin indicates that successive child LWPs are launched on different locality domains until all domains in the system have been used by LWPs in this process. At that point, the selection of locality domains begins again from the system wide pool of domains. As with all launch policies, the LWP is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETLWP_FILL: This call establishes a fill first policy for the specified LWP. Fill first indicates that successive child LWPs are launched on the same locality domain as their parent LWP until one LWP has been created for each processor in the domain. At that point, a new locality domain is selected and successive LWPs launched there until there is one LWP per processor. All domains in the system will be used before the original domain is selected again. As with all launch policies, the LWP is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETLWP_PACKED: This call establishes a packed policy for the specified LWP. Packed indicates that successive child LWPs are launched on the same locality domain as their parent LWP. As with all launch policies, the LWP is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETLWP_LEASTLOAD: This call establishes a least loaded policy for the specified LWP. Least loaded indicates that successive child LWPs are launched on the least loaded locality domain in the system regardless of the location of their parent LWP. As with all launch policies, the LWP is bound to the locality domain on which it was launched. The ldom argument is ignored.
MPC_SETLWP_NONE: This call unsets any launch policy in the LWP. In removing a launch policy, the LWP is no longer bound to the locality domain on which it was launched. The ldom argument is ignored.

To change the processor assignment, locality domain assignment, or launch policy of another process, the caller must be either a member of a group having PRIV_MPCTL access, have the same effective user id of the target process, or be the super-user.

ERRORS

If mpctl fails, -1 will be returned. If mpctl is successful, the value returned will be as specified for that command/option. Note: in some cases a negative number other than -1 may be returned that indicates a successful return. In general, mpctl fails if one or more of the following is true:

[EINVAL]: request is an illegal number.
[EINVAL]: request is MPC_GETNEXTSPU or MPC_GETNEXTSPU_SYS and spu identifies the last processor. Or request is MPC_GETNEXTLDOM or MPC_GETNEXTLDOM_SYS and ldom identifies the last locality domain.
[ESRCH]: pid or lwpid identifies a process or LWP that does not exist.
[EINVAL]: request is to bind a process or an LWP to a processor or locality domain that is not in the processor set of the specified process or LWP.
[EPERM]: request is MPC_SETPROCESS, MPC_SETPROCESS_FORCE, or MPC_SETLDOM, spu is not MPC_SPUNOCHANGE or MPC_LDOMNOCHANGE, pid identifies another process, and the caller is not the super-user, does not have the same effective user id of the target process, or is not a member of a group having PRIV_MPCTL access.
[EPERM]: request is MPC_SETPROCESS_RR, MPC_SETPROCESS_FILL, MPC_SETPROCESS_PACKED, MPC_SETPROCESS_LEASTLOAD, or MPC_SETPROCESS_NONE, pid identifies another process, and the caller is not the super-user, does not have the same effective user id of the target process, or is not a member of a group having PRIV_MPCTL access.

mpctl(2)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

REMARKS

DESCRIPTION

Machine Topology Information

Processor Set Information

Processor and Locality Domain Binding

Obtaining Processor and Locality Domain Binding Type

Launch Policies

ERRORS

SEE ALSO