NAME       : HCPDSVBK
 DESCRIPTION: DiSpatch Vector BlocK
 DSECT      : DSVBK
 FUNCTION   : The DSVBK maps the format of a Dispatch Vector.
              Each online CPU is associated with a DSVBK, but
              several CPUs may share the same DSVBK.
              Additionally, there is one to contain Master-
              Only work.  This DSECT maps the storage defined in
              the module HCPDSV.
 LOCATED BY : HCPDSVMS is the address of the Master-Only DSVBK.
              HCPDSVST is the starting address of the other DSVBKs.
              They are contiguous in storage.
              PFXDSVBK identifies the DSVBK that the processor
              is associated with.
              CORDSVBK identifies the DSVBK that the processors
              of this core are associated with.
 CREATED BY : The DSVBKs are DCed in module HCPDSV.
 DELETED BY : Never deleted
 RELOCATION CONSIDERATIONS : None

 DSVBK DSECT
Top of page

Hex   Dec Type/Val   Lng Label (dup)    Comments
---- ---- --------- ---- -------------- --------
0000    0 Structure      DSVBK          DiSpatch Vector BlocK
      Format of the header:
          00000000       DSVHEADR       * Base value to be used when
                                        referencing the DSVBK header
0000    0 Bitstring    1 *              Reserved for IBM use.
0001    1 Bitstring    1 DSVHDFLG       Flag byte for DSVBK status
          1... ....      DSVHDOFL       X'80' DSVHDOFL Set when DSVBK has
                                        "overflowed"
          .1.. ....      DSVTIDLE       X'40' DSVTIDLE Set to indicate
                                        that a scan should be made of the
                                        test-idle users by HCPDSP.
          ...1 ....      DSVIMBAL       X'10' DSVIMBAL Possible processor
                                        workload imbalance
          .... 1...      DSVNOPTL       X'08' DSVNOPTL We could not
                                        obtain the PTIL lock for any of
                                        the VMDBKs in the master-only
                                        DSVBK.
          .... .1..      DSVNEWRK       X'04' DSVNEWRK Used to tell
                                        HCPSTLWT that new work was added
                                        to this DSVBK between the time
                                        the dispatcher released the DSVBK
                                        lock and when HCPSTLWT turns on
                                        the wait bit in SRMCPUWT. This is
                                        necessary since the dispatcher
                                        does not hold the scheduler lock
                                        exclusive or the DSVBK lock
                                        during that time and another
                                        processor could add work to the
                                        DSVBK and the dispatcher could go
                                        into wait state without knowing
                                        that work is available. The DSVBK
                                        lock must be held to turn this
                                        bit on or off.
          .... ..1.      DSVOFLER       X'02' DSVOFLER Indicates that
                                        this DSVBK had the
                                        DSVHDOFL/DSVLOREJ mismatch error
                                        at least one time
0002    2 Address      1 DSVHDFRE       Anchor of the "entries not in
                                        use" queue.
0003    3 Address      1 DSVHDWRK       Anchor of the "entries in use"
                                        queue.
0004    4 Address      4 DSVNXTDV       Pointer to the next dispatch
                                        vector in a circular linked list
                                        of dispatch vectors that belong
                                        to CPUs of the same CPU type.
                                        i.e: zIIP,zAAP,CP,IFL. Protected
                                        by the scheduler lock.
0008    8 Signed       4 DSVLOREJ       Lowest-value (best) priority
                                        which was rejected from this
                                        DSVBK
000C   12 Signed       2 DSVUSERC       User count - number of VMDBKS in
                                        this DSVBK
000E   14 Address      1 DSVLSTEN       Last DSVENTRY in DSVHDWRK queue
000F   15 Address      1 *              Reserved for future IBM use
0010   16 Dbl-Word     8 DSVLOCK (6)    Lock area for the DSVBK lock.
                                        This lock is a formal exclusive
                                        spin lock and it is used to
                                        serialize access to a DSVBK. The
                                        HCPLKPLD and HCPULPLD macros are
                                        used to obtain and release it. At
                                        least a share of the scheduler
                                        lock must be held before
                                        requesting this lock. This means
                                        that any DSVBK can be accessed or
                                        even changed without its DSVBK
                                        lock if the scheduler lock is
                                        held in exclusive mode. More than
                                        one DSVBK lock can be held by a
                                        processor only if the scheduler
                                        lock is first held in exclusive
                                        mode. The scheduler lock cannot
                                        be obtained in exclusive mode
                                        while a DSVBK lock is held.
