Programming Interface Information:
This information is NOT intended to be
used as Programming Interfaces of z/VM.

SYNBK

Prolog  

Control Block Contents  
   SYNBK DSECT
   SYNBX DSECT
   SYNBXENT DSECT

Storage Layout  

Cross Reference (Contains links to field and bit definitions)  


SYNBK Prolog

 NAME       : HCPSYNBK
 DESCRIPTION: FORMAL SPIN LOCK CONTROL BLOCK
 DSECT      : SYNBK
 FUNCTION   : THIS DSECT DESCRIBES THE CONTROL AREA WHICH
              IS USED TO REPRESENT A SPIN LOCK.  IN GENERAL,
              THE SPIN LOCKS IN THE SYSTEM ARE PERMANENTLY
              IMBEDDED WITHIN OTHER CONTROL BLOCKS OR MODULES.
              THIS DSECT DESCRIBES COMMON FORMAT OF ALL SPIN
              LOCKS.
              A spin lock may be either exclusive-only or
              shared-exclusive.  An exclusive-only lock is
              mapped by the SYNBK DSECT.  A shared-exclusive lock
              is mapped by the SYNBK DSECT and by a contiguous
              extension mapped by the SYNBX DSECT.
              ALL SPIN LOCKS ARE OBTAINED THROUGH A STANDARD
              SYSTEM MACRO, WITH A CALL TO MODULE HCPSYN IF
              THE LOCK IS NOT OBTAINED IN-LINE TO THE REQUESTING
              CODE.
 LOCATED BY : THE SYNBK DESCRIBES ANY OF THE SEVERAL SPECIFIC SPIN
              LOCKS, THEREFORE LOCATING IT DEPENDS UPON LOCATING THE
              PARTICULAR SPIN LOCK OF INTEREST.  FOR EXAMPLE, THE
              SCHEDULER SPIN LOCK IS CODED IN THE SRMBK AS:
              SRMSLOCK DS    (SYNBKDSZ)D    SCHEDULER LOCK
 CREATED BY : GENERALLY THE SYNBK OF A SPIN LOCK IS:
              (1) HARD-CODED IN A MODULE AND THEREFORE GENERATED
              BY THE ASSEMBLER.  E.G., THE SWITCH-MASTER LOCK
              IN HCPMPF.
              (2) IMBEDDED IN A PERMANENTLY ALLOCATED CONTROL BLOCK.
              E.G., THE SCHEDULER LOCK IN THE SRMBK.
 DELETED BY : GENERALLY SYNBK'S ARE NOT DELETED SINCE THEY ARE GENERALLY
              IMBEDDED IN MODULES OR IN PERMANENTLY ALLOCATED CONTROL
              BLOCKS.
 RELOCATION CONSIDERATIONS : None
 NOTES      : OBTAINED BY -
              THE HCPSYNC MACRO (A 'PRIMITIVE').  HCPSYNC IS ALWAYS
              IMBEDDED FOR ACTUAL USE IN ANOTHER MACRO SUCH AS:
              HCPLKSCH  -  GET THE SCHEDULER LOCK.
              HCPLKSWM  -  GET THE SWITCH-MASTER LOCK.
              HCPLKSYN  -  USED BY OUT-OF-LINE CODE IN HCPSYN TO GET
              ANY SPIN LOCK IF IN-LINE ATTEMPT FAILS.
              RELEASED BY -
              THE HCPUSYNC MACRO (A 'PRIMITIVE').  HCPUSYNC IS ALWAYS
              IMBEDDED FOR ACTUAL USE IN ANOTHER MACRO SUCH AS:
              HCPULSCH  -  RELEASE THE SCHEDULER LOCK.
              HCPULSWM  -  RELEASE THE SWITCH-MASTER LOCK.
              Notes      :
              If the size of the SYNBK changes, the equate
              called SYNBKDSZ in HCPEQUAT must be changed to
              match the new size.  Similarly, if the size of
              the SYNBX changes, SYNBXDSZ in HCPEQUAT must be
              changed.
              A detailed explanation of formal spin locks is
              included in the prologue of HCPSYN.

 

SYNBK Control Block Content


SYNBK DSECT

