TOPBK | Back to Index page

| Prolog Control Block Contents TOPBK 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.

TOPBK Prolog | Top of page

     NAME       : HCPTOPBK
     DESCRIPTION: CPU Topology Block
     DSECT      : TOPBK
     FUNCTION   : The CPU Topology block is a data structure used to form
                  a tree that represents the cache structure of the real
                  hardware.  This tree will be used to help minimize
                  dispatcher stealing between CPUs that do not share cache
                  and to allow for more intelligent workload balancing.
     LOCATED BY : HCPDSVTO, DSVTOPBK, TOPPARNT, TOPCHILD, TOPSIBLG, TOPLVLFP
                  RCCTOPBF, RCCTOPCU
     CREATED BY : HCPHIPPT (all TOPBKs are pre-allocated during
                  initialization)
     DELETED BY : TOPBKs are never released, once pre-allocated
     REFERENCES : None
     SERIALIZED : Topology Lock (HCPDSVTL).  The code which updates
                  the topology tree (HCPHIPRT) also holds the scheduler
                  lock and vary processor lock, so these may be
                  sufficient to prevent changes to the topology tree, but
                  the topology lock is preferred.  See the module prolog
                  in HCPHIP for additional serialization discussion.
     RELOCATION CONSIDERATIONS : None
     COMPATIBILITY AND MIGRATION CONCERNS : None

