|
Programming Interface Information:
This information is NOT intended to be used as Programming Interfaces of z/VM. |
SYNBK
Control Block Contents
SYNBK DSECT
SYNBX DSECT
SYNBXENT DSECT
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.
A spin lock may be either exclusive-only or
shared-exclusive. An exclusive-only lock is
mapped by the SYNBK DSECT. A shared-exclusive lock
is mapped by the SYNBK DSECT and by a contiguous
extension mapped by the SYNBX DSECT.
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.
RELOCATION CONSIDERATIONS : None
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 the SYNBK changes, the equate
called SYNBKDSZ in HCPEQUAT must be changed to
match the new size. Similarly, if the size of
the SYNBX changes, SYNBXDSZ in HCPEQUAT must be
changed.
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
00000030 SYNBKEXT *
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.
Extension of SYNBK used for spin locks capable of shared
as well as exclusive access. These entries represent the
states of the CPUs that either hold or are waiting for
this lock. SYNBX contains four entries, one for each
potential state that a CPU can be in with respect to the
lock. That is, it is either waiting for shared or
exclusive access or holding it in one of those two modes.
Each entry is mapped by the SYNBXENT DSECT.
SYNBX DSECT
Hex Dec Type/Val Lng Label (dup) Comments ---- ---- --------- ---- -------------- -------- 0000 0 Structure SYNBX FORMAL SPIN LOCK CONTROL BLOCK 0000 0 Bitstring 24 SYNBXW4S Waiting for a share entry 0018 24 Bitstring 24 SYNBXHLS Held shared entry 0030 48 Bitstring 24 SYNBXW4X Waiting for exclusive entry 0048 72 Bitstring 24 SYNBXHLX Held exclusive entry 00000060 SYNBXBSZ *-SYNBX Size of SYNBK extension in bytes 0000000C SYNBXDWS (*-SYNBX+7)/8 Size of SYNBK extension in DWs Mapping of each of the four elements in the SYNBX.
SYNBXENT DSECT
Hex Dec Type/Val Lng Label (dup) Comments ---- ---- --------- ---- -------------- -------- 0000 0 Structure SYNBXENT FORMAL SPIN LOCK CONTROL BLOCK 0000 0 Dbl-Word 8 SYNBXMSK CPU bit mask representing CPUs in the associated state (not used for SYNBXHLX) 0008 8 Signed 4 SYNBXATT Count of attempts to identify a diagnose x'9C' target 000C 12 Signed 4 SYNBXFTG Count of times target was found 0010 16 Signed 4 SYNBXPTC Count of potential targets considered (for which a SIGP SRS was performed) 0014 20 Signed 4 * Reserved for future IBM use 00000018 SYNBXELN *-SYNBXENT Size of an entry in bytes
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
*** SYNBX - FORMAL SPIN LOCK CONTROL BLOCK
*
* +-------------------------------------------------------+
* 0 | |
* = SYNBXW4S =
* | |
* +-------------------------------------------------------+
* 18 | |
* = SYNBXHLS =
* | |
* +-------------------------------------------------------+
* 30 | |
* = SYNBXW4X =
* | |
* +-------------------------------------------------------+
* 48 | |
* = SYNBXHLX =
* | |
* +-------------------------------------------------------+
* 60
*
*** SYNBX - FORMAL SPIN LOCK CONTROL BLOCK
*** SYNBXENT - FORMAL SPIN LOCK CONTROL BLOCK
*
* +-------------------------------------------------------+
* 0 | SYNBXMSK |
* +---------------------------+---------------------------+
* 8 | SYNBXATT | SYNBXFTG |
* +---------------------------+---------------------------+
* 10 | SYNBXPTC |///////////////////////////|
* +---------------------------+---------------------------+
* 18
*
*** SYNBXENT - FORMAL SPIN LOCK CONTROL BLOCK
SYNBK Cross Reference
Symbol Dspl Value -------------- ---- ----- SYNAVAIL 0000 00000000 SYNAVLEX 0000 00000001 SYNAVLSH 0000 00000002 SYNBKEXT 0028 00000030 SYNBXATT 0008 SYNBXBSZ 0048 00000060 SYNBXDWS 0048 0000000C SYNBXELN 0014 00000018 SYNBXFTG 000C SYNBXHLS 0018 SYNBXHLX 0048 SYNBXMSK 0000 SYNBXPTC 0010 SYNBXW4S 0000 SYNBXW4X 0030 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
Copyright IBM Corporation, 1990, 2011