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 V6R1.0. Last updated on 18 Feb 2010 at 09:14:43 EDT.
Copyright IBM Corporation, 1990, 2008