Tiny RPC: Remote Procedure Call Protocol Description
by Daniel L. Henry
Revision 1.1 – October 9, 2011 Copyright © 2000-2011 by Daniel L. Henry
Tiny RPC: Remote Procedure Call CPD
Revision History Rev. 1.0 1.1
Date 5/9/03 10/9/11
Changed By Dan L. Henry Dan L. Henry
Reason for Change Made suitable for “external” use. Define serialization/deserialization responsibility.
i
Tiny RPC: Remote Procedure Call CPD
Contents 1
INTRODUCTION ...............................................................................................................................................1 1.1 PURPOSE .........................................................................................................................................................1 1.2 SCOPE .............................................................................................................................................................1 1.3 DEFINITIONS, ACRONYMS, AND ABBREVIATIONS ...........................................................................................1 1.3.1 Definitions .............................................................................................................................................1 1.3.2 Acronyms ...............................................................................................................................................1 1.3.3 Abbreviations .........................................................................................................................................1 1.4 REFERENCES...................................................................................................................................................2 1.5 DOCUMENT CONVENTIONS .............................................................................................................................2 1.6 OVERVIEW......................................................................................................................................................2
2
THE RPC MODEL .............................................................................................................................................3
3
TRANSPORTS AND SEMANTICS ..................................................................................................................4
4
EXTERNAL DATA REPRESENTATION (XDR) ...........................................................................................5
5
THE TINY RPC MESSAGE PROTOCOL ......................................................................................................6 5.1 5.2
MESSAGE FORMATS .......................................................................................................................................6 OPERATION EXAMPLE ....................................................................................................................................7
Figures Tables Table 1 – 8-bit control field formats ..............................................................................................................................6
ii
Tiny RPC: Remote Procedure Call CPD
1 Introduction The introduction of this Communication Protocol Description (CPD) provides an overview of the entire CPD.
1.1
Purpose
Communication protocols are sets of rules that govern the interaction of concurrent processes in distributed systems. A protocol specification consists of five parts. To be complete, each specification should include: 1. 2. 3. 4. 5.
The service(s) to be provided by the protocol The assumptions about the environment in which the protocol is executed The vocabulary of messages used to implement the protocol The encoding (format) of each message in the vocabulary The procedure rules guarding the consistency of message exchanges
This CPD attempts to address all of these parts, describing the protocol without ambiguity.
1.2
Scope
This CPD describes the Tiny Remote Procedure Call (RPC) protocol and external data representation (XDR). Communication protocol layers above and below the RPC layer (e.g., the application, data link, and physical layers) are beyond the scope of this document. The intended audience of this CPD is Project Management and Engineering Staff who are responsible for reviewing the communications protocol design prior to implementation and who are responsible for product enhancement and software maintenance.
1.3
Definitions, Acronyms, and Abbreviations
This section defines the terms used in this specification. Words in italics indicate terms that are defined elsewhere in the list of definitions.
1.3.1 Definitions Client-server – The model of interaction in a distributed system in which a program at one site sends a request to a program at another site and awaits a response. The requesting program is called a client; the program satisfying the request is the server. Client – The entity in an RPC transaction that requests invocation of a remote procedure. Server – The entity in an RPC transaction that services the request for procedure invocation.
1.3.2 Acronyms BAC BCC CPD HDLC LAPB RPC TCP UDP XDR
Balanced operation Asynchronous balanced mode Class (of HDLC) Balanced operation Connectionless mode Class (of HDLC) Communication Protocol Description High-level Data Link Control Link Access Procedure Balanced Remote Procedure Call Transmission Control Protocol User Datagram Protocol eXternal Data Representation
1.3.3 Abbreviations ACK
Positive Acknowledgement
1
Tiny RPC: Remote Procedure Call CPD
1.4
References
Information related to the subject of this CPD is found in the following documents: 1.
2.
Srinivasan, R. Internet RFC 1831 – RPC: Remote Procedure Call Protocol Specification Version 2. Sun Microsystems, August 1995 http://www.faqs.org/ftp/rfc/rfc1831.txt Srinivasan, R. Internet RFC 1832 – XDR: External Data Representation Standard. Sun Microsystems, August 1995 http://www.faqs.org/ftp/rfc/rfc1832.txt
1.5
Document Conventions
Hexadecimal values are identified (where not clear from context) by prefixing the value with “0x”. Binary values are identified (where not clear from context) by prefixing the value with “0b”. Several notational conventions are used in this document to visually differentiate text. Courier
Italic Courier
Program or algorithm text, input, output, file names, regular expressions, or other text where use of a mono-spaced font enhances readability Formal parameters to be replaced by user-specified names or values
Any CPD that uses the phrase to be determined (TBD) is not a complete CPD. The TBD is, however, a necessity when a CPD is being developed. TBDs are indicated in the document using italics in the form [TBD:…]. The TBD should be accompanied by: a)
A description of the conditions causing the TBD (for example, why an answer is not known) so that the situation can be resolved b) A description of what must be done to eliminate the TBD, who is responsible for its elimination, and by when it must be eliminated
1.6
Overview
This CPD describes a trivial protocol based on RPC (Remote Procedure Call protocol, also called Remote Operations Service Element in ISO terminology). Remote Procedure Calls are a high level communications paradigm which allows distributed applications to be developed by way of specialized kinds of procedure calls designed to hide the details of the underlying communication mechanisms. RPC provides reliable, two-way transfer of information between application processes and remote services. RPC is an asymmetric protocol. The RPC caller (the client) performs a call to a remote procedure much as it would call a local procedure. Unlike a local procedure, however, the client uses a communication channel to pass arguments to, and receive results from, the remote procedure located on the RPC server. The terms client and server only apply to a particular RPC transaction; a particular hardware entity (device) or software entity (process or program) could operate in both roles at different times. Tiny RPC is a trivial protocol compared to “full-blown” RPC protocols found on larger networked systems. Tiny RPC is optimized for small embedded systems. It does not use the administered program/procedure numbers, authentication, or a formal RPC language that can be found on larger systems. Having now made a distinction between RPC and Tiny RPC, this document uses RPC and Tiny RPC synonymously unless otherwise specified.
2
Tiny RPC: Remote Procedure Call CPD
2 The RPC Model The RPC protocol is based on the remote procedure call model, which 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 register window). It then transfers control to the procedure, and eventually regains 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 model is similar. One thread of control logically winds through two processes: the caller's process, and a server's process. The caller process first sends a call message to the server process and waits (blocks) for a reply message. The call message includes the procedure's parameters, and the reply message includes the procedure's results. 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 message, and then awaits the next call message. In this model, only one of the two processes is active at any given time. However, this model is only given as an example. The RPC protocol makes no restrictions on the concurrency model implemented, and others are possible. For example, an implementation may choose to have RPC calls be asynchronous, so that the client may do useful work while waiting for the reply from the server. Another possibility is to have the server create a separate task to process an incoming call, so that the original server can be free to receive other requests. There are a few important ways in which remote procedure calls differ from local procedure calls: 1.
Error handling: failures of the remote server or network must be handled when using remote procedure calls.
2.
Global variables and side-effects: since the server does not have access to the client's address space, hidden arguments cannot be passed as global variables or returned as side effects.
3.
Performance: remote procedures usually operate one or more orders of magnitude slower than local procedure calls.
The paragraphs above describe a normal call with the client caller expecting a reply from the server. Tiny RPC also has the notion of a tossed call, which provides a mechanism for the client to “toss” a procedure call (as in “throw with a careless motion”) to the server without any expectation of receiving a reply. In fact, when the server receives a tossed procedure call, it may not even execute the procedure (and the client should not really care one way or the other), but if executed, the procedure does not return any results. To illustrate how a tossed call might be used, assume a client wants to display a “continuously” updating completion percentage of some ongoing client process and the physical display is attached to the server. The server provides disp_clear(void) and disp_progress(percent) procedures. Initially, the client invokes disp_clear() as a normal call to ensure that the display is cleared before starting to update the display continuously, then after the client receives the procedure’s reply message, it periodically “tosses” disp_progress() calls to the server with the current completion percentage. The next value displayed overwrites the previously displayed value, so the client neither cares if the previous disp_progress() call succeeded nor cares whether the server even received the previous call message at all. In this case, the client tosses the procedure calls to the server, hoping that the server receives the message and attempts to execute the procedure on a “best effort” basis.
3
Tiny RPC: Remote Procedure Call CPD
3 Transports and Semantics The RPC protocol can be implemented on several different transport protocols. The RPC protocol does not care how a message is passed from one process to another, but only with specification and interpretation of messages. However, the application may wish to obtain information about (and perhaps control over) the transport layer through an interface not specified in this document. For example, the transport protocol may impose a restriction on the maximum size of RPC messages, or it may be stream-oriented like TCP with no size limit. The client and server must agree on their transport protocol choices. It is important to point out that RPC does not try to implement any kind of reliability and that the application may need to be aware of the type of transport protocol underneath RPC. If it knows it is running on top of a reliable transport such as TCP or HDLC BAC 2,8 (LAPB), then most of the work is already done for it. On the other hand, if it is running on top of an unreliable transport such as UDP or HDLC BCC, it must implement its own time-out, retransmission, and duplicate detection policies, as the RPC protocol does not provide these services. Because of transport independence, the RPC protocol does not attach specific semantics to the remote procedures or their execution requirements. Semantics can be inferred from (but should be explicitly specified by) the underlying transport protocol. For example, consider RPC running on top of an unreliable transport such as UDP or HDLC BCC. If an application retransmits RPC call messages after time-outs, and does not receive a reply, it cannot infer anything about the number of times the procedure was executed. If it does receive a reply, then it can infer that the procedure was executed at least once. A server may wish to remember previously granted requests from a client and not re-grant them in order to insure some degree of execute-at-most-once semantics. A server can do this by taking advantage of the transaction ID that is packaged with every RPC message. The main use of this transaction ID is by the client RPC entity in matching replies to calls. However, a client application may choose to reuse its previous transaction ID when retransmitting a call. The server may choose to remember this ID after executing a call and not execute calls with the same ID in order to achieve some degree of execute-at-most-once semantics. The server is not allowed to examine this ID in any other way except as a test for equality. On the other hand, if using a "reliable" transport such as TCP or LAPB, the application can infer from a reply message that the procedure was executed exactly once, but if it receives no reply message, it cannot assume that the remote procedure was not executed. Note that even if a connection-oriented protocol like TCP or LAPB is used, an application still needs time-outs and reconnection to handle server crashes.
4
Tiny RPC: Remote Procedure Call CPD
4 External Data Representation (XDR) The external data representation (XDR) specifies the width and byte order for multi-byte data objects as they appear on the communication channel. Tiny RPC differs from normal RPC with respect to the XDR. Normal RPC XDR defines a “network byte order” that is big-endian. Since Tiny RPC is optimized for small (often 8-bit) systems, the XDR may be big-endian or little-endian, depending on the inferior system’s native hardware or compiler byte ordering convention. For example, an embedded system using a small microcontroller may be connected to a PC. In this case, the embedded system is the “inferior system” in terms of CPU horsepower and available memory when compared to the PC. The XDR byte order for the example system favors the inferior embedded system, so that it can work with the RPC data objects without having to perform byte-swapping. The following C language macros might be a useful template. #include /* LBO specifies the local (i.e., "this" system's) byte order. * XBO specifies the XDR byte order favoring the inferior system. */ #define LBO LE /* Example: little-endian */ #define XBO BE /* Example: big-endian */ #define LE 0 #define BE 1 /* XDR16() and XDR32() convert 16-bit and 32-bit integers respectively, * to/from the local compiler/machine byte order from/to RPC's external * data representation (XDR) byte order. Consider changing the swapping * macros to use compiler intrinsics if available for better performance. */ #if XBO == LBO #define XDR16(x16) (x16) #define XDR32(x32) (x32) #else #define XDR16(x16) ((((uint16_t)(x16) & 0xFF00) >> 8) | \ (((uint16_t)(x16) & 0x00FF) > 24) | \ (((uint32_t)(x32) & 0x00FF0000) >> 8) | \ (((uint32_t)(x32) & 0x0000FF00)
