LIMBK Back to Index page
 
Prolog 
Control Block Contents 
   LIMBK 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.


  LIMBK Prolog Top of page
 
 NAME       : HCPLIMBK
 DESCRIPTION: Limiting block for a CPU Pool
              ===      =   =
 DSECT      : LIMBK
 FUNCTION   : This control block holds all of the fields which describe
              ONE defined CPU Pool. A CPU Pool limits virtual CPU
              resources of one type (CP or IFL) for a group of userids.
 LOCATED BY : LCPNEXT:  LIMBK chain pointer to NEXT (FIRST) LIMBK
              LCPPREV:  LIMBK chain pointer to PREVIOUS (LAST) LIMBK
              LIMNEXT:  LIMBK chain FORWARD pointer to NEXT LIMBK
              LIMPREV:  LIMBK chain BACKWARD pointer to PREVIOUS LIMBK
              Only the DEFINE CPUPOOL and DELETE CPUPOOL
              commands update the above four fields.
              VMDLIMBK: VMDBK points to the LIMBK of the CPU Pool it
              belongs to.  When a user is assigned to a CPU
              Pool, all VMDBKs (origin, MP-VMDBKs)
              to be limited have VMDLIMBK set.  Only the
              SCHEDULE command and VMRELOCATE command update
              this field.
              RLOLIMBK: Relocating user's RLOBK on the target system
              points to the LIMBK of the CPU Pool it will
              belong to once on the target system so it
              can not be deleted during the move.  Only the
              VMRELOCATE command updates this field.
 CREATED BY : HCPLMCDF:  Process DEFINE CPUPOOL command
 DELETED BY : HCPLMCDL:  Process DELETE CPUPOOL command
 REFERENCES : NONE
 SERIALIZED : The creation/deletion of the LIMBK is serialized by the
              LIMBK CHAIN LOCK, LCPLLCK.  DEFINE CPUPOOL and DELETE
              CPUPOOL are the only commands that create/delete LIMBKs.
              A LIMBK may not be dequeued or released if its LIMCTPTR
              field is nonzero because at least one VMDBK VMDLIMBK field
              or RLOBK RLOLIMBK field contains its address.
              The fields in the LIMBK are serialized by the LIMBK CHAIN
              LOCK and/or the SCHEDULER LOCK and/or the VMDBK List Lock.
              The LIMBK CHAIN LOCK must be held exclusively to enqueue/
              dequeue a LIMBK or to update any of the LIMBK fields in
              the first section of the control block.  It must be held
              shared to search the LIMBK chain and examine the LIMBK's
              fields in the first section of the control block which do
              not require the SCHEDULER LOCK to update.
              Any field that requires two locks (LIMBK CHAIN LOCK and
              SCHEDULER LOCK) to update it only requires one of these
              locks to read/examine it.
              Scheduling-related fields in the LIMBK are serialized by
              the SCHEDULER LOCK and are located in the second section
              of the LIMBK.  The scheduler finds the correct LIMBK
              from the VMDBK of the user being processed so it does not
              need to obtain the LIMBK CHAIN LOCK (LCPLLCK) to find the
              correct LIMBK.  In addition, only the SCHEDULER LOCK held
              EXCLUSIVE is needed to update these fields. A comment
              specifies which fields are serialized in this way.
              While the VMDBK List Lock is not needed to serialize the
              fields in the LIMBK, while changes are being made for the
              SET command, the VMDBK List Lock is held to keep other
              tasks from using the list until the settings are changed.
              To add or remove a CPU Pool member, the LIMBK CHAIN LOCK,
              SCHEDULER LOCK EXCLUSIVE, user's LOCAL CYCLIC LIST LOCK,
              and VMDBK List Lock are needed (must be obtained in that
              order). Once all 4 are obtained, the VMDLIMBK pointer(s)
              and count fields (LIMCTMEM, LIMCTPTR) in the LIMBK can be
              updated.  To ensure that the relationship between a VMDBK
              and LIMBK can not change, only ONE lock (LIMBK CHAIN LOCK
              or SCHEDULER LOCK) is needed.  This allows the scheduler
              code which already has the SCHEDULER LOCK EXCLUSIVE (and
              can not get the other ones) to use the VMDLIMBK pointer
              to get to the LIMBK knowing the link can not be broken.
              When the Scheduler lock and VMD List Lock (LIMVMDLK) need
              to be held concurrently, the Scheduler Lock must be
              acquired first.
 RELOCATION CONSIDERATIONS : None
 COMPATIBILITY AND MIGRATION CONCERNS : Each field in this control block must specify how it is
              serialized.  The only locks used for CPU Pooling fields
              are LIMBK CHAIN LOCK, SCHEDULER LOCK and VMDBK List Lock.
              The 1/19/2011 version of BICOPY VMSKEL was used to create
              this new control block.
 
 
  LIMBK Control Block Content Top of page
 

 LIMBK DSECT Top of page
