SYNBK Back to Index page
 
Prolog 
Control Block Contents 
   SYNBK DSECT
Storage Layout 
Cross Reference (Contains links to field and bit definitions)
Programming Interface Information:
This information is NOT intended to be
used as Programming Interfaces of z/VM.


  SYNBK Prolog Top of page
 
 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 Control Block Content Top of page
 

 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 Storage Layout Top of page
 
          
*** 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
 
 
  SYNBK Cross Reference Top of page
 
 
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
 
This information is based on z/VM 7.3.0 Last updated on 22 Jun 2022 at 15:56:46 EDT.
Copyright IBM Corporation, 1990, 2022