kra_attachrset Subroutine

Purpose

Attaches a work component to a resource set.

Syntax

#include <sys/rset.h>
int kra_attachrset (rstype, rsid, rset, flags)
rstype_t rstype;
rsid_t rsid;
rsethandle_t rset;
unsigned int flags;

Description

The kra_attachrset subroutine attaches a work component specified by the rstype and rsid parameters to a resource set specified by the rset parameter.

The work component is an existing process identified by the process ID or an existing kernel thread identified by the kernel thread ID (tid). A process ID or thread ID value of RS_MYSELF indicates the attachment applies to the current process or the current kernel thread, respectively.

The following conditions must be met to successfully attach a process to a resource set:

The resource set must contain processors that are available in the system.
The calling process must either have root authority or have CAP_NUMA_ATTACH capability.
The calling process must either have root authority or the same effective userid as the target process.
The target process must not contain any threads that have bindprocessor bindings to a processor.
The resource set must be contained in (be a subset of ) the target process' partition resource set.
The resource set must be a superset of all the thread's rset in the target process.

The following conditions must be met to successfully attach a kernel thread to a resource set:

The resource set must contain processors that are available in the system.
The calling process must either have root authority or have CAP_NUMA_ATTACH capability.
The calling process must either have root authority or the same effective userid as the target process.
The target thread must not have bindprocessor bindings to a processor.
The resource set must be contained in (be a subset of ) the target thread's process effective and partition resource set.

If any of these conditions are not met, the attachment will fail.

Once a process is attached to a resource set, the threads in the process will only run on processors contained in the resource set. Once a kernel thread is attached to a resource set, that thread will only run on processors contained in the resource set.

The flags parameter can be set to indicate the policy for using the resources contained in the resource set specified in the rset parameter. The only supported scheduling policy is R_ATTACH_STRSET, which is useful only when the processors of the system are running in simultaneous multithreading mode. Processors like the POWER5 support simultaneous multithreading, where each physical processor has two execution engines, called hardware threads. Each hardware thread is essentially equivalent to a single CPU, and each is identified as a separate CPU in a resource set. The R_ATTACH_STRSET flag indicates that the process is to be scheduled with a single-threaded policy; namely, that it should be scheduled on only one hardware thread per physical processor. If this flag is specified, then all of the available processors indicated in the resource set must be of exclusive use. A new resource set, called an ST resource set, is constructed from the specified resource set and attached to the process according to the following rules:

All offline processors are ignored.
If all the hardware threads (CPUs) of a physical processor (when running in simultaneous multithreading mode, there will be more than one active hardware thread per physical processor) are not included in the specified resource set, the other CPUs of the processor are ignored when constructing the ST resource set.
Only one CPU (hardware thread) resource per physical processor is included in the ST resource set.

Parameters

Item	Description
rstype	Specifies the type of work component to be attached to the resource set specified by the rset parameter. The rstype parameter must be the following value, defined in rset.h: R_PROCESS: existing process R_THREAD: existing kernel thread
rsid	Identifies the work component to be attached to the resource set specified by the rset parameter. The rsid parameter must be the following: Process ID (for rstype of R_PROCESS): set the rsid_t at_pid field to the desired process' process ID. Kernel thread ID (for rstype of R_THREAD): set the rsid_t at_tid field to the desired kernel thread's thread ID.
rset	Specifies which work component (specified by the rstype and rsid parameters) to attach to the resource set.
flags	Specifies the scheduling policy for the work component being attached. The only supported value is R_ATTACH_STRSET value, which is only applicable if the rstype parameter is set to R_PROCESS. The R_ATTACH_STRSET value indicates that the process is to be scheduled with a single-threaded policy (only on one hardware thread per physical processor).

Return Values

Upon successful completion, the kra_attachrset subroutine returns a 0. If unsuccessful, one or more of the following are true:

Item	Description
EINVAL	One of the following is true: The flags parameter contains an invalid value. The rstype parameter contains an invalid type qualifier. The R_ATTACH_STRSET flags parameter is specified and one or more processors in the rset parameter are not assigned for exclusive use.
ENODEV	The resource set specified by the rset parameter does not contain any available processors, or the R_ATTACH_STRSET flags parameter is specified and the constructed ST resource set does not have any available processors.
ESRCH	The process or kernel thread identified by the rstype and rsid parameters does not exist.
EPERM	One of the following is true: If the rstype is R_PROCESS, either the resource set specified by the rset parameter is not included in the partition resource set of the process identified by the rstype and rsid parameters, or any of the thread's R_THREAD rset in this process is not a subset of the resource set specified by the rset parameter. If the rstype is R_THREAD, the resource set specified by the rset parameter is not included in the target thread's process effective or partition (real) resource set. The calling process has neither root authority nor CAP_NUMA_ATTACH attachment privilege. The calling process has neither root authority nor the same effective user ID as the process identified by the rstype and rsid parameters. The process or thread identified by the rstype and rsid parameters has one or more threads with a bindprocessor processor binding.