Hex Dec Type/Val Lng Label (dup) Comments ---- ---- --------- ---- -------------- -------- 0000 0 Structure LIMBK Limiting block for a CPU Pool **** SECTION 1: Fields changed via the CPU Pooling Commands These are usually serialized by LIMBK CHAIN LOCK (LCKLLCK). See below for full comments. 0000 0 Address 4 LIMNEXT Next LIMBK address Serialized by LIMBK CHAIN LOCK 0004 4 Address 4 LIMPREV Previous LIMBK address Serialized by LIMBK CHAIN LOCK 0008 8 Character 8 LIMPOOL CPU pool name Serialized by LIMBK CHAIN LOCK 0010 16 Signed 4 LIMCTMEM Count of CPU pool members (ie: number of ORIGIN VMDBKs and RLOBKs for users relocating to this system that point to this LIMBK) Query CPUPOOL reports this value. Update serialized by LIMBK CHAIN LOCK & SCHEDULER LOCK EXCLUSIVE Read serialized by 1 of these 2 locks held SHARED or EXCLUSIVE. 0014 20 Signed 4 LIMMXSHR CPU pool maximum absolute share (LIMITHARD). 0 means NO LIMIT. (Analog of VMDMXSHR) Update serialized by LIMBK CHAIN LOCK & SCHEDULER LOCK EXCLUSIVE Read serialized by 1 of these 2 locks held SHARED or EXCLUSIVE. Unit of value is a hexadecimal factor scaled 16 bits. For example, X'00010000' = 1.00(100%), X'0000C000' = 0.75(75%),etc The range is 1% to 100%. The value is a percentage of the real CPUs on which the virtual CPU type is currently being dispatched. For example: If this is 70% for virtual CP engines and the system has 3 real CP CPUs, the limit is 70% x 3 CPUs = 2.10 CPUs. 0018 24 Signed 4 LIMMXENG CPU pool maximum engine share (CAPACITY). 0 means NO LIMIT. Update serialized by LIMBK CHAIN LOCK & SCHEDULER LOCK EXCLUSIVE Read serialized by 1 of these 2 locks held SHARED or EXCLUSIVE. Unit of value is a hexadecimal factor scaled 16 bits. For example, X'00010000' = 1.00(100%), X'0000C000' = 0.75(75%),etc The range is 0.01 to 999. The value is the number of CPUs of the virtual CPU type. For example: 0.7 = 70% = 0.7 CPUs 2.1 = 210% = 2.1 CPUs 001C 28 Bitstring 1 LIMCPUTY Virtual CPU type that this CPU pool is limiting. Currently, this can only be CP or IFL. Once it is set in HCPLMCDF (DEFINE command), it cannot be changed. 001D 29 Bitstring 1 * Reserved for IBM use 001E 30 Signed 2 LIMMXSTP CPU Pool storage limit percent in hundredths. 0 means NO LIMIT. 0020 32 Dbl-Word 8 LIMMXSTO CPU Pool storage limit in frames. 0 means NO LIMIT. 0028 40 Signed 4 * Reserved for IBM use 002C 44 Signed 4 LIMCTINM Count of incoming members (RLOBKs) pointing to this LIMBK. This is incremented during VSIM eligibility test for move and decremented when the CPU type is set in the dest ORIGIN VMDBK and RLOLIMBK is moved to VMDLIMBK. Update serialized by LIMBK CHAIN LOCK held exclusive. Read serialized by LIMBK CHAIN LOCK held shared or exclusive. **** SECTION 2: Fields changed by the CP SCHEDULER code These are usually serialized by SCHEDULER LOCK held EXCLUSIVE. See below for full comments. 0030 48 Signed 4 LIMCTPTR Count of VMDBKs and RLOBKs pointing to this LIMBK. Includes VMDBKs (origin, MP-VMDBKs) and RLOBKs only. LIMCTPTR >= LIMCTMEM. Update serialized by LIMBK CHAIN LOCK & SCHEDULER LOCK EXCLUSIVE Read serialized by 1 of these 2 locks held SHARED or EXCLUSIVE. 0034 52 Signed 4 LIMCTLL Count of VMDBKs on the Limit- List because the group limit was hit. Includes VMDBKs (origin, MP-VMDBKs) LIMCTPTR >= LIMCTLL always. Serialized by SCHEDULER LOCK held EXCLUSIVE 0038 56 Bitstring 1 LIMFLAGS Limit flags Serialized by SCHEDULER LOCK held EXCLUSIVE 1... .... LIMITED X'80' LIMITED CPU Pool is limited The users in this CPU Pool have hit the group CPU resource limit and are being limited. When set, at least one user in the group should be on the limit list and time used is counted in the NEXT group interval (via LIMNTIME). .1.. .... LIMFAIR X'40' LIMFAIR Use fair share memory limiting 0039 57 Bitstring 1 LIMRSTRT Reason STaRTed the last group interval (for DEBUG ONLY) Serialized by SCHEDULER LOCK held EXCLUSIVE 00000001 LIMRLIML X'01' LIMRLIML - Remove from Limit List VMDBKs that were being limited due to the group limit (VMDLIMGR = ON) were removed from the limit list. Their time was served. 00000002 LIMRNACT X'02' LIMRNACT - No activity (LIMTODST is 0) There are NO users in the CPU pool (LIMCTMEM = 0) so there is no activity. A new group interval is started when the group becomes active again. 00000003 LIMRSET X'03' LIMRSET - Set command issued The SET CPUPOOL command was issued when the group was not limited. 00000004 LIMRCPUA X'04' LIMRCPUA - IFL CPU Affinity toggled A system change caused CPU Affinity to toggle while the group was not limited. 00000005 LIMRST0 X'05' LIMRST0 - Just Starting (LIMTODST was 0) A user is being added to the dispatch list after a period of group inactivity and LIMTODST = 0 so need to initialize it. 00000006 LIMRHITX X'06' LIMRHITX - Hit GRINTMAX second interval The group is not being limited but it has been GRINTMAX seconds since LIMTODST was reset. 00000007 LIMRPAST X'07' LIMRPAST - LIMTODLM is in the PAST A new group interval was not started at LIMTODLM because no VMDBK was on the limit list at that time (all were taken off early). Start one now this CPU pool. The CPU pool has been inactive since it was defined on the system. LIMTODST was reset because: 003A 58 Bitstring 2 * Reserved for IBM Use 003C 60 Signed 4 LIMCIFLA Sequence number of the IFL CPU Affinity toggle that is currently being processed. Since each user in this CPU pool will visit this LIMBK once, this value is used to ensure only one group interval is started for each CPU Affinity change/toggle. NOTE: ONLY used for CPU pools that are limiting virtual IFLs 0040 64 Signed 8 LIMTODST Group limit interval start TOD (Analog of VMDTODST) Serialized by SCHEDULER LOCK held EXCLUSIVE 0048 72 Signed 8 LIMTODLM Group limit list expiration TOD (Analog of VMDTODLM) If MT is enabled, this field is calculated from prorated core time; Otherwise, this field is calculated from raw CPU time. Serialized by SCHEDULER LOCK held EXCLUSIVE 0050 80 Signed 8 LIMTTIME Total TTIME consumed by users in this CPU pool in the current group interval. If the group is not being limited, time used is added here until the limit is hit and applied to the current group interval. If MT is enabled, this field contains prorated core time; Otherwise, this field contains raw CPU time. Serialized by SCHEDULER LOCK held EXCLUSIVE 0058 88 Signed 8 LIMNTIME Total TTIME consumed by users in this CPU pool to be counted in the next group interval. When the group is limited, some VMDBKs are on the limit list and some VMDBKs can still run until end of time slice. Time used by running VMDBKs is tracked and added to the next group interval. If MT is enabled, this field contains prorated core time; Otherwise, this field contains raw CPU time. Serialized by SCHEDULER LOCK held EXCLUSIVE 0060 96 Signed 8 LIMMTTIM FOR MONITOR ONLY: Total TTIME consumed by users in the CPU pool since it was created Always increasing. If MT is enabled, this field contains prorated core time; Otherwise, this field contains raw CPU time. Serialized by LIMMONLK LOCK held EXCLUSIVE 0068 104 Signed 8 LIMMTODE FOR MONITOR ONLY: TOD when most recent limiting interval for CPU pool ended. Serialized by LIMMONLK LOCK held EXCLUSIVE 0070 112 Signed 4 LIMMTNUM FOR MONITOR ONLY: Total NUMber of times the CPU pool has been limited since the CPU pool was created. Always increasing. Add 1 when group limiting ends. Serialized by LIMMONLK LOCK held EXCLUSIVE 0074 116 Signed 4 LIMFACTR Limit factor - most recently computed group limit, scaled, in terms of number of CPUs 0078 120 Dbl-Word 8 LIMMONLK (6) Monitor data spin lock 00A8 168 Dbl-Word 8 LIMSTORE Total page frames consumed 00B0 176 Dbl-Word 8 LIMRESTO Total page frames reserved 00B8 184 Signed 4 LIMTRQBK Asynch runner of group memory trim routine 00BC 188 Signed 4 * Reserved for IBM use 00C0 192 Dbl-Word 8 LIMVMDLK (6) LIMVMDLS exclusive-only formal spinlock. 00F0 240 Dbl-Word 8 LIMVMDLS (0) Anchor for doubly-linked list of origin VMDBKs in the group. Ptrs = A(LIMVMDLS) when empty. Serialized by LIMVMDLK. 00F0 240 Signed 4 LIMVMDLSF LIMVMDLS forward pointer. 00F4 244 Signed 4 LIMVMDLSB LIMVMDLS backward pointer. 00F8 248 Bitstring 1 LIMMEMFL Memory flag byte 1... .... LIMMEMHX X'80' LIMMEMHX This flag tells the asynch task running via LIMTRQBK to stop running and to fret the TRQBK .1.. .... LIMLIMHX X'40' LIMLIMHX Should only be on when LIMMEMHX is on; additionally tells asynch task to fret the LIMBK too 00F9 249 Bitstring 1 LIMHXSYN TS lock to synchronize clearing of LIMTRQBK and LIMMEMHX/LIMHX 00FA 250 Signed 2 LIMTSMLT Time slice multiplier for setting the next trim task timer pop 00FC 252 Bitstring 1 * (4) reserved for IBM use 0100 256 Character 8 LIMCREAT Pool creator's user ID 0108 264 Signed 8 LIMLIMTM Cumulative elapsed time pool members have been limited 0110 272 Signed 4 LIMLIMCT Total number of pool members limited 0114 276 Signed 4 LIMMXCED Total number of times pool memory limit exceeded 0118 280 Dbl-Word 8 LIMMOVER Cumulative number of frames by which pool exceeded memory limit 0120 288 Dbl-Word 8 LIMMTRIM Cumulative number of frames trimmed from pool members 0128 296 Dbl-Word 8 LIMSTAMP TOD pool definition last changed 0130 304 Dbl-Word 8 LIMTRCPU Cumulative CPU time consumed trimming 00000027 LIMSIZE (*-LIMBK+7)/8 size in double words 00000138 LIMBSIZE LIMSIZE*8 size in bytes
 
 
  LIMBK Storage Layout Top of page
 
          
