Programming Interface Information: The Monitor Records are intended Programming Interfaces that allow the customer to write programs to obtain services of z/VM.

#### MRPRCSXL

Prolog
Control Block Contents
Cross Reference

#### MRPRCSXL Prolog

     DSECT NAME - PRCSXL
     FUNCTION - Map a Monitor record.
     LOCATED BY -
            Through the Monitor Control Area
     REFERENCED CONTROL BLOCKS -
            MRRECHDR    Monitor Record Header
     NAME - MRPRCSXL
     DESCRIPTIVE NAME - Monitor Sample Record
                        Domain 5 - Processor Domain
                        Record 22 - Shared-Exclusive Spinlock Utilization
     DESCRIPTION - Distributed shared-exclusive spinlock per-processor
                   data. These records are generated for any processor
                   that has been online any time since IPL, even if the
                   processor is currently offline.

       List of locks with data in the record:

       Lock ID    Lock Description
       --------   ----------------
       SRMSLOCK:  scheduler lock (distributed shared-exclusive)
                  The name SRMSLOCK is used to be consistent with
                  the name already used in MRSYTLCK(D0 R23). However,
                  SRMSLOCK is no longer the Scheduler Lock data structure.
                  It is now an SXL-style lock with the SXLXL located at
                  SRMSCHLK.
       HCPDSVTL:  topology lock (distributed shared-exclusive)

       This record consists of two sections:
       1) a header at the start of the record
       2) an array of entries. One per spinlock listed above.
          These contain the statistics for each of the locks
          listed above.

       The header includes the information needed to locate and
       interpret the data in the other section.  That is,
       for the array, the header has fields that contain the
       number of entries in the array, the size of an entry,
       and the displacement in bytes from the beginning of this
       record to the first entry in the array.

       The array has entries for all distributed shared-exclusive
       spinlocks. An entry in this array is described by
       PRCSXL_CALLKDATA.

     SHARED-EXCLUSIVE SPINLOCK STATISTICS:

       This Monitor record provides explanatory information
       about shared-exclusive spinlock usage and how that
       contributes to changes in spinlock contention reported
       in MRSYTLCK (D0 R23) for Scheduler and Topology locks.

       The purpose and use of this record is similar to
       MRSYTLCK (D0 R23), but this record provides more
       detailed information.

       Spin time for shared requests is reported separately for
       standard unconditional requests, as well as for the
       LOCKSEQ internal spin used in HCPDSP for the Scheduler
       Lock.  And that is reported separately for cancelled
       spins and successful spins.

       Increases in spinlock contention are often related to
       the request rates, or the mix of request types. While
       shared lock holds can run concurrently with each other,
       exclusive holds block all requests regardless of type.
       Therefore lock contention is more sensitive to increases
       in exclusive request rates than share request rates.

       While share requests can be blocked only when exclusive
       is held, exclusive requests can be blocked when the lock
       is held exclusive or shared, or when a share-pending
       condition is present. Counts and spin time for each of
       these are reported separately for exclusive requests.
       The count of shares for which exclusive requests had to
       wait indicates how frequently share scans paused to wait
       for a share to be released.

       The share-pending statistics provide indications as to
       how often share requests relied on the share-pending
       setting to halt exclusive requests and allow share
       requests to be processed.

       The difference between the Diagnose 9C usage data reported
       in this record and MRSYTLCK is that this record organizes
       the data based on the type of target being considered
       which is determined by the condition causing the spin.

     SHARED-EXCLUSIVE SPINLOCK REQUEST TYPES:

       Each spinlock is described by a set of data that explains
       the usage of the lock. Because these locks are shared-
       exclusive spinlocks, they may be acquired shared as well
       as exclusive. Each acquisition type may be acquired by a
       conditional, or an unconditional request method. For the
       conditional requests, the lock is acquired only if it is
       immediately available. For conditional share requests,
       there is support for a LOCKSEQ parameter which is used
       in specialized routines that perform their own lock spin
       including all of the necessary checks for processor
       failures, use of Diagnose x'9C', etc.

       Conditional requests may be successful or unsuccessful
       while unconditional requests always complete successfully
       but may need to spin for a while before they complete.
       Conditional requests never end up in the normal spin
       routine if the lock isn't available. However, when the
       invoker manages its own spin (LOCKSEQ case), then the
       conditional request may spin, but not in the normal
       spin routine. This special case is the only case where a
       spin on a lock may be ended without acquiring the lock.

       There are two additional lock request types. These
       additional types require that the lock is held in one
       mode and switch to the other. These types are EX2SHR,
       which is a demote from exclusive to shared, and SHR2EX,
       which is a promote from shared to exclusive. The demote
       is always successful but promote is successful only if
       the an exclusive hold is immediately available. Neither
       of these request types ever spin.

     LOCK ACQUISITION MECHANISMS:

       Unlike the typical semaphore lock design, the shared-
       exclusive spinlock design is a distributed lock design.
       There is still a global lock word that records whether
       the lock is held exclusive and who holds it, but that
       word holds nothing about shared holds of the lock.
       It does contain a flag for share-pending which is
       described in the next section. Every processor has its
       own processor-local cache line where it records whether
       it holds a share of the lock.

       A processor acquiring a share starts by marking itself
       as holding a share in its local cache line and then
       inspecting the global word to see if the lock is held
       exclusive.  If it isn't, then the share is held.  If
       exclusive is held and the share request was conditional,
       it turns off the share in its local cache line and ends
       the share request unsuccessfully.  If exclusive was held
       and the request was unconditional, the local share flag
       is turned off to allow the exclusive request forward
       progress, and then spins until exclusive is turned off.
       When that happens it repeats the original process of
       marking the share in the local cache line and then
       checking exclusive again until it has observed exclusive
       not held while it has its share set.  Share requests
       spin only because of exclusive requests.

       An exclusive request begins by attempting to turn on
       exclusive while observing share-pending and exclusive
       are off. Conditional requests fail if this can't be done
       on the inital attempt while unconditional requests spin
       until successful. Once it sets exclusive it must then
       inspect every processor's local memory area to ensure no
       shares are held.  If it encounters a processor that
       holds a share then it waits until the share gets turned
       off before checking the next share.  The exclusive
       acquisition is complete when all of the processors have
       been observed as not holding a share.  Exclusive
       requests could spin when trying to start the exclusive
       acquisition process because exclusive is set or because
       share-pending is set.  For the purposes of statistics
       tracking, this spin is considered a spin on exclusive if
       exclusive was observed on the last time it spun before a
       successful acquisition because that was the last request
       that blocked it.  However, if it last observed only
       share-pending on then it is considered a spin on share-
       pending.  After exclusive acquisition has started, it
       may then spin on one or more shares as it checks all of
       the processors.  It is considered a spin on shares
       unless none were observed held for any processor.
       Conditional exclusive requests complete successfully
       only if exclusive can be set while exclusive and share-
       pending are off and no shares are observed held during
       the scan of shares.  If the conditional request
       encounters a share, it turns off exclusive and
       terminates the request.

       EX2SHR (demote) requests simply set the share on in the
       local memory area and turn off exclusive. The fact that
       they held exclusive means no other exclusive request is
       held or in SXLBK scan processing, and no shares are
       actively held yet. No other checks are needed.

       SHR2EX (promote) requests follow the same logic as a
       conditional exclusive acquisition while leaving the
       share set. If exclusive is acquired successfully,
       it turns off the share and the promote is successful. If
       the conditional exclusive acquisition was unsuccessful,
       the share is left held and the promote is not successful.

     SHARE STARVATION PROTECTION:

       The shared-exclusive lock manager design gives priority
       to exclusive requests in that once they make forward
       progress in the exclusive acquisition, shares must back
       out and wait for the exclusive to complete. Exclusive
       requests wait for existing share holds to complete but
       block new share requests. High exclusive usage rates
       could potentially starve share requests. To prevent this,
       share requests that have been delayed by exclusive
       requests that exceed a threshold are allowed to use the
       share-pending mechanism to force a window for share
       acquisitions by causing new exclusive requests to wait
       until that pending share request completes. While the
       share-pending state is set, other processors can also
       acquire shares allowing the share backlog to drain before
       exclusive requests start again. The share-pending window
       is closed when the processor that set share-pending
       releases its share and turns off share-pending.

     LOCAL LOCK SPIN REPORTING:

       A deficiency in the old shared-exclusive spinlock
       manager was that the time HCPDSP spent in its
       internal spin loop for the Scheduler Lock was not
       reported in SYTLCK_CALSTIME, SYTSCG_CALSLKTM, or
       SYTPRP_PFXSPINT.  This resulted in significant under-
       reporting of Scheduler Lock contention.  Those fields
       now include the local spin time in HCPDSP. Further, this
       Monitor record breaks out HCPDSP local spin statistics
       separately.  Because the new shared-exclusive spinlock
       manager is much more cache-efficient, the total spin
       times are expected to be significantly lower even with
       this additional component of spin time included.

     ------------------------------------------------------------

     TABLES OF STATISTICS REPORTED PER LOCK:
     - Abbreviation and symbol descriptions follow the tables.

     ------------------------------------------------------------

     REQUEST RATES, SPIN TIMES, SHARE-PENDING USAGE:
     ------------------------------------------------------------
     |                |      |   Shared     |Exclusive|    |    |
     ------------------------------------------------------------
     |                | rm-> | SC | SL | SU | XC | XU | SX | XS |
     ------------------------------------------------------------
     |   Statistics   | ssss |    |    |    |    |    |    |    |
     ------------------------------------------------------------
     | Req cts        |      |    |    |    |    |    |    |    |
     |   Unsucc       | CU   | Y  | Y  |    |  Y |    | Y  |    |
     |   Succ         |      |    |    |    |    |    |    |    |
     |     No Spin    | CN   | Y  | Y  | Y  |  Y | Y  | Y  | Y  |
     |     Spin (any) | CSA  |    | Y  | Y  |    | Y  |    |    |
     |       on X     | CSX  |    | Y  | Y  |    | Y  |    |    |
     |       on S-P   | CSP  |    |    |    |    | Y  |    |    |
     |       on S     | CSS  |    |    |    |    | Y  |    |    |
     ------------------------------------------------------------
     | Spin time      |      |    |    |    |    |    |    |    |
     |   Unsucc       | TSU  |    | Y  |    |    |    |    |    |
     |   Succ         |      |    |    |    |    |    |    |    |
     |     Spin (any) |      |    |    |    |    |    |    |    |
     |       on X     | TSX  |    | Y  | Y  |    | Y  |    |    |
     |       on S-P   | TSP  |    |    |    |    | Y  |    |    |
     |       on S     | TSS  |    |    |    |    | Y  |    |    |
     ------------------------------------------------------------
     | Shr-Pnd        |      |    |    |    |    |    |    |    |
     |   Set          | PS   |    | Y  | Y  |    |    |    |    |
     |   Reset        | PR   |    | Y  |    |    |    |    |    |
     |   Obs          | PO   | Y  | Y  | Y  |    |    |    |    |
     ------------------------------------------------------------
     | Shares Obs     | SO   |    |    |    |    | Y  |    |    |
     | Excl Obs       | XO   |    | Y  | Y  |    | Y  |    |    |
     ------------------------------------------------------------

     KEY TO ABBREVIATIONS IN THE TABLE ABOVE:
      - field names are defined by rm and ssss in this format:
        PRCSXL_SXLErmssss.

     ROW HEADINGS FOR TABLE 1

     - ROW 1
       - Shared = Shared lock requests.  These may be
         unconditional, conditional with the caller doing a
         local spin, or typical single-attempt conditional.
       - Exclusive = Exclusive lock requests.  These may be
         either unconditional or conditional.

     - ROW 2 (rm values)
       - rm-> = Request type and Modifier values in the row
         following this label indicate the rm value used in
         the field name PRCSXL_SXLErmssss.  The specific
         rm values are described below.
       - SC = DSPOLICY=RETURN was specified, but LOCKSEQ was
         not.  This is a conditional share request.  A single
         attempt is made to acquire the lock.  If not
         immediately available, the lock is not acquired.
       - SL = DSPOLICY=RETURN was specified with LOCKSEQ.
         Conditional, but the requestor does its own spin
         which might not acquire a share if it cancels the
         spin.  This is used only for the Scheduler Lock
         (SRMSCHLK, previously known as SRMSLOCK) in HCPDSP.
       - SU = DSPOLICY=SPIN was specified.  This is an
         unconditional request for a share.
       - XC = DSPOLICY=RETURN was specified. These are
         conditional exclusive requests.
       - XU = DSPOLICY=SPIN was specified.  These are
         unconditional exclusive requests.
       - SX = SHR2EX request (promote).  These are
         conditional by definition.
       - XS = EX2SHR request (demote).  These are
         unconditional by definition because they always
         succeed, however never need to spin.

     COLUMN HEADINGS  FOR TABLE 1

     - COLUMN 1
       - Req cts = Lock Request counts
       - Unsucc = Unsuccessful requests.  These occur only
         for conditional requests.  For the
         SHARE,DSPOLICY=RETURN,LOCKSEQ case this includes
         only cases where the invoking routine cancelled its
         local spin before the lock was acquired.
       - Succ = Successful requests.
       - No Spin = Lock requests that completed successfully
         without spinning.
       - Spin (any) = requests that spun for any reason.
         This count is incremented only once for requests that
         spun for multiple different reasons. Spin time does
         not use this category because time is allocated to
         specific spin reasons. Subcategories follow for the
         specific causes.
       - on X = requests that spun because eXclusive was held.
       - on S-P = requests that spun because a Share-Pending
         condition was present.
       - on S = requests that spun because a Share was held.
       - Shr-Pnd = Share-Pending - a mechanism used by share
         requests to prevent share starvation.  The statistics
         in this category describe behavior of requests that
         exploit share-pending.
       - Set = share-pending was Set during lock acquisition.
         It is set only during share requests that spin.
         Although LOCKSEQ is specified with DSPOLICY=RETURN,
         the invoker manages its own spin and may use share-
         pending. In this case it may also reset it if the
         spin is cancelled before the share is acquired.
       - Reset = share-pending was turned off (Reset) during
         lock acquisition because the requestor stopped
         waiting to acquire the lock.  It can be reset only by
         the same lock request that set it. This occurs only in
         cases where the LOCKSEQ spin in HCPDSP was cancelled.
       - Obs = share-pending was Observed set at the time the
         share was acquired, but was not set by this requestor.
       - Shares Obs = The number of Shares that were Observed
         held as Exclusive requests scanned processors for
         shares held.
       - Excl Obs = The number of exclusive requests that were
         processed during the spin for other lock requests.
         It is updated only for requests that acquire the lock.

     - COLUMN 2 (ssss values)

       - rm-> = see the description for row 2 above.
       - ssss = The values in column 2 after this row are the
         ssss values used in the field name PRCSXL_SXLErmssss.
         The value indicates the type of statistic this field
         contains. The statistic is described above in the
         corresponding column 1 entry.

     ------------------------------------------------------------

     DIAGNOSE X'9C' USAGE:
     --------------------------------------
     |      |  Shared   |    Exclusive    |
     --------------------------------------
     | rm-> | SL  | SU  | XU  | XU  | XU  |
     --------------------------------------
     |  b-> |  X  |  X  |  X  |  P  |  S  |
     --------------------------------------
     |  ss  |     |     |     |     |     |
     --------------------------------------
     |  9T  |  Y  |  Y  |  Y  |  Y  |  Y  |
     |  9S  |  Y  |  Y  |  Y  |  Y  |  Y  |
     |  9F  |  Y  |  Y  |  Y  |  Y  |  Y  |
     |  99  |  Y  |  Y  |  Y  |  Y  |  Y  |
     |  94  |  Y  |  Y  |  Y  |  Y  |  Y  |
     --------------------------------------

     KEY TO ABBREVIATIONS IN THE TABLE ABOVE:
      - field names in the main section of the lock entry
        that are mapped by SXLEX are of this format:
        PRCSXL_SXLEXrmb
      - field names in the SXLEX are of this format:
        PRCSXL_SXLEXss

     ROW HEADINGS

     - ROW 1
       - Shared = Shared lock requests.  These may be
         unconditional, conditional with the caller doing a
         local spin, or typical single-attempt conditional.
       - Exclusive = Exclusive lock requests.  These may be
         either unconditional or conditional.

     - ROW 2 (rm values)
       - SL = DSPOLICY=RETURN was specified with LOCKSEQ.
         Conditional, but the requestor does its own spin
         which might not acquire a share if it cancels the
         spin.  This is used only for the Scheduler Lock
         (SRMSCHLK, previously known as SRMSLOCK) in HCPDSP.
       - SU = DSPOLICY=SPIN was specified.  This is an
         unconditional request for a share.
       - XU = DSPOLICY=SPIN was specified.  These are
         unconditional exclusive requests.

     - ROW 3 (b values - conditions causing the spin)
       - X = while spinning due to exclusive being held.
       - P = while spinning due to share-pending condition.
       - S = while spinning due to shares held.

     COLUMN HEADINGS

     - COLUMN 1 (ss values)
       - 9T = The number of times attempts were made to find
         a target for Diag 9C during lock spins.
       - 9S = The number of times the state of a potential
         Diagnose 9C target was checked during lock spins.
       - 9F = The number of times a target was successfully
         found during lock spins.
       - 99 = The number of times a Diagnose 9C was issued
         for a target identified during lock spins.
       - 94 = The number of times a Diagnose 44 was issued
         during lock spins.

     ------------------------------------------------------------

       Block comments in the record below provide suggestions
       for using the individual values to calculate higher level
       statistics for evaluating shared-exclusive spinlock usage.

     ------------------------------------------------------------

     NOTES:

       The statistics reported in this record are preserved over
       periods of time when the processor is varied offline so
       the counts will appear monotonically increasing for the
       life of the system.

       All spin time is measured as elapsed time using the TOD
       clock and is reported in TOD clock units.

       The Scheduler Lock, which is one of the two locks reported
       in this Monitor record, is usually the most frequently
       acquired spinlock in the system. These detailed statistics
       are defined specifically for the more complicated usage
       of the Scheduler lock. Therefore some of the fields will
       contain zeroes for other spinlocks. For example, LOCKSEQ
       is not used with any other lock.

     Definitions of record version numbers.

     Version N+1 contains all the sections of data in version
     N along with any new sections defined by the version N+1.
     In effect the version number determines the structure of the
     record header area where variable sections are described.
     The version number is placed in the field PRCSXL_CALVERSN
     in the header.

     Versions:
       PRCSXL_CALVERSN = 0
         Version 0 includes basic spin lock data as defined by
         PRCSXL_CALLKDATA.

