[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index


$CMEXEC

Changes the access mode of the calling process to executive mode.

Format

SYS$CMEXEC routin ,[arglst]


C Prototype

int sys$cmexec (int (*routin)(__unknown_params), unsigned int *arglst);


Arguments

routin


OpenVMS usage: procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference

Routine to be executed while the process is in executive mode. The routin argument is the address of this routine.

arglst


OpenVMS usage: arg_list
type: longword (unsigned)
access: read only
mechanism: by reference

Argument list to be passed to the routine specified by the routin argument. The arglst argument is the address of this argument list.

If the arglst value is nonzero and is not accessible as an address or if the routine is inaccessible, the service returns SS$_ACCVIO.

Alpha and I64 systems require a pointer to a valid argument list or a value of 0 in the arglst argument. This means that the arglst argument must contain an accessible virtual address for an argument list, the first longword of which must be a valid list size.


Description

The Change to Executive Mode service allows a process to change its access mode to executive, execute a specified routine, and then return to the access mode in effect before the call was issued.

The $CMEXEC service uses standard procedure calling conventions to pass control to the specified routine.

On Alpha and I64 systems, to conform to the OpenVMS calling standard, you must not omit the arglst argument.

On VAX systems, if no argument list is specified, the argument pointer (AP) contains a 0. However, to conform to the OpenVMS calling standard, you must not omit the arglst argument.

On Alpha, and I64, and VAX systems, when you use the $CMEXEC service, the system service dispatcher modifies the registers before entry into the target routine. The specified routine must exit with a RET instruction and should place a status value in R0 before returning.

All of the Change Mode system services are intended to allow for the execution of a routine at an access mode more (not less) privileged than the access mode from which the call is made. If $CMEXEC is called while a process is executing in kernel mode, the routine specified by the routin argument executes in kernel mode, not executive mode.

Required Access or Privileges

To call this service, the process must either have CMEXEC or CMKRNL privilege or be currently executing in executive or kernel mode.

Required Quota

None

Related Services

None


Condition Values Returned

SS$_ACCVIO The arglst or routine argument is not accessible.
SS$_BADPARAM The routine specified is in a translated image.
SS$_NOPRIV The process does not have the privilege to change mode to executive.
All other values The routine executed returns all other values.

$CMEXEC_64 (Alpha and I64)

On Alpha and I64 systems, changes the access mode of the calling process to executive mode.

This service accepts 64-bit addresses.


Format

SYS$CMEXEC_64 routin_64 ,arglst_64


C Prototype

int sys$cmexec_64 (int (*routin_64)(__unknown_params), unsigned __int64 *arglst_64);


Arguments

routin_64


OpenVMS usage: procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference

Routine to be executed while the process is in executive mode. The routin_64 argument is the 32- or 64-bit address of this routine.

arglst_64


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

Argument list to be passed to the routine specified by the routin_64 argument. The arglst_64 argument is the 32- or 64-bit address of this argument list.

If the arglst value is nonzero and is not accessible as an address or if the routine is inaccessible, the service returns SS$_ACCVIO.

Alpha and I64 systems require a pointer to a valid argument list or a value of 0 in the arglst_64 argument. This means that the arglst_64 argument, if nonzero, must contain an accessible virtual address for an argument list, the first quadword of which must be a number between 0 and 255 specifying the number of quadwords that follow it on the list.


Description

The Change to Executive Mode with Quadword Argument List service allows a process to change its access mode to executive, execute a specified routine, and then return to the access mode in effect before the call was issued.

The $CMEXEC_64 service uses standard procedure-calling conventions to pass control to the specified routine.

When you use the $CMEXEC_64 service, the system modifies the registers before entry into the target routine. The specified routine must exit with a RET instruction.

All of the Change Mode system services are intended to allow for the execution of a routine at an access mode more (not less) privileged than the access mode from which the call is made. If $CMEXEC_64 is called while a process is executing in kernel mode, the routine specified by the routin_64 argument executes in kernel mode, not executive mode.

Required Access or Privileges

To call this service, the process must either have CMEXEC or CMKRNL privilege or be currently executing in executive or kernel mode.

Required Quota

None

Related Services

$CMEXEC, $CMKRNL, $CMKRNL_64


Condition Values Returned

SS$_ACCVIO The arglst argument or routine is not accessible.
SS$_BADPARAM The routine specified is in a translated image.
SS$_NOCMEXEC The process does not have the privilege to change mode to executive.
All other values The routine executed returns all other values.

$CMKRNL

Changes the access mode of the calling process to kernel mode. This service allows a process to change its access mode to kernel, execute a specified routine, and then return to the access mode in effect before the call was issued.

Format

SYS$CMKRNL routin ,[arglst]


C Prototype

int sys$cmkrnl (int (*routin)(__unknown_params), unsigned int *arglst);


Arguments

routin


OpenVMS usage: procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference

Routine to be executed while the process is in kernel mode. The routin argument is the address of this routine.

arglst


OpenVMS usage: arg_list
type: longword (unsigned)
access: read only
mechanism: by reference

Argument list to be passed to the routine specified by the routin argument. The arglst argument is the address of this argument list.

If the arglst value is nonzero and is not accessible as an address or if the routine is inaccessible, the service returns SS$_ACCVIO.

Alpha systems require a pointer to a valid argument list or a value of 0 in the arglst argument. This means that the arglst argument must contain an accessible virtual address for an argument list, the first longword of which must be a valid list size.


Description

The Change Mode to Kernel ($CMKRNL) and the Change Mode to Executive ($CMEXEC) system services provide a simple and secure path for applications to execute code in the privileged kernel and executive processor modes. These services first check for the necessary CMKRNL or CMEXEC privileges, and then call the routine specified in the argument list in the specified processor mode.

When code is executing in a privileged processor mode, such as executive or kernel mode, the code executes with full OpenVMS privileges. Furthermore, specific protection checks can also be bypassed. For example, $CMKRNL bypasses the check for CMKRNL privilege that is normally required when $CMKRNL is called from executive mode, and $SETPRV calls are processed without SETPRV privilege when called from executive or kernel mode.

The condition value returned from the procedure specified in the argument list is used as the return status from the $CMKRNL or $CMEXEC system service call. Based on the OpenVMS calling standard, this condition value is returned by register R0, using a language-specific mechanism.

Note

The $CMKRNL and $CMEXEC system services are typically used to access privileged or internal OpenVMS routines or data structures. The code to access these data structures can be OpenVMS version-dependent, particularly if the internal routines or data structures change. Errors that occur in code executing in a privileged processor mode can lead to one or more possible situations: data corruptions, process deletions, or system crashes.

The particular library routines and libraries that can be called from code executing in executive or kernel mode can also be limited, because not all library routines accessible from user mode can be called from kernel mode.

Code Example

The following code example shows how to call a specified routine in kernel mode using this service:


/*
//  cmkrnl.c
//
//  OpenVMS example of calling a specified routine in kernel mode,
//  using the SYS$CMKRNL system service.
//
//  Requires CMKRNL privilege.
//
//  Errors in kernel-mode code can corrupt critical data structures,
//  can cause process deletions, and can potentially crash the OpenVMS
//  operating system.
//
//  To build:
//
//    $ CC/DECC CMKRNL
//    $ LINK CMKRNL
//    $ RUN CMKRNL
*/
#include <ssdef.h>
#include <starlet.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stsdef.h>

/*
//  The KernelRoutine routine executes in kernel mode, but does
//  absolutely nothing useful.
*/
int KernelRoutine( int *UsrArg1, int *UsrArg2)
  {
  return SS$_NORMAL;
  }
main()
  {
  int RetStat;
  int ArgList[3];
  int i = 0;

  printf("OpenVMS Alpha example of calling sys$cmkrnl\n");

  /*
  //  Build the routine argument list in an array -- the KernelRoutine
  //  call expects two arguments, necessitating an array containing the
  //  count and the two arguments.
  */
  ArgList[++i] = 1;
  ArgList[++i] = 2;
  ArgList[0] = i;

  /*
  //  Now invoke the KernelRoutine in kernel mode...
  */
  RetStat = sys$cmkrnl( KernelRoutine, ArgList );
  if (!$VMS_STATUS_SUCCESS( RetStat ))
    return RetStat;

  printf("Now successfully back in user mode.\n");

  return SS$_NORMAL;
  }

Required Access or Privileges

To call the $CMKRNL service, a process must either have CMKRNL privilege or be currently executing in executive or kernel mode.

Required Quota

None

Related Services

$CMEXEC, $CMEXEC_64, $CMKRNL_64, $SETPRV


Condition Values Returned

SS$_ACCVIO The arglst argument or routine is not accessible.
SS$_BADPARAM The routine specified is in a translated image.
SS$_NOCMKRNL The process does not have the privilege to change mode to kernel.
All other values The routine executed returns all other values.

$CMKRNL_64 (Alpha and I64)

On Alpha and I64 systems, changes the access mode of the calling process to kernel mode. This service allows a process to change its access mode to kernel, execute a specified routine, and then return to the access mode in effect before the call was issued.

This service accepts 64-bit addresses.


Format

SYS$CMKRNL_64 routin_64 ,arglst_64


C Prototype

int sys$cmkrnl_64 (int (*routin_64)(__unknown_params), unsigned __int64 *arglst_64);


Arguments

routin_64


OpenVMS usage: procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference

Routine to be executed while the process is in kernel mode. The routin_64 argument is the 32- or 64-bit address of this routine.

arglst_64


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

Quadword argument list to be passed to the routine specified by the routin_64 argument. The routin_64 argument is the 32- or 64-bit address of this routine.

If the arglst value is nonzero and is not accessible as an address or if the routine is inaccessible, the service returns SS$_ACCVIO.

Alpha and I64 systems require a pointer to a valid argument list or a value of 0 in the arglst_64 argument. This means that the arglst_64 argument, if nonzero, must contain an accessible virtual address for an argument list, the first quadword of which must be a number between 0 and 255 specifying the number of quadwords that follow it on the list.


Description

The Change to Kernel Mode with Quadword Argument List service allows a process to change its access mode to kernel, execute a specified routine, and then return to the access mode in effect before the call was issued.

The $CMKRNL_64 service uses standard procedure calling conventions to pass control to the specified routine.

When you use the $CMKRNL_64 service, the system modifies the registers before entry into the target routine. The system loads R4 with the address of the process control block (PCB). The specified routine (if programmed in MACRO-32) must exit with a RET instruction.

Required Access or Privileges

To call the $CMKRNL_64 service, a process must either have CMKRNL privilege or be currently executing in executive or kernel mode.

Required Quota

None

Related Services

$CMEXEC, $CMEXEC_64, $CMKRNL, $SETPRV


Condition Values Returned

SS$_ACCVIO The arglst argument or routine is not accessible.
SS$_BADPARAM The routine specified is in a translated image.
SS$_NOCMKRNL The process does not have the privilege to change mode to kernel.
All other values The routine executed returns all other values.

$CONNECT

The Connect service establishes a record stream by associating and connecting a RAB with a FAB. You can invoke the Connect service only for files that are already open.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.


$CPU_CAPABILITIES (Alpha and I64)

On Alpha and I64 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.


Previous Next Contents Index