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.2.0 Last updated on 24 Jun 2020 at 09:28:15 EDT.
Copyright IBM Corporation, 1990, 2020