Hex   Dec Type/Val   Lng Label (dup)    Comments
---- ---- --------- ---- -------------- --------
0000    0 Structure      SYNBK          FORMAL SPIN LOCK CONTROL BLOCK
        SYNLOCKD is the doubleword lock area.  There are
        various fields contained in this doubleword.  Block
        concurrent operations should be used to fetch and
        store this doubleword when more than one of those
        fields will be examined.  For example, to determine if
        the lock is currently held by this processor by
        checking both SYNSTATE and SYNHCPAD, this doubleword
        should be fetched with a block concurrent operation
        and then the two tests needed to verify both those
        conditions can be done on the fetched copy of the
        field.  This is necessary to ensure that those two
        fields are tested at the same instant.  If the state
        and holding CPU address are tested at different
        instants, it would be possible to see the state is
        held-exclusive but then the CPU address may have
        changed by the time that field is tested.  SYNHCPAD can
        change to either x'FFFF' or a CPU address (but not of
        this processor) during that window.
0000    0 Dbl-Word     8 SYNLOCKD       First doubleword of the lock
0000    0 Signed       4 SYNLOCKF       First fullword of the lock
       The order of the four 1-byte fields in SYNLOCKF is
       important.  Code in HCPSYN and the HCPSYNC and HCPUSYNC
       macros relies on this ordering.  The code in those parts
       is written for efficiency and would need to change if the
       positions of these fields are changed.
0000    0 Bitstring    1 SYNSTATE       Current state of this lock Note
                                        that SYNAVAIL and SYNAVLEX should
                                        not be changed to different
                                        values as composite tests that
                                        rely on these current values are
                                        done for the sake of efficiency.
                                        For efficiency in the lock
                                        macros, these states are used as
                                        unique bits. They are also used
                                        as codes because of the way that
                                        SYNAVAIL is defined. Due to this
                                        dual nature, care should be taken
                                        if more bits (or codes) are
                                        defined in SYNSTATE.
          00000000       SYNAVAIL       00 SYNAVAIL Lock is not held and
                                        it is available for acquisition
                                        by both shared and exclusive
                                        requests
          00000001       SYNAVLEX       01 SYNAVLEX Lock is not held and
                                        is only available for exclusive
                                        requests
          00000002       SYNAVLSH       02 SYNAVLSH Lock is not held and
                                        is only available for shared
                                        requests
          00000004       SYNHLDEX       04 SYNHLDEX Lock is held
                                        exclusive and the CPU addr of the
                                        holder is in the SYNHCPAD field
          00000008       SYNHLDSH       08 SYNHLDSH Lock is held shared
                                        and the count of processors
                                        holding shares is in the SYNSHCNT
                                        field
          0000000F       SYNSTATB       00002
                                        SYNAVAIL+SYNAVLEX+SYNAVLSH+SYNHLD
                                        EX+SYNHLDSH,2 This equate
                                        contains all the bits in SYNSTATE
                                        that are used to indicate the
                                        current state of the lock. It is
                                        used to clear the state to make
                                        it AVAILABLE
0001    1 Bitstring    1 SYNSHCNT       Share hold count...count of CPUs
                                        currently holding a share of this
                                        lock
0002    2 Bitstring    1 SYNXWCNT       Exclusive wait count ... count of
                                        CPUs currently waiting for this
                                        lock in exclusive mode. This
                                        field is always zero if the lock
                                        can only be obtained exclusive
                                        (CANSHARE=NO on its
                                        HCPSYNC/HCPUSYNC invocations)
0003    3 Bitstring    1 SYNSWCNT       Shared wait count ... count of
                                        CPUs currently waiting for a
                                        share of this lock. This field is
                                        always zero if the lock can only
                                        be obtained exclusive
                                        (CANSHARE=NO on its
                                        HCPSYNC/HCPUSYNC invocations)
0004    4 Signed       2 SYNSEQ         Sequence number for serializing
                                        acquisition of this lock. This is
                                        incremented by one each time the
                                        lock is released from exclusive
                                        mode. This field is always zero
                                        if the lock can only be obtained
                                        exclusive (CANSHARE=NO on its
                                        HCPSYNC/HCPUSYNC invocations)
       WARNING:  Most locks are initialized to all zeroes when
                 defined.  This means that initially, SYNHCPAD
                 is zeroes, not x'FFFF'.  HCPSYNC, HCPOBTN, and
                 HCPSYN have been coded to be able to handle
                 this.  Therefore, once the lock has been
                 released once (and any subsequent time that it
                 is not HELD-EXCLUSIVE) SYNHCPAD will be x'FFFF'.
                 However, any code that expects to compare
                 SYNHCPAD and PFXCPUAD to determine if a
                 particular CPU holds a lock must be careful,
                 as seeing zeroes in SYNHCPAD could be mistaken
                 as the lock being held by CPU 0.  The code must
                 either ensure that the lock is initialized
                 specially to have SYNHCPAD set to x'FFFF', or
                 must first test SYNSTATE to verify that the
                 lock is indeed HELD-EXCLUSIVE, before checking
                 SYNHCPAD to see if a particular CPU holds the
                 lock.