#### MRPRCSXL Control Block Contents

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

      0   0  Structure   68+ PRCSXL                 Start of monitor record
      0   0  Character    0  PRCSXL_CALMRHDR        Record header. See MRRECHDR
                                                    for details.
      0   0  Character   20  MRHDR
      0   0  Unsigned     2  MRHDRLEN
      2   2  Unsigned     2  MRHDRZER
      4   4  Unsigned     1  MRHDRDM
      5   5  Unsigned     1  *
      6   6  Unsigned     2  MRHDRRC
      8   8  Character    8  MRHDRTOD
     16  10  Character    4  *
     20  14  Character    0  MRHDR_END
     20  14  Unsigned     4  PRCSXL_CALNMLKS        Number of spin locks in this
                                                    record. That is, the number of
                                                    PRCSXL_CALLKDATA entries
                                                    included after this header.
     24  18  Unsigned     2  PRCSXL_CALENTSZ        The size (in bytes) of each
                                                    PRCSXL_CALLKDATA entry.
     26  1A  Unsigned     2  PRCSXL_CALENTDSP       The displacement (in bytes)
                                                    from the beginning of this
                                                    record to the first
                                                    PRCSXL_CALLKDATA entry. The
                                                    entries are consecutive in
                                                    storage starting with the first
                                                    at this displacement.
     28  1C  Unsigned     1  PRCSXL_CALVERSN        Record version number:
                                                    See PRCSXL_VERnnn constant
                                                    definition in the prolog above.
     29  1D  Unsigned     1  *                      Reserved for IBM use.
     30  1E  Unsigned     2  PRCSXL_SXLCPUAD        Processor's CPU address.
     32  20  Unsigned     1  PRCSXL_SXLCPUTY        CPU Type. Valid values:
                                                    X'00' - General Purpose (CP)
                                                    X'02' - zSeries Application
                                                            Assist (zAAP)
                                                    X'03' - Integrated Facility
                                                            for Linux (IFL)
                                                    X'04' - Internal Coupling
                                                            Facility (ICF)
                                                    X'05' - zSeries Integrated
                                                            Information (zIIP)
     33  21  Unsigned     1  PRCSXL_SXLFLAGS        Flags:
                                                    X'80' - processor is offline.
                                                    X'40' - processor was online
                                                            at some point since IPL.
     34  22  Unsigned     2  *                      Reserved for IBM use.
     36  24  Character    8  PRCSXL_SXLTIME         TOD value at the time of
                                                    the transition to the current
                                                    state which is either online
                                                    or offline.
     44  2C  Character    8  PRCSXL_PFXPRBTM        Total raw CPU time spent in
                                                    emulation mode on this
                                                    processor for all users.
                                                    This field starts at
                                                    x'7FFFFFFFF_00000000' and
                                                    advances down (in the negative
                                                    direction).
     52  34  Character    8  PRCSXL_PFXUTIME        Total raw CPU time spent on this
                                                    processor which was charged to
                                                    users.  It includes both time
                                                    spent running the guest and
                                                    time that CP spends on behalf
                                                    of a user doing such things as
                                                    instruction simulation or page
                                                    translation. This is in raw CPU
                                                    time, not elapsed (or wall
                                                    clock) time.
                                                    This field starts at
                                                    x'7FFFFFFFF_00000000' and
                                                    advances down (in the negative
                                                    direction).
     60  3C  Character    8  PRCSXL_PFXTMSYS        Total raw CPU time spent on this
                                                    processor which has been
                                                    charged to the system instead
                                                    of the user. In general, this
                                                    is processing that is
                                                    inappropriate to charge to any
                                                    one particular user. Examples
                                                    include portions of the
                                                    following functions: scheduling
                                                    decisions, handling
                                                    interruptions, monitoring, and
                                                    page migration.
                                                    This field starts at
                                                    x'7FFFFFFFF_00000000' and
                                                    advances down (in the negative
                                                    direction).
     68  44  Character    0  PRCSXL_CALENTS         Start of the array of
                                                    lock data which contains the
                                                    general spin lock data
                                                    (PRCSXL_CALLKDATA) entries,
                                                    one for each formal spin lock
                                                    arranged one after the other
                                                    at the end of this record.
                                                    There is an ID field in each
                                                    entry that should be used to
                                                    determine which lock the entry
                                                    represents. See the list of
                                                    LOCKIDs above to determine
                                                    which ID represents which lock.
    Mapping of an array entry for a shared-exclusive spinlock containing
    statistics for that spinlock. (See the list of locks in the prologue.)

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

      0   0  Structure  424  PRCSXL_CALLKDATA       Formal spin lock data
                                                    entry.
      0   0  Character    8  PRCSXL_CALLCKID        IDentifier for this
                                                    lock.
      8   8  Bitstring    1  PRCSXL_SXLECTRL        Control settings.
             1... ....       PRCSXL_SXLASSST        Assist allow usage when 1
             .1.. ....       PRCSXL_SXLNIAI2        NIAI-2 allow usage when 1
             ..1. ....       PRCSXL_SXLNIAI4        NIAI-4 allow usage when 1
             ...1 ....       PRCSXL_SXLNIAI8        NIAI-8 allow usage when 1
             .... 1...       PRCSXL_SXLCAD          CAD allow usage when 1.  Only
                                                    set if SXLPFD6 is also set.
             .... .1..       PRCSXL_SXLPFD6         PFD-6/7 used when 1.
             .... ..1.       PRCSXL_SXLPPA14        PPA-14 used when 1.
             .... ...1       PRCSXL_SXLPPA15        PPA-15 used when 1.
      9   9  Bitstring    1  PRCSXL_SXLEFLAGS       Lock flags.
             1... ....       PRCSXL_SXLLKSEQ        LOCKSEQ is exploited.
             .1.. ....       *
             ..1. ....       *
             ...1 ....       *
             .... 1...       *
             .... .1..       *
             .... ..1.       *
             .... ...1       *
     10   A  Unsigned     2  *                      Reserved for IBM use.
     12   C  Unsigned     2  PRCSXL_SXLXLSQT        Sequence number increase
                                                    threshold for setting
                                                    share-pending (SXLXLSPD) for
                                                    unconditional share requests.
     14   E  Unsigned     2  PRCSXL_SXLXLSQTL       Sequence number increase
                                                    threshold for setting
                                                    share-pending (SXLXLSPD) for
                                                    LOCKSEQ invokers with local
                                                    spin lock routines.
     16  10  Character    8  *                      Reserved for IBM use.
    REQUEST COUNTS:

        Request counts are reported in mutually exclusive counts
        for each request type so that the sum of the individual
        counts indicates the overall request rate for that request
        type and method.

        For an rm value, the sum of the CU, CN and CSA values
        provided for that request type and method provides the
        total request count. The CSX, CSP and CSS values provide
        details for the reasons for the spin, but the sum of those
        is likely to be greater than the CSA value because an
        exclusive request might wait because of an exclusive hold,
        or share-pending, but then also wait because of shares.

        The total share requests is the sum of the total for the
        rm values SC, SL and SU. For exclusive, sum XC and XU.

        Various subtotals are meaningful and referred to below:
          Ctot - total requests.
          Ltot - total lock acquisitions (CN + CSA).
          Stot - total lock spins. Normally CSA, but for
                 rm = SL, Stot = CU + CSA because the CU
                 value represents the number of spins started,
                 but cancelled before the lock was acquired.

        Comparing the relative percentages of the Ctot values
        across rm values provides indications of which request
        types and modifiers are most common.

        Counts of unsuccessful conditional lock requests.

        These values are used to determine the failure rates of
        conditional lock requests.
        - for rm = SC, XC, and SX:
          %failure = 100*CU/Ctot
        - for rm = SL (internal spin loop might have been cancelled)
          %failure = 100*CU/Ctot

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

     24  18  Character    8  PRCSXL_SXLESCCU        Count of unsuccessful share
                                                    requests with DSPOLICY=RETURN
                                                    but LOCKSEQ was not specified.
     32  20  Character    8  PRCSXL_SXLESLCU        Count of unsuccessful share
                                                    requests with DSPOLICY=RETURN
                                                    and LOCKSEQ but the invoker
                                                    cancelled the spin before the
                                                    share was acquired.
     40  28  Character    8  PRCSXL_SXLEXCCU        Count of unsuccessful
                                                    exclusive requests with
                                                    DSPOLICY=RETURN.
     48  30  Character    8  PRCSXL_SXLESXCU        Count of unsuccessful
                                                    SHR2EX requests (promote).

        Counts of successful lock acquisitions not requiring a spin.

        Ltot(rm = SC, XC, XS and SX) = CN
           because those request types don't spin.

        These values are used with the spin counts to determine
        Ltot and collision rates for rm = SL, SU and XU which
        are request types that can spin. See the next section.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

     56  38  Character    8  PRCSXL_SXLESCCN        Count of shares acquired by
                                                    requests with DSPOLICY=RETURN
                                                    but LOCKSEQ was not specified.
     64  40  Character    8  PRCSXL_SXLESLCN        Count of shares acquired by
                                                    requests with DSPOLICY=RETURN
                                                    and LOCKSEQ that did not
                                                    require a spin in the invoker.
     72  48  Character    8  PRCSXL_SXLESUCN        Count of shares acquired by
                                                    requests with DSPOLICY=RETURN
                                                    that did not require a spin.
     80  50  Character    8  PRCSXL_SXLEXCCN        Count of exclusive
                                                    acquisitions by requests with
                                                    DSPOLICY=RETURN.
     88  58  Character    8  PRCSXL_SXLEXUCN        Count of exclusive
                                                    acquisitions by requests with
                                                    DSPOLICY=SPIN that did not
                                                    require a spin.
     96  60  Character    8  PRCSXL_SXLESXCN        Count of SHR2EX requests
                                                    that successfully promoted from
                                                    a share to exclusive.
    104  68  Character    8  PRCSXL_SXLEXSCN        Count of EX2SHR requests
                                                    that successfully demoted from
                                                    a exclusive to share.

        Counts of lock requests that spun trying to acquire the
        lock for any reason. Incremented once per lock acquisition
        that spins for one or multiple reasons.

        Ltot(rm = SL, SU, and XU) = CN + CSA
           because those request types spin.
        Lock collision rates as a percentage of total acquisitions
           100*CSA/Ltot
        Lock collision rates as a percentage of total requests
           100*Stot/Ctot

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

    112  70  Character    8  PRCSXL_SXLESLCSA       Count of shares acquired by
                                                    requests with DSPOLICY=RETURN
                                                    and LOCKSEQ that required a
                                                    spin in the invoker for any
                                                    reason.
    120  78  Character    8  PRCSXL_SXLESUCSA       Count of shares acquired by
                                                    requests with DSPOLICY=SPIN
                                                    that required a spin for any
                                                    reason.
    128  80  Character    8  PRCSXL_SXLEXUCSA       Count of exclusive
                                                    acquisitions by requests with
                                                    DSPOLICY=SPIN that required a
                                                    spin for any reason.

        Counts of lock requests that spun for a specific reason
        during lock acquisition. Incremented once per request
        that spins for that specific reason.

        Collision rates for specific reasons can be calculated
        using these values in place of the CSA values.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

    136  88  Character    8  PRCSXL_SXLESLCSX       Count of shares acquired by
                                                    requests with DSPOLICY=RETURN
                                                    and LOCKSEQ that required a
                                                    spin in the invoker to wait
                                                    for exclusive to be released.
    144  90  Character    8  PRCSXL_SXLESUCSX       Count of shares acquired by
                                                    requests with DSPOLICY=SPIN
                                                    that required a spin to wait
                                                    for exclusive to be released.
    152  98  Character    8  PRCSXL_SXLEXUCSX       Count of exclusive
                                                    acquisitions by requests with
                                                    DSPOLICY=SPIN that required a
                                                    spin to wait for exclusive to
                                                    be released.
    160  A0  Character    8  PRCSXL_SXLEXUCSP       Count of exclusive
                                                    acquisitions by requests with
                                                    DSPOLICY=SPIN that required a
                                                    spin to wait because
                                                    share-pending was set.
    168  A8  Character    8  PRCSXL_SXLEXUCSS       Count of exclusive
                                                    acquisitions by requests with
                                                    DSPOLICY=SPIN that required a
                                                    spin to wait for one or more
                                                    shares to be released.

        Spin times when the lock was not immediately available.
        These values accumulate time only when the request is
        spinning for the specified condition.

        STIMtot = Total spin time for all share requests is the
        sum of the TSX and TSU values for SL and SU rm values
        because it should include spin time for cancelled spins.
        STIMtot(rm = SL) = TSX + TSU
        STIMtot(rm = SU) = TSX

        STIMtot = Total spin time for exclusive acquisitions is
        SUM of the TSX, TSP and TSS values for the XU rm value.
        STIMtot(rm = XU) = TSX + TSP + TSS

        Average spin time = STIMtot/Stot.

        Spin % busy can be calculated from the STIMtot values.

        Average spin time and spin % busy can also be calculated
        for the individual spin conditions for exclusive.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

    176  B0  Character    8  PRCSXL_SXLESLTSU       Time spent spinning on
                                                    share requests with
                                                    DSPOLICY=RETURN and LOCKSEQ
                                                    after beginning a spin in the
                                                    invoker but ending the spin
                                                    before the share was acquired.
    184  B8  Character    8  PRCSXL_SXLESLTSX       Time spent spinning on
                                                    share requests with
                                                    DSPOLICY=RETURN and LOCKSEQ
                                                    that required a spin in the
                                                    invoker to wait for exclusive
                                                    to be released.
    192  C0  Character    8  PRCSXL_SXLESUTSX       Time spent spinning on
                                                    share requests with
                                                    DSPOLICY=SPIN that required
                                                    a spin to wait for exclusive
                                                    to be released.
    200  C8  Character    8  PRCSXL_SXLEXUTSX       Portion of time acquiring
                                                    exclusive with DSPOLICY=SPIN
                                                    spent spinning waiting for an
                                                    exclusive hold to be released.
    208  D0  Character    8  PRCSXL_SXLEXUTSP       Portion of time acquiring
                                                    exclusive with DSPOLICY=SPIN
                                                    spent spinning waiting for
                                                    share-pending to be removed.
    216  D8  Character    8  PRCSXL_SXLEXUTSS       Portion of time acquiring
                                                    exclusive with DSPOLICY=SPIN
                                                    spent spinning waiting for
                                                    shares to be released.

        Share-pending usage statistics.

        In general, the higher the ratio of PO/PS, the better
        because it represents efficient usage. A ratio value
        near or below the number of processors is reasonable.
        When calculating the ratio, use the sum of the PO and
        sum of the PS values.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

    224  E0  Character    8  PRCSXL_SXLESUPS        Count of times share-pending
                                                    was set to acquire a share
                                                    excluding LOCKSEQ spins.
    232  E8  Character    8  PRCSXL_SXLESLPS        Count of times share-pending
                                                    was set to acquire a share
                                                    during LOCKSEQ spin.
    240  F0  Character    8  PRCSXL_SXLESLPR        Count of times share-pending
                                                    was removed in a LOCKSEQ spin
                                                    after previously setting it
                                                    without acquiring a share.
    248  F8  Character    8  PRCSXL_SXLESCPO        Count of times share-pending
                                                    was set when acquiring a
                                                    conditional share acquisition
                                                    excluding LOCKSEQ spin.
    256 100  Character    8  PRCSXL_SXLESLPO        Count of times share-pending
                                                    was observed when getting a
                                                    share during a LOCKSEQ spin.
    264 108  Character    8  PRCSXL_SXLESUPO        Count of times share-pending
                                                    was observed during an
                                                    unconditional share
                                                    acquisition.

        Shares observed during exclusive acquisition.

        The ratio SO/CSS is the average number of shares for
        which an exclusive request had to wait while spinning on
        shares.  The value will be greater than 1, but is not
        expected to be a lot higher because while the exclusive
        request is waiting for the first share, other processors
        are in the process of finishing up their holds as well.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

    272 110  Character    8  PRCSXL_SXLEXUSO        Number of CPUs observed
                                                    holding shares while attempting
                                                    to acquire the lock exclusive.

        Exclusive requests observed during lock acquisition.

        The ratio XO/CSX for an rm value is the average number of
        exclusive acquisitions by other processors that occur
        while the rm type requests are blocked by exclusive holds.
        The higher the ratios, the more likely the ratio CSX/Ltot
        is high. A high CSX/Ltot ratio would be closer to 1, while
        a high XO/CSX ratio would be higher than 2.

        These ratios can be calculated for rm = SL, SU and XU.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

    280 118  Character    8  PRCSXL_SXLESLXO        The number of exclusive
                                                    lock acquisitions that occurred
                                                    while other requests spun
                                                    getting a share in HCPDSP
                                                    using its local spin.
    288 120  Character    8  PRCSXL_SXLESUXO        The number of exclusive
                                                    lock acquisitions that occurred
                                                    while other requests spun
                                                    getting a share excluding
                                                    HCPDSP local spin.
    296 128  Character    8  PRCSXL_SXLEXUXO        The number of exclusive
                                                    lock acquisitions that occurred
                                                    while other requests spun
                                                    getting exclusive.

    Diagnose x'9C' and Diag x'44' usage statistics.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

    304 130  Character   24  PRCSXL_SXLEXSLX(LENGTH(SXLEX)) LOCKSEQ share
                                                    requests blocked by exclusive.
    328 148  Character   24  PRCSXL_SXLEXSUX(LENGTH(SXLEX)) Unconditional
                                                    Share requests block by exclusive.
    352 160  Character   24  PRCSXL_SXLEXXUX(LENGTH(SXLEX)) Exclusive
                                                    requests blocked by exclusive.
    376 178  Character   24  PRCSXL_SXLEXXUP(LENGTH(SXLEX)) Exclusive
                                                    requests blocked by share-pending.
    400 190  Character   24  PRCSXL_SXLEXXUS(LENGTH(SXLEX)) Exclusive
                                                    requests blocked by CPUs holding
                                                    a share.
    424 198  Character    0  *                      End of PRCSXL_CALLKDATA.

        Mapping for each of the above elements.  That is, for:
        PRCSXL_SXLEXSLX, PRCSXL_SXLEXSUX, PRCSXL_SXLEXXUX,
        PRCSXL_SXLEXXUP and PRCSXL_SXLEXXUS.

    Offsets
    Dec Hex  Type       Len  Name (Dim)             Description

      0   0  Character   24  PRCSXL_SXLEX
      0   0  Unsigned     4  PRCSXL_SXLEX9T         Count of attempts to
                                                    identify a diagnose x'9C'
                                                    target.
      4   4  Unsigned     4  PRCSXL_SXLEX9S         Count of potential targets
                                                    considered (for which a SIGP
                                                    SRS was performed).
      8   8  Unsigned     4  PRCSXL_SXLEX9F         Count of times a target
                                                    was found.
     12   C  Unsigned     4  PRCSXL_SXLEX9C         Count of Diag x'9C's
                                                    issued.
     16  10  Unsigned     4  PRCSXL_SXLEX44         Count of Diag x'44's
                                                    issued.
     20  14  Unsigned     4  *                      Reserved for IBM use.
     24  18  Character    0  *                      End of PRCSXL_SXLEX.

