VCTC Support in VM/ESA - Logic in CP

This section is intended to help you find your way from an external action (e.g. QUERY VIRTUAL 500) to the internal routines in VCTC simulation that are invoked.

This following external actions are included:

Define an Adapter

This can be done via the CP DEFINE command, or by the action of the "SPECIAL" statement in the directory at LOGON time.

Related VCTC code:

  • Entry Point HCPCTVDF is invoked by the general virtual device definition logic to create the CACBK extension for the VDEV.

The adapter is "uncoupled" when it is first created. That means the CACXSIDE half of the CACBK is linked to its own "null" CACYSIDE to represent an adapter with no connection to the other side.

CP will simulate I/O for an uncoupled adapter, and it behaves much like a "real" adapter when the "other" system is not running. Independent commands can be performed immediately, but dependent commands are suspended to wait for a complementary Y-SIDE operation.

Most operations are processed as if a normal connection exists. When it is important to know if the Y-SIDE is disconnected (e.g. when CP would normally generate an interrupt for the Y-SIDE user) CP tests flag byte CACYAFLG, bit CACADISC.

Couple an Adapter

This can only be done via the CP COUPLE command.

Related VCTC code:

  • Entry Point HCPCPLCP is invoked by the CP command handler to process the "COUPLE" command. This routine will parse the command line, validate the target, and call entry point HCPCTVCP.
  • Entry Point HCPCTVCP is invoked by the COUPLE command handler to interconnect the two halves of the adapter.

The adapter is "coupled" after this point. That means the CACXSIDE half of one CACBK is linked to the CACXSIDE half of the other CACBK to represent an adapter that is connected to each side. While the two virtual devices are coupled, operations performed on one side will be reflected on the other side (as determined by the CTCA architecture).

While the two sides are "coupled" they share:

  • a CP Lock Word (LKWRD) found by the pointer CACXLOCK and CACYLOCK.
  • an internal buffer (CABFR) found by the pointer CACXBUFF and CACYBUFF.

    Detach an Adapter

    This can be done via the CP DETACH command, or will be done automatically when the owning user logs off the system.

    Related VCTC code:

    • Entry Point HCPCTVDT is invoked by the general virtual device configuration logic to reset the device and delete the VDEV extension (the CACBK).
    • Entry Point HCPCTVDX is invoked by HCPCTVDT to release the CACBK and any related storage. If any activity is pending (check the CACXACTR) when the adapter is detached, this call will be delayed until the last pending task is ready to release the adapter lock.

    Reset an Adapter

    Several CP commands and operations exist that could reset the adapter:

    • CP RESET xxxx (Selective Reset for device "xxxx").
    • CP SYSTEM RESET (System Reset for each device).
    • CP IPL (System Reset for each device).
    • CP LOGOFF (Interface Disconnect for each device before DETACH processing).
    • Execution of a halt or clear function via the I/O interface.

    Related VCTC code:

    • Entry Point HCPCTVSY is invoked to perform a System Reset. This is a normal part of CP IPL or CP SYSTEM RESET.
    • Entry Point HCPCTVSR is invoked to perform a Selective Reset. This is a normal part of CP RESET, or execution of a Clear Subchannel, Clear I/O, or Clear Device instruction.
    • Entry Point HCPCTVID is invoked to perform an Interface Disconnect. This is a normal part of CP DETACH, or execution of a Halt Subchannel, Halt I/O, or Halt Device instruction.
    • Entry Point HCPCTCHX may be invoked by any of the above reset routines if the channel program on either side of the adapter is suspended. This entry point will cancel the suspended task and stack the associated CPEBK to return to the caller.

    Query an Adapter

    The CP QUERY "vaddr" command will display information about the designated virtual device.

    Related VCTC code:

    • Entry Point HCPCTVQA is called by the CP query modules (specifically module HCPQVD) to get information for the command response. If the adapter is coupled, HCPCTVQA returns the userid and virtual device address of the "other" side of the adapter.

    Execute an I/O Command

    When an application running in a Virtual Machine, it executes a series of I/O commands (called a channel program) using the SIO, SIOF, or SSCH instruction. The general I/O simulation is responsible for "driving" the channel program (finding the next CCW, resolving the storage address, and maintaining virtual device I/O status). The virtual device simulation is called for each I/O command (also called a Channel Command Word, or CCW). Then, the device simulation must call general I/O routines to alter the virtual device I/O status).

    Related VCTC code:

    • Entry Point HCPCTCVS is called by HCPIOVOP to simulate the execution of an I/O command (CCW) on the designated virtual device (represented by a VDEV with a CACBK extension).
    • HCPCTCVS calls entry point HCPIOVUS to reflect Unit Status, like Channel End (CE), for the virtual device.
    • HCPCTCVS calls entry point HCPIOVMV to move data between the user's virtual storage and the adapter's internal buffer. For example, a Sense ID CCW (X'E4') requires a call to HCPIOVMV to transfer the response to the virtual address specified in the channel program.
    • HCPCTCVS calls entry point HCPCTVUI to reflect unsolicited interrupts (like an Attention interrupt) for the designated virtual device. This is an indirect (stacked) call because it is normally invoked to reflect an interrupt for the "other" side of the adapter. For example, when user(X) executes a Write CCW, the Unsolicited ATTN interrupt must be presented to user(Y).
    • HCPCTCVS calls entry point HCPCTVBM to switch from Extended Mode to Basic Mode.
    • HCPCTCVS calls entry point HCPCTVDX to destroy an obsolete CACBK when it is time to release the adapter lock.

    (Back to VCTC Main Document)