0006    6 Signed       2 SYNHCPAD       CPU addr of lock holder when it
                                        is held in exclusive mode. Set to
                                        x'FFFF' when not held exclusive
0008    8 Signed       4 SYNHOLDR       Address of holder of this lock if
                                        it is held in exclusive mode. See
                                        SYNPLSDS for address of the
                                        holder when it is held shared
000C   12 Signed       2 SYNPLSDS       For shared locks, displacement
                                        into the PLSBK of the fullword
                                        field that contains the address
                                        of the code that holds a share of
                                        this lock for this processor.
                                        This field must be filled in when
                                        the lock area is obtained or at
                                        CP initialization
000E   14 Bitstring    1 SYNFLAG1       Flag containing info about lock
          1... ....      SYNCANSH       x'80' SYNCANSH This lock can be
                                        held shared
000F   15 Bitstring    1 *              Reserved for future IBM use
0010   16 Signed       4 SYNXSCNT       Exclusive spin count ... number
                                        of times to the formal spin lock
                                        manager when attempting to get
                                        this lock in exclusive mode
0014   20 Signed       4 SYNSSCNT       Share spin count ... number of
                                        times to the formal spin lock
                                        manager when attempting to get a
                                        share of the lock
0018   24 Dbl-Word     8 SYNXTIME       Total elapsed wall-clock spin
                                        time on this lock when attempting
                                        to get it in exclusive mode,
                                        starting at zero and counting up
0020   32 Dbl-Word     8 SYNSTIME       Total elapsed wall-clock spin
                                        time on this lock when attempting
                                        to get a share, starting at zero
                                        and counting up
0028   40 Dbl-Word     8 *              Reserved for future IBM use
          00000030       SYNBKEXT       *
          00000006       SYNSIZE        (*-SYNBK+7)/8 SYNBK size in
                                        doublewords which should be
                                        changed with care as it is
                                        imbedded in other control blocks
                                        and code.
      Extension of SYNBK used for spin locks capable of shared
      as well as exclusive access.  These entries represent the
      states of the CPUs that either hold or are waiting for
      this lock.  SYNBX contains four entries, one for each
      potential state that a CPU can be in with respect to the
      lock.  That is, it is either waiting for shared or
      exclusive access or holding it in one of those two modes.
      Each entry is mapped by the SYNBXENT DSECT.

SYNBX DSECT

Hex   Dec Type/Val   Lng Label (dup)    Comments
---- ---- --------- ---- -------------- --------
0000    0 Structure      SYNBX          FORMAL SPIN LOCK CONTROL BLOCK
0000    0 Bitstring   24 SYNBXW4S       Waiting for a share entry
0018   24 Bitstring   24 SYNBXHLS       Held shared entry
0030   48 Bitstring   24 SYNBXW4X       Waiting for exclusive entry
0048   72 Bitstring   24 SYNBXHLX       Held exclusive entry
          00000060       SYNBXBSZ       *-SYNBX Size of SYNBK extension
                                        in bytes
          0000000C       SYNBXDWS       (*-SYNBX+7)/8 Size of SYNBK
                                        extension in DWs
      Mapping of each of the four elements in the SYNBX.

SYNBXENT DSECT

Hex   Dec Type/Val   Lng Label (dup)    Comments
---- ---- --------- ---- -------------- --------
0000    0 Structure      SYNBXENT       FORMAL SPIN LOCK CONTROL BLOCK
0000    0 Dbl-Word     8 SYNBXMSK       CPU bit mask representing CPUs in
                                        the associated state (not used
                                        for SYNBXHLX)
0008    8 Signed       4 SYNBXATT       Count of attempts to identify a
                                        diagnose x'9C' target
000C   12 Signed       4 SYNBXFTG       Count of times target was found
0010   16 Signed       4 SYNBXPTC       Count of potential targets
                                        considered (for which a SIGP SRS
                                        was performed)
