HP OpenVMS System Services Reference Manual


Previous Contents Index

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 and Integrity servers)

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


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.
CST$K_CPU_POWER_OFF The requested operation is initiated on the 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_ON The requested operation is initiated on the 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:

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_CPU Any CPU in the configure set, regardless of the active set state
CST$K_ANY_ACTIVE_CPU Any CPU in the active set
CST$K_ANY_STOPPED_CPU Any CPU in the configure set, but not the 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_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:

A CPU in the configure set can transition:

A CPU in the Galaxy unassigned state (not in the configure set of any partition in the platform) can transition:

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$_NOPRIV 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 and Integrity servers)

On Alpha and Integrity server 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, see the description of $CPU_TRANSITION in this manual.

This service accepts 64-bit addresses.

For more information, see the HP OpenVMS Alpha Partitioning and Galaxy Guide.


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


$CREATE

The Create service constructs a new file according to the attributes you specify in the FAB. If any XABs are chained to the FAB, then the characteristics described in the XABs are applied to the file. This service performs implicit Open and Display services.

For additional information about this service, see the OpenVMS Record Management Services Reference Manual.


$CREATE_BUFOBJ_64 (Alpha and Integrity servers)

On Alpha and Integrity server systems, creates a buffer object out of a range of pages.

This service accepts 64-bit addresses.


Format

SYS$CREATE_BUFOBJ_64 start_va_64 ,length_64 ,acmode ,flags ,return_va_64 ,return_length_64 ,buffer_handle_64


C Prototype

int sys$create_bufobj_64 (void *start_va_64, unsigned __int64 length_64, unsigned int acmode, unsigned int flags, void *(*(return_va_64)), unsigned __int64 *return_length_64, struct _generic_64 *buffer_handle_64);


Arguments

start_va_64


OpenVMS usage: address
type: quadword address
access: read only
mechanism: by value

Starting virtual address of the pages to be included in the buffer object. The specified virtual address will be rounded down to a CPU-specific page boundary.

The virtual address space must already exist.

length_64


OpenVMS usage: byte count
type: quadword (unsigned)
access: read only
mechanism: by value

Length of the virtual address space to be included in the buffer object. The specified length will be rounded up to a CPU-specific page boundary such that it includes all CPU-specific pages in the requested range.

acmode


OpenVMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value

Access mode on behalf of which the request is being made. The acmode argument is a longword containing the access mode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in SYS$STARLET_C.TLB define the following symbols and their values for the four access modes:
Value Symbolic Name Access Mode
0 PSL$C_KERNEL Kernel
1 PSL$C_EXEC Executive
2 PSL$C_SUPER Supervisor
3 PSL$C_USER User

The most privileged access mode used is the access mode of the caller. For the $CREATE_BUFOBJ_64 service to complete successfully, the resultant access mode must be equal to or more privileged than the access mode already associated with the pages in the specified input range.

flags


OpenVMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value

Flag mask specifying the request options. The flags argument is a longword bit vector in which each bit corresponds to a flag. The $CBODEF macro in STARLET.MLB and CBODEF.H file in SYS$STARLET_C.TLB define a symbolic name for each flag.

The following table describes each flag that is valid for the $CREATE_BUFOBJ_64 service:
Flag Value Description
CBO$M_RETSVA 1 If set, returns the system virtual address in the return_va_64 argument instead of the process virtual address range. (Valid for inner mode callers only.)
CBO$M_SVA_32 4 If set, creates the buffer object window in 32-bit S0/S1 space. (By default, this service creates the window in 64-bit S2 space.)

return_va_64


OpenVMS usage: address
type: quadword address
access: write only
mechanism: by 32- or 64-bit reference

The lowest process virtual address of the pages in the buffer object. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the virtual address.

return_length_64


OpenVMS usage: byte count
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference

The length of the virtual address range in the buffer object. The return_length_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length of the virtual address range in bytes.

buffer_handle_64


OpenVMS usage: handle
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword into which a buffer handle is returned to be used when referencing the created buffer object.

Description

The Create Buffer Object service creates a buffer object for use by the I/O subsystem. The pages that constitute the buffer object are permanently locked into physical memory (but not the process's working set) and double mapped into system space. The net effect is the following:

If the condition value, SS$_ACCVIO, is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64, return_length_64, and buffer_handle_64 arguments.

If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully made part of the buffer object before the error occurred. If no pages were made part of the buffer object, the return_va_64 argument will contain the value -1, and a value is not returned in the memory location pointed to by the return_length_64 argument.

Required Privileges

No privileges are required if calling $CREATE_BUFOBJ_64 from an inner mode. If calling from user mode, the process must hold the rights identifier VMS$BUFFER_OBJECT_USER at the time of the call. This identifier is normally granted by the system administrator via the Authorize utility.

Required Quota

No process quota is charged, but the number of pages is limited by the system parameter MAXBOBMEM.

Related Services

$CRETVA_64, $DELETE_BUFOBJ, $EXPREG_64


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The return_va_64, return_length_64, or buffer_handle_64 argument cannot be written by the caller.
SS$_BADPARAM Invalid flags options specified.
SS$_EXBUFOBJLM Buffer object cannot be created because it would bring the total number of buffer object pages above the systemwide limit MAXBOBMEM.
SS$_INSFMEM Insufficient dynamic memory.
SS$_INSFSPTS Insufficient system page table entries.
SS$_NOBUFOBJID The process attempted to create a buffer object from user mode but was not holding required rights identifier VMS$BUFFER_OBJECT_USER.
SS$_NOPRIV Valid flag options were specified but from user mode.
SS$_PAGNOTWRITE A page within the address range is not writable.
SS$_PAGOWNVIO The pages could not be put into the buffer object because the access mode associated with the call to $CREATE_BUFOBJ_64 was less privileged than the access mode associated with the pages.


Previous Next Contents Index