#### MRPRCSXL Cross Reference

                          Hex           Hex
    Name                  Offset Length Value

    MRHDR                      0     20
    MRHDR_END                 14      0
    MRHDRDM                    4      1
    MRHDRLEN                   0      2
    MRHDRRC                    6      2
    MRHDRTOD                   8      8
    MRHDRZER                   2      2
    PRCSXL                     0     69+
    PRCSXL_CALENTDSP          1A      2
    PRCSXL_CALENTS            2C      0
    PRCSXL_CALENTSZ           18      2
    PRCSXL_CALLCKID            0      8
    PRCSXL_CALLKDATA           0    424
    PRCSXL_CALMRHDR            0      0
    PRCSXL_CALNMLKS           14      4
    PRCSXL_CALVERSN           1C      1
    PRCSXL_MRHDR               0      0
    PRCSXL_PFXPRBTM           2C      8
    PRCSXL_PFXTMSYS           3C      8
    PRCSXL_PFXUTIME           34      8
    PRCSXL_SXLASSST            8           80
    PRCSXL_SXLCAD              8           08
    PRCSXL_SXLCUPAD           1E      2
    PRCSXL_SXLCPUTY           20      1
    PRCSXL_SXLECTRL            8      1
    PRCSXL_SXLEFLAGS           9      1
    PRCSXL_SXLESCCN           38      8
    PRCSXL_SXLESCCU           18      8
    PRCSXL_SXLESCPO           F8      8
    PRCSXL_SXLESLCN           40      8
    PRCSXL_SXLESLCSA          70      8
    PRCSXL_SXLESLCSX          88      8
    PRCSXL_SXLESLCU           20      8
    PRCSXL_SXLESLPO          100      8
    PRCSXL_SXLESLPR           F0      8
    PRCSXL_SXLESLPS           E8      8
    PRCSXL_SXLESLTSU          B0      8
    PRCSXL_SXLESLTSX          B8      8
    PRCSXL_SXLESLXO          118      8
    PRCSXL_SXLESUCN           48      8
    PRCSXL_SXLESUCSA          78      8
    PRCSXL_SXLESUCSX          90      8
    PRCSXL_SXLESUPO          108      8
    PRCSXL_SXLESUPS           E0      8
    PRCSXL_SXLESUTSX          C0      8
    PRCSXL_SXLESUXO          120      8
    PRCSXL_SXLESXCN           60      8
    PRCSXL_SXLESXCU           30      8
    PRCSXL_SXLEX               0     24
    PRCSXL_SXLEX44            10      4
    PRCSXL_SXLEX9C             C      4
    PRCSXL_SXLEX9F             8      4
    PRCSXL_SXLEX9S             4      4
    PRCSXL_SXLEX9T             0      4
    PRCSXL_SXLEXCCN           50      8
    PRCSXL_SXLEXCCU           28      8
    PRCSXL_SXLEXSCN           68      8
    PRCSXL_SXLEXSLX          130     24
    PRCSXL_SXLEXSUX          148     24
    PRCSXL_SXLEXUCN           58      8
    PRCSXL_SXLEXUCSA          80      8
    PRCSXL_SXLEXUCSP          A0      8
    PRCSXL_SXLEXUCSS          A8      8
    PRCSXL_SXLEXUCSX          98      8
    PRCSXL_SXLEXUSO          110      8
    PRCSXL_SXLEXUTSP          D0      8
    PRCSXL_SXLEXUTSS          D8      8
    PRCSXL_SXLEXUTSX          C8      8
    PRCSXL_SXLEXUXO          128      8
    PRCSXL_SXLEXXUP          178     24
    PRCSXL_SXLEXXUS          190     24
    PRCSXL_SXLEXXUX          160     24
    PRCSXL_SXLFLAGS           21      1
    PRCSXL_SXLLKSEQ            9           80
    PRCSXL_SXLNIAI2            8           40
    PRCSXL_SXLNIAI4            8           20
    PRCSXL_SXLNIAI8            8           10
    PRCSXL_SXLPFD6             8           04
    PRCSXL_SXLPPA14            8           02
    PRCSXL_SXLPPA15            8           01
    PRCSXL_SXLTIME            24      8
    PRCSXL_SXLXLSQT            C      2
    PRCSXL_SXLXLSQTL           E      2

    This information is
    based on z/VM V7R2.0.

    Last updated on 09 August 2020 at 14:49:43.

    Copyright IBM Corporation, 1990, 2020