MSVBK | Back to Index page

| Prolog Control Block Contents MSVBK 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.

MSVBK Prolog | Top of page

     NAME       : HCPMSVBK
     DESCRIPTION: Mappings for MAC Services Control Block
     DSECT      : MSVBK
     FUNCTION   :
                  The MSVBK structure keeps track of MAC Addresses and
                  their attributes for a specific network device.
                  Important Notice: The MSVBK Block is transmitted by Live
                  Guest Migration (LGR) from this system
                  to another.  Therefore, any changes
                  made to this control block must have
                  corresponding code in LGR logic to
                  copy the bit or byte.
     LOCATED By -
       We keep track of all allocated MSVBKs via the "Assigned
       MAC MLT Table" anchored off SLMMACTB in the "System
       Management Block" (SLMBK).  Depending if the MSVBK is
       locally or remotely owned, we also maintain the
       following MSVBK queues:
       VMDMSVBK = Chain for "Locally Owned" VDEV MSVBKs
                  assigned to a specific guest.  Anchored from
                  the BASE VMDBK only.
       SLMMSVBK = Chain for "Locally Owned" VSWITCH MSVBKs
                  anchored by SLMMSVBK.
       ASSIGNED = "Remotely Owned" VDEV MSVBKs for a MAC
       MAC MLT    currently in use by another system in a
                  SSI cluster.
                  A MSVBK that is only "Remotely Owned" is NOT
                  anchored off any queue in the system.  The
                  only pointer to a "Remotely Owned" MSVBK is
                  the "Assigned MAC MLT".  Only a *NETWORK
                  operation code 1 "Release MAC Request" or an
                  operation code 2 "Synchronize MAC Table" will
                  delete a MSVBK that is "Remotely Own".
     CREATED BY :
                  VDEV MSVBK
                  Created by the SET NIC MACID CP Command or the
                  *NETWORK System Service (HCPMLMAM)
                  VSWITCH MSVBK
                  Created by entry point HCPMLMVS.
     DELETED BY :
                  VDEV MSVBK
                  Deleted at virtual machine LOGOFF or by the *NETWORK
                  System Service.
                  VSWITCH MSVBK
                  Deleted at DETACH VSWITCH by HCPMLMVS.
     SERIALIZED :
                  For VDEV MSVBKs:
                  Compare and swap logic serializes additions to the
                  MSVBK chain.
                  For VSWITCH MSVBKs:
                  The SLMMACLK serializes changes to the chain.  An
                  MSVBK is created at VSWITCH LANBK creation and
                  deleted by DETACH VSWITCH.
                  MSVLKWRD serializes changes to a single MSVBK.
     RELOCATION CONSIDERATIONS : This control block is relocated as part of a live
                  guest relocation (LGR).  The bits and fields that
                  need to be relocated are defined in the
                  corresponding LGRMSVBK COPY file.  Whenever changes
                  are made to this control block, consideration must
                  be given to any effects these changes will have on
                  a relocation.  If any new fields or bits are
                  defined, they may need to be relocated.  If
                  existing bits or fields are changed, corresponding
                  modifications may be required in the LGR version of
                  this control block.  Consider also the effects of
                  these changes on a relocation involving a back-level
                  release of CP.
     GENERAL NOTES      :
      . There are three MAC fields and three MAC status flags.
                  1) CURRENT MAC Address
                  The MAC Address currently assigned and possibly
                  in use by the network device.
                  2) PENDING MAC Address
                  The MAC Address to be assigned to the network
                  device when the guest reestablishes a QDIO
                  Connection.
                  3) ADAPTER MAC Address
                  The default MAC Address for a simulated network
                  adapter.  This MAC Address will be used when
                  a QDIO Connection is established on a device
                  associated with the NIC that doesn't have an
                  explicit MAC Address assigned by the SET NIC
                  MACID CP Command.
                  A pending MAC is set and allocated when a SET NIC MACID
                  is issued and its possible that the guest may still be
                  using the current MAC for an active network connection.
                  We don't want to release the current MAC until the
                  guest retrieves the MAC Address again.  This typically
                  occurs when activating a new network connection either
                  through a Diagnose or SSCH Instruction.  At which time
                  a pending MAC Address will be promoted to the current
                  MAC Address.
     2. AN MSVBK IS ALLOCATED AT THE FOLLOWING TIMES:
                  - DEFINE NIC:  A VDEV MSVBK is created for an ADAPTER
                  MAC Address and it is assigned for the base (first)
                  device number associated with the NIC.  The MSVBK
                  is added to the guest's BASE VMDMSVBK anchor.
                  - SET NIC MACID command:  An MSVBK is created for a
                  network device that is currently in or will be added
                  to a virtual machine's I/O configuration.  The MSVBK
                  is linked to the guest's BASE VMDMSVBK anchor.
                  - DIAG X'26C', SUBCODE X'30', OPCODE X'00':  An MSVBK
                  is created if one does not exist for the device
                  number requested in the diagnose parameters.  This is
                  how it is created for a dedicated device if no SET
                  NIC MACID command was issued.  The MSVBK is added to
                  the guest's BASE VMDMSVBK anchor.
                  - VSWITCH RDEV initialization:  (HCPVLCCN call to
                  HCPMLMVR) when doing back end of initialization.  The
                  MSVBK is added to the Controller's BASE VMDMSVBK
                  anchor.
                  - DEFINE VSWITCH:  (HCPSWMMA call to HCPMLMVS).  The
                  MSVBK is added to the SLMMSVBK anchor.
                  - *NETWORK System Service.  The MSVBK is added to the
                  Assigned MAC MLT for "Remotely Owned" MAC Addresses.
      . MACs allocated for simulated devices (guest NICs),
                  dedicated devices, or SET NIC MACID commands, are
                  released under the following circumstances.
                  a) LOGOFF: All local MAC addresses are released.
                  b) DIAG X'26C', Subcode X'30', Opcode X'00'issued:
                  A pending MAC is promoted to the current MAC if
                  the QDIO Connection is NOT activated.
                  c) DETACH NIC: If a pending MAC is defined, the current
                  MAC is freed and the pending MAC is promoted to the
                  current MAC.
                  d) SET NIC MACID command issued for the device number:
                  If a pending MAC is defined and allocated, the
                  pending MAC is freed and the definition replaced.
                  e) DIAG X'2A8', Operation Code 0 "Query" issued:
                  A pending MAC is promoted to the current MAC if
                  the QDIO Connection is NOT activated.
                  f) Device Reset will promote a pending MAC address to
                  the current MAC.  The old current MAC is released.
      . A MAC allocated for a VSWITCH RDEV is released when the
                  RDEV connection is broken (HCPVLCDC call to HCPMLMVR).
      . A MAC allocated for a VSWITCH is released at DETACH
                  VSWITCH (HCPVLFRL call to HCPMLMVS).
      . A "Remotely Owned" MAC will be removed from the
                  Assigned MAC MLT by the *NETWORK System Service
                  when it is no longer being used by active SSI cluster
                  member.

