Document revision date: 30 March 2001

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.

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.

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);

	privacy and legal statement
4527PRO_011.HTML