0040   64 Dbl-Word     8 * (0)
0040   64 Bitstring    8 DSVASSOC       Mask of CPUs that are associated
                                        with this dispatch vector
0048   72 Signed       2 DSVASCAO       Dispatch vector associated CPU
                                        address origin (bit index)
004A   74 Signed       2 *              Reserved for IBM use
004C   76 Signed       4 *              Reserved for IBM use
0050   80 Signed       4 DSVFTRMK       Mask of features available on all
                                        CPUs associated with this
                                        dispatch vector
0054   84 Address      4 DSVGLIST       Global list pointer, either to
                                        all active DSVBKs or to all
                                        DSVBKs in the free list
0058   88 Address      4 DSVTOPBK       Pointer to containing TOPBK
005C   92 Signed       4 DSVCAPAC       The amount of unparked CPU/core
                                        capacity for all CPUs/cores
                                        associated with this DSVBK. An
                                        entire real CPU/core of capacity
                                        is represented as x'10000'. This
                                        is an unsigned value, as a
                                        CPU/core will never have negative
                                        capacity.
0060   96 Signed       4 DSVRCAP        The amount of remaining capacity
                                        which hasn't been earmarked for a
                                        VMDBK with affinity to this
                                        DSVBK. This value is in the same
                                        units as DSVCAPAC, however, it is
                                        a signed number.
         Notes      : For a single-level topology, DSVTOPID has the
               format x'bb000000' where bb is the TOPCNTID of
               the TOPNL=1 TOPBK.
               For a two-level topology, DSVTOPID has the format
               x'bbcc0000' where bb is the TOPCNTID of the
               TOPNL=2 TOPBK, and cc is the TOPCNTID of the
               TOPNL=1 TOPBK.
               Currently z/VM supports machines with up to
               two levels of CPU topology.  The architecture
               allows for up to 5 topology levels.  This field
               has room for 4 topology levels.  If z/VM were to
               support more than 4 levels of topology, DSVTOPID
               would need to be expanded.
0064  100 Bitstring    4 DSVTOPID       Topology identifier. This
                                        consists of the container ids
                                        (TOPCNTID) for the TOPBKs above
                                        this DSVBK in the topology tree,
                                        specified left to right with the
                                        highest (greatest TOPNL value)
                                        TOPBKs listed first.
0068  104 Signed       4 DSVDSPCT       Count of VMDBKs dispatched on
                                        processors associated with this
                                        DSVBK
006C  108 Signed       4 DSVCBF         Chargeback factor. Updated only
                                        by the single HCPMTCPL task in
                                        the system. Scaled by
                                        HisMT_Entry_kMetricFactor or by
                                        shifting the value using
                                        HisMT_Entry_kMetricShift
0070  112 Signed       8 DSVTIMWT       TOD clock value when a CPU
                                        associated with this DSVBK last
                                        exited wait state.
0078  120 Signed       4 *              Reserved for IBM use
007C  124 Signed       2 *              Reserved for IBM use
007E  126 Signed       2 DSVUNPAO       Associated unparked CPU address
                                        origin (bit index)
0080  128 Bitstring    8 DSVUNPRK       Mask of associated CPUs that are
                                        currently in the unparked state
          00000088       DSVHDLEN       *-DSVHEADR Length in bytes of the
                                        DSVBK header.
      List of DSVBK entries:
0088  136 Dbl-Word     8 DSVENTRS (0)   Start of DSVENTRY list.
0088  136 Bitstring    1 * (320)
      DSVBK Trailer.  Follows last of the entries.
