 |
OpenVMS System Services Reference Manual
$CPU_CAPABILITIES (Alpha Only)
On Alpha systems, allows modification of the user capability set for a
specified CPU, or for the global user capability CPU default.
This service accepts 64-bit addresses.
Format
SYS$CPU_CAPABILITIES cpu_id [,select_mask] [,modify_mask] [,prev_mask]
[,flags]
C Prototype
int sys$cpu_capabilities (int cpu_id, struct _generic_64 *select_mask,
struct _generic_64 *modify_mask, struct _generic_64 *prev_mask, struct
_generic_64 *flags);
Arguments
cpu_id
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Identifier of the CPU whose user capability mask is to be modified or
returned. The cpu_id argument is a longword containing
this number, which is in the supported range of individual CPUs from 0
to SYI$_MAX_CPUS - 1 .
Specifying the constant CAP$K_ALL_ACTIVE_CPUS applies the current
modification operation to all CPUs currently in the active set, and to
the default CPU initialization context in SCH$GL_DEFAULT_CPU_CAP. If
the prev_mask argument is also supplied, the previous
default CPU initialization context in SCH$GL_DEFAULT_CPU_CAP will be
returned rather than any specific CPU state.
To modify only the user capabilities in SCH$GL_DEFAULT_CPU_CAP, the
flags argument has a bit constant
CAP$M_FLAG_DEFAULT_ONLY. When this bit is set, all service operations
are performed on the global cell rather than on an individual CPU
specified in the cpu_id argument. This bit does not
supersede the CAP$K_ALL_ACTIVE_CPUS constant, however. If both
constants are specified, CAP$K_ALL_ACTIVE_CPUS take precedence;
nevertheless, the operations to SCH$GL_DEFAULT_CPU are identical
because that function is a direct subset of the other.
select_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Mask specifying which bits of the specified CPU's user capability mask
are to be modified. The select_mask argument is the
32- or 64-bit address of a quadword bit vector wherein a bit, when set,
specifies that the corresponding user capability is to be modified.
The individual user capability bits in select_mask can
be referenced by their symbolic constant names, CAP$M_USER1 through
CAP$M_USER16. These constants (not zero-relative) specify the position
in the mask quadword that corresponds to the bit name. Multiple
capabilities can be selected by connecting the appropriate bits with a
logical OR operation.
The constant CAP$K_ALL_USER, when specified in the
select_mask argument, selects all user capability bits.
modify_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Mask specifying the settings for those capabilities selected in the
select_mask argument. The modify_mask
argument is the 32- or 64-bit address of a quadword bit vector wherein
a bit, when set, specifies that the corresponding user capability is to
be added to the specified CPU; when clear, the corresponding user
capability is to be removed from the specified CPU.
The bit constants CAP$M_USER1 through CAP$M_USER16 can be used to
modify the appropriate bit position in modify_mask.
Multiple capabilities can be modified by connecting the appropriate
bits with OR.
To add a specific user capability to the specified CPU, that bit
position must be set in both select_mask and
modify_mask. To remove a specific user capability from
the specified CPU, that bit position must be set in
select_mask and cleared in
modify_mask.
The symbolic constant CAP$K_ALL_USER_ADD, when specified in
modify_mask, indicates that all capabilities specified
in select_mask are to be added to the current user
capability set. The constant CAP$K_ALL_USER_REMOVE indicates that all
capabilities specified are to be cleared from the set.
prev_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
Previous user capability mask for the specified CPU before execution of
this call to $CPU_CAPABILITIES. The prev_mask argument
is the 32- or 64-bit address of a quadword into which $CPU_CAPABILITIES
writes a quadword bit mask specifying the previous user capabilities.
If this argument is specified in conjunction with CAP$K_ALL_ACTIVE_CPUS
as the cpu_id selection constant or with
CAP$M_FLAG_DEFAULT_ONLY, the user capability portion of the default
boot initialization state context SCH$GL_DEFAULT_CPU_CAP will be
returned.
flags
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Options selected for the user capability modification. The
flags argument is a quadword bit vector wherein a bit
corresponds to an option. Only the bits specified in the following
table are used; the remainder of the quadword bits are reserved and
must be 0.
Each option (bit) has a symbolic name, defined by the $CAPDEF macro.
The flags argument is constructed by performing a
logical OR operation using the symbolic names of each desired option.
The following table describes the symbolic name of each option:
| Symbolic Name |
Description |
|
CAP$M_FLAG_DEFAULT_ONLY
|
Indicates that the specified operations are to be performed on the
global context cell instead of on a specific CPU. This bit supersedes
any individual CPU specified in
cpu_id but does not override the all active set
behavior (CAP$K_ALL_ACTIVE_CPUS). Specifying this bit constant applies
this operation to the default startup capabilities for all CPUs booted
for the first time.
|
|
CAP$M_FLAG_CHECK_CPU
|
Determines whether the kernel thread can be left in a nonrunnable state
under some circumstances. No operation of this service allows a
transition from a runnable to blocked state; however, if the kernel
thread is already at a blocked state, this bit determines whether the
result of the operation must leave it runnable. If CAP$M_FLAG_CHECK_CPU
is set or
flags is not specified, the kernel thread is checked
to ensure that it can safely run on one of the CPUs in the active set.
If CAP$M_FLAG_CHECK_CPU is not set, any state operations on kernel
threads already in a blocked state are allowed.
|
Description
The Modify CPU User Capabilities system service, based on the arguments
select_mask and modify_mask, adds or
removes user capabilities for the specified cpu_id. If
specified, the previous capability mask is returned in
prev_mask. With the modify_mask
argument, multiple user capabilities for a CPU can be added or removed
in the same system service call.
Either modify_mask or prev_mask, or
both, must be specified as arguments. If modify_mask
is specified, select_mask must be specified as an
argument. If modify_mask is not specified, no
modifications are made to the user capability mask for the specified
CPU. In this case, select_mask is ignored. If
prev_mask is not specified, no previous mask is
returned.
No service state changes that will place any currently runnable kernel
thread into a blocked state are allowed.
If CAP$K_ALL_ACTIVE_CPUS is specified in cpu_id, the
user capability modifications are performed on all CPUs currently in
the active set, as well as the global initialization cell. If the bit
constant CAP$M_FLAG_DEFAULT_ONLY is set in the flags
argument, the user capability modifications are made only to the global
initialization cell, regardless of what individual CPU is specified in
cpu_id.
Required Access or Privileges
The caller must have both ALTPRI and WORLD privileges to call
SYS$CPU_CAPABILITIES to modify CPU user capabilities.
No privileges are required if SYS$CPU_CAPABILITIES is called only to
retrieve the current user capabilities mask from the specified CPU or
global default.
Related Services
$PROCESS_CAPABILITIES
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_BADPARAM
|
One or more arguments has an invalid value, or the specified CPU is not
in the configuration.
|
|
SS$_ACCVIO
|
The service cannot access the locations specified by one or more
arguments.
|
|
SS$_NOPRIV
|
Insufficient privilege for attempted operation.
|
|
SS$_CPUCAP
|
Attempted operation would place one or more processes in an unrunnable
state.
|
|
SS$_INSFARG
|
Fewer than the required number of arguments were specified, or no
operation was specified.
|
$CPU_TRANSITION (Alpha Only)
On Alpha systems, changes the current processing state of a CPU in the
configure set of the current system or an unassigned CPU in an OpenVMS
Galaxy configuration. This service completes asynchronously. For
synchronous completion, use the $CPU_TRANSITIONW service.
This service accepts 64-bit addresses. Parameter and bit definitions
are resolved in $CSTDEF in the appropriate STARLET library.
Refer to the OpenVMS Alpha Partitioning and Galaxy Guide for more information.
Format
SYS$CPU_TRANSITION tran_code ,cpu_id ,nodename ,node_id ,flags ,efn
,iosb ,astadr_64 ,astprm_64
C Prototype
int sys$cpu_transition (int tran_code, int cpu_id,
dsc64$descriptor_s_pq nodename, int node_id, uint32 flags, int efn,
IOSB *iosb, VOID_PQ astadr, uint64 astprm, uint32 timout);
Arguments
tran_code
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Identifier specifying the type of state change to be initiated on the
target CPU. The tran_code argument is a longword
containing one of the following values:
| Symbolic Name |
Description |
|
CST$K_CPU_STOP
|
The target CPU is to be removed from the active set and halted into
console mode. It remains in the configure set of the current partition.
|
|
CST$K_CPU_MIGRATE
|
The target CPU is removed from the configure set of the local partition
and the console is requested to add it to the configure set of the
partition specified in node_id. If the CPU is currently in the active
set, it is automatically brought to console mode through the
CST$K_CPU_STOP function first.
|
|
CST$K_CPU_START
|
The target CPU is requested to exit console mode and join the active
set of the current partition. The CPU must already be part of the
configure set.
|
|
CST$K_CPU_FAILOVER
|
The CPU is assigned a default target partition where it will
automatically migrate on system failure. This assignment persists until
it is superseded. To remove an assignment or partition name, the
current partition ID should be specified.
|
cpu_id
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Identifier of the CPU whose state is to be modified. The
cpu_id argument is a longword number in the supported
range of individual CPUs from 0 to SYI$_MAX_CPUS - 1. In a Galaxy, this
CPU must be in the configure set of the local partition or not assigned
to any other partitions. The symbolic values, CST$K_ANY_LOCAL_CPU can
be used in certain types of transitions to allow the next available
processor of the appropriate type be used instead of a specific one.
node_id
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Identifier of the target Galaxy partition in CST$K_CPU_ASSIGN,
CST$K_CPU_FAILOVER, or CST$K_CPU_MIGRATE transition. The
node_id argument is a longword containing a number in
the supported range of IDs provided by the console for the current
hardware platform. If the nodename parameter is
specified, node_id is ignored.
flags
| OpenVMS usage: |
longword_mask |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Options selected for the CPU state transition. The
flags argument is a longword bit vector wherein a bit
corresponds to an option. Only the bits specified below are used; the
remainder of the longword bits are reserved and must be 0.
Each option (bit) has a symbolic name. The flags
argument is constructed by performing a logical OR operation using the
symbolic names of the following options:
| Symbolic Name |
Description |
|
CST$V_CPU_DEFAULT_CAPABILITIES
|
At the completion of the transition, the CPU's user capabilities are
set back to the default system value. If this option is not specified,
modified user capabilities are maintained across STOP and START
transitions as long as the CPU remains in the local partition configure
set.
|
|
CST$V_CPU_ALLOW_ORPHANS
|
The transition is to be allowed even though it will leave at least one
thread in the system unable to execute on any CPU in the active set.
|
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The event flag to be set when the state transition attempt has
completed. The efn argument is a longword specifying
the number of the event flag; however, this service only uses the
low-order byte.
When you invoke $CPU_TRANSITION, the specified event flag is cleared;
when the operation is complete, the event flag is set.
iosb
| OpenVMS usage: |
io_status_area |
| type: |
IOSB structure |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference |
The I/O status area to receive the final completion status of the
transition operation. The iosb argument is the 32-bit
or 64-bit virtual address of the I/O status area. The I/O status area
structure is 32 bytes in length; its definition can be found in
$IOSBDEF in STARLET.MLB for macro and in the file IOSBDEF.H in
SYS$STARLET_C.TLB for C.
When you call $CPU_TRANSITION, the I/O status area is cleared. After
the transition operation is complete, the block is modified as follows:
| Symbolic Name |
Description |
|
iosb$w_status
|
The first word contains the condition value return, indicating the
final completion status of the operation.
|
|
|
The first bit in the second word of the IOSB is set only if an error
occurred during the operation; the remaining bits are zeroes.
|
astadr_64
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by 32-bit or 64-bit reference |
The AST routine to be executed when the requested transition attempt
has completed. The astadr_64 argument is the 32-bit or
64-bit virtual address of this routine. If you specify the
astadr_64 argument, the AST routine executes at the
access mode from which the state transition was requested.
astprm_64
| OpenVMS usage: |
user_arg |
| type: |
quadword |
| access: |
read only |
| mechanism: |
by value |
The quadword AST parameter to be passed to the AST routine.
Description
The state transition in tran_id is requested for the
target cpu_id.
A CPU currently in the active set can transition:
- To the STOPPED state; removed from the active set and left in the
configure set, halted in console mode.
A CPU in the configure set can transition:
- To the UNASSIGNED state by STOPPING it and then DEASSIGNING it back
to the console.
- To the ACTIVE state; warm rebooted and a full member of the
symmetric multiprocessing (SMP) active set on the requesting partition.
- To another partition through MIGRATION; the target CPU is removed
from the configure set and added to the configure set of the partition
specified by node_id.
A CPU in the Galaxy unassigned state (not in the configure set of any
partition in the platform) can transition:
- To the ASSIGNED state; in the configure set of the partition.
specified by node_id. Any partition can make the
assignment, but the CPU must be unassigned.
CPU state transition is a two-phase operation in the OpenVMS scheduling
model. This service initiates the request in the process context of the
caller and returns the setup status in the service condition value.
Phase 2 proceeds asynchronously; the efn and
iosb arguments can be used to indicate the completion
of the transition through the standard wait system services. Additional
notification of the completion can be made through the OpenVMS AST
mechanisms using a routine specified in astadr_64 and
a user-supplied parameter in astprm_64.
Required Privileges
The caller must have the CMKRNL privilege to call SYS$CPU_TRANSITION to
modify CPU states.
Related Services
$CPU_TRANSITIONW
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_BADPARAM
|
One of more arguments has an invalid value or the specified CPU is not
in the configuration.
|
|
SS$_ACCVIO
|
The service cannot access the locations specified by one or more
arguments.
|
|
SS$_NOCMKRNL
|
Caller does not have CMKRNL privilege needed to complete operation.
|
|
SS$_INSFARG
|
Fewer than the required number of arguments were specified or no
operation was specified.
|
|
SS$_TOO_MANY_ARGS
|
More arguments were specified than are allowed by the service.
|
|
SS$_INVCOMPID
|
The target partition ID is not valid in this configuration.
|
|
SS$_CPUNOTACT
|
The specified CPU is not part of the current partition's active set.
|
|
SS$_NOSUCHCPU
|
The specified CPU does not exist in the current hardware configuration,
or is not in the configure set of the local partition.
|
|
SS$_CPUSTARTD
|
The specified CPU is already in the local active set, or is in the
process of joining it.
|
|
SS$_CPUSTOPPING
|
The specified CPU is already STOPPED or in the processing of leaving
the active set.
|
$CPU_TRANSITIONW (Alpha Only)
On Alpha systems, changes the current processing state of a CPU in the
configure set or an unassigned CPU in a Galaxy configuration. This
service completes synchronously; that is, it returns to the caller only
after the final completion status of the operation is known.
In all other respects, $CPU_TRANSITIONW is identical to
$CPU_TRANSITION. For all other information about the $CPU_TRANSITIONW
service, refer to the description of $CPU_TRANSITION in this manual.
This service accepts 64-bit addresses.
Refer to the OpenVMS Alpha Partitioning and Galaxy Guide for more information.
Format
SYS$CPU_TRANSITIONW tran_id ,cpu_id ,nodename ,node_id ,flags ,efn
,iosb ,astadr_64 ,astprm_64
C Prototype
int sys$cpu_transitionw (int tran_code, int cpu_id,
dsc64$descriptor_s_pq nodename, int node_id, uint32 flags, int efn,
IOSB *iosb, UINT64_PQ astadr, uint64 astprm, uint32 timout);
|
