VMUBK Back to Index page
 
Prolog 
Control Block Contents 
   VMUBK DSECT
   VMUTOPEN DSECT
   VMUARYEN 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.


  VMUBK Prolog Top of page
 
 NAME       : HCPVMUBK
 DESCRIPTION: Virtual Machine CPU Usage block
 DSECT      : VMUBK
 FUNCTION   : Contains the data necessary to track CPU usage by a
              particular virtual CPU and then to predict its future
              CPU usage in the next interval.  The prediction is used
              as part of the algorithm in the work load rebalance
              routine when it is deciding to which dispatch vector the
              VMDBK should be assigned.
 LOCATED BY : The pointer VMDVMUBK in each VMDBK and one of the
              RCCVMUOA or RCCVMUUA arrays of VMUBKs during rebalance
 CREATED BY : HCPBVMBK at logon or relocation time
 DELETED BY : HCPALLFG or HCPSTLDT at logoff time or DETACH CPU
 REFERENCES : None
 SERIALIZED : This control block is only used by the thread that is
              called once every two seconds to do work load rebalancing.
              That thread is HCPHIPTM, the Periodic HiperDispatch Routine.
              It includes execution of a work load rebalance routine.
              The rebalance is done in two steps.  First, the CPU usage
              of all VMDBKs in the system during the previous interval
              is calculated and stored in the VMDBK's VMUBK.  This first
              step also builds two arrays of origin VMUBKs:  an ordered
              array (RCCVMUOA) and an unordered array (RCCVMUUA).  The
              RCCVMUOA array is ordered by total predicted CPU usage
              of the guest.  The second step is the actual rebalance
              operation which occurs in a later part of the Periodic
              HiperDispatch Routine.
              The Periodic HiperDispatch Routine can only run on one
              processor at a time because the timer to schedule the
              next invocation is not set until the thread completes.
              When the VMUBK arrays are built during the first step of
              rebalance, the RCCVMULK lock is obtained.  It is held
              until the actual rebalance completes in the second part
              of the rebalance operation.  That means this lock is
              obtained near the beginning of the Periodic HiperDispatch
              routine and is held until rebalance is complete.
              The RCCVMULK lock is obtained early in the rebalance
              process so that the RCCVMUOA and RCCVMUUA arrays can be
              built without holding the scheduler lock.  However, the
              scheduler lock is required for the actual rebalancing.
              Because of this, the RCCVMULK lock must be obtained
              before the vary on, scheduler, and topology locks.
              The only other times a VMUBK is referenced is when it is
              obtained or released, or during the monitor sampling
              process.  Obtain is done at logon before any other
              process can access the block.  Release of an origin
              VMDBK's VMUBK is done under protection of the RCCVMULK
              and thus cannot happen until the rebalance thread is done.
              A virtual MP's (or adjunct's) VMUBK is not released until
              an MP delay is done similar to how a vMP VMDBK is released.
              Since the vMP VMUBK is only accessed during rebalance scan
              of the RCCVMUOA and RCCVMUUA arrays and since there is no
              loss of control during that scan, the MP delay stops the
              logoff code in HCPSTLDT from releasing the vMP VMUBK until
              after the rebalance function is done with the array scan
              without requiring the RCCVMULK lock.  This is necessary
              because HCPSTLDT runs under protection of the scheduler
              lock and obtaining the RCCVMULK during that routine would
              violate the lock heirarchy.  The monitor references to
              the VMUBK are protected in the same manner that its
              references to the vMP VMDBK are serialized.
 RELOCATION CONSIDERATIONS : This control block is associated with a virtual CPU but
              it is not relocated along with the virtual machine.
              Instead, on the relocation destination system, a new
              instance is created and initialized as it would be at
              logon time.
 COMPATIBILITY AND MIGRATION CONCERNS : None
 NOTES      : 1) All fields that contain CPU usage values are expressed
              as a percentage of a CPU scaled by x'10000'.  So a
              usage of half of a CPU would be kept as x'8000' and
              usage of one and a half CPUs would be x'18000'.
 
 
  VMUBK Control Block Content Top of page
 

 VMUBK DSECT Top of page
