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.3.0 Last updated on 22 Jun 2022 at 15:52:58 EDT.
Copyright IBM Corporation, 1990, 2022