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

 
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