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.
 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 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
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       4 DSVFTRMK       Mask of features available on all
                                        CPUs associated with this
                                        dispatch vector
004C   76 Address      4 DSVGLIST       Global list pointer, either to
                                        all active DSVBKs or to all
                                        DSVBKs in the free list
0050   80 Address      4 DSVTOPBK       Pointer to containing TOPBK
0054   84 Signed       4 DSVCAPAC       The amount of unparked CPU
                                        capacity for all CPUs associated
                                        with this DSVBK. An entire real
                                        CPU of capacity is represented as
                                        x'10000'. This is an unsigned
                                        value, as a CPU will never have
                                        negative capacity.
0058   88 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.
005C   92 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.
0060   96 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).
0064  100 Signed       4 *              Reserved for IBM use
0068  104 Signed       8 DSVTIMWT       TOD clock value when a CPU
                                        associated with this DSVBK last
                                        exited wait state.
0070  112 Dbl-Word     8 * (0)
0070  112 Bitstring    8 DSVUNPRK       Mask of associated CPUs that are
                                        currently in the unparked state
0078  120 Bitstring   64 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.
          000000B8       DSVHDLEN       *-DSVHEADR Length in bytes of the
                                        DSVBK header.
      Format of each entry:
00B8  184 Dbl-Word     8 DSVENTRY (0)   Base value to be used when
                                        referencing a DSVBK entry.
00B8  184 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.
00BA  186 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
00BB  187 Address      1 DSVFPNT        Forward pointer to next entry in
                                        queue. Zero if this is the last
                                        entry.
00BC  188 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
          00000200       DSVLEN         (DSVHDLEN+DSVMAXUS*DSVENTLN+255)/
                                        256*256 Length in bytes of a
                                        DSVBK.
          00000040       DSVSIZE        (DSVLEN+7)/8 Size in doublewords
                                        of a DSVBK

          
*** DSVBK - DiSpatch Vector BlocK
*
*     +------+------+------+------+---------------------------+
*   0 |:HDWKB|:HDFLG|:HDFRE|:HDWRK|         DSVNXTDV          |
*     +------+------+------+------+-------------+------+------+
*   8 |         DSVLOREJ          |  DSVUSERC   |:LSTEN|//////|
*     +---------------------------+-------------+------+------+
*  10 |                                                       |
*     =                       DSVLOCK                         =
*     |                                                       |
*     +-------------------------------------------------------+
*  40 |                       DSVASSOC                        |
*     +---------------------------+---------------------------+
*  48 |         DSVFTRMK          |         DSVGLIST          |
*     +---------------------------+---------------------------+
*  50 |         DSVTOPBK          |         DSVCAPAC          |
*     +---------------------------+---------------------------+
*  58 |         DSVRCAP           |         DSVTOPID          |
*     +---------------------------+---------------------------+
*  60 |         DSVNXTTO          |///////////////////////////|
*     +---------------------------+---------------------------+
*  68 |                       DSVTIMWT                        |
*     +-------------------------------------------------------+
*  70 |                       DSVUNPRK                        |
*     +-------------------------------------------------------+
*  78 |                                                       |
*     =                       DSVCPARY                        =
*     |                                                       |
*     +--------------------+----------------------------------+
*  B8 |     DSVVMDBK       | BB
*     +--------------------+
*
*** DSVBK - DiSpatch Vector BlocK
          
*** Overlay for DSVVMDBK+2 in DSVBK
*
*                   +------+------+---------------------------+
*  B8 ...        BA |:FLAGS|:FPNT |         DSVPRIOR          |
*                   +------+------+---------------------------+
*  C0
*
*** Overlay for DSVVMDBK+2 in DSVBK

 
Symbol         Dspl Value
-------------- ---- -----
DSVASSOC       0040
DSVCAPAC       0054
DSVCPARY       0078
DSVDSCAN       0000 80
DSVENTLN       00BC 00000008
DSVENTRY       00B8
DSVFLAGS       00BA
DSVFPNT        00BB
DSVFTRMK       0048
DSVGLIST       004C
DSVHDFLG       0001
DSVHDFRE       0002
DSVHDLEN       0078 000000B8
DSVHDOFL       0001 80
DSVHDWKB       0000
DSVHDWRK       0003
DSVHEADR       0000 00000000
DSVIMBAL       0001 10
DSVINUSE       00B8 80
DSVLEN         00BC 00000200
DSVLOCK        0010
DSVLOREJ       0008
DSVLSTEN       000E
DSVMAXUS       00BC 00000028
DSVNEWRK       0001 04
DSVNOOWN       0000 20
DSVNOPTL       0001 08
DSVNOSTL       00BA 08
DSVNXTDV       0004
DSVNXTTO       0060
DSVOFLER       0001 02
DSVPRIOR       00BC
DSVRCAP        0058
DSVRCGAL       0000 40
DSVSHIFT       00BC 00000003
DSVSIZE        00BC 00000040
DSVSXSPM       0000 10
DSVTIDLE       0001 40
DSVTIMWT       0068
DSVTOPBK       0050
DSVTOPID       005C
DSVUNPRK       0070
DSVUSERC       000C
DSVVMDBK       00B8