*** LIMBK - Limiting block for a CPU Pool
*
*     +---------------------------+---------------------------+
*   0 |         LIMNEXT           |         LIMPREV           |
*     +---------------------------+---------------------------+
*   8 |                       LIMPOOL                         |
*     +---------------------------+---------------------------+
*  10 |         LIMCTMEM          |         LIMMXSHR          |
*     +---------------------------+------+------+-------------+
*  18 |         LIMMXENG          |:CPUTY|//////|  LIMMXSTP   |
*     +---------------------------+------+------+-------------+
*  20 |                       LIMMXSTO                        |
*     +---------------------------+---------------------------+
*  28 |///////////////////////////|         LIMCTINM          |
*     +---------------------------+---------------------------+
*  30 |         LIMCTPTR          |         LIMCTLL           |
*     +------+------+-------------+---------------------------+
*  38 |:FLAGS|:RSTRT|/////////////|         LIMCIFLA          |
*     +------+------+-------------+---------------------------+
*  40 |                       LIMTODST                        |
*     +-------------------------------------------------------+
*  48 |                       LIMTODLM                        |
*     +-------------------------------------------------------+
*  50 |                       LIMTTIME                        |
*     +-------------------------------------------------------+
*  58 |                       LIMNTIME                        |
*     +-------------------------------------------------------+
*  60 |                       LIMMTTIM                        |
*     +-------------------------------------------------------+
*  68 |                       LIMMTODE                        |
*     +---------------------------+---------------------------+
*  70 |         LIMMTNUM          |         LIMFACTR          |
*     +---------------------------+---------------------------+
*  78 |                                                       |
*     =                       LIMMONLK                        =
*     |                                                       |
*     +-------------------------------------------------------+
*  A8 |                       LIMSTORE                        |
*     +-------------------------------------------------------+
*  B0 |                       LIMRESTO                        |
*     +---------------------------+---------------------------+
*  B8 |         LIMTRQBK          |///////////////////////////|
*     +---------------------------+---------------------------+
*  C0 |                                                       |
*     =                       LIMVMDLK                        =
*     |                                                       |
*     +---------------------------+---------------------------+
*  F0 |        LIMVMDLSF          |        LIMVMDLSB          |
*     +------+------+-------------+---------------------------+
*  F8 |:MEMFL|:HXSYN|  LIMTSMLT   |///////////////////////////|
*     +------+------+-------------+---------------------------+
* 100 |                       LIMCREAT                        |
*     +-------------------------------------------------------+
* 108 |                       LIMLIMTM                        |
*     +---------------------------+---------------------------+
* 110 |         LIMLIMCT          |         LIMMXCED          |
*     +---------------------------+---------------------------+
* 118 |                       LIMMOVER                        |
*     +-------------------------------------------------------+
* 120 |                       LIMMTRIM                        |
*     +-------------------------------------------------------+
* 128 |                       LIMSTAMP                        |
*     +-------------------------------------------------------+
* 130 |                       LIMTRCPU                        |
*     +-------------------------------------------------------+
* 138
*
*** LIMBK - Limiting block for a CPU Pool
 
 
  LIMBK Cross Reference Top of page
 
 
