On Alpha and Integrity server 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.
For more information, see the VSI OpenVMS Alpha Partitioning and
Galaxy Guide.
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);
1 – 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_ The CPU is assigned a default target partition
FAILOVER 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.
CST$K_CPU_POWER_ The requested operation is initiated on the
OFF target CPU to bring the electrical power to
the OFF state. 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_POWER_ The requested operation is initiated on the
ON target CPU to bring the electrical power to
the ON state.
Each $K code represents an end state operation, each of which
has a specific start state that the CPU must be in, in order to
initiate the transition.
This service may automatically initiate a successful completion
of the requested operation by initiating one or more transparent
transitions. This operation takes place if the CPU is not in that
specific start state, and there are an obvious and unique set
of transitions that can be initiated prior to the specified end
state.
Multiple transitions can also be initiated simultaneously through
the system service tran_code parameter. Each transition code has
a $M form as shown in the following list, that can be or'd with a
specific end state $K code:
o CST$M_CPU_STOP
o CST$M_CPU_MIGRATE
o CST$M_CPU_START
o CST$M_CPU_FAILOVER
o CST$M_CPU_POWER_OFF
o CST$M_CPU_POWER_ON
Any legal combination of transitions can be specified with the $M
form, however no more than one $K code is allowed.
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.
Generic identifiers can also be used to allow OpenVMS to select
the most appropriate resource. The following table lists these
codes:
Code Description
CST$K_ANY_OWNED_ Any CPU in the configure set, regardless of
CPU the active set state
CST$K_ANY_ACTIVE_ Any CPU in the active set
CPU
CST$K_ANY_STOPPED_ Any CPU in the configure set, but not the
CPU active set
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_ At the completion of the transition, the CPU's
DEFAULT_ user capabilities are set back to the default
CAPABILITIES 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_ The transition is to be allowed even though it
ORPHANS 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_ The first word contains the condition value return,
status 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.