16.1 SYS$CPU_TRANSITION
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.
Format
SYS$CPU_TRANSITION tran_code, cpu_id, nodename,
node_id, flags, efn, iosb, astadr_64, astprm_64
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 automati-
cally migrate on system failure. This
assignment persists until it is super-
seded. 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 long-
word 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 ar-
gument 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_ At the completion of the transition, the
CAPABILITIES CPU's user capabilities are set back to
the default system value. If this option
is not specified, modified user capa-
bilities are maintained across STOP
and START transitions as long as the
CPU remains in the local partition
configure set.
CST$V_CPU_ALLOW_ The transition is to be allowed even
ORPHANS 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 condi-
tion 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 rou-
tine.
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 ACTIVE state; warm rebooted and a full member
of the SMP active set on the requesting partition.
* To another partition through reassignmnet; the target
CPU is removed from the configure set and added to the
configure set of the partition specified bynode_id .
CPU state transition is a two-phase operation in the
OpenVMS scheduling model. This service initiates the re-
quest 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 comple-
tion 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 privi-
lege 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 gNode ID is not valid in
this configuration
SS$_CPUNOTACT The specified CPU is not part of the
current partitions'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