Symbol         Dspl Value
-------------- ---- -----
LIMBSIZE       0130 00000138
LIMCIFLA       003C
LIMCPUTY       001C
LIMCREAT       0100
LIMCTINM       002C
LIMCTLL        0034
LIMCTMEM       0010
LIMCTPTR       0030
LIMFACTR       0074
LIMFAIR        0038 40
LIMFLAGS       0038
LIMHXSYN       00F9
LIMITED        0038 80
LIMLIMCT       0110
LIMLIMHX       00F8 40
LIMLIMTM       0108
LIMMEMFL       00F8
LIMMEMHX       00F8 80
LIMMONLK       0078
LIMMOVER       0118
LIMMTNUM       0070
LIMMTODE       0068
LIMMTRIM       0120
LIMMTTIM       0060
LIMMXCED       0114
LIMMXENG       0018
LIMMXSHR       0014
LIMMXSTO       0020
LIMMXSTP       001E
LIMNEXT        0000
LIMNTIME       0058
LIMPOOL        0008
LIMPREV        0004
LIMRCPUA       0039 00000004
LIMRESTO       00B0
LIMRHITX       0039 00000006
LIMRLIML       0039 00000001
LIMRNACT       0039 00000002
LIMRPAST       0039 00000007
LIMRSET        0039 00000003
LIMRSTRT       0039
LIMRST0        0039 00000005
LIMSIZE        0130 00000027
LIMSTAMP       0128
LIMSTORE       00A8
LIMTODLM       0048
LIMTODST       0040
LIMTRCPU       0130
LIMTRQBK       00B8
LIMTSMLT       00FA
LIMTTIME       0050
LIMVMDLK       00C0
LIMVMDLS       00F0
LIMVMDLSB      00F4
LIMVMDLSF      00F0
 
This information is based on z/VM 7.3.0 Last updated on 22 Jun 2022 at 15:52:11 EDT.
Copyright IBM Corporation, 1990, 2022