Sun RPC part 0

[sources-request at genrad.UUCP]

From: blyon at 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.