01C8  456 Dbl-Word     8 DSVTRALR (0)
01C8  456 Bitstring    1 DSVHDWKB       Byte of Work Bits All bit
                                        manipulations must be serialized
                                        by compare-and-swap logic. See
                                        note in block comment above.
          1... ....      DSVDSCAN       X'80' DSVDSCAN A Steal Task may
                                        need to be started
          .1.. ....      DSVRCGAL       X'40' DSVRCGAL A foreground
                                        replenish of the cleared global
                                        available list is required
          ..1. ....      DSVNOOWN       X'20' DSVNOOWN High priority
                                        reclaim noown resources
          ...1 ....      DSVSXSPM       X'10' DSVSXSPM High priority
                                        SXSPM work
          .... .1..      DSVRUGAL       X'04' DSVRUGAL The uncleared
                                        global available lists need to be
                                        replenished.
          .... ..1.      DSVEMPTY       X'02' DSVEMPTY DSVHDWRK=0
                                        (empty).
          1111 .1..      DSVHiPri       DSVDSCAN+DSVRCGAL+DSVNOOWN+DSVSXS
                                        PM+DSVRUGAL DSVHiPri *cmt
01C9  457 Bitstring    1 * (3)          Reserved for IBM use.
01CC  460 Address      4 DSVNXTTO       Pointer to the next dispatch
                                        vector in a circular linked list
                                        of dispatch vectors of the same
                                        CPU type that belong to the same
                                        NL=1 TOPBK. Serialized by the
                                        topology lock (HCPDSVTL).
01D0  464 Bitstring  512 DSVCPARY       Cache penalty array. An indexed
                                        array of one-byte entries that
                                        contain the "cache penalty" or
                                        topological distance from each of
                                        the other DSVBKs of the same CPU
                                        type. Indexed by position in the
                                        array of DSVBKs starting at
                                        HCPDSVST. An entry value of x'FF'
                                        means there is no active DSVBK at
                                        that index into the HCPDSVST
                                        array.
          00000030       DSVTRRES       1024-(*-DSVBK) space left in
                                        first 4 cache lines
03D0  976 Bitstring    1 *              Reserved for IBM use
          00000238       DSVTRLEN       *-DSVTRALR Length of DSVBK
                                        Trailer.
          00000400       DSVBKLEN       *-DSVBK Length of
                                        header+entries+trailer.
          00000400       DSVEND         * End of the DSVBK defined
                                        content.
      Format of each entry:
0088  136 Dbl-Word     8 DSVENTRY (0)   Base value to be used when
                                        referencing a DSVBK entry.
0088  136 Address      3 DSVVMDBK       Bits 0 to 19 of the user's VMDBK
                                        address. Bits 20 to 31 are known
                                        to be zero and need not be stored
                                        in the Vector entry.
          1... ....      DSVINUSE       X'80' DSVINUSE High-order bit is
                                        set when the DSVBK entry is "in
                                        use", whenever the entry is in
                                        the chain starting from DSVHDWRK.
008A  138 Bitstring    1 DSVFLAGS       A flag nibble
          .... 1...      DSVNOSTL       X'08' DSVNOSTL Set when work MUST
                                        not be stolen, in order to
                                        respect VMDBK's affinity
                                        requirements
008B  139 Address      1 DSVFPNT        Forward pointer to next entry in
                                        queue. Zero if this is the last
                                        entry.
008C  140 Signed       4 DSVPRIOR       A representation of this VMDBK's
                                        priority in the dispatch list.
                                        The value in this field is a
                                        function of the VMDBK's VMDDPRTY.
          00000008       DSVENTLN       *-DSVENTRY Length in bytes of a
                                        DSVBK entry
          00000028       DSVMAXUS       40 Maximum number of users in a
                                        DSVBK
          00000003       DSVSHIFT       3 Number of bits to shift to
                                        convert a DSVENTRY index into a
                                        displacement from DSVHEADR
          0000000A       DSVLFCTR       10 shift value used to divide by
                                        the length of a DSVBK DSVLEN must
                                        be a power of two so that use of
                                        DSVLFCTR as a shift value for
                                        DSVBK length is valid
      Constants used for DSVBK allocation:
          00000400       DSVLEN         (DSVBKLEN+255)/256*256 Length in
                                        bytes of a multiple of cache
                                        lines required for 1 DSVBK.
          00000080       DSVSIZE        (DSVLEN+7)/8 DSVLEN size in
                                        dwords.

          
