 |
HP OpenVMS System Services Reference Manual
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 and I64)
On Alpha and I64 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 HP 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.
|
|
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:
- CST$M_CPU_STOP
- CST$M_CPU_MIGRATE
- CST$M_CPU_START
- CST$M_CPU_FAILOVER
- CST$M_CPU_POWER_OFF
- 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_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:
- 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 and I64)
On Alpha and I64 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 HP 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);
$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.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.
$CREATE_BUFOBJ_64 (Alpha and I64)
On Alpha and I64 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:
- I/O can be initiated to or from the buffer without the need to
probe or lock the buffer pages.
- The process is still fully swappable.
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.
|
|
