|
Programming Interface Information:
This information is NOT intended to be used as Programming Interfaces of z/VM. |
SYNBK
Control Block Contents
SYNBK 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. 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
Copyright IBM Corporation, 1990, 2007