Hex Dec Type/Val Lng Label (dup) Comments ---- ---- --------- ---- -------------- -------- 0000 0 Structure VMUBK Virtual Machine CPU Usage block 0000 0 Address 4 VMUVMDBK Pointer (HLA) to associated VMDBK 0004 4 Address 4 VMUHLPBK Pointer (HLA) to the HLPBK (only used in the origin VMDBK's VMUBK) 0008 8 Signed 8 VMUTTSUI VMDTTIME at Start of the current Usage Interval 0010 16 Signed 4 VMUTPUSG This guest's total predicted CPU usage for the next interval. This is a scaled number where x'10000' = 100% of one CPU. This field is used to sort the origin VMUBKs by predicted CPU usage in descending order. Valid only in VMUBK of origin VMDBK 0014 20 Signed 4 VMULIUSG This VMDBK's CPU usage during the last usage interval. This is a scaled number where x'10000' = 100% of one CPU. It is valid in all VMUBKs. 0018 24 Address 4 VMUVMDLU HL addr of the VMDBK in the local cyclic list with the largest actual CPU usage in the latest interval. Valid only in the VMUBK of the origin VMDBK and serialized by the local-cyclic-list lock 001C 28 Signed 4 VMUMAXLU Actual CPU usage in the last interval of the vCPU (VMDBK) that used the most CPU during that interval. This is a percentage of a CPU scaled by x'10000'. Valid only in the VMUBK of the origin VMDBK. The following array of fields contains a fullword for each CPU type. The fullwords contain this guest's total CPU usage for each CPU type during the last usage interval. These fields are only valid in the VMUBK of the origin VMDBK. The CPU type value as defined in HCPEQUAT can be used to index into this array. This CPU usage is a scaled number where x'10000' represents 100% of one CPU. 0020 32 Signed 4 VMULUSGT (6) Array of CPU usages totaled by CPU type during the last interval 00000018 VMULUSGL *-VMULUSGT Length of the array 00000006 VMULUSGC VMULUSGL/(L'VMULUSGT) Count of array entries Data collected for inclusion in monitor records. These fields are maintained by the rebalance function in HCPDSB. 0038 56 Signed 4 VMUNRBAL Number of times this guest's VMDBKs have gone through the DSVBK rebalance function (Valid only in the origin VMDBK) Array of fullword elements with each element containing a cumulative count. One of these counts is incremented each time the virtual configuration is rebalanced and not all of the configuration's VMDBKs are placed in the same DSVBK. Which counter is incremented depends on the maximum topological distance between any two VMDBKs in the virtual configuration. That is, the first count is the number of times all VMDBKs were placed in two or more DSVBKs on the same topology nesting level 1 (NL1). The second count is incremented whenever all the guest's VMDBKs are placed in the same nesting level 2 (NL2) topological location but not the same NL1 location. The third count is incremented whenever all the guest's VMDBKs are placed in the same nesting NL3 topological location but not the same NL2 location. And so, forth up to MAXTOPO nesting levels. The number of times the entire configuration was placed within the same dispatch vector can be determined by subtracting the sum of the counters in this array from the VMUNRBAL counter. This array is only valid in the origin VMDBK's VMUBK. 003C 60 Signed 4 VMUPLTL (6) Array of counters of maximum rebalance topology distance placement (Valid only in the origin VMDBK's VMUBK) Array of fullword elements with each element containing a cumulative count. One of these counts is incremented each time the virtual configuration is rebalanced and this VMDBK is moved away from its previous dispatch vector. The first count is the number of times the VMDBK was moved to a new dispatch vector in the same topology nesting level 1 location. The second count is the number of times the VMDBK was moved one topology nesting level away from its previous home level by rebalance; that is when the VMDBK is assigned to a new DSVBK that is in a different NL1 location but the same NL2 location as its previous home. The third counter is the number of times the VMDBK was moved two topology nesting levels away from its previous home; to a DSVBK that is in a different NL2 but the same NL3 location. And so forth up to MAXTOPO levels of separation. The number of times the VMDBK was not moved out of its previous dispatch vector during a rebalance can be determined by subtracting the sum of the counters in this array from the VMUNRBAL counter in the origin VMDBK's VMUBK. This array is contained in all VMUBKs, not just in the origin's VMUBK. 0054 84 Signed 4 VMUVMTL (6) Array of counts of how far the VMDBK was moved topologically during work load rebalancing. (Valid in all VMDBK's VMUBK except vSIE VMDBKs) Array of six fullword elements with each element containing a cumulative count. One of these counts is incremented each time the VMDBK associated with this VMUBK is stolen and dispatched by a CPU which is not associated with the VMDBK's home DSVBK (VMDHDSV). Which counter is incremented depends on how far away in the CPU topology the stealing CPU is from the CPUs associated with the home DSVBK. The array is origin 0, indexed by the highest container (TOPBK) nest level which differs between the stealing CPU and those associated with the home DSVBK. An index of 0 indicates that the stealing CPU is topologically equivalent to those associated with the home DSVBK. An index of 1 indicates that the stealing CPU had a different NL=1 TOPBK than those associated with the home DSVBK, but their NL=2 and higher (if they exist) TOPBKs are identical. 006C 108 Signed 4 VMUSTLTL (6) Array of counters indicating how many times this VMDBK was stolen across different topology levels. 0084 132 Bitstring 2 * Reserved for future IBM use An array of ten 6-byte elements that contain the DSVBK ID and topology descriptor of the last ten DSVBKs to which this VMDBK was assigned by the last ten rebalance functions. This is a circular array with the VMUTOPDX field pointing to the most recently updated element. This array is contained in all VMDBK records, not just the origin. Within a virtual configuration the Nth element of the array for each VMDBK represents the assignment made during the same rebalance operation. 0086 134 Bitstring 1 VMUTOPLK Test-and-set lock used to keep consistency between the actual VMUTOPDA array and its index pointer (VMUTOPDX) and the count of rebalances done in system lifetime (VMUREBAL). 0087 135 Bitstring 1 VMUTOPDX Index into the circular VMUTOPDA array indicating which element represents the most recent of the ten entries (Valid in all VMDBKs) 0088 136 Signed 4 VMUREBAL The value of RCCREBAL (the count of the number of times a rebalance was done on this system) at the time of the most recent rebalance. 008C 140 Bitstring 16 VMUTOPDA (10) Circular array whose elements contain the DSVBK ID and topology descriptor of the last ten DSVBKs to which this VMDBK was assigned by the rebalance function. Each entry is mapped by VMUTOPEN. An entry is all FFs initially until it is used and made valid. (Valid in all VMDBKs) 000000A0 VMUTOPDL *-VMUTOPDA Length of entire VMUTOPDA array An array of elements indexed by CPU type that contains the number of VMDBKs of each CPU type counted in the last invocation of HCPVMUPU just before a rebalance operation. 012C 300 Signed 4 VMUVMDCT (6) Array of counts of the number of this guest's VMDBKs for each dispatch CPU type determined when gathering information to be used for dispatch vector rebalance (Valid only in the origin VMDBK) 00000018 VMUVMDCL *-VMUVMDCT Length of the entire array 0144 324 Signed 4 VMURSHFSQ Reshuffle sequence number of the last time this vConfig was visited by reshuffle. Valid only in the origin VMDBK's VMUBK. 0148 328 Address 4 VMURSHFPR Preferred DSVBK to use for this vConfig during the reshuffle with the sequence number in VMURSHFSQ. Valid only in the origin VMDBK's VMUBK. The following fields are statistics gathered by the dispatcher about how long a VMDBK has been dispatched and how long the VMDBK had to wait to be dispatched once it was ready to consume CPU time. The deltas of these fields between monitor intervals can be used to determine average dispatch time and average wait times, and using the sum of the squares, the standard deviations of those time samples. 014C 332 Signed 4 VMUDWTCT Count of the number of times this VMDBK became ready to be dispatched (unsigned fullword). This is calculated using VMUDWTCT. Updated only when the dispatch lock of its VMDBK is held. 0150 336 Bitstring 8 VMUDWTETM Accumulated elapsed time between when this VMDBK became ready to be dispatched and when it was dispatched (unsigned doubleword in microseconds) Updated only when the dispatch lock of its VMDBK is held. 0158 344 Bitstring 16 VMUDWTTSQ Sum of the squares of the individual elapsed time samples which comprise VMUDWTETM (unsigned quadword in squared microseconds) Note: Use the VMUDWTCT field with VMUDWTETM and this field to calculate the average amount of elapsed time this VMDBK waited to be dispatched once it became ready and the standard deviation of those time samples. Updated only when the dispatch lock of its VMDBK is held. 0168 360 Signed 4 * Reserved for future IBM use 016C 364 Signed 4 VMUDSPCT Count of the number of times this VMDBK was dispatched (unsigned fullword). This is calculated using VMUDSPCT. Note: This count can be used with both the dispatched times and the VMDTTIME values as those are all calculated at the same moment. Updated only when the dispatch lock of its VMDBK is held. 0170 368 Bitstring 8 VMUDSPETM Accumulated elapsed time during which this VMDBK was dispatched (unsigned doubleword in microseconds) Updated only when the dispatch lock of its VMDBK is held. 0178 376 Bitstring 16 VMUDSPTSQ Sum of the squares of the individual elapsed time samples which comprise VMUDSPETM (unsigned quadword in squared microseconds) Note: Use the VMUDSPCT field with VMUDSPETM and this field to calculate the average amount of elapsed time this VMDBK was dispatched and the standard deviation of those time samples. Updated only when the dispatch lock of its VMDBK is held. 0188 392 Bitstring 16 VMUTTIMSQ Sum of the squares of the individual CPU timer samples added to VMDTTIME at undispatch (unsigned quadword in squared TOD clock units) Note: Use the VMUDSPCT field with VMDTTIME and this field to calculate the average amount of CPU time this VMDBK consumed while it was dispatched and the standard deviation of those time samples. Updated only when the dispatch lock of its VMDBK is held. 0198 408 Bitstring 8 VMULPPUV Doubleword used as the operand of the LPP instruction by the dispatcher. 0198 408 Bitstring 2 VMUFVCPU Flag and vCPU field 1... .... VMUFADJ X'80' Adjunct flag .1.. .... VMUFVSIE X'40' vSIE flag ..1. .... VMUFATC X'20' AT Command flag Flag codes should only be defined for the first 4 bits of this field. 00000FFF VMUVCPU x'0FFF' Virtual CPU address mask 0000F000 VMULPPFL x'F000' Program parameter flag nybble 019A 410 Bitstring 6 VMU6USER The six-byte compressed userID of the sampled user. 00000034 VMUSIZE (*-VMUBK+7)/8 Size in double words of the VMUBK 000001A0 VMUBSIZE VMUSIZE*8 Size in bytes of the VMUBK 0000000A VMUTOPNE 10 Number of elements that fit in the VMDTOPDA array This DSECT maps an entry in the VMUTOPDA array.
 VMUTOPEN DSECT Top of page
Hex Dec Type/Val Lng Label (dup) Comments ---- ---- --------- ---- -------------- -------- 0000 0 Structure VMUTOPEN Virtual Machine CPU Usage block 0000 0 Bitstring 2 VMUTOPDI DSVBK ID assigned 0002 2 Bitstring 4 VMUTOPDS Topo descriptor of DSV assigned. This topology descriptor or identifier consists of the container IDs (TOPCNTID) for the TOPBKs in the topology tree above the DSVBK specified in USEACT_VMUTOPDI. These container IDs are positioned left to right with the highest (greatest TOPNL value) TOPBKs listed first. 0006 6 Bitstring 1 VMURSVD1 Reserved for possible future topology level expansion 0007 7 Bitstring 1 VMUTOPFL Flag bits 1... .... VMURROBN X'80' VMURROBN Placed via round robin algorithm .1.. .... VMUMODRB X'40' VMUMODRB Placed by a modified rebalance 0008 8 Bitstring 4 VMUTOPLU CPU usage of this VMDBK which was used to do the home DSVBK assignment. This is a scaled number where x'10000' = 100% of one CPU. 000C 12 Signed 4 VMUASNORD DSV assignment order number that represents the relative position in which this guest was visited and assigned a home by rebalance. Valid in all VMUBKs. 00000010 VMUTOPEL *-VMUTOPEN Length in bytes of an entry This DSECT maps an entry on either the ordered (RCCVMUOA) or unordered (RCCVMUUA) arrays of VMUBKs built by the guest CPU usage prediction routine and used by the rebalance function.
 VMUARYEN DSECT Top of page
Hex Dec Type/Val Lng Label (dup) Comments ---- ---- --------- ---- -------------- -------- 0000 0 Structure VMUARYEN Virtual Machine CPU Usage block 0000 0 Address 4 VMUARYAD VMUBK address for this entry 0004 4 Signed 4 VMUARYUS Guest total predicted CPU usage for this entry. This is a scaled number where x'10000' represents 100% of one CPU. 00000008 VMUARYEL *-VMUARYEN Size of an entry in bytes
 
 
  VMUBK Storage Layout Top of page
 
          
*** VMUBK - Virtual Machine CPU Usage block
*
*     +---------------------------+---------------------------+
*   0 |         VMUVMDBK          |         VMUHLPBK          |
*     +---------------------------+---------------------------+
*   8 |                       VMUTTSUI                        |
*     +---------------------------+---------------------------+
*  10 |         VMUTPUSG          |         VMULIUSG          |
*     +---------------------------+---------------------------+
*  18 |         VMUVMDLU          |         VMUMAXLU          |
*     +---------------------------+---------------------------+
*  20 |                                                       |
*     =                       VMULUSGT                        =
*     |                                                       |
*     +---------------------------+---------------------------+
*  38 |         VMUNRBAL          |                           |
*     +---------------------------+                           |
*  40 |                                                       |
*     =                       VMUPLTL                         =
*     |                           +---------------------------+
*     |                           |                           |
*     +---------------------------+                           |
*  58 |                                                       |
*     =                       VMUVMTL                         =
*     |                           +---------------------------+
*     |                           |                           |
*     +---------------------------+                           |
*  70 |                                                       |
*     =                       VMUSTLTL                        =
*     |                           +-------------+------+------+
*  80 |                           |/////////////|:TOPLK|:TOPDX|
*     +---------------------------+-------------+------+------+
*  88 |         VMUREBAL          |                           |
*     +---------------------------+                           |
*  90 |                                                       |
*     =                       VMUTOPDA                        =
*     |                           +---------------------------+
*     |                           |                           |
*     +---------------------------+                           |
* 130 |                                                       |
*     =                       VMUVMDCT                        =
*     |                           +---------------------------+
* 140 |                           |        VMURSHFSQ          |
*     +---------------------------+---------------------------+
* 148 |        VMURSHFPR          |         VMUDWTCT          |
*     +---------------------------+---------------------------+
* 150 |                      VMUDWTETM                        |
*     +-------------------------------------------------------+
* 158 |                      VMUDWTTSQ                        |
*     |                                                       |
*     +---------------------------+---------------------------+
* 168 |///////////////////////////|         VMUDSPCT          |
*     +---------------------------+---------------------------+
* 170 |                      VMUDSPETM                        |
*     +-------------------------------------------------------+
* 178 |                      VMUDSPTSQ                        |
*     |                                                       |
*     +-------------------------------------------------------+
* 188 |                      VMUTTIMSQ                        |
*     |                                                       |
*     +-------------------------------------------------------+
* 198 |                       VMULPPUV                        |
*     +-------------------------------------------------------+
* 1A0
*
*** VMUBK - Virtual Machine CPU Usage block
          
*** Overlay for VMULPPUV in VMUBK
*
*     +-------------+-----------------------------------------+
* 198 |  VMUFVCPU   |                VMU6USER                 |
*     +-------------+-----------------------------------------+
* 1A0
*
*** Overlay for VMULPPUV in VMUBK
          
*** VMUTOPEN - Virtual Machine CPU Usage block
*
*     +-------------+---------------------------+------+------+
*   0 |  VMUTOPDI   |         VMUTOPDS          |:RSVD1|:TOPFL|
*     +-------------+-------------+-------------+------+------+
*   8 |         VMUTOPLU          |        VMUASNORD          |
*     +---------------------------+---------------------------+
*  10
*
*** VMUTOPEN - Virtual Machine CPU Usage block
          
*** VMUARYEN - Virtual Machine CPU Usage block
*
*     +---------------------------+---------------------------+
*   0 |         VMUARYAD          |         VMUARYUS          |
*     +---------------------------+---------------------------+
*   8
*
*** VMUARYEN - Virtual Machine CPU Usage block
 
 
  VMUBK Cross Reference Top of page
 
 
Symbol         Dspl Value
-------------- ---- -----
VMUARYAD       0000
VMUARYEL       0004 00000008
VMUARYUS       0004
VMUASNORD      000C
VMUBSIZE       019A 000001A0
VMUDSPCT       016C
VMUDSPETM      0170
VMUDSPTSQ      0178
VMUDWTCT       014C
VMUDWTETM      0150
VMUDWTTSQ      0158
VMUFADJ        0198 80
VMUFATC        0198 20
VMUFVCPU       0198
VMUFVSIE       0198 40
VMUHLPBK       0004
VMULIUSG       0014
VMULPPFL       0198 0000F000
VMULPPUV       0198
VMULUSGC       0020 00000006
VMULUSGL       0020 00000018
VMULUSGT       0020
VMUMAXLU       001C
VMUMODRB       0007 40
VMUNRBAL       0038
VMUPLTL        003C
VMUREBAL       0088
VMURROBN       0007 80
VMURSHFPR      0148
VMURSHFSQ      0144
VMURSVD1       0006
VMUSIZE        019A 00000034
VMUSTLTL       006C
VMUTOPDA       008C
VMUTOPDI       0000
VMUTOPDL       008C 000000A0
VMUTOPDS       0002
VMUTOPDX       0087
VMUTOPEL       000C 00000010
VMUTOPFL       0007
VMUTOPLK       0086
VMUTOPLU       0008
VMUTOPNE       019A 0000000A
VMUTPUSG       0010
VMUTTIMSQ      0188
VMUTTSUI       0008
VMUVCPU        0198 00000FFF
VMUVMDBK       0000
VMUVMDCL       012C 00000018
VMUVMDCT       012C
VMUVMDLU       0018
VMUVMTL        0054
VMU6USER       019A
 
This information is based on z/VM 7.3.0 Last updated on 22 Jun 2022 at 15:57:51 EDT.
Copyright IBM Corporation, 1990, 2022