NAME       : HCPSYNBK
 DESCRIPTION: Formal exclusive-only spinlock 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 formal
              exclusive-only spinlocks.
              For shared-exclusive spinlocks see HCPSXLBK COPY.
              All exclusive-only spinlocks are obtained using
              standard macros, with a call to module HCPSYN is
              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
              TRQBK Queue SPIN LOCK IS CODED IN HCPTRQ AS:
              HCPTRQLK DS    (SYNBKDSZ)D    TRQBK queue 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 ATOD 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:
              HCPLKTRQ  -  Get the TRQBK queue lock.
              HCPLKSWM  -  GET THE SWITCH-MASTER LOCK.
              RELEASED BY -
              THE HCPUSYNC MACRO (A 'PRIMITIVE').  HCPUSYNC IS ALWAYS
              IMBEDDED FOR ACTUAL USE IN ANOTHER MACRO SUCH AS:
              HCPULTRQ  -  Release the TRQBK queue 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.
              A detailed explanation of formal exclusive-only
              spinlocks is included in the prologue of HCPSYN.
              For shared-exclusive spinlocks see HCPSXL.

 SYNBK DSECT
Top of page

Hex   Dec Type/Val   Lng Label (dup)    Comments
---- ---- --------- ---- -------------- --------
0000    0 Structure      SYNBK          Formal exclusive-only spinlock 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
          .... ....      SYNINITF       X'00000000' SYNINITF
                                        Uninitialized SYNLOCKF value
                                        prior to first acquisition.
          SYNLOCKF       SYNAVALF       X'0000FFFF' SYNAVALF Available
                                        SYNLOCKF value after the first
                                        acquisition.
       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
          00000080       SYNEXCL        X'80' SYNEXCL Exclusive held.
          00000000       SYNAVAIL       X'00' SYNAVAIL Available.
0001    1 Bitstring    1 *              Reserved for IBM use.
       WARNING:  Most locks are initialized to all zeroes when
                 defined.  This means that initially, SYNHCPAD
                 is zeroes, not x'FFFF'.  HCPSYNC and HCPOBTN
                 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.
0002    2 Signed       2 SYNHCPAD       CPU addr of lock holder when it
                                        is held in exclusive mode. Set to
                                        x'FFFF' when not held exclusive
          0000FFFF       SYNNOCPU       X'FFFF' Indicates no CPU holds
                                        the lock after first acquisition.
0004    4 Signed       4 SYNHOLDR       Address of holder of this lock if
                                        it is held in exclusive mode.
0008    8 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
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 SYNCADEX       Count of CAD instructions for
                                        exclusive lock requests
0018   24 Dbl-Word     8 * (3)          Reserved for IBM use.
          00000030       SYNBKEND       * End of SYNBK.
          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.

          
*** SYNBK - Formal exclusive-only spinlock block
*
*     +-------------------------------------------------------+
*   0 |                       SYNLOCKD                        |
*     +-------------------------------------------------------+
*   8
*
*** SYNBK - Formal exclusive-only spinlock block
          
*** Overlay for SYNLOCKD in SYNBK
*
*     +---------------------------+
*   0 |         SYNLOCKF          | 4
*     +---------------------------+
*
*** Overlay for SYNLOCKD in SYNBK
          
*** Overlay for SYNLOCKD in SYNBK
*
*     +------+------+-------------+---------------------------+
*   0 |:STATE|//////|  SYNHCPAD   |         SYNHOLDR          |
*     +------+------+-------------+---------------------------+
*   8 |                       SYNXTIME                        |
*     +---------------------------+---------------------------+
*  10 |         SYNXSCNT          |         SYNCADEX          |
*     +---------------------------+---------------------------+
*  18 |///////////////////////////////////////////////////////|
*     =///////////////////////////////////////////////////////=
*     |///////////////////////////////////////////////////////|
*     +-------------------------------------------------------+
*  30
*
*** Overlay for SYNLOCKD in SYNBK

 
Symbol         Dspl Value
-------------- ---- -----
SYNAVAIL       0000 00000000
SYNAVALF       0000 SYNLOCKF
SYNBKEND       0018 00000030
SYNCADEX       0014
SYNEXCL        0000 00000080
SYNHCPAD       0002
SYNHOLDR       0004
SYNINITF       0000 00
SYNLOCKD       0000
SYNLOCKF       0000
SYNNOCPU       0002 0000FFFF
SYNSIZE        0018 00000006
SYNSTATE       0000
SYNXSCNT       0010
SYNXTIME       0008