MSVBK Control Block Content | Top of page

     MSVBK DSECT
    Top of page

    Hex   Dec Type/Val   Lng Label (dup)    Comments
    ---- ---- --------- ---- -------------- --------
    0000    0 Structure      MSVBK          Mappings for MAC Services Control Block
    0000    0 Address      4 MSVNEXT        Pointer to Next MSVBK
    0004    4 Signed       4 *              Reserved for Future IBM Use
    0008    8 Dbl-Word     8 MSVLKWRD (3)   MAC Services lock word
    0020   32 Signed       4 MSVVDEVN (0)   Virtual device number
    0020   32 Bitstring    1 MSVVDFLG       Virtual Device Type Flag
              1... ....      MSVVSWIT       X'80' MSVVSWIT Indicates VSWITCH
                                            pseudo-VDEV number
    0021   33 Bitstring    1 *              Reserved for future IBM use
    0022   34 Signed       2 MSVDEV#        Virtual Device Number
    0024   36 Signed       4 MSVVMDBK       VDEV MSVBKs: Base VMDBK of owner
                                            VSWITCH MSVBKs: SYSTEM VMDBK
          MSVBK Status Flag
          MSVDIAG  -  MAC Address was assign to the network device
                      by a Diagnose x'26C'.
          MSVLOCAL -  is an internal indication used by MAC Services
                      indicating the CURRENT, PENDING and ADAPTER
                      MAC Addresses in this MSVBK block are
                      currently assigned to a network device,
                      adapter or VSWITCH on this image of z/VM.
          MSVREMOT -  is an internal indication used by MAC Services
                      indicating one or more MAC Addresses assigned
                      to this device is currently assigned to a
                      network device, adapter or VSWITCH in another
                      member of a SSI cluster.  The "Remotely" owned
                      MACs in the MSVBK are indicated in the MAC
                      Services Flag for each MAC Address.
          Notes      : Dual "Local" and Remote" ownership of a MSVBK will
                occur when a Live Guest Migration (LGR) is active.
                Until LGR processing determines which guest will
                resume running after the migration, the MAC
                Addresses assigned to the guest must be owned by
                both systems.
    0028   40 Bitstring    1 MSVSTAT        MSVBK status flag
              1... ....      MSVDIAG        X'80' MSVDIAG Diagnose x'26C'
                                            subcode x'30' issued
              .1.. ....      MSVLOCAL       X'40' MSVLOCAL Locally defined
                                            MAC Address
              ..1. ....      MSVREMOT       X'20' MSVREMOT Remotely defined
                                            MAC Address
              .11. ....      MSVDUAL        MSVLOCAL+MSVREMOT MSVDUAL Local
                                            and Remote Owned MAC
          MAC Protection
    0029   41 Bitstring    1 MSVMACPR       Current MACProtect setting
                                            MSVMACPR Codes defined by
                                            HCPSLMBK SLMMACPR
    002A   42 Signed       2 MSVROWN        SSI Slot ID of owning system for
                                            a REMOTELY OWNED MAC
    002C   44 Signed       4 *              Reserved for Future IBM Use
          CURRENT MAC Address Entry
    0030   48 Character    6 MSVCMAC (0)    CURRENT MAC address field
    0030   48 Bitstring    3 MSVCMACP       CURRENT MAC Prefix field
    0033   51 Bitstring    3 MSVCMACS       CURRENT MAC Suffix (MACID) field
    0036   54 Bitstring    1 MSVCFL         CURRENT MAC Services Flag HCPNIC
                                            has a dependency that this field
                                            follows MSVCMAC
              1... ....      MSVXFLAL       X'80' MACID is allocated
              ...1 ....      MSVXFNMG       X'10' Non-MANAGED MAC Address
              .... 1...      MSVXFLUS       X'08' USER MACID requested
              .... .1..      MSVXFLSY       X'04' SYSTEM MACID requested
              .... ..1.      MSVXFLAD       X'02' MACID is an ADAPTER MAC
              .... ...1      MSVXFLRM       X'01' MACID is "Remotely" Owned
    0037   55 Bitstring    1 *              Reserved for Future IBM Use
          PENDING MAC Address Entry
    0038   56 Character    6 MSVPMAC (0)    PENDING MAC address field
    0038   56 Bitstring    3 MSVPMACP       PENDING MAC Prefix field
    003B   59 Bitstring    3 MSVPMACS       PENDING MAC Suffix (MACID) field
    003E   62 Bitstring    1 MSVPFL         PENDING MAC Services Flag HCPNIC
                                            has a dependency that this field
                                            follows MSVPMAC
    003F   63 Bitstring    1 *              Reserved for Future IBM Use
          ADAPTER MAC Address Entry      Specified in BASE NIC
                                              Device Only
    0040   64 Character    6 MSVAMAC (0)    ADAPTER MAC address field
    0040   64 Bitstring    3 MSVAMACP       ADAPTER MAC Prefix field
    0043   67 Bitstring    3 MSVAMACS       ADAPTER MAC Suffix (MACID) field
    0046   70 Bitstring    1 MSVAFL         ADAPTER MAC Services Flag
    0047   71 Bitstring    1 *              Reserved for Future IBM Use
          User ID of a REMOTELY OWNED MAC Address
    0048   72 Dbl-Word     8 MSVUSER        8 Byte EBCDIC of Owning User
              00000050       MSVBKSZ        *-MSVBK Size of MSVBK in bytes
              0000000A       MSVBKSZD       (*-MSVBK+7)/8 Size of MSVBK in
                                            doublewords

