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 Dbl-Word     8 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.
0018   24 Dbl-Word     8 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.
0020   32 Dbl-Word     8 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.
0028   40 Dbl-Word     8 TOPCPUPL (0)   Array of CPU masks indexed by
                                        polarization value
0028   40 Dbl-Word     8 TOPCPUHZ       Mask of horizontal CPUs
0030   48 Dbl-Word     8 TOPCPUVL       Mask of vertical low CPUs
0038   56 Dbl-Word     8 TOPCPUVM       Mask of vertical medium CPUs
0040   64 Dbl-Word     8 TOPCPUVH       Mask of vertical high CPUs
0048   72 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
0048   72 Address      4 TOPDSVCP       CP type DSVBKs
004C   76 Address      4 *
0050   80 Address      4 TOPDSVZA       zAAP type DSVBKs
0054   84 Address      4 TOPDSVIF       IFL type DSVBKs
0058   88 Address      4 TOPDSVIC       ICF type DSVBKs
005C   92 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.
0060   96 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.
0060   96 Signed       4 TOPCAPCP       CP capacity
0064  100 Signed       4 *
0068  104 Signed       4 TOPCAPZA       zAAP capacity
006C  108 Signed       4 TOPCAPIF       IFL capacity
0070  112 Signed       4 TOPCAPIC       ICF capacity
0074  116 Signed       4 TOPCAPZI       zIIP capacity
0078  120 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.
0078  120 Signed       4 TOPRCAPCP      CP remaining capacity
007C  124 Signed       4 *
0080  128 Signed       4 TOPRCAPZA      zAAP remaining capacity
0084  132 Signed       4 TOPRCAPIF      IFL remaining capacity
0088  136 Signed       4 TOPRCAPIC      ICF remaining capacity
008C  140 Signed       4 TOPRCAPZI      zIIP remaining capacity
0090  144 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).
0094  148 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
00C4  196 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.
          0000001F       TOPSIZE        (*-TOPBK+7)/8 size in double
                                        words
          000000F8       TOPBSIZE       TOPSIZE*8 size in bytes
          00000100       TOPBK_aligned_len
                                        256 Byte-alignment on which we
                                        will "allocate" TOPBKs
          00000008       TOPBK_Shift    8 Number of bits to shift to
                                        convert between TOPBK count and
                                        byte units (TOPBKs are allocated
                                        as 256 bytes long)

 
*** TOPBK - CPU Topology Block
*
*     +---------------------------+---------------------------+
*   0 |         TOPPARNT          |         TOPCHILD          |
*     +---------------------------+------+------+-------------+
*   8 |         TOPSIBLG          |TOPNL |:CNTID|/////////////|
*     +---------------------------+------+------+-------------+
*  10 |                       TOPCPUMK                        |
*     +-------------------------------------------------------+
*  18 |                       TOPASSOC                        |
*     +-------------------------------------------------------+
*  20 |                       TOPUNPRK                        |
*     +-------------------------------------------------------+
*  28 |                       TOPCPUHZ                        |
*     +-------------------------------------------------------+
*  30 |                       TOPCPUVL                        |
*     +-------------------------------------------------------+
*  38 |                       TOPCPUVM                        |
*     +-------------------------------------------------------+
*  40 |                       TOPCPUVH                        |
*     +---------------------------+---------------------------+
*  48 |         TOPDSVCP          |///////////////////////////|
*     +---------------------------+---------------------------+
*  50 |         TOPDSVZA          |         TOPDSVIF          |
*     +---------------------------+---------------------------+
*  58 |         TOPDSVIC          |         TOPDSVZI          |
*     +---------------------------+---------------------------+
*  60 |         TOPCAPCP          |///////////////////////////|
*     +---------------------------+---------------------------+
*  68 |         TOPCAPZA          |         TOPCAPIF          |
*     +---------------------------+---------------------------+
*  70 |         TOPCAPIC          |         TOPCAPZI          |
*     +---------------------------+---------------------------+
*  78 |        TOPRCAPCP          |///////////////////////////|
*     +---------------------------+---------------------------+
*  80 |        TOPRCAPZA          |        TOPRCAPIF          |
*     +---------------------------+---------------------------+
*  88 |        TOPRCAPIC          |        TOPRCAPZI          |
*     +---------------------------+---------------------------+
*  90 |         TOPLVLFP          |                           |
*     +---------------------------+                           |
*  98 |                                                       |
*     =                       TOPCPUCT                        =
*     |                           +---------------------------+
*     |                           |                           |
*     +---------------------------+                           |
*  C8 |                                                       |
*     =                       TOPCPUCR                        =
*     |                           +---------------------------+
*     |                           | F4
*     +---------------------------+
*
*** TOPBK - CPU Topology Block

 
Symbol         Dspl Value
-------------- ---- -----
TOPASSOC       0018
TOPBK_aligned_len
               00C4 00000100
TOPBK_Shift    00C4 00000008
TOPBSIZE       00C4 000000F8
TOPCAPAC       0060
TOPCAPCP       0060
TOPCAPIC       0070
TOPCAPIF       006C
TOPCAPZA       0068
TOPCAPZI       0074
TOPCHILD       0004
TOPCNTID       000D
TOPCPUCR       00C4
TOPCPUCT       0094
TOPCPUCT_len   0094 00000030
TOPCPUHZ       0028
TOPCPUMK       0010
TOPCPUPL       0028
TOPCPUVH       0040
TOPCPUVL       0030
TOPCPUVM       0038
TOPDsvTableLen
               005C 00000018
TOPDSVBK       0048
TOPDSVCP       0048
TOPDSVIC       0058
TOPDSVIF       0054
TOPDSVZA       0050
TOPDSVZI       005C
TOPLVLFP       0090
TOPNL          000C
TOPPARNT       0000
TOPRCAP        0078
TOPRCAPCP      0078
TOPRCAPIC      0088
TOPRCAPIF      0084
TOPRCAPZA      0080
TOPRCAPZI      008C
TOPSIBLG       0008
TOPSIZE        00C4 0000001F
TOPUNPRK       0020