VMS Help  —  System Services, $PROCESS AFFINITY (Alpha and Integrity servers)
    On Alpha and Integrity server systems, allows modification of the
    CPU affinity set for a specified kernel thread.

    This service accepts 64-bit addresses.

    Format

      SYS$PROCESS_AFFINITY  [pidadr], [prcnam], [select_mask],

                            [modify_mask], [prev_mask], [flags]

                            [,[mask_length]]

    C Prototype

      int sys$process_affinity  (unsigned int *pidadr, void *prcnam,

                                struct _generic_64 *select_mask,

                                struct _generic_64 *modify_mask,

                                struct _generic_64 *prev_mask, struct

                                _generic_64 *flags,...);

1  –  Arguments

 pidadr

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Process identification (PID) of a kernel thread whose affinity
    mask is to be modified or returned. The pidadr argument is the
    32- or 64-bit address of a longword that contains the PID.

    Process selection is made through a combination of the pidadr
    and prcnam arguments. If neither are specified or if both have a
    zero value, the service operations are made to the user affinity
    mask of the current kernel thread of the calling process. The
    pidadr argument takes precedence over the prcnam argument in any
    circumstances where both are supplied in the service call.

 prcnam

    OpenVMS usage:process_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor
    Process name of the process whose affinity mask is to be modified
    or returned. The prcnam argument is the 32- or 64-bit address
    of a character string descriptor pointing to the process name
    string. A process can be identified with a 1- to 15-character
    string. The service operations are made to the user affinity mask
    of the initial thread of the specified process.

    If pidadr and prcnam are both specified, then pidadr is modified
    or returned and prcnam is ignored. If neither argument is
    specified, then the context of the current kernel thread of the
    calling process is modified or returned.

 select_mask

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The select-mask argument specifies which bits of the specified
    process's affinity 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 CPU
    position in the mask is to be modified.

 modify_mask

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Mask specifying the settings for those explicit affinities
    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 CPU is to be added to
    the specified process affinity set; when clear, the corresponding
    CPU is to be removed from the specified process affinity set.

    To add a specific CPU to the affinity mask set, that bit position
    must be set in both select_mask and modify_mask. To remove a
    specific CPU from the affinity mask set, that bit position must
    be set in select_mask and clear in modify_mask.

    The constant CAP$K_ALL_CPU_ADD, when specified in modify_mask,
    indicates that all CPUs specified in select_mask are to be added
    to the affinity mask set. The constant CAP$K_ALL_CPU_REMOVE
    indicates that all CPUs in select_mask are to be removed from
    the affinity mask set.

 prev_mask

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       write only
    mechanism:    by 32- or 64-bit reference
    Previous CPU affinity mask for the specified kernel thread before
    execution of this call to $PROCESS_AFFINITY. The prev_mask
    argument is the 32- or 64-bit address of a quadword into which
    $PROCESS_AFFINITY writes the previous explicit affinity bitmap.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by 32- or 64-bit reference
    Options selected for affinity modification. The flags argument
    is a quadword bit vector wherein a bit corresponds to an option.
    Only the bits specified below are used; the remainder of the
    quadword bits are reserved and must be 0.

    Each option (bit) has a symbolic name, which the $CAPDEF macro
    defines. 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_PERMANENT   Indicates whether to modify the permanent
                           process affinities in addition to the
                           current image copy. If CAP$M_FLAG_
                           PERMANENT is set, then both the permanent
                           and current affinities are modified.
                           If the flag bit is clear or flags is
                           unspecified, then just the current image
                           process affinities are modified.

                           This bit also determines which of the
                           affinity masks are returned in prev_
                           mask. If set, the permanent mask, used
                           to reinitialize the current set at image
                           rundown, is returned. If the bit is clear
                           or the flags argument is not specified,
                           the current running mask is returned.

    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 will allow 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 unspecified, the kernel thread
                           will be checked to ensure it can safely
                           run on one of the CPUs in the active set;
                           otherwise, any valid state operations on
                           kernel threads already in a blocked state
                           will be allowed.

    CAP$M_FLAG_CHECK_CPU_  Indicates whether a check is made to
    ACTIVE                 verify that all CPUs in the select mask
                           that are about to be selected for affinity
                           binding are in the active set. This does
                           not apply to CPUs that are about to be
                           cleared from the current affinity set.
                           Unlike CAP$M_FLAG_CHECK_CPU where only
                           a single CPU has to be valid for the
                           condition to pass, CAP$M_FLAG_CHECK_
                           CPU_ACTIVE requires that all CPUs in the
                           selected set must pass the criteria.

    CAP$M_PURGE_WS_IF_     Causes the working set of the process
    NEW_RAD                to be purged if the choice of affinity
                           results in a change to the home RAD of the
                           process.

 mask_length

    OpenVMS usage:bitmap
    type:         quadword bitmap
    access:       read only
    mechanism:    by 32- or 64-bit reference
    The mask_length specifies the length in bytes of each of the
    three bitmaps: select_mask, modify_mask, prev_mask. If mask_
    length is not supplied or specified as zero, a length of 8 bytes
    is used.

    The correct value for mask_length is determined by the number of
    supported CPUs on the system. You can compute the number of bytes
    needed for the bitmap as follows: Use the $GETSYI system service
    with an item code of SYI$_MAX_CPUS to find the minimum number of
    bits needed, round this number up to a multiple of 64, and divide
    the result by 8.
Close Help