MSVBK Storage Layout | Top of page

    *** MSVBK - Mappings for MAC Services Control Block
    *
    *     +---------------------------+---------------------------+
    *   0 |         MSVNEXT           |///////////////////////////|
    *     +---------------------------+---------------------------+
    *   8 |                                                       |
    *     =                       MSVLKWRD                        =
    *     |                                                       |
    *     +------+------+-------------+---------------------------+
    *  20 |:VDFLG|//////|  MSVDEV#    |         MSVVMDBK          |
    *     +------+------+-------------+---------------------------+
    *  28 |:STAT |:MACPR|  MSVROWN    |///////////////////////////|
    *     +------+------+------+------+-------------+------+------+
    *  30 |     MSVCMACP       |     MSVCMACS       |MSVCFL|//////|
    *     +--------------------+--------------------+------+------+
    *  38 |     MSVPMACP       |     MSVPMACS       |MSVPFL|//////|
    *     +--------------------+--------------------+------+------+
    *  40 |     MSVAMACP       |     MSVAMACS       |MSVAFL|//////|
    *     +--------------------+--------------------+------+------+
    *  48 |                       MSVUSER                         |
    *     +-------------------------------------------------------+
    *  50
    *
    *** MSVBK - Mappings for MAC Services Control Block

MSVBK Cross Reference | Top of page

    Symbol         Dspl Value
    -------------- ---- -----
    MSVAFL         0046
    MSVAMAC        0040
    MSVAMACP       0040
    MSVAMACS       0043
    MSVBKSZ        0048 00000050
    MSVBKSZD       0048 0000000A
    MSVCFL         0036
    MSVCMAC        0030
    MSVCMACP       0030
    MSVCMACS       0033
    MSVDEV#        0022
    MSVDIAG        0028 80
    MSVDUAL        0028 60
    MSVLKWRD       0008
    MSVLOCAL       0028 40
    MSVMACPR       0029
    MSVNEXT        0000
    MSVPFL         003E
    MSVPMAC        0038
    MSVPMACP       0038
    MSVPMACS       003B
    MSVREMOT       0028 20
    MSVROWN        002A
    MSVSTAT        0028
    MSVUSER        0048
    MSVVDEVN       0020
    MSVVDFLG       0020
    MSVVMDBK       0024
    MSVVSWIT       0020 80
    MSVXFLAD       0036 02
    MSVXFLAL       0036 80
    MSVXFLRM       0036 01
    MSVXFLSY       0036 04
    MSVXFLUS       0036 08
    MSVXFNMG       0036 10

This information is based on z/VM 7.2.0 Last updated on 24 Jun 2020 at 09:29:18 EDT.
Copyright IBM Corporation, 1990, 2020