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
);
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.
DESCRIPTION
mpctl
provides a means
of determining how many processors are installed in the system
and
assigning proceses/lightweight processes to run on specific processors.
This 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
assignment
in lieu of a synchronization mechanism (such as semaphores).
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 system.
It will always be greater than or equal to 1.
The
spu
and
pid
(or
lwpid)
arguments are ignored.
- MPC_GETFIRSTSPU
This request returns the number of the first processor in the system.
The
spu
and
pid
(or
lwpid)
arguments are ignored.
- MPC_GETNEXTSPU
This request returns the number of the next processor in the system
after
spu.
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 numbers of the remaining spus.
The
pid
(or
lwpid)
argument is ignored.
- MPC_GETCURRENTSPU
This request returns the number of the processor the process
is currently running on (NOT the processor assignment of the caller).
The number of the processor the process is currently running on is
undefined if the process is multithreaded.
The
spu
and
pid
(or
lwpid)
arguments are ignored.
This information may be out-of-date
arbitrarily soon after the call completes.
- MPC_SETPROCESS
This call is
advisory.
This request asynchronously assigns process
pid
to processor
spu.
Since the new
spu
assignment is returned,
the
spu
MPC_SPUNOCHANGE
may be passed to read the current assignment.
The
pid
MPC_SELFPID
may be used to refer to the calling process.
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 choose another process/lightweight
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 threads (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 process to processor binding will override the scheduling
policy.
This call is synchronous.
For example, when a processor is ready choose another process/lightweight
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 threads (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 thread (lightweight process - LWP)
lwpid
to processor
spu.
This option is only available to change the assignment for
threads (LWPs) in the current process.
Since the new
spu
assignment is returned,
the
spu
MPC_SPUNOCHANGE
may be passed to read the current assignment.
The
lwpid
MPC_SELFLWPID
may be used to refer to the calling thread (LWP).
The
spu
MPC_SPUFLOAT
may be used to break any specific-processor assignment.
This allows the thread (LWP) to float to any processor.
Note: This call is
advisory.
If the scheduling policy for a thread (LWP) conflicts with this processor
assignment, the scheduling policy takes precedence.
For example, when a processor is ready choose another thread (LWP)
to execute, and the highest priority
SCHED_FIFO
thread (LWP) is bound to a different processor, that thread (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 thread (LWP) to processor binding will override the scheduling
policy.
This call is synchronous.
For example, when a processor is ready choose another thread (LWP)
to execute, and the highest priority
SCHED_FIFO
thread (LWP) is bound to a different processor, that thread (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 thread (LWP) to
execute on the processor.
Note: This option will not guarantee compliance with POSIX real-time
scheduling algorithms.
- MPC_GETPROCESS_BINDINGTYPE
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.
- MPC_GETLWP_BINDINGTYPE
This request returns MPC_ADVISORY or MPC_MANDATORY to indicate the
current binding type of the thread (LWP) specified by
lwpid.
The
spu
argument is ignored.
To change the processor assignment of another process, the caller must be a member of a group having
PRIV_MPCTL
access (or be the super-user).
If the
request
argument specifies
MPC_SETPROCESS
or
MPC_SETPROCESS_FORCE
and the process specified by
pid
is a multi-threaded process,
the processor binding specified shall be applied for all lightweight processes
contained within
pid.
Each process shall contain a specified processor binding.
Each lightweight process shall contain a processor binding.
The processor binding for a lightweight process does not have to match the
processor binding for the process.
When a process creates another process (via
fork()
or
vfork())
the child process will inherit the parent processes processor binding.
The initial lightweight process in the child process shall inherit its
processor binding from the child process.
Lightweight processes other than the initial lightweight process shall
inherit their processor binding from the creating lightweight process.
ERRORS
In general,
mpctl
fails if one or more of the following is true:
- [EINVAL]
request
is an illegal number.
- [EINVAL]
request
is
MPC_GETNEXTSPU
and
spu
identifies the last processor.
- [ESRCH]
pid
or
lwpid
identifies a process or LWP that does not exist.
- [EPERM]
request
is
MPC_SETPROCESS
or
MPC_SETPROCESS_FORCE,
spu
is not
MPC_SPUNOCHANGE,
pid
identifies another process,
and the caller is not the super-user
or a member of a group having
PRIV_MPCTL
access.
