|
Programming Interface Information:
This information is NOT intended to be used as Programming Interfaces of z/VM. |
FREBK
Control Block Contents
FREBK DSECT
Cross Reference (Contains links to field and bit definitions)
FREBK Prolog
NAME : HCPFREBK
DESCRIPTION: FREE STORAGE BLOCK
DSECT : FREBK
FUNCTION :
MAPS A FREE STORAGE BLOCK HEADER AND TRAILER
FOR BOTH ACTIVE AND INACTIVE FREE STORAGE BLOCKS.
CREATED BY : HCPFREE OR HCPFREVM WHEN A BLOCK IS
REQUESTED. THIS BLOCK IS NEVER ALLOCATED
AS A SEPARATE BLOCK.
DELETED BY : HCPFRET WHEN A BLOCK IS RETURNED TO
FREE STORAGE. THIS BLOCK IS NEVER
DEALLOCATED AS A SEPARATE BLOCK.
SERIALIZED :
IT IS THE RESPONSIBILITY OF THE REQUESTOR TO
ENSURE THAT ACCESS TO THE FREE STORAGE BLOCK IS
SERIALIZED.
NOTES : WHEN A FREE STORAGE BLOCK IS ISSUED TO SATISFY A
FREE STORAGE REQUEST, THE FREE STORAGE MANAGER
PLACES A ONE DOUBLEWORD HEADER AND A TWO
DOUBLEWORD TRAILER AROUND THE BLOCK. THESE AREAS
ARE USED FOR DEBUGGING PURPOSES.
WHEN THE BLOCK IS RETURNED, THESE AREAS ARE
EXAMINED. IF EITHER OR BOTH HAVE BEEN CORRUPTED, AN
ABEND IS ISSUED.
FREBK Control Block Content
FREBK DSECT
Hex Dec Type/Val Lng Label (dup) Comments
---- ---- --------- ---- -------------- --------
0000 0 Structure FREBK FREE STORAGE BLOCK
This is a picture of how the fields in this DSECT are actually used:
+----------------------------------------------------+
0 | FREHEADR |
+----------------------------------------------------+
8 : :
: (control block) :
: :
+----------------------------------------------------+
xx | FRETRALR |
| |
+----------------------------------------------------+
xx+10
The free storage header (FREHEADR) and free storage trailer (FRETRALR)
areas are maintained both for internal functional uses and as debugging
aids for free storage related problems. The free storage header
immediately precedes the start of the free storage block returned in
response to an obtain free storage request (HCPGETST). The trailer,
when present (which is always, except for Fast Allocated Blocks),
follows the end of the free storage requested by the caller (there may
be a gap between the end of the size of block requested by the caller
and the free storage trailer, as we round the requested size up to a
convenient boundary in certain cases). The exact format and content of
these fields depends on the type of free storage being used and whether
the free storage block is active or inactive:
+- free storage block itself in here
|
V
<----FREHEADR-----> <-------------FRETRALR-------------->
Normal (non-subpooled) and V=R (subpooled) free storage:
In use (for undefined blocks, cbi == '<<<') +--------+--------+
+--------+--------+--------+--------+ |0000rqsz| >>>> |-| >>> |-| <--obtainer->|
Normal subpooled (non-FAB, non-V=R) free storage:
In use (normal): +--------+--------+
+--------+--------+--------+--------+ | >> rqsz|1 subbk@|-| > rqsz|0 subbk@|-| <--obtainer->|
Available (on collection pile): +--------+--------+
+--------+--------+--------+--------+ | fpnt |0 subbk@|-| <--obtainer->|
Fast Allocated Block free storage:
In use (normal): +--------+--------+
+--------+--------+--------+--------+ |sli 0FAB|1
subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx| +--------+--------+
+--------+--------+--------+--------+
In use (flagged for collection pile): +--------+--------+
+--------+--------+--------+--------+ |sli 0FAB|0
subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx| +--------+--------+
+--------+--------+--------+--------+
Available (normal): +--------+--------+
+--------+--------+--------+--------+ | fpnt |1
subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx| +--------+--------+
+--------+--------+--------+--------+
Available (on collection pile): +--------+--------+
+--------+--------+--------+--------+ | fpnt |0
subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx| +--------+--------+
+--------+--------+--------+--------+
Notes : Free storage trailer not maintained and is unreliable for Fast
Allocated Blocks!
0000 0 Dbl-Word 8 FRESTRT (0) START OF VARIABLE LENGTH DATA
0000 0 Dbl-Word 8 FREHEADR FREE STORAGE BLOCK HEADER
00000008 FREHEADL *-FREHEADR LENGTH OF HEADER IN
BYTES
0000 0 Dbl-Word 8 FRETRALR (2) FREE STORAGE BLOCK TRAILER
00000010 FRETRALL *-FRETRALR LENGTH OF TRAILER IN
BYTES
00000003 FRERECL (FREHEADL+FRETRALL+7)/8 SIZE IN
DOUBLE WORDS
0000 0 Signed 4 FREESIZE (0) # OF DWORDS OF STORAGE REQUESTED
0000 0 Signed 2 FREHSPSE (0) Mini-eyecatcher for non-FAB SPS,
0 for normal non-subpooled free
storage, or SLI for FAB SPS:
0000 0 Signed 2 FREHFSLI System Location Identifier (SLI)
for Fast Allocated Block
subpooled free storage
0002 2 Signed 2 FREHSIZE Actual count of DWs requested
Notes : The maximum allowable size value for FREESIZE / FREHSIZE is the
number of doublewords which can fit into a single 4K page (not counting
the free storage header and trailer), or 509 doublewords, x'1FD' for
everything other than Fast Allocate Blocks. Since the trailer is not
maintained and may not even exist for Fast Allocated Blocks, the
maximum allowable size is 511 doublewords, x'1FF'. For normal
non-subpooled free storage, and for V=R free storage (which is
subpooled, but the "old way"), the high order halfword of FREESIZE (aka
FREHSPSE) must be zero; for normal (non-FAB, non-V=R) subpooled free
storage, FREHSPSE contains the mini- eyecatcher '>>' == x'6E6E'.
For Fast Allocated Block subpooled free storage, FREHSPSE contains the
System Location Identifier (SLI) number, which identifies where in the
system the block was obtained.
A FREHSIZE value of x'FAB' in active subpooled free storage blocks is
not a size, but is used to indicate that the block is an active "fast
allocated block".
0004 4 Signed 4 FRESUBBK (0) Address of SUBBK for subpool blk
The high order bit of FRESUBBK is
normally 1, and is set to 0 by
garbage collection (HCPFRFDX) to
indicate that the block should be
queued on the collection pile
when freed (to attempt to reclaim
the frame)
0004 4 Character 4 FREESFLG ALLOCATED BLOCK CHARACTER STRI
Note that the free storage trailer is not maintained, and is therefore
unreliable for Fast Allocated Blocks.
0000 0 Character 4 FREEID CONTROL BLOCK'S IDENTIFIER (THE
FIRST CHARACTER IS '<', AND
THE ID FOR UNDEFINED BLOCKS IS
'<<<<' )
0004 4 Signed 4 FREFSCBK (0) Addr of storage obtainers FSCBK
0004 4 Character 4 FREEEFLG CHARACTER STRING '<<<
0008 8 Signed 4 FREEDISP REQUEST'S OFFSET IN CALLING
MODULE (1ST HALF WORD = X'00 00')
000C 12 Character 4 FREEMOD MODULE ID OF CALLING MODULE THE
FIRST BYTE'S ALWAYS SET TO 0
0000 0 Signed 4 FREEPNT PNTR TO NEXT BLOCK IN FREE
STORAGE CHAIN OR 0 (IF
END-OF-CHAIN)
0004 4 Signed 4 FRETSIZE Size of available block in DWs or
the size in bytes for a larger
than subpool size block that is
on the free storage chain
Notes : For for subpooled free storage, FRETSIZE as such is not used.
Instead the address of the SUBBK which represents this subpool remains
here in the second word of the free storage header (as field FRESUBBK).
Since the maximum allowable value for FRETSIZE for normal (non-FAB)
free storage is 509 (x'1FD'), any larger value in this field indicates
that the block in question is in a frame used for subpooled free
storage (since SUBBKs can't reside in low prefix page addresses like
x'1FD' and below). However, in order to use this fact to distinguish
between types, caution must be used, since the high order bit of the
SUBBK address is used as a free storage garbage collection flag.
Also note that in *active* subpooled free storage blocks, a value of
x'FAB' in the actual requested size in dws (in FREHSIZE) is not a size,
but an indicator that the block is an active "fast allocated block"
(the requested size is not kept for fast allocated blocks, we know the
actual size allocated because we know which subpool it's from).
Note that the free storage trailer is not maintained, and may not even
exist in some cases, and is therefore unreliable for available blocks
that were last used as Fast Allocated Blocks.
0000 0 Character 4 FRETID CONTROL BLOCK'S IDENTIFIER (THE
FIRST CHARACTER IS '<', AND
THE ID FOR UNDEFINED BLOCKS IS
'<<<<' ) THIS FIELD
IS PRESERVED FROM THE HCPFREE
CALL WHICH ORIGINALLY OBTAINED
THIS CONTROL BLOCK
0004 4 Character 4 FRETMOD MODID OF HCPFRET CALLER THE FIRST
BYTE'S ALWAYS SET TO 0
0008 8 Signed 2 FRETDISP DISPL INTO MODID OF HCPFRET CALL
000A 10 Bitstring 1 FREECALL (6) LOW-ORDER 2 BYTES OF "FREEDISP"
AND "FREEMOD PRESERVED FROM THE
HCPFREE CALL WHICH ORIGINALLY
OBTAINED THIS CONTROL BLOCK
FREBK Storage Layout
*** FREBK - FREE STORAGE BLOCK
*
*
*** FREBK - FREE STORAGE BLOCK
*** Overlay for FRESTRT in FREBK
*
* +-------------------------------------------------------+
* 0 | FREHEADR |
* +-------------------------------------------------------+
* 8
*
*** Overlay for FRESTRT in FREBK
*** Overlay for FRESTRT in FREBK
*
* +-------------------------------------------------------+
* 0 | FRETRALR |
* | |
* +-------------------------------------------------------+
* 10
*
*** Overlay for FRESTRT in FREBK
*** Overlay for FREHEADR in FREBK
*
* +-------------+-------------+---------------------------+
* 0 | FREHFSLI | FREHSIZE | FREESFLG |
* +-------------+-------------+---------------------------+
* 8
*
*** Overlay for FREHEADR in FREBK
*** Overlay for FRETRALR in FREBK
*
* +---------------------------+---------------------------+
* 0 | FREEID | FREEEFLG |
* +---------------------------+---------------------------+
* 8 | FREEDISP | FREEMOD |
* +---------------------------+---------------------------+
* 10
*
*** Overlay for FRETRALR in FREBK
*** Overlay for FREHEADR in FREBK
*
* +---------------------------+---------------------------+
* 0 | FREEPNT | FRETSIZE |
* +---------------------------+---------------------------+
* 8
*
*** Overlay for FREHEADR in FREBK
*** Overlay for FRETRALR in FREBK
*
* +---------------------------+---------------------------+
* 0 | FRETID | FRETMOD |
* +-------------+-------------+---------------------------+
* 8 | FRETDISP | FREECALL |
* +-------------+-----------------------------------------+
* 10
*
*** Overlay for FRETRALR in FREBK
FREBK Cross Reference
Symbol Dspl Value -------------- ---- ----- FREECALL 000A FREEDISP 0008 FREEEFLG 0004 FREEID 0000 FREEMOD 000C FREEPNT 0000 FREESFLG 0004 FREESIZE 0000 FREFSCBK 0004 FREHEADL 0000 00000008 FREHEADR 0000 FREHFSLI 0000 FREHSIZE 0002 FREHSPSE 0000 FRERECL 0000 00000003 FRESTRT 0000 FRESUBBK 0004 FRETDISP 0008 FRETID 0000 FRETMOD 0004 FRETRALL 0000 00000010 FRETRALR 0000 FRETSIZE 0004
Copyright IBM Corporation, 1990, 2002