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