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.2.0 Last updated on 24 Jun 2020 at 09:28:57 EDT.
Copyright IBM Corporation, 1990, 2020