From sources-request@genrad.UUCP Fri Apr 12 10:56:45 1985 Relay-Version: version B 2.10.3 alpha 4/3/85; site seismo.UUCP Posting-Version: version B 2.10.2 9/3/84; site genrad.UUCP Path: seismo!harvard!talcott!panda!genrad!sources-request From: sources-request@genrad.UUCP Newsgroups: mod.sources Subject: Sun RPC part 0 Message-ID: <749@genrad.UUCP> Date: 12 Apr 85 15:56:45 GMT Date-Received: 13 Apr 85 03:27:25 GMT Sender: john@genrad.UUCP Organization: GenRad, Inc., Bolton, Mass. Lines: 185 Approved: john@genrad.UUCP From: blyon@sun (Bob Lyon) [I have taken selected parts of the rpc.spec document (after nroff'ing) and included it here to describe this what this package is, and what it does. This will be a ten part "shar" distribution - the moderator ] Remote Procedure Call Protocol Specification 1. Introduction This document specifies a message protocol used in implementing Sun's Remote Procedure Call (RPC) package. The protocol is specified with the eXternal Data Representation (XDR) language. This document assumes that the reader is familiar with both RPC and XDR. It does not attempt to justify RPC or its uses. Also, the casual user of RPC does not need to be familiar with the information in this document. 1.1. Terminology The document discusses servers, services, programs, procedures, clients and versions. A server is a machine where some number of network services are implemented. A service is a collection of one or more remote programs. A remote program implements one or more remote procedures; the procedures, their parameters and results are documented in the specific program's protocol specif- ication (see Appendix 3 for an example). Network clients are pieces of software that initiate remote procedure calls to ser- vices. A server may support more than one version of a remote program in order to be forward compatible with changing proto- cols. For example, a network file service may be composed of two pro- grams. One program may deal with high level applications such as file system access control and locking. The other may deal with low-level file I/O, and have procedures like ``read'' and ``write''. A client machine of the network file service would call the procedures associated with the two programs of the ser- vice on behalf of some user on the client machine. 1.2. The RPC Model The remote procedure call model is similar to the local procedure call model. In the local case, the caller places arguments to a procedure in some well-specified location (such as a result register). It then transfers control to the procedure, and eventually gains back control. At that point, the results of the procedure are extracted from the well-specified location, and the caller continues execution. The remote procedure call is similar, except that one thread of control winds through two processes - one is the caller's pro- cess, the other is a server's process. That is, the caller pro- cess sends a call message to the server process and waits (blocks) for a reply message. The call message contains the procedure's parameters, among other things. The reply message contains the procedure's results, among other things. Once the reply message is received, the results of the procedure are extracted, and caller's execution is resumed. On the server side, a process is dormant awaiting the arrival of a call message. When one arrives the server process extracts the procedure's parameters, computes the results, sends a reply mes- sage, and then awaits the next call message. Note that in this model, only one of the two processes is active at any given time. That is, the RPC protocol does not explicitly support multi- threading of caller or server processes. 1.3. Transports and Semantics The RPC protocol is independent of transport protocols. That is, RPC does not care how a message is passed from one process to another. The protocol only deals with the specification and interpretation of messages. Because of transport independence, the RPC protocol does not attach specific semantics to the remote procedures or their exe- cution. Some semantics can be inferred from (but should be explicitly specified by) the underlying transport protocol. For example, RPC message passing using UDP/IP is unreliable. Thus, if the caller retransmits call messages after short time-outs, the only thing he can infer from no reply message is that the remote procedure was executed zero or more times (and from a reply message, one or more times). On the other hand, RPC mes- sage passing using TCP/IP is reliable. No reply message means that the remote procedure was executed at most once, whereas a reply message means that the remote procedure was exactly once. (Note: At Sun, RPC is currently implemented on top of TCP/IP and UDP/IP transports.) 1.4. Binding and Rendezvous Independence The act of binding a client to a service is NOT part of the remote procedure call specification. This important and neces- sary function is left up to some higher level software. (The software may use RPC itself; see Appendix 3.) Implementors should think of the RPC protocol as the jump- subroutine instruction (``JSR'') of a network; the loader (binder) makes JSR useful, and the loader itself uses JSR to accomplish its task. Likewise, the network makes RPC useful, using RPC to accomplish this task. . . . 3. Other Uses and Abuses of the RPC Protocol The intended use of this protocol is for calling remote pro- cedures. That is, each call message is matched with a response message. However, the protocol itself is a message passing pro- tocol with which other (non-RPC) protocols can be implemented. Sun currently uses (abuses) the RPC message protocol for the fol- lowing two (non-RPC) protocols: batching (or pipelining) and broadcast RPC. These two protocols are discussed (but not defined) below. 3.1. Batching Batching allows a client to send an arbitrarily large sequence of call messages to a server; batching uses reliable bytes stream protocols (like TCP/IP) for their transport. In the case of batching, the client never waits for a reply from the server and the server does not send replies to batch requests. A sequence of batch calls is usually terminated by a legitimate RPC in order to flush the pipeline (with positive acknowledgement). 3.2. Broadcast RPC In broadcast RPC based protocols, the client sends an a broadcast packet to the network and waits for numerous replies. Broadcast RPC uses unreliable, packet based protocols (like UDP/IP) as their transports. Servers that support broadcast protocols only respond when the request is successfully processed, and are silent in the face of errors. . . . 6. Appendix 2: Record Marking Standard (RM) When RPC messages are passed on top of a byte stream protocol (like TCP/IP), it is necessary, or at least desirable, to delimit one message from another in order to detect and possibly recover from user protocol errors. Sun uses this RM/TCP/IP transport for passing RPC messages on TCP streams. One RPC message fits into one RM record. A record is composed of one or more record fragments. A record fragment is a four-byte header followed by 0 to 2^31-1 bytes of fragment data. The bytes encode an unsigned binary number; as with XDR integers, the byte order is from highest to lowest. The number encodes two values - a boolean which indicates whether the fragment is the last fragment of the record (bit value 1 implies the fragment is the last fragment) and a 31-bit unsigned binary value which is the length in bytes of the fragment's data. The boolean value is the highest-order bit of the header; the length is the 31 low-order bits. (Note that this record specification is not in XDR standard form!) 7. Appendix 3: Port Mapper Program Protocol The port mapper program maps RPC program and version numbers to UDP/IP or TCP/IP port numbers. This program makes dynamic bind- ing of remote programs possible. This is desirable because the range of reserved port numbers is very small and the number of potential remote programs is very large. By running only the port mapper on a reserved port, the port numbers of other remote programs can be ascertained by querying the port mapper.