0014   20 Signed       4 *              Reserved for future IBM use
          00000018       SYNBXELN       *-SYNBXENT Size of an entry in
                                        bytes

 

SYNBK Storage Layout

          
*** SYNBK - FORMAL SPIN LOCK CONTROL BLOCK
*
*     +-------------------------------------------------------+
*   0 |                       SYNLOCKD                        |
*     +-------------------------------------------------------+
*   8
*
*** SYNBK - FORMAL SPIN LOCK CONTROL BLOCK
          
*** Overlay for SYNLOCKD in SYNBK
*
*     +---------------------------+
*   0 |         SYNLOCKF          | 4
*     +---------------------------+
*
*** Overlay for SYNLOCKD in SYNBK
          
*** Overlay for SYNLOCKD in SYNBK
*
*     +------+------+------+------+-------------+-------------+
*   0 |:STATE|:SHCNT|:XWCNT|:SWCNT|   SYNSEQ    |  SYNHCPAD   |
*     +------+------+------+------+-------------+------+------+
*   8 |         SYNHOLDR          |  SYNPLSDS   |:FLAG1|//////|
*     +---------------------------+-------------+------+------+
*  10 |         SYNXSCNT          |         SYNSSCNT          |
*     +---------------------------+---------------------------+
*  18 |                       SYNXTIME                        |
*     +-------------------------------------------------------+
*  20 |                       SYNSTIME                        |
*     +-------------------------------------------------------+
*  28 |///////////////////////////////////////////////////////|
*     +-------------------------------------------------------+
*  30
*
*** Overlay for SYNLOCKD in SYNBK
          
*** SYNBX - FORMAL SPIN LOCK CONTROL BLOCK
*
*     +-------------------------------------------------------+
*   0 |                                                       |
*     =                       SYNBXW4S                        =
*     |                                                       |
*     +-------------------------------------------------------+
*  18 |                                                       |
*     =                       SYNBXHLS                        =
*     |                                                       |
*     +-------------------------------------------------------+
*  30 |                                                       |
*     =                       SYNBXW4X                        =
*     |                                                       |
*     +-------------------------------------------------------+
*  48 |                                                       |
*     =                       SYNBXHLX                        =
*     |                                                       |
*     +-------------------------------------------------------+
*  60
*
*** SYNBX - FORMAL SPIN LOCK CONTROL BLOCK
          
*** SYNBXENT - FORMAL SPIN LOCK CONTROL BLOCK
*
*     +-------------------------------------------------------+
*   0 |                       SYNBXMSK                        |
*     +---------------------------+---------------------------+
*   8 |         SYNBXATT          |         SYNBXFTG          |
*     +---------------------------+---------------------------+
*  10 |         SYNBXPTC          |///////////////////////////|
*     +---------------------------+---------------------------+
*  18
*
*** SYNBXENT - FORMAL SPIN LOCK CONTROL BLOCK

 

SYNBK Cross Reference

Symbol         Dspl Value
-------------- ---- -----
SYNAVAIL       0000 00000000
SYNAVLEX       0000 00000001
SYNAVLSH       0000 00000002
SYNBKEXT       0028 00000030
SYNBXATT       0008
SYNBXBSZ       0048 00000060
SYNBXDWS       0048 0000000C
SYNBXELN       0014 00000018
SYNBXFTG       000C
SYNBXHLS       0018
SYNBXHLX       0048
SYNBXMSK       0000
SYNBXPTC       0010
SYNBXW4S       0000
SYNBXW4X       0030
SYNCANSH       000E 80
SYNFLAG1       000E
SYNHCPAD       0006
SYNHLDEX       0000 00000004
SYNHLDSH       0000 00000008
SYNHOLDR       0008
SYNLOCKD       0000
SYNLOCKF       0000
SYNPLSDS       000C
SYNSEQ         0004
SYNSHCNT       0001
SYNSIZE        0028 00000006
SYNSSCNT       0014
SYNSTATB       0000 0000000F
SYNSTATE       0000
SYNSTIME       0020
SYNSWCNT       0003
SYNXSCNT       0010
SYNXTIME       0018
SYNXWCNT       0002

This information is based on z/VM V6R2.0. Last updated on 21 Nov 2011 at 11:25:52 EDT.
Copyright IBM Corporation, 1990, 2011