__pset_rtctl(2)

NAME

__pset_rtctl() — real-time processor set control

SYNOPSIS

#include <sys/rtpset.h>

int __pset_rtctl(
pset_rt_req_t request,
psetid_t pset,
int arg,
);

DESCRIPTION

HP-UX Processor Sets allow a subset of processors in the system to be isolated for exclusive use by specified threads and processes. Only the threads bound to a processor set can execute on processors in that processor set (see pset_create(2)).

The __pset_rtctl() function extends processor set functionality for real-time applications to minimize operating system activities in a processor set. A processor set can be configured as a real-time processor set (referred to as RTE processor set). An RTE processor set has the following special features that are not available in standard processor sets:

No Kernel Daemons: The scheduler does not schedule kernel daemons on processors in the RTE processor set. Kernel daemons are restricted to processors in non-RTE processor sets.
No External I/O Interrupts: External I/O interrupts on processors in the RTE processor set are disabled. The system is reconfigured to not deliver any external I/O interrupts to processors in the RTE processor set. (The clock interrupt still continues to come on each processor though). This feature may not be supported on all platforms (see intctl(1M) for details).
Callouts Migration: All pending callouts on processors in the RTE processor set are reassigned to processors in non-RTE processor sets. However, if a real-time application in an RTE processor set requests a service which requires callout support in the kernel, such callouts may execute on RTE processors.

The system always has at least one non-RTE processor set. The system default processor set (see pset_create(2)) cannot be configured as an RTE processor set. Since the system default processor set is never empty, there is always at least one processor in a non-RTE processor set to execute the kernel daemons, I/O interrupts and callouts for the system.

The request argument specifies the operation to perform on the processor set pset for real time extension. The following values are supported:

RTE_PSET_CONFIG

Configure the specified processor set, pset, as an RTE processor set. The processor set may or may not have processors assigned at this point. If pset has processors assigned to it at the time of this request, these processors are made unavailable to the kernel daemons. External I/O interrupts and pending callouts on processors in pset are reassigned to processors in non-RTE processor sets in the system. The processor set attribute values are changed to default values for an RTE processor set. If pset has any assigned workload, it continues to execute in that processor set. The arg argument is ignored.

RTE_PSET_UNCONFIG

Unconfigure the specified processor set pset as an RTE processor set. The processors, if any, in this processor set are made available to the kernel daemons. The system may redistribute the external I/O interrupts with availability of these processors. Pending callouts in the system are not redistributed to these processors. The processor set attribute values are restored to default values for a non-RTE processor set as applicable. If pset has any assigned workload, it continues to execute in that processor set. The arg argument is ignored.

RTE_PSET_GETFIRSTPSET

Return the ID of the first RTE processor set in the system. The pset and arg arguments are ignored.

RTE_PSET_GETNEXTPSET

Return the ID of the next RTE processor set in the system after pset. The arg argument is ignored.

Typically, RTE_PSET_GETFIRSTPSET is called to determine the first RTE processor set. RTE_PSET_GETNEXTPSET is then called in a loop (until the call returns -1) to determine the IDs of the remaining RTE processor sets in the system.

See pset_ctl(2) for additional processor set query operations. The pset_ctl() function allows users to query all processor sets in the system, processors in a specific processor set, processor set given a processor, etc.

A processor may be added to an RTE processor set using the pset_assign() function. In this case, the processor is made unavailable to the kernel daemons; external I/O interrupts and pending callouts on this processor are reassigned to processors in non-RTE processor sets in the system. Conversely, if a processor is removed from an RTE processor set and added to a non-RTE processor set, it is made available to the kernel daemons and for external I/O interrupts. Similarly, if a non-empty RTE processor set is destroyed, its processors are made available to the kernel daemons and for external I/O interrupts.

Only a user with appropriate privileges may configure and unconfigure an RTE processor set. However, any user may query the IDs and configuration of RTE processor sets. Only a user with appropriate privileges may reassign processors into or out of an RTE processor set, change attribute values, or destroy an RTE processor set. Any user with EXEC permissions in an RTE processor set may run applications in that RTE processor set.

HP-UX processor sets define processor set attributes to provide users explicit control in managing their processor set configuration and work load assignment among many users and applications (see pset_getattr(2) for details). A processor set is assigned default values for these attributes at creation time. The RTE processor sets attributes are assigned different default values at time of configuration. The supported attributes and their default values are:

