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, 2009