FREBK Back to Index page
 
Prolog 
Control Block Contents 
   FREBK 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.


  FREBK Prolog Top of page
 
 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.
 RELOCATION CONSIDERATIONS : None
 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 Top of page
 

 FREBK DSECT Top of page
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): In use (for undefined blocks, cbi == '<<<') +--------+--------+ +--------+--------+--------+--------+ |0000rqsz| >>>> |-| >>> |-| <--obtainer->| Normal subpooled (non-FAB) 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 normal non-subpooled free storage, the high order halfword of FREESIZE (aka FREHSPSE) must be zero; for normal (non-FAB) subpooled free stg, FREHSPSE has 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 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 Top of page
 
          
*** 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 Top of page
 
 
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
 
This information is based on z/VM 7.3.0 Last updated on 22 Jun 2022 at 15:50:34 EDT.
Copyright IBM Corporation, 1990, 2022