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

SYNBK

Prolog  

Control Block Contents  
   SYNBK 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.  THE LOCK IS ALWAYS 6 DOUBLE-WORDS.
              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.
 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 this control block changes, the
              equate called SYNBKDSZ in HCPEQUAT must be
              changed to match the new size.
              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
          00000006       SYNSIZE        (*-SYNBK+7)/8 SYNBK size in
                                        doublewords which must be 6
                                        doubelwords since it is imbedded
                                        in other control blocks and code.

 

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

 

SYNBK Cross Reference

Symbol         Dspl Value
-------------- ---- -----
SYNAVAIL       0000 00000000
SYNAVLEX       0000 00000001
SYNAVLSH       0000 00000002
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 V5R3.0. Last updated on 25 Jun 2007 at 17:40:38 EDT.
Copyright IBM Corporation, 1990, 2007