TOPBK Control Block Content | Top of page

     TOPBK DSECT
    Top of page

    Hex   Dec Type/Val   Lng Label (dup)    Comments
    ---- ---- --------- ---- -------------- --------
    0000    0 Structure      TOPBK          CPU Topology Block
    0000    0 Address      4 TOPPARNT       Pointer to parent TOPBK (or zero
                                            if this is the top level TOPBK
    0004    4 Address      4 TOPCHILD       Pointer to first child TOPBK of
                                            this TOPBK (or zero if this is
                                            the lowest level TOPBK)
    0008    8 Address      4 TOPSIBLG       Pointer to the next sibling
                                            TOPBK. TOPSIBLG pointers form a
                                            circular singly- linked list of
                                            sibling TOPBKs. Siblings are
                                            TOPBKs at the same nest level
                                            (TOPNL) which have the same
                                            parent TOPBK (TOPPARNT).
    000C   12 Bitstring    1 TOPNL          Nest level. Corresponds to the
                                            nest level field in
                                            containter-type TLEs in the STSI
                                            15.1.x response. Values range
                                            between 1 and x-1.
    000D   13 Bitstring    1 TOPCNTID       Container ID. This field
                                            corresponds to the container ID
                                            found in the STSI 15.1.x response
                                            for container-type TLEs.
    000E   14 Bitstring    2 *              Reserved
    0010   16 Bitstring   64 TOPCPUMK       Mask of CPUs defined to be in
                                            this branch of the topology tree.
                                            This mask is derived from the
                                            STSI 15.1.x response.
    0050   80 Bitstring   64 TOPASSOC       Mask of CPUs associated with this
                                            TOPBK. If this is the lowest
                                            level TOPBK, this mask is the OR
                                            of all DSVASSOC for all DSVBKs in
                                            the TOPDSVBK list. If this is not
                                            the lowest level TOPBK, this is
                                            the OR of all TOPASSOC for all
                                            children TOPBKs. Notes : TOPASSOC
                                            may differ from TOPCPUMK if there
                                            are CPUs that are configured in
                                            the partition, but not associated
                                            with DSVBKs. However, usually
                                            TOPASSOC and TOPCPUMK will be
                                            identical. The times when they do
                                            not match are in the middle of a
                                            topology change, or if a CPU is
                                            logically offline.
    0090  144 Bitstring   64 TOPUNPRK       Mask of associated CPUs which are
                                            currently in the unparked state.
                                            If this is an NL=1 TOPBK, this is
                                            the OR of all DSVUNPRK for all
                                            DSVBKs in the TOPDSVBK lists. If
                                            NL>1, this is the OR of all
                                            TOPUNPRK for all children TOPBKs.
    00D0  208 Bitstring   64 TOPCPUPL (0)   Array of CPU masks indexed by
                                            polarization value
    00D0  208 Bitstring   64 TOPCPUHZ       Mask of horizontal CPUs
    0110  272 Bitstring   64 TOPCPUVL       Mask of vertical low CPUs
    0150  336 Bitstring   64 TOPCPUVM       Mask of vertical medium CPUs
    0190  400 Bitstring   64 TOPCPUVH       Mask of vertical high CPUs
    01D0  464 Address      4 TOPDSVBK (0)   Table of pointers to the first
                                            DSVBK which contains CPUs of the
                                            same type, corresponding to this
                                            lowest level TOPBK (or zero if
                                            this is not a lowest level
                                            TOPBK). Table indexed by CPU type
    01D0  464 Address      4 TOPDSVCP       CP type DSVBKs
    01D4  468 Address      4 *
    01D8  472 Address      4 TOPDSVZA       zAAP type DSVBKs
    01DC  476 Address      4 TOPDSVIF       IFL type DSVBKs
    01E0  480 Address      4 TOPDSVIC       ICF type DSVBKs
    01E4  484 Address      4 TOPDSVZI       zIIP type DSVBKs
              00000018       TOPDsvTableLen *-TOPDSVBK Length of DSVBK table
             Notes      : TOPCAPAC and TOPRCAP for lowest level TOPBKs
                   are the (per CPU type) sums of DSVCAPAC and
                   DSVRCAP for all DSVBKs in the TOPDSVBK chains
                   which are not dedicated (FTRNTDED).  For higher
                   level TOPBKs, TOPCAPAC and TOPRCAP are the sums
                   for all lower level TOPBKs below this TOPBK in
                   the topology tree.
    01E8  488 Bitstring   24 TOPCAPAC (0)   The amount of unparked CPU/core
                                            capacity for all CPUs/cores
                                            associated with this TOPBK,
                                            indexed by CPU type. A value of
                                            1.0 represented scaled as
                                            x'10000' is a whole real CPU/core
                                            of capacity. This is an unsigned
                                            value, as a CPU/core will never
                                            have negative capacity.
    01E8  488 Signed       4 TOPCAPCP       CP capacity
    01EC  492 Signed       4 *
    01F0  496 Signed       4 TOPCAPZA       zAAP capacity
    01F4  500 Signed       4 TOPCAPIF       IFL capacity
    01F8  504 Signed       4 TOPCAPIC       ICF capacity
    01FC  508 Signed       4 TOPCAPZI       zIIP capacity
    0200  512 Bitstring   24 TOPRCAP (0)    The amount of remaining capacity
                                            which hasn't been earmarked for a
                                            VMDBK with affinity to a DSVBK
                                            underneath this TOPBK, indexed by
                                            CPU type. This value is in the
                                            same units as TOPCAPAC, however,
                                            it is a signed number, as we may
                                            dole out more capacity than we
                                            have unparked.
    0200  512 Signed       4 TOPRCAPCP      CP remaining capacity
    0204  516 Signed       4 *
    0208  520 Signed       4 TOPRCAPZA      zAAP remaining capacity
    020C  524 Signed       4 TOPRCAPIF      IFL remaining capacity
    0210  528 Signed       4 TOPRCAPIC      ICF remaining capacity
    0214  532 Signed       4 TOPRCAPZI      zIIP remaining capacity
    0218  536 Address      4 TOPLVLFP       Nest level list forward pointer.
                                            The nest level list is a
                                            circular, single- linked list of
                                            all TOPBKs of a given nest level
                                            (TOPNL). TOPBKs in this list do
                                            not necessarily share the same
                                            parent TOPBK (TOPPARNT).
    021C  540 Signed       2 TOPCPUCT (24)  Array of counts of CPUs which are
                                            associated with DSVBKs underneath
                                            this TOPBK, indexed first by CPU
                                            type, then by polarization.
              00000030       TOPCPUCT_len   *-TOPCPUCT Length (bytes) of the
                                            entire TOPCPUCT array
    024C  588 Signed       2 TOPCPUCR (24)  Array of counts of CPUs indexed
                                            first by CPU type, then by
                                            polarization. Copied from
                                            TOPCPUCT for use during the CPU
                                            park/unpark calculation routine.
              00000050       TOPSIZE        (*-TOPBK+7)/8 size in double
                                            words
              00000280       TOPBSIZE       TOPSIZE*8 size in bytes
              00000400       TOPBK_aligned_len
                                            1024 Byte-alignment on which we
                                            will "allocate" TOPBKs
              0000000A       TOPBK_Shift    10 Number of bits to shift to
                                            convert between TOPBK count and
                                            byte units (TOPBKs are allocated
                                            as 1024 bytes long) Verify the
                                            TOPBK_Shift gets us to 1024 bytes
                                            exactly

TOPBK Storage Layout | Top of page

    *** TOPBK - CPU Topology Block
    *
    *     +---------------------------+---------------------------+
    *   0 |         TOPPARNT          |         TOPCHILD          |
    *     +---------------------------+------+------+-------------+
    *   8 |         TOPSIBLG          |TOPNL |:CNTID|/////////////|
    *     +---------------------------+------+------+-------------+
    *  10 |                                                       |
    *     =                       TOPCPUMK                        =
    *     |                                                       |
    *     +-------------------------------------------------------+
    *  50 |                                                       |
    *     =                       TOPASSOC                        =
    *     |                                                       |
    *     +-------------------------------------------------------+
    *  90 |                                                       |
    *     =                       TOPUNPRK                        =
    *     |                                                       |
    *     +-------------------------------------------------------+
    *  D0 |                                                       |
    *     =                       TOPCPUHZ                        =
    *     |                                                       |
    *     +-------------------------------------------------------+
    * 110 |                                                       |
    *     =                       TOPCPUVL                        =
    *     |                                                       |
    *     +-------------------------------------------------------+
    * 150 |                                                       |
    *     =                       TOPCPUVM                        =
    *     |                                                       |
    *     +-------------------------------------------------------+
    * 190 |                                                       |
    *     =                       TOPCPUVH                        =
    *     |                                                       |
    *     +---------------------------+---------------------------+
    * 1D0 |         TOPDSVCP          |///////////////////////////|
    *     +---------------------------+---------------------------+
    * 1D8 |         TOPDSVZA          |         TOPDSVIF          |
    *     +---------------------------+---------------------------+
    * 1E0 |         TOPDSVIC          |         TOPDSVZI          |
    *     +---------------------------+---------------------------+
    * 1E8 |         TOPCAPCP          |///////////////////////////|
    *     +---------------------------+---------------------------+
    * 1F0 |         TOPCAPZA          |         TOPCAPIF          |
    *     +---------------------------+---------------------------+
    * 1F8 |         TOPCAPIC          |         TOPCAPZI          |
    *     +---------------------------+---------------------------+
    * 200 |        TOPRCAPCP          |///////////////////////////|
    *     +---------------------------+---------------------------+
    * 208 |        TOPRCAPZA          |        TOPRCAPIF          |
    *     +---------------------------+---------------------------+
    * 210 |        TOPRCAPIC          |        TOPRCAPZI          |
    *     +---------------------------+---------------------------+
    * 218 |         TOPLVLFP          |                           |
    *     +---------------------------+                           |
    * 220 |                                                       |
    *     =                       TOPCPUCT                        =
    *     |                           +---------------------------+
    *     |                           |                           |
    *     +---------------------------+                           |
    * 250 |                                                       |
    *     =                       TOPCPUCR                        =
    *     |                           +---------------------------+
    *     |                           | 27C
    *     +---------------------------+
    *
    *** TOPBK - CPU Topology Block

TOPBK Cross Reference | Top of page

    Symbol         Dspl Value
    -------------- ---- -----
    TOPASSOC       0050
    TOPBK_aligned_len
                   024C 00000400
    TOPBK_Shift    024C 0000000A
    TOPBSIZE       024C 00000280
    TOPCAPAC       01E8
    TOPCAPCP       01E8
    TOPCAPIC       01F8
    TOPCAPIF       01F4
    TOPCAPZA       01F0
    TOPCAPZI       01FC
    TOPCHILD       0004
    TOPCNTID       000D
    TOPCPUCR       024C
    TOPCPUCT       021C
    TOPCPUCT_len   021C 00000030
    TOPCPUHZ       00D0
    TOPCPUMK       0010
    TOPCPUPL       00D0
    TOPCPUVH       0190
    TOPCPUVL       0110
    TOPCPUVM       0150
    TOPDsvTableLen
                   01E4 00000018
    TOPDSVBK       01D0
    TOPDSVCP       01D0
    TOPDSVIC       01E0
    TOPDSVIF       01DC
    TOPDSVZA       01D8
    TOPDSVZI       01E4
    TOPLVLFP       0218
    TOPNL          000C
    TOPPARNT       0000
    TOPRCAP        0200
    TOPRCAPCP      0200
    TOPRCAPIC      0210
    TOPRCAPIF      020C
    TOPRCAPZA      0208
    TOPRCAPZI      0214
    TOPSIBLG       0008
    TOPSIZE        024C 00000050
    TOPUNPRK       0090

This information is based on z/VM 7.2.0 Last updated on 24 Jun 2020 at 09:31:20 EDT.
Copyright IBM Corporation, 1990, 2020