*** DSVBK - DiSpatch Vector BlocK
*
*     +------+------+------+------+---------------------------+
*   0 |//////|:HDFLG|:HDFRE|:HDWRK|         DSVNXTDV          |
*     +------+------+------+------+-------------+------+------+
*   8 |         DSVLOREJ          |  DSVUSERC   |:LSTEN|//////|
*     +---------------------------+-------------+------+------+
*  10 |                                                       |
*     =                       DSVLOCK                         =
*     |                                                       |
*     +-------------------------------------------------------+
*  40 |                       DSVASSOC                        |
*     +-------------+-------------+---------------------------+
*  48 |  DSVASCAO   |/////////////|///////////////////////////|
*     +-------------+-------------+---------------------------+
*  50 |         DSVFTRMK          |         DSVGLIST          |
*     +---------------------------+---------------------------+
*  58 |         DSVTOPBK          |         DSVCAPAC          |
*     +---------------------------+---------------------------+
*  60 |         DSVRCAP           |         DSVTOPID          |
*     +---------------------------+---------------------------+
*  68 |         DSVDSPCT          |          DSVCBF           |
*     +---------------------------+---------------------------+
*  70 |                       DSVTIMWT                        |
*     +---------------------------+-------------+-------------+
*  78 |///////////////////////////|/////////////|  DSVUNPAO   |
*     +---------------------------+-------------+-------------+
*  80 |                       DSVUNPRK                        |
*     +-------------------------------------------------------+
*  88 |///////////////////////////////////////////////////////|
*     =///////////////////////////////////////////////////////=
*     |///////////////////////////////////////////////////////|
*     +------+--------------------+---------------------------+
* 1C8 |:HDWKB|////////////////////|         DSVNXTTO          |
*     +------+--------------------+---------------------------+
* 1D0 |                                                       |
*     =                       DSVCPARY                        =
*     |                                                       |
*     +------+------------------------------------------------+
* 3D0 |//////| 3D1
*     +------+
*
*** DSVBK - DiSpatch Vector BlocK
          
*** Overlay for DSVENTRS in DSVBK
*
*     +--------------------+
*  88 |     DSVVMDBK       | 8B
*     +--------------------+
*
*** Overlay for DSVENTRS in DSVBK
          
*** Overlay for DSVVMDBK+2 in DSVBK
*
*                   +------+------+---------------------------+
*  88 ...        8A |:FLAGS|:FPNT |         DSVPRIOR          |
*                   +------+------+---------------------------+
*  90
*
*** Overlay for DSVVMDBK+2 in DSVBK

 
Symbol         Dspl Value
-------------- ---- -----
DSVASCAO       0048
DSVASSOC       0040
DSVBKLEN       03D0 00000400
DSVCAPAC       005C
DSVCBF         006C
DSVCPARY       01D0
DSVDSCAN       01C8 80
DSVDSPCT       0068
DSVEMPTY       01C8 02
DSVEND         03D0 00000400
DSVENTLN       008C 00000008
DSVENTRS       0088
DSVENTRY       0088
DSVFLAGS       008A
DSVFPNT        008B
DSVFTRMK       0050
DSVGLIST       0054
DSVHiPri       01C8 F4
DSVHDFLG       0001
DSVHDFRE       0002
DSVHDLEN       0080 00000088
DSVHDOFL       0001 80
DSVHDWKB       01C8
DSVHDWRK       0003
DSVHEADR       0000 00000000
DSVIMBAL       0001 10
DSVINUSE       0088 80
DSVLEN         008C 00000400
DSVLFCTR       008C 0000000A
DSVLOCK        0010
DSVLOREJ       0008
DSVLSTEN       000E
DSVMAXUS       008C 00000028
DSVNEWRK       0001 04
DSVNOOWN       01C8 20
DSVNOPTL       0001 08
DSVNOSTL       008A 08
DSVNXTDV       0004
DSVNXTTO       01CC
DSVOFLER       0001 02
DSVPRIOR       008C
DSVRCAP        0060
DSVRCGAL       01C8 40
DSVRUGAL       01C8 04
DSVSHIFT       008C 00000003
DSVSIZE        008C 00000080
DSVSXSPM       01C8 10
DSVTIDLE       0001 40
DSVTIMWT       0070
DSVTOPBK       0058
DSVTOPID       0064
DSVTRALR       01C8
DSVTRLEN       03D0 00000238
DSVTRRES       01D0 00000030
DSVUNPAO       007E
DSVUNPRK       0080
DSVUSERC       000C
DSVVMDBK       0088