Virtual CTCA Terminology
The following terms are used extensively in the material that describes the Channel-to-Channel Adapter (CTCA):
These terms are also used to document the code that handles Virtual CTCA simulation.
X-SIDE and Y-SIDE terminology
The Channel-to-Channel adapter is designed to link two systems, giving each system a channel interface that behaves like an I/O device. The specifications for this I/O interface describe the "device" connected to the initiating an event as the "X side of the adapter" (or X-SIDE) and the "device" connected to the opposite system as the "Y side of the adapter" (or the Y-SIDE). It is important to note that these labels (X-SIDE verses Y-SIDE) are NOT static. The perspective can change depending on which side of the adapter initiated the subject operation. For example:
- System A initiates a control command to an idle adapter. The control command is accepted on the X-SIDE (System A) and suspended.
- Next, System B initiates a sense-command-byte command. The sense-command-byte command is accepted on the X-SIDE (System B) and completes the Y-SIDE (System A) control command.
X-SIDE of the Adapter
In general, you can think of the X-SIDE of the adapter as "this" virtual device, and the Y-SIDE as the "other" device. The two sides of the adapter are symmetric, so the terms are interchangeable. They are used in the hardware specifications and the CP commentary to express the side in the context of a specific operation.
In CP code, the X-SIDE of the adapter is referenced using the CACXSIDE fields of the CACBK control block.
See X-SIDE and Y-SIDE for more information.
Y-SIDE of the Adapter
In general, you can think of the Y-SIDE of the adapter as the "other" virtual device, and the X-SIDE as "this" device. The two sides of the adapter are symmetric, so the terms are interchangeable. They are used in the hardware specifications and the CP commentary to express the side in the context of a specific operation.
In CP code, the Y-SIDE of the adapter is referenced using the CACYSIDE fields of the CACBK control block.
See X-SIDE and Y-SIDE for more information.
Basic Mode and Extended Mode terminology
The terms "Basic Mode" and "Extended Mode" refer to the protocol that is in effect for the adapter.
The Virtual CTCA (like the 3088 hardware) is in Basic Mode
while both sides of the adapter are set to Basic Mode.
If either side of the adapter is set to Extended Mode,
the active protocol for both sides becomes Extended Mode.
Basic Mode
"Basic Mode" uses a limited set of commands to provide basic data transfer. Significant features of "Basic Mode" are:
- Write End of File (WEOF) CCW is treated as a traditional Write CCW.
- Unit Check device status is not used. When a data transfer fails, the residual length must be used to determine the number of bytes that were actually transferred.
- Sense Adapter State (X'04') CCW is treated as a Sense Command Byte function.
- READY and NOTREADY states are not defined. When the other side of the adapter is inactive, any "dependent" command initiated on this side will be suspended until the partner responds.
The original CTCA hardware only operated in "Basic Mode."
The 3088 hardware operates in "Basic Mode" or
"Extended Mode" under control
of the application programs.
Extended Mode
"Extended Mode" uses additional commands and status information to provide data transfer. Significant features of "Extended Mode" are:
- Write End of File (WEOF) CCW is supported. This allows an application to signal the partner (who might be executing a long chain of Read commands) that there is no more data to transmit. This is more efficient than writing a series of empty buffers to match the partner's Read chain.
- Unit Check device status is used to reflect a device error (e.g. NOTREADY).
- Sense Adapter State (X'04') CCW is supported to retrieve sense data pertaining to the current failure (e.g. Intervention Required).
- READY and NOTREADY states are defined.
Standard Mode
"Standard Mode" is the default operational mode for the ESCON device. When the ESCON control device is an "SCTC" the adapter operates in Standard Mode. The ESCON Standard Mode is fundamentally the same as the 3088 Extended Mode with the following exceptions:
- The ESCON SCTC device can never enter Basic Mode.
- The ESCON CNC device can only be switched to Basic Mode by being COUPLEd to an ESCON BCTC device.
- The 3088 "Set Basic Mode" CCW (x'C3') is treated as a NOP (the adapter remains in Standard Mode).
- Reset operations (Halt, Clear, or System Reset) leave the adapter in Standard Mode.
Adapter States
System/390 Channel Architecture defines the state of a
given device as Available, Interruption Pending, or Working.
The behavior of the CTCA working on a Dependent command is
significantly different than the traditional Working state,
so both are included in the list of Adapter States:
Since the operation of either side may also be affected by the state of the other side, the adapter function is generally described based on the following CTCA cases:
CASE 1: x = A, y = W(D) CASE 2: x = A, y = A, I, or W(C) CASE 3: x = W, y = any state CASE 4: x = I, y = any state
CACBK Extension for VCTC
One CACBK is created for a VCTC device when it is defined. The CACBK definition maps two symmetrical structures (CACXSIDE and CACYSIDE) which MUST be interchangeable. Since the VCTC is NOT initially connected (or coupled) at that point, the CACBK is defined with enough space to map both parts. The CACYSIDE part of the CACBK storage is only used when the the adapter is uncoupled. The rest of the time, the CACYSIDE fields are used to map the CACXSIDE portion of THIS CACBK or the OTHER CACBK.
Serialization for a specific adapter is maintained using:
- The Adapter Lock for normal I/O simulation
- The VCTC Global Lock for configuration changes
Each side of the CACBK contains status flags and buffers to represent the equivalent hardware latches for one side of the Channel-to-Channel Adapter.
An uncoupled adapter is represented by a single virtual device. It behaves as if the "other" side of the adapter is NOT connected to any system.
Owner VDEV: VDEVCTCA = A(CACBK(X)) for the primary CACBK VDEVINTV = 1 (Intervention Required) CACBK(X) at CACXSIDE using CACXSIDE: CACADISC = 0 (This side is NOT disconnected) CACXVDEV = A(VDEV) for owner CACXLINK = A(CACYSIDE) (Using the Y-SIDE definition) CACXLOCK = A(CACXLKWD) (Using the internal Adapter Lock) CACXBUFF = 0 CACBK(X) at CACYSIDE using CACYSIDE: CACADISC = 1 (This side IS disconnected) CACYVDEV = 0 (No device) CACYLINK = A(CACXSIDE) for the primary CACBK CACYLOCK = A(CACXLKWD) (Using the internal Adapter Lock) CACYBUFF = 0
A coupled adapter is represented by two virtual devices. It behaves as if both sides of the adapter are connected to live systems (represented by the VM users).
X-SIDE VDEV: VDEVCTCA = A(CACBK(X)) VDEVINTV = 0 (coupled) CACBK(X) at CACXSIDE using CACXSIDE: CACADISC = 0 (This side is NOT disconnected) CACXVDEV = A(VDEV) for X-SIDE device CACXLINK = A(CACBK(Y)) for the partner CACBK CACXLOCK = A(LKWRD) (shared Adapter Lock) CACXBUFF = A(CABFR) (shared data exchange buffer) Y-SIDE VDEV: VDEVCTCA = A(CACBK(Y)) VDEVINTV = 0 (coupled) CACBK(Y) at CACXSIDE using CACYSIDE: CACADISC = 0 (This side is NOT disconnected) CACYVDEV = A(VDEV) for Y-SIDE device CACYLINK = A(CACXSIDE) for the partner CACBK CACYLOCK = A(LKWRD) (shared Adapter Lock) CACYBUFF = A(CABFR) (shared data exchange buffer)
VCTC Serialization
The VCTC Global Lock serializes configuration changes (DEFINE, COUPLE, and DETACH) for VCTC devices. It must be held in exclusive mode whenever an operation might affect multiple VCTC devices, or whenever an operation might conflict with normal I/O simulation. The Adapter Lock is defined for each adapter (which could be represented by one or two CACBK structures). The Adapter Lock must be held in exclusive mode to reference either CACBK. Normal I/O simulation only requires the Adapter Lock. The Adapter Lock is not sufficient for configuration changes because an operation like COUPLE could involve as many as three different devices belonging to three different users. CP also maintains a VDEV Lock for each virtual device, but the VDEV Lock management is generally left to the Virtual I/O subsystem. If the VDEV lock is required for an operation, it MUST NOT be requested while holding the VCTC Global Lock or the Adapter Lock.
VCTC Global Lock
The VCTC Global Lock is a lock word as defined by HCPLKWRD. It resides in HCPIOLCT, and is never destroyed. Refer to VCTC Serialization for related information.
The VCTC Global Lock is required for:
- DEFINE operations (to avoid conflict with DETACH)
- COUPLE operations (to avoid conflict with DETACH)
- DETACH operations (to avoid conflict with DEFINE or COUPLE).
All other operations can be initiated and performed without obtaining the VCTC Global Lock.
VCTC Adapter Lock
The Adapter Lock is a lock word as defined by HCPLKWRD. When the CACBK is uncoupled, the Adapter Lock resides within the CACBK (a section is reserved for the LKWRD).
When the CACBK is coupled, the internal LKWRD is destroyed (by calling HCPLCKDX) and a shared LKWRD is acquired from free storage. Both sides of the adapter (both CACBKs) point to this common Adapter Lock while they are coupled.
When a coupled adapter becomes uncoupled (e.g. one side is detached), then the shared LKWRD is destroyed and each CACBK is reset to use its own internal LKWRD as the Adapter Lock.