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.2.0 Last updated on 24 Jun 2020 at 09:31:01 EDT.
Copyright IBM Corporation, 1990, 2020