PSET_ATTR_OWNID: UID of the processor set owner. When a processor set is converted into an RTE pset, the owner of the pset changes to that of the effective uid of the calling process. The owner of the pset or a user with appropriate privilege can change this attribute using pset_setattr(). (See pset_setattr(2).)
PSET_ATTR_GRPID: GID of processor set's owner group. When a processor set is converted into an RTE pset, the group of the pset changes to that of the effective gid of the calling process. The owner of the pset or a user with appropriate privilege can change this attribute using pset_setattr(). (See pset_setattr(2).)
PSET_ATTR_PERM: Access permissions for the processor set. When a processor set is converted to an RTE processor set, the permissions are reset such that the processor set owner has all permissions, group has READ and EXEC permissions, and others have only READ permissions. The owner of the pset or a user with appropriate privileges can change this attribute using pset_setattr(). (See pset_setattr(2).)
PSET_ATTR_EMPTY: Indicates the behavior on a request to bind a process or a thread to a processor set that does not contain any processors. For RTE processor sets, such a request is rejected by default. However, a user with appropriate privileges or a user with WRITE access to the pset can change the value of this attribute to allow deletion of an empty RTE processor set. See pset_getattr(2) for supported values.
PSET_ATTR_IOINTR: A flag to indicate if processors in the processor set are configured to receive external I/O interrupts or not. All processors in an RTE processor set are disabled to receive interrupts. This attribute cannot be enabled until the processor set is unconfigured as an RTE processor set.
PSET_ATTR_LASTSPU: Indicates the behavior on a request to remove the last processor from a processor set if there are active processes and threads bound to the processor set. For RTE processor sets, such a request is rejected by default. However, a user with appropriate privileges or a user with WRITE access to the pset can change the value of this attribute to allow removal of the last processor from an RTE processor set even if the processor set is busy. See pset_setattr(2) for supported values.
PSET_ATTR_NONEMPTY: Indicates the behavior on a request to destroy a non-empty processor set. A non-empty processor set has at least one processor assigned to it. For RTE processor sets, such a request will be rejected by default. However, a user with appropriate privileges or a user with WRITE access to the pset can change the value of this attribute to allow deletion of an RTE processor set in use. See pset_setattr(2) for supported values.
PSET_ATTR_LCPU: Indicates whether the physical processor cores in the RTE pset is enabled with logical processors (LCPUs). See pset_setattr(2) for details and supported values.

Processor Set Support

Use sysconf() with _SC_PSET_SUPPORT to see if the processor set functionality is supported by the underlying HP-UX operating system version.

Use sysconf() with _SC_PSET_RTE_SUPPORT to see if the RTE processor set functionality is supported by the underlying HP-UX operating system version.

Security Restrictions

Some or all of the actions associated with this system call require the PSET privilege. Processes owned by the superuser have this privilege. Processes owned by other users may have this privilege, depending on system configuration. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

__pset_rtctl() returns zero on successful completion for RTE_PSET_CONFIG and RTE_PSET_UNCONFIG requests.

For RTE_PSET_GETFIRSTPSET and RTE_PSET_GETNEXTPSET requests, the ID of an RTE processor set is returned if one is found.

Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS

__pset_rtctl fails if one or more of the following is true:

EALREADY: The specified processor set pset is already configured as RTE processor set, and the RTE_PSET_CONFIG request is issued.
EINVAL: The request is invalid.
EINVAL: The specified processor set pset is invalid.
EINVAL: The specified processor set pset is not an RTE processor set, and RTE_PSET_UNCONFIG request is issued.
EINVAL: The request is RTE_PSET_GETNEXTPSET and there is no other RTE processor set after pset.
ENOSYS: The RTE processor set functionality is not supported by the underlying HP-UX version.
EPERM: The user does not have necessary permissions to perform the requested operation.
EPERM: The specified processor set, pset, is a special, reserved processor set, and cannot be configured as an RTE processor set.

EXAMPLES

Create a new processor set, and configure it as an RTE processor set:

#include <sys/rtpset.h> 

psetid_t    new_psetid; 
int         ret; 

if ((ret = pset_create(&new_psetid)) < 0) { 
    perror("pset_create()"); 
    exit(1); 
} 

if ((ret = __pset_rtctl(RTE_PSET_CONFIG, new_psetid, 0)) < 0) { 
    perror("__pset_rtctl()"); 
    exit(2); 
} 

__pset_rtctl(2)

Technical documentation

» Table of Contents

» Index