1
0 Ref. A2
- A PROTOCOL FOR USING VMCF (Ref. A2)
+ _ ________ ___ _____ ____ ___ __
0 Version 8
+ _______ _
0 8 March 1982
+ _ _____ ____
0 P M Girard
+ _ _ ______
1. Introduction
+ ____________
0 This paper defines a protocol for conducting multiple
conversations between any two virtual machines, built
around the IBM Virtual Machine Communication Facility
(Ref. M3).
-
0 2. Basic Requirements
+ _____ ____________
0 (a) Ability to set up and close down multiple logical
"connections", each with individual flow control.
0 (b) Sufficiently flexible ways of addressing the target
'process' when setting up a connection.
0 (c) Multiple sub-channels within a connection, to allow
full-duplex operation and the multiplexing of many
conversations onto each connection where required.
-
0 3. Basic Principles
+ _____ __________
0 A connection is created when one end sends a CONNECT
message containing Addressing information acceptable to
the other end, and the latter replies with an ACCEPT
message. Either end may subsequently destroy the
connection by sending a DISCONNECT message.
0 The end which sent the successful CONNECT is defined to be
the "caller", and the end which replied with ACCEPT is
defined to be the "listener". These terms are meaningful
only for established connections, and a virtual machine
may be the "caller" on some of its connections and the
"listener" on others.
0 There is provision for negotiating the number of sub-
channels for a connection, by proposing a number when
sending a CONNECT and proposing another number when
replying with ACCEPT.
0 A GLOBAL DISCONNECT message is also defined.
- A PROTOCOL FOR USING VMCF PAGE 1
1
0 Ref. A2
-
0 4. Conventions
+ ___________
0 The protocol does not define how the number of sub-
channels is to be finally resolved. Nor does it define
how the sub-channels are to be used.
0 However, unless otherwise agreed for a given pair of
virtual machines, the following conventions should apply.
The number of sub-channels should be the smaller of the
two numbers proposed at CONNECT and ACCEPT time. The sub-
channels should be used in pairs, each sub-channel
carrying data in one direction only. The "caller" should
use even-numbered sub-channels (0, 2, etc) for
transmitting data, and odd-numbered sub-channels for
receiving it. The "listener" must of course do the
opposite. Data should be transmitted using SEND and
either taken using RECEIVE or refused using REJECT.
-
5. Labels and Logical Channel Numbers
+ ______ ___ _______ _______ _______
0 To satisfy VMCF itself, while providing independent flow
control on every sub-channel, the VMCPMID field needs to
be unique for a given connection, and within the
connection unique for each sub-channel. To achieve this,
a "Label" is chosen by the caller's virtual machine in an
incremental manner, so that every connection attempt
acquires an identification that has not been used before,
consisting of the caller's USERID plus the Label. The
VMCPMID field is then constructed from the Label (22
bits), and a sub-channel number (10 bits). The first
Label assigned by each machine should be 'randomised' by
deriving it from the clock. Thereafter, whenever a
connection is set up, both machines should verify that the
Label assigned is not already in use between them, in the
same direction. The sub-channel usage conventions
proposed in Section 4 ensure that the same label may be
used in opposite directions where necessary, for instance
where a virtual machine makes a connection to itself.
0 The Logical Channel Number (LCN) has no logical
significance in the protocol, its function being simply to
help the other end to find its control blocks quickly.
Each virtual machine assigns a non-zero LCN when a
+ ________
connection is set up, and the LCNs are exchanged. Each
end can then quote the other end's LCN in all subsequent
messages. The LCN, to be useful, should be related in
some way to the addresses of the relevant local control
blocks.
-
A PROTOCOL FOR USING VMCF PAGE 2
1
0 Ref. A2
-
6. Control Functions
+ _______ _________
0 The mechanism for setting up and closing down connections
uses the SENDX and IDENTIFY operations. Four basic
control functions are defined, known as CONNECT, ACCEPT,
DISCONNECT and GLOBAL DISCONNECT. Fields not mentioned
are either not used, or are used in the standard VMCF
manner. The type of "Addressing" information to be used
is at the discretion of each virtual machine. The maximum
number of sub-channels allowed is 511.
0 (a) CONNECT
+ _______
VMCPFUNC : X'0004' (SENDX)
VMCPMID : Caller's Label (22 bits)
No. of subchannels + 512 (10 bits)
(counting from 1)
VMCPUSER : Other end's userid
VMCPVADA/LENA : Address / Length of VMCPBUF
VMCPVADB : Caller's LCN (22 bits)
Type of SENDX (10 bits) (=1)
VMCPUSE : Zeros (22 bits)
Zeros (10 bits)
User-defined information (32 bits)
0 VMCPBUF : Listener addressing (16 bytes)
Caller addressing (16 bytes)
Application-level addressing
(16 bytes)
- (b) ACCEPT
+ ______
VMCPFUNC : X'0004' (SENDX)
VMCPMID : Caller's Label (22 bits)
No. of sub-channels (10 bits)
(counting from 1)
VMCPUSER : Other end's userid
VMCPVADA/LENA : Address / Length of VMCPBUF
VMCPVADB : Listener's LCN (22 bits)
Type of SENDX (10 bits) (=2)
VMCPUSE : Other end's LCN (22 bits)
Zeros (10 bits)
User-defined information (32 bits)
0 VMCPBUF : Listener addressing (16 bytes)
Application-level addressing
(32 bytes)
-
-
- A PROTOCOL FOR USING VMCF PAGE 3
1
0 Ref. A2
0 (c) DISCONNECT
+ __________
VMCPFUNC : X'000A' (IDENTIFY)
VMCPMID : Caller's Label (22 bits)
Reason (4 bits)
Type of IDENTIFY (6 bits) (=3)
VMCPUSER : Other end's userid
VMCPVADA/LENA : Other end addressing
(if LCN not specified)
VMCPVADB/LENB : Other end addressing
(if LCN not specified)
VMCPUSE : Other end's LCN (22 bits)
(zero if unknown)
Zeros (10 bits)
User-defined information (32 bits)
- (d) GLOBAL DISCONNECT
+ _________________
VMCPFUNC : X'000A' (IDENTIFY)
VMCPMID : Label (22 bits)
Reason (4 bits)
Type of IDENTIFY (6 bits) (=4)
VMCPUSER : Other end's userid
VMCPVADA/LENA : This end addressing (or blanks)
VMCPVADB/LENB : This end addressing (or blanks)
VMCPUSE : Zeros (32 bits)
User-defined information (32 bits)
-
7. VMCF Data Messages
+ ____ ____ ________
0 VMCPUSER : Other end's userid
VMCPMID : Caller's Label (22 bits)
Sub-channel No. (10 bits)
(counting from zero)
VMCPUSE : Other end's LCN (22 bits)
Sub-channel No. (10 bits)
(counting from zero)
User-defined information (32 bits)
-
8. Connection and Disconnection Procedure
+ __________ ___ _____________ _________
0 The response to CONNECT must be ACCEPT or DISCONNECT.
ACCEPT may be followed immediately by data if appropriate.
A CONNECT must not be followed by data until an ACCEPT has
arrived. A CONNECT may, however, be followed immediately
by DISCONNECT.
0 Either end may send a DISCONNECT at any time, and should
consider the connection to be dead without expecting a
reply. The receiver of a DISCONNECT should also assume
the connection to be already dead.
- A PROTOCOL FOR USING VMCF PAGE 4
1
0 Ref. A2
- Either end may send a GLOBAL DISCONNECT at any time,
whether or not any connections actually exist. It
destroys all connections between the two virtual machines,
except that if either of the Addressing fields is non-
blank, its scope is limited to those connections
associated (at CONNECT or ACCEPT time) with the Addressing
information specified. The Label should be unique, but it
has no defined function in the protocol.
-
9. Invalid or unwanted Input
+ _______ __ ________ _____
0 Incoming SEND or SEND/RECV messages must not be simply
discarded, even if they are unwanted or in violation of
the protocol, because they will then remain pending in
VMCF. Such messages may be disposed of by issuing a VMCF
REJECT. Other unwanted messages (including SENDX and
IDENTIFY) can be safely discarded as far as VMCF is
concerned.
0 Rejection codes are listed in Section 12, below.
-
10. Flow Control
+ ____ _______
0 This is guaranteed by VMCF as a result of the protocol's
use of the VMCPMID field. VMCF will allow only one
message to be in transit per sub-channel. Assuming SEND
and RECEIVE are being used, it is merely necessary to wait
for the response interrupt before issuing a new SEND on
the same sub-channel. The response interrupt will not
arrive until the receiving end has issued a RECEIVE or
REJECT.
-
11. Involuntary Disconnections
+ ___________ ______________
0 If one of the virtual machines disappears, VMCF itself
will notify the survivor, if any VMCF operation is
outstanding, or if a new VMCF operation is attempted.
However, if a task within a virtual machine disappears, it
is the virtual machine's responsibility to provide a
mechanism for closing down the associated connections.
0 Applications must protect themselves, if necessary,
against the sort of situation where one virtual machine is
waiting for data from the other, but the latter has in
fact disappeared without a VMCF operation pending.
-
0 A PROTOCOL FOR USING VMCF PAGE 5
1
0 Ref. A2
- 12. Error Codes
+ _____ _____
0 (1) Disconnection Reason Codes:
+ _____________ ______ _____
0 0-9 : User-defined
10-11 : Reserved
12 : SENDX data transfer error (VMCF code is passed
in bits 32-39 of User Doubleword)
13 : User task or process has gone away
14 : Unacceptable label in CONNECT
15 : Incoming CONNECT not matched
- (2) Rejection Codes:
+ _________ _____
0 Where an incoming message is rejected (using VMCF REJECT),
a code may be passed in bits 32-39 of the user doubleword,
as follows:-
0 X'00' to X'EF' : User-defined
X'F0' to X'FA' : Reserved
X'FB' : Connection closed with SEND pending
X'FC' : SEND on wrong sub-channel
X'FD' : SEND received in wrong connection State
X'FE' : SEND invalid or unrecognised
X'FF' : Unsupported message type received
-
13. Acknowledgements
+ ________________
0 Many of the ideas incorporated in the specification were
contributed by Chris Cooper, Alan Mayhook and Steve
Tunstall in the course of a number of discussions.
- 14. References
+ __________
0 M3: IBM VM/370 System Programmers Guide (IBM)
-
-
-
-
-
0 A PROTOCOL FOR USING VMCF PAGE 6