2 * \addtogroup rxrpc-spec RX RPC Specification
6 * \mainpage AFS-3 Programmer's Reference: Specification for the Rx Remote
7 * Procedure Call Facility
9 * AFS-3 Programmer's Reference:
11 * Specification for the Rx Remote Procedure Call Facility
12 * \author Edward R. Zayas
13 * Transarc Corporation
15 * \date 28 August 1991 10:11 .cCopyright 1991 Transarc Corporation All Rights
18 * \page chap1 Chapter 1 -- Overview of the Rx RPC system
20 * \section sec1-1 Section 1.1: Introduction to Rx
23 * The Rx package provides a high-performance, multi-threaded, and secure
25 * remote procedure calls (RPCs) may be performed between programs executing
27 * network of computers. The Rx protocol is adaptive, conforming itself to
29 * network communication media. It allows user applications to define and
31 * security modules, allowing them to execute the precise end-to-end
32 * authentication algorithms
33 * required to suit their needs and goals. Although pervasive throughout the
35 * file system, all of its agents, and many of its standard application
36 * programs, Rx is entirely
37 * separable from AFS and does not depend on any of its features. In fact, Rx
38 * can be used to build applications engaging in RPC-style communication under
39 * a variety of unix-style file systems. There are in-kernel and user-space
40 * implementations of the Rx facility, with both sharing the same interface.
42 * This document provides a comprehensive and detailed treatment of the Rx RPC
45 * \section sec1-2 Section 1.2: Basic Concepts
48 * The Rx design operates on the set of basic concepts described in this
51 * \subsection sec1-2-1 Section 1.2.1: Security
54 * The Rx architecture provides for tight integration between the RPC mechanism
55 * and methods for making this communication medium secure. As elaborated in
56 * Section 5.3.1.3 and illustrated by the built-in rxkad security system
57 * described in Chapter 3, Rx defines the format for a generic security module,
58 * and then allows application programmers to define and activate
59 * instantiations of these modules. Rx itself knows nothing about the internal
60 * details of any particular security model, or the module-specific state it
61 * requires. It does, however, know when to call the generic security
62 * operations, and so can easily execute the security algorithm defined. Rx
63 * does maintain basic state per connection on behalf of any given security
66 * \subsection sec1-2-2 Section 1.2.2: Services
69 * An Rx-based server exports services, or specific RPC interfaces that
70 * accomplish certain tasks. Services are identified by (host-address,
71 * UDP-port, serviceID) triples. An Rx service is installed and initialized on
72 * a given host through the use of the rx NewService() routine (See Section
73 * 5.6.3). Incoming calls are stamped with the Rx service type, and must match
74 * an installed service to be accepted. Internally, Rx services also carry
75 * string names which identify them, which is useful for remote debugging and
76 * statistics-gathering programs. The use of a service ID allows a single
77 * server process to export multiple, independently-specified Rx RPC services.
79 * Each Rx service contains one or more security classes, as implemented by
80 * individual security objects. These security objects implement end-to-end
81 * security protocols. Individual peer-to-peer connections established on
82 * behalf of an Rx service will select exactly one of the supported security
83 * objects to define the authentication procedures followed by all calls
84 * associated with the connection. Applications are not limited to using only
85 * the core set of built-in security objects offered by Rx. They are free to
86 * define their own security objects in order to execute the specific protocols
89 * It is possible to specify both the minimum and maximum number of lightweight
90 * processes available to handle simultaneous calls directed to an Rx service.
91 * In addition, certain procedures may be registered with the service and
92 * called at specific times in the course of handling an RPC request.
94 * \subsection sec1-2-3 Section 1.2.3: Connections
97 * An Rx connection represents an authenticated communication path, allowing a
98 * sequence of multiple asynchronous conversations (calls). Each connection is
99 * identified by a connection ID. The low-order bits of the connection ID are
100 * reserved so that they may be stamped with the index of a particular call
101 * channel. With up to RX MAXCALLS concurrent calls (set to 4 in this
102 * implementation), the bottom two bits are set aside for this purpose. The
103 * connection ID is not sufficient to uniquely identify an Rx connection by
104 * itself. Should a client crash and restart, it may reuse a connection ID,
105 * causing inconsistent results. Included with the connection ID is the epoch,
106 * or start time for the client side of the connection. After a crash, the next
107 * incarnation of the client will choose a different epoch value. This will
108 * differentiate the new incarnation from the orphaned connection record on the
111 * Each connection is associated with a parent service, which defines a set of
112 * supported security models. At creation time, an Rx connection selects the
113 * particular security protocol it will implement, referencing the associated
114 * service. The connection structure maintains state for each individual call
115 * simultaneously handled.
117 * \subsection sec1-2-4 Section 1.2.4: Peers
120 * For each connection, Rx maintains information describing the entity, or
121 * peer, on the other side of the wire. A peer is identified by a (host,
122 * UDP-port) pair, with an IP address used to identify the host. Included in
123 * the information kept on this remote communication endpoint are such network
124 * parameters as the maximum packet size supported by the host, current
125 * readings on round trip time and retransmission delays, and packet skew (see
126 * Section 1.2.7). There are also congestion control fields, including
127 * retransmission statistics and descriptions of the maximum number of packets
128 * that may be sent to the peer without pausing. Peer structures are shared
129 * between connections whenever possible, and, hence, are reference-counted. A
130 * peer object may be garbage-collected if it is not actively referenced by any
131 * connection structure and a sufficient period of time has lapsed since the
132 * reference count dropped to zero.
134 * \subsection sec1-2-5 Section 1.2.5: Calls
137 * An Rx call represents an individual RPC being executed on a given
138 * connection. As described above, each connection may have up to RX MAXCALLS
139 * calls active at any one instant. The information contained in each call
140 * structure is specific to the given call.
142 * "Permanent" call state, such as the call number, is maintained in the
143 * connection structure itself.
145 * \subsection sec1-2-6 Section 1.2.6: Quotas
148 * Each attached server thread must be able to make progress to avoid system
149 * deadlock. The Rx facility ensures that it can always handle the arrival of
150 * the next unacknowledged data packet for an attached call with its system of
151 * packet quotas. A certain number of packets are reserved per server thread
152 * for this purpose, allowing the server threads to queue up an entire window
153 * full of data for an active call and still have packet buffers left over to
154 * be able to read its input without blocking.
156 * \subsection sec1-2-7 Section 1.2.7: Packet Skew
159 * If a packet is received n packets later than expected (based on packet
160 * serial numbers), then we define it to have a skew of n. The maximum skew
161 * values allow us to decide when a packet hasn't been received yet because it
162 * is out of order, as opposed to when it is likely to have been dropped.
164 * \subsection sec1-2-8 Section 1.2.8: Multicasting
167 * The rx multi.c module provides for multicast abilities, sending an RPC to
168 * several targets simultaneously. While true multicasting is not achieved, it
169 * is simulated by a rapid succession of packet transmissions and a collection
170 * algorithm for the replies. A client program, though, may be programmed as if
171 * multicasting were truly taking place. Thus, Rx is poised to take full
172 * advantage of a system supporting true multicasting with minimal disruption
173 * to the existing client code base.
175 * \section sec1-3 Section 1.3: Scope
178 * This paper is a member of a documentation suite providing specifications as
179 * to the operation and interfaces offered by the various AFS servers and
180 * agents. Rx is an integral part of the AFS environment, as it provides the
181 * high-performance, secure pathway by which these system components
182 * communicate across the network. Although AFS is dependent on Rx's services,
183 * the reverse is not true. Rx is a fully independent RPC package, standing on
184 * its own and usable in other environments.
186 * The intent of this work is to provide readers with a sufficiently detailed
187 * description of Rx that they may proceed to write their own applications on
188 * top of it. In fact, code for a sample Rx server and client are provided.
190 * One topic related to Rx will not be covered by this document, namely the
191 * Rxgen stub generator. Rather, rxgen is addressed in a separate document.
193 * \section sec1-4 Section 1.4: Document Layout
196 * After this introduction, Chapter 2 will introduce and describe various
197 * facilities and tools that support Rx. In particular, the threading and
198 * locking packages used by Rx will be examined, along with a set of timer and
199 * preemption tools. Chapter 3 proceeds to examine the details of one of the
200 * built-in security modules offered by Rx. Based on the Kerberos system
201 * developed by MIT's Project Athena, this rxkad module allows secure, ecrypted
202 * communication between the server and client ends of the RPC. Chapter 5 then
203 * provides the full Rx programming interface, and Chapter 6 illustrates the
204 * use of this programming interface by providing a fully-operational
205 * programming example employing Rx. This rxdemo suite is examined in detail,
206 * ranging all the way from a step-by-step analysis of the human-authored
207 * files, and the Rxgen-generated files upon which they are based, to the
208 * workings of the associated Makefile. Output from the example rxdemo server
209 * and client is also provided.
211 * \section sec1-5 Section 1.5: Related Documents
214 * Titles for the full suite of AFS specification documents are listed below.
215 * All of the servers and agents making up the AFS computing environment,
216 * whether running in the unix kernel or in user space, utilize an Rx RPC
217 * interface through which they export their services.
219 * \li AFS-3 Programmer's Reference: Architectural Overview: This paper
220 * provides an architectual overview of the AFS distributed file system,
221 * describing the full set of servers and agents in a coherent way,
222 * illustrating their relationships to each other and examining their
224 * \li AFS-3 Programmer's Reference: file Server/Cache Manager Interface: This
225 * document describes the workings and interfaces of the two primary AFS
226 * agents, the file Server and Cache Manager. The file Server provides a
227 * centralized disk repository for sets of files, regulating access to them.
228 * End users sitting on client machines rely on the Cache Manager agent,
229 * running in their kernel, to act as their agent in accessing the data stored
230 * on file Server machines, making those files appear as if they were really
232 * \li AFS-3 Programmer's Reference:Volume Server/Volume Location Server
233 * Interface: This document describes the services through which "containers"
234 * of related user data are located and managed.
235 * \li AFS-3 Programmer's Reference: Protection Server Interface: This paper
236 * describes the server responsible for mapping printable user names to and
237 * from their internal AFS identifiers. The Protection Server also allows users
238 * to create, destroy, and manipulate "groups" of users, which are suitable for
239 * placement on access control lists (ACLs).
240 * \li AFS-3 Programmer's Reference: BOS Server Interface: This paper
241 * explicates the "nanny" service which assists in the administrability of the
244 * In addition to these papers, the AFS 3.1 product is delivered with its own
245 * user, system administrator, installation, and command reference documents.
247 * \page chap2 Chapter 2 -- The LWP Lightweight Process Package
249 * \section sec2-1 Section 2.1: Introduction
251 * This chapter describes a package allowing multiple threads of control to
252 * coexist and cooperate within one unix process. Each such thread of control
253 * is also referred to as a lightweight process, in contrast to the traditional
254 * unix (heavyweight) process. Except for the limitations of a fixed stack size
255 * and non-preemptive scheduling, these lightweight processes possess all the
256 * properties usually associated with full-fledged processes in typical
257 * operating systems. For the purposes of this document, the terms lightweight
258 * process, LWP, and thread are completely interchangeable, and they appear
259 * intermixed in this chapter. Included in this lightweight process facility
260 * are various sub-packages, including services for locking, I/O control,
261 * timers, fast time determination, and preemption.
263 * The Rx facility is not the only client of the LWP package. Other LWP clients
264 * within AFS include the file Server, Protection Server, BOS Server, Volume
265 * Server, Volume Location Server, and the Authentication Server, along with
266 * many of the AFS application programs.
268 * \section sec2-2 Section 2.2: Description
270 * \subsection Section 2.2.1: sec2-2-1 LWP Overview
273 * The LWP package implements primitive functions that provide the basic
274 * facilities required to enable procedures written in C to execute
275 * concurrently and asynchronously. The LWP package is meant to be
276 * general-purpose (note the applications mentioned above), with a heavy
277 * emphasis on simplicity. Interprocess communication facilities can be built
278 * on top of this basic mechanism and in fact, many different IPC mechanisms
279 * could be implemented.
281 * In order to set up the threading support environment, a one-time invocation
282 * of the LWP InitializeProcessSupport() function must precede the use of the
283 * facilities described here. This initialization function carves an initial
284 * process out of the currently executing C procedure and returns its thread
285 * ID. For symmetry, an LWP TerminateProcessSupport() function may be used
286 * explicitly to release any storage allocated by its counterpart. If this
287 * function is used, it must be issued from the thread created by the original
288 * LWP InitializeProcessSupport() invocation.
290 * When any of the lightweight process functions completes, an integer value is
291 * returned to indicate whether an error condition was encountered. By
292 * convention, a return value of zero indicates that the operation succeeded.
294 * Macros, typedefs, and manifest constants for error codes needed by the
295 * threading mechanism are exported by the lwp.h include file. A lightweight
296 * process is identified by an object of type PROCESS, which is defined in the
299 * The process model supported by the LWP operations is based on a
300 * non-preemptive priority dispatching scheme. A priority is an integer in the
301 * range [0..LWP MAX PRIORITY], where 0 is the lowest priority. Once a given
302 * thread is selected and dispatched, it remains in control until it
303 * voluntarily relinquishes its claim on the CPU. Control may be relinquished
304 * by either explicit means (LWP_DispatchProcess()) or implicit means (through
305 * the use of certain other LWP operations with this side effect). In general,
306 * all LWP operations that may cause a higher-priority process to become ready
307 * for dispatching preempt the process requesting the service. When this
308 * occurs, the dispatcher mechanism takes over and automatically schedules the
309 * highest-priority runnable process. Routines in this category, where the
310 * scheduler is guaranteed to be invoked in the absence of errors, are:
311 * \li LWP_WaitProcess()
312 * \li LWP_MwaitProcess()
313 * \li LWP_SignalProcess()
314 * \li LWP_DispatchProcess()
315 * \li LWP_DestroyProcess()
317 * The following functions are guaranteed not to cause preemption, and so may
318 * be issued with no fear of losing control to another thread:
319 * \li LWP_InitializeProcessSupport()
320 * \li LWP_NoYieldSignal()
321 * \li LWP_CurrentProcess()
322 * \li LWP_ActiveProcess()
323 * \li LWP_StackUsed()
327 * The symbol LWP NORMAL PRIORITY, whose value is (LWP MAX PRIORITY-2),
328 * provides a reasonable default value to use for process priorities.
330 * The lwp debug global variable can be set to activate or deactivate debugging
331 * messages tracing the flow of control within the LWP routines. To activate
332 * debugging messages, set lwp debug to a non-zero value. To deactivate, reset
333 * it to zero. All debugging output from the LWP routines is sent to stdout.
335 * The LWP package checks for stack overflows at each context switch. The
336 * variable that controls the action of the package when an overflow occurs is
337 * lwp overflowAction. If it is set to LWP SOMESSAGE, then a message will be
338 * printed on stderr announcing the overflow. If lwp overflowAction is set to
339 * LWP SOABORT, the abort() LWP routine will be called. finally, if lwp
340 * overflowAction is set to LWP SOQUIET, the LWP facility will ignore the
341 * errors. By default, the LWP SOABORT setting is used.
343 * Here is a sketch of a simple program (using some psuedocode) demonstrating
344 * the high-level use of the LWP facility. The opening #include line brings in
345 * the exported LWP definitions. Following this, a routine is defined to wait
346 * on a "queue" object until something is deposited in it, calling the
347 * scheduler as soon as something arrives. Please note that various LWP
348 * routines are introduced here. Their definitions will appear later, in
352 * #include <afs/lwp.h>
353 * static read_process(id)
355 * { /* Just relinquish control for now */
356 * LWP_DispatchProcess();
359 * /* Wait until there is something in the queue */
360 * while (empty(q)) LWP_WaitProcess(q);
361 * /* Process the newly-arrived queue entry */
362 * LWP_DispatchProcess();
368 * The next routine, write process(), sits in a loop, putting messages on the
369 * shared queue and signalling the reader, which is waiting for activity on the
370 * queue. Signalling a thread is accomplished via the LWP SignalProcess()
374 * static write_process()
376 * /* Loop, writing data to the shared queue. */
377 * for (mesg = messages; *mesg != 0; mesg++)
380 * LWP_SignalProcess(q);
386 * finally, here is the main routine for this demo pseudocode. It starts by
387 * calling the LWP initialization routine. Next, it creates some number of
388 * reader threads with calls to LWP CreateProcess() in addition to the single
389 * writer thread. When all threads terminate, they will signal the main routine
390 * on the done variable. Once signalled, the main routine will reap all the
391 * threads with the help of the LWP DestroyProcess() function.
398 * PROCESS *id; /* Initial thread ID */
399 * /* Set up the LWP package, create the initial thread ID. */
400 * LWP_InitializeProcessSupport(0, &id);
401 * /* Create a set of reader threads. */
402 * for (i = 0; i < nreaders; i++)
403 * LWP_CreateProcess(read_process, STACK_SIZE, 0, i, "Reader",
406 * /* Create a single writer thread. */
407 * LWP_CreateProcess(write_process, STACK_SIZE, 1, 0, "Writer", &writer);
408 * /* Wait for all the above threads to terminate. */
409 * for (i = 0; i <= nreaders; i++)
410 * LWP_WaitProcess(&done);
412 * /* All threads are done. Destroy them all. */
413 * for (i = nreaders-1; i >= 0; i--)
414 * LWP_DestroyProcess(readers[i]);
418 * \subsection sec2-2-2 Section 2.2.2: Locking
420 * The LWP locking facility exports a number of routines and macros that allow
421 * a C programmer using LWP threading to place read and write locks on shared
422 * data structures. This locking facility was also written with simplicity in
425 * In order to invoke the locking mechanism, an object of type struct Lock must
426 * be associated with the object. After being initialized with a call to
427 * LockInit(), the lock object is used in invocations of various macros,
428 * including ObtainReadLock(), ObtainWriteLock(), ReleaseReadLock(),
429 * ReleaseWriteLock(), ObtainSharedLock(), ReleaseSharedLock(), and
432 * Lock semantics specify that any number of readers may hold a lock in the
433 * absence of a writer. Only a single writer may acquire a lock at any given
434 * time. The lock package guarantees fairness, legislating that each reader and
435 * writer will eventually obtain a given lock. However, this fairness is only
436 * guaranteed if the priorities of the competing processes are identical. Note
437 * that ordering is not guaranteed by this package.
439 * Shared locks are read locks that can be "boosted" into write locks. These
440 * shared locks have an unusual locking matrix. Unboosted shared locks are
441 * compatible with read locks, yet incompatible with write locks and other
442 * shared locks. In essence, a thread holding a shared lock on an object has
443 * effectively read-locked it, and has the option to promote it to a write lock
444 * without allowing any other writer to enter the critical region during the
445 * boost operation itself.
447 * It is illegal for a process to request a particular lock more than once
448 * without first releasing it. Failure to obey this restriction will cause
449 * deadlock. This restriction is not enforced by the LWP code.
451 * Here is a simple pseudocode fragment serving as an example of the available
452 * locking operations. It defines a struct Vnode object, which contains a lock
453 * object. The get vnode() routine will look up a struct Vnode object by name,
454 * and then either read-lock or write-lock it.
456 * As with the high-level LWP example above, the locking routines introduced
457 * here will be fully defined later, in Section 2.3.2.
460 * #include <afs/lock.h>
464 * struct Lock lock; Used to lock this vnode
470 * struct Vnode *get_vnode(name, how) char *name;
476 * ObtainReadLock(&v->lock);
478 * ObtainWriteLock(&v->lock);
483 * \subsection sec2-2-3 Section 2.2.3: IOMGR
486 * The IOMGR facility associated with the LWP service allows threads to wait on
487 * various unix events. The exported IOMGR Select() routine allows a thread to
488 * wait on the same set of events as the unix select() call. The parameters to
489 * these two routines are identical. IOMGR Select() puts the calling LWP to
490 * sleep until no threads are active. At this point, the built-in IOMGR thread,
491 * which runs at the lowest priority, wakes up and coalesces all of the select
492 * requests together. It then performs a single select() and wakes up all
493 * threads affected by the result.
495 * The IOMGR Signal() routine allows an LWP to wait on the delivery of a unix
496 * signal. The IOMGR thread installs a signal handler to catch all deliveries
497 * of the unix signal. This signal handler posts information about the signal
498 * delivery to a global data structure. The next time that the IOMGR thread
499 * runs, it delivers the signal to any waiting LWP.
501 * Here is a pseudocode example of the use of the IOMGR facility, providing the
502 * blueprint for an implemention a thread-level socket listener.
505 * void rpc_SocketListener()
507 * int ReadfdMask, WritefdMask, ExceptfdMask, rc;
508 * struct timeval *tvp;
511 * ExceptfdMask = ReadfdMask = (1 << rpc_RequestSocket);
514 * rc = IOMGR_Select(8*sizeof(int), &ReadfdMask, &WritefdMask,
515 * &ExceptfdMask, tvp);
519 * case 0: /* Timeout */ continue;
520 * /* Main while loop */
522 * case -1: /* Error */
523 * SystemError("IOMGR_Select");
526 * case 1: /* RPC packet arrived! */ ...
530 * default: Should never occur
536 * \subsection sec2-2-4 Section 2.2.4: Timer
538 * The timer package exports a number of routines that assist in manipulating
539 * lists of objects of type struct TM Elem. These struct TM Elem timers are
540 * assigned a timeout value by the user and inserted in a package-maintained
541 * list. The time remaining to each timer's timeout is kept up to date by the
542 * package under user control. There are routines to remove a timer from its
543 * list, to return an expired timer from a list, and to return the next timer
546 * A timer is commonly used by inserting a field of type struct TM Elem into a
547 * structure. After setting the desired timeout value, the structure is
548 * inserted into a list by means of its timer field.
550 * Here is a simple pseudocode example of how the timer package may be used.
551 * After calling the package initialization function, TM Init(), the pseudocode
552 * spins in a loop. first, it updates all the timers via TM Rescan() calls.
553 * Then, it pulls out the first expired timer object with TM GetExpired() (if
554 * any), and processes it.
557 * static struct TM_Elem *requests;
559 * TM_Init(&requests); /* Initialize timer list */ ...
561 * TM_Rescan(requests); /* Update the timers */
562 * expired = TM_GetExpired(requests);
565 * . . . process expired element . . .
569 * \subsection sec2-2-5 Section 2.2.5: Fast Time
572 * The fast time routines allows a caller to determine the current time of day
573 * without incurring the expense of a kernel call. It works by mapping the page
574 * of the kernel that holds the time-of-day variable and examining it directly.
575 * Currently, this package only works on Suns. The routines may be called on
576 * other architectures, but they will run more slowly.
578 * The initialization routine for this package is fairly expensive, since it
579 * does a lookup of a kernel symbol via nlist(). If the client application
580 * program only runs for only a short time, it may wish to call FT Init() with
581 * the notReally parameter set to TRUE in order to prevent the lookup from
582 * taking place. This is useful if you are using another package that uses the
583 * fast time facility.
585 * \section sec2-3 Section 2.3: Interface Specifications
587 * \subsection sec2-3-1 Section 2.3.1: LWP
590 * This section covers the calling interfaces to the LWP package. Please note
591 * that LWP macros (e.g., ActiveProcess) are also included here, rather than
592 * being relegated to a different section.
594 * \subsubsection sec2-3-1-1 Section 2.3.1.1: LWP_InitializeProcessSupport
595 * _ Initialize the LWP package
598 * int LWP_InitializeProcessSupport(IN int priority; OUT PROCESS *pid)
600 * This function initializes the LWP package. In addition, it turns the current
601 * thread of control into the initial process with the specified priority. The
602 * process ID of this initial thread is returned in the pid parameter. This
603 * routine must be called before any other routine in the LWP library. The
604 * scheduler will NOT be invoked as a result of calling
605 * LWP_InitializeProcessSupport().
607 * LWP EBADPRI The given priority is invalid, either negative or too large.
609 * \subsubsection sec2-3-1-2 Section 2.3.1.2: LWP_TerminateProcessSupport
610 * _ End process support, perform cleanup
613 * int LWP_TerminateProcessSupport()
615 * This routine terminates the LWP threading support and cleans up after it by
616 * freeing any auxiliary storage used. This routine must be called from within
617 * the process that invoked LWP InitializeProcessSupport(). After LWP
618 * TerminateProcessSupport() has been called, it is acceptable to call LWP
619 * InitializeProcessSupport() again in order to restart LWP process support.
621 * ---Always succeeds, or performs an abort().
623 * \subsubsection sec2-3-1-3 Section 2.3.1.3: LWP_CreateProcess _ Create a
627 * int LWP_CreateProcess(IN int (*ep)(); IN int stacksize; IN int priority; IN
628 * char *parm; IN char *name; OUT PROCESS *pid)
630 * This function is used to create a new lightweight process with a given
631 * printable name. The ep argument identifies the function to be used as the
632 * body of the thread. The argument to be passed to this function is contained
633 * in parm. The new thread's stack size in bytes is specified in stacksize, and
634 * its execution priority in priority. The pid parameter is used to return the
635 * process ID of the new thread.
637 * If the thread is successfully created, it will be marked as runnable. The
638 * scheduler is called before the LWP CreateProcess() call completes, so the
639 * new thread may indeed begin its execution before the completion. Note that
640 * the new thread is guaranteed NOT to run before the call completes if the
641 * specified priority is lower than the caller's. On the other hand, if the new
642 * thread's priority is higher than the caller's, then it is guaranteed to run
643 * before the creation call completes.
645 * LWP EBADPRI The given priority is invalid, either negative or too large.
646 * \n LWP NOMEM Could not allocate memory to satisfy the creation request.
648 * \subsubsection sec2-3-1-4 Section: 2.3.1.4: LWP_DestroyProcess _ Create
652 * int LWP_DestroyProcess(IN PROCESS pid)
654 * This routine destroys the thread identified by pid. It will be terminated
655 * immediately, and its internal storage will be reclaimed. A thread is allowed
656 * to destroy itself. In this case, of course, it will only get to see the
657 * return code if the operation fails. Note that a thread may also destroy
658 * itself by returning from the parent C routine.
660 * The scheduler is called by this operation, which may cause an arbitrary
661 * number of threads to execute before the caller regains the processor.
663 * LWP EINIT The LWP package has not been initialized.
665 * \subsubsection sec2-3-1-5 Section 2.3.1.5: WaitProcess _ Wait on an
669 * int LWP WaitProcess(IN char *event)
671 * This routine puts the thread making the call to sleep until another LWP
672 * calls the LWP SignalProcess() or LWP NoYieldSignal() routine with the
673 * specified event. Note that signalled events are not queued. If a signal
674 * occurs and no thread is awakened, the signal is lost. The scheduler is
675 * invoked by the LWP WaitProcess() routine.
677 * LWP EINIT The LWP package has not been initialized.
678 * \n LWP EBADEVENT The given event pointer is null.
680 * \subsubsection sec2-3-1-6 Section 2.3.1.6: MwaitProcess _ Wait on a set
684 * int LWP MwaitProcess(IN int wcount; IN char *evlist[])
686 * This function allows a thread to wait for wcount signals on any of the items
687 * in the given evlist. Any number of signals of a particular event are only
688 * counted once. The evlist is a null-terminated list of events to wait for.
689 * The scheduler will be invoked.
691 * LWP EINIT The LWP package has not been initialized.
692 * \n LWP EBADCOUNT An illegal number of events has been supplied.
694 * \subsubsection sec2-3-1-7 Section 2.3.1.7: SignalProcess _ Signal an
698 * int LWP SignalProcess(IN char *event)
700 * This routine causes the given event to be signalled. All threads waiting for
701 * this event (exclusively) will be marked as runnable, and the scheduler will
702 * be invoked. Note that threads waiting on multiple events via LWP
703 * MwaitProcess() may not be marked as runnable. Signals are not queued.
704 * Therefore, if no thread is waiting for the signalled event, the signal will
707 * LWP EINIT The LWP package has not been initialized. LWP EBADEVENT A null
708 * event pointer has been provided. LWP ENOWAIT No thread was waiting on the
711 * \subsubsection sec2-3-1-8 Section 2.3.1.8: NoYieldSignal _ Signal an
712 * event without invoking scheduler
715 * int LWP NoYieldSignal(IN char *event)
717 * This function is identical to LWP SignalProcess() except that the scheduler
718 * will not be invoked. Thus, control will remain with the signalling process.
720 * LWP EINIT The LWP package has not been initialized. LWP EBADEVENT A null
721 * event pointer has been provided. LWP ENOWAIT No thread was waiting on the
724 * \subsubsection sec2-3-1-9 Section 2.3.1.9: DispatchProcess _ Yield
725 * control to the scheduler
728 * int LWP DispatchProcess()
730 * This routine causes the calling thread to yield voluntarily to the LWP
731 * scheduler. If no other thread of appropriate priority is marked as runnable,
732 * the caller will continue its execution.
734 * LWP EINIT The LWP package has not been initialized.
736 * \subsubsection sec2-3-1-10 Section 2.3.1.10: CurrentProcess _ Get the
737 * current thread's ID
740 * int LWP CurrentProcess(IN PROCESS *pid)
742 * This call places the current lightweight process ID in the pid parameter.
744 * LWP EINIT The LWP package has not been initialized.
746 * \subsubsection sec2-3-1-11 Section 2.3.1.11: ActiveProcess _ Get the
747 * current thread's ID (macro)
750 * int LWP ActiveProcess()
752 * This macro's value is the current lightweight process ID. It generates a
753 * value identical to that acquired by calling the LWP CurrentProcess()
754 * function described above if the LWP package has been initialized. If no such
755 * initialization has been done, it will return a value of zero.
757 * \subsubsection sec2-3-1-12 Section: 2.3.1.12: StackUsed _ Calculate
761 * int LWP StackUsed(IN PROCESS pid; OUT int *max; OUT int *used)
763 * This function returns the amount of stack space allocated to the thread
764 * whose identifier is pid, and the amount actually used so far. This is
765 * possible if the global variable lwp stackUseEnabled was TRUE when the thread
766 * was created (it is set this way by default). If so, the thread's stack area
767 * was initialized with a special pattern. The memory still stamped with this
768 * pattern can be determined, and thus the amount of stack used can be
769 * calculated. The max parameter is always set to the thread's stack allocation
770 * value, and used is set to the computed stack usage if lwp stackUseEnabled
771 * was set when the process was created, or else zero.
773 * LWP NO STACK Stack usage was not enabled at thread creation time.
775 * \subsubsection sec2-3-1-13 Section 2.3.1.13: NewRock _ Establish
776 * thread-specific storage
779 * int LWP NewRock (IN int tag; IN char **value)
781 * This function establishes a "rock", or thread-specific information,
782 * associating it with the calling LWP. The tag is intended to be any unique
783 * integer value, and the value is a pointer to a character array containing
786 * Users of the LWP package must coordinate their choice of tag values. Note
787 * that a tag's value cannot be changed. Thus, to obtain a mutable data
788 * structure, another level of indirection is required. Up to MAXROCKS (4)
789 * rocks may be associated with any given thread.
791 * ENOROCKS A rock with the given tag field already exists. All of the MAXROCKS
795 * \subsubsection sec2-3-1-14 Section: 2.3.1.14: GetRock _ Retrieve
796 * thread-specific storage
799 * int LWP GetRock(IN int tag; OUT **value)
801 * This routine recovers the thread-specific information associated with the
802 * calling process and the given tag, if any. Such a rock had to be established
803 * through a LWP NewRock() call. The rock's value is deposited into value.
805 * LWP EBADROCK A rock has not been associated with the given tag for this
808 * \subsection sec2-3-2 Section 2.3.2: Locking
811 * This section covers the calling interfaces to the locking package. Many of
812 * the user-callable routines are actually implemented as macros.
814 * \subsubsection sec2-3-2-1 Section 2.3.2.1: Lock Init _ Initialize lock
818 * void Lock Init(IN struct Lock *lock)
820 * This function must be called on the given lock object before any other
821 * operations can be performed on it.
823 * ---No value is returned.
825 * \subsubsection sec2-3-2-2 Section 2.3.2.2: ObtainReadLock _ Acquire a
829 * void ObtainReadLock(IN struct Lock *lock)
831 * This macro obtains a read lock on the specified lock object. Since this is a
832 * macro and not a function call, results are not predictable if the value of
833 * the lock parameter is a side-effect producing expression, as it will be
834 * evaluated multiple times in the course of the macro interpretation.
835 * Read locks are incompatible with write, shared, and boosted shared locks.
837 * ---No value is returned.
839 * \subsubsection sec2-3-2-3 Section 2.3.2.3: ObtainWriteLock _ Acquire a
843 * void ObtainWriteLock(IN struct Lock *lock)
845 * This macro obtains a write lock on the specified lock object. Since this is
846 * a macro and not a function call, results are not predictable if the value of
847 * the lock parameter is a side-effect producing expression, as it will be
848 * evaluated multiple times in the course of the macro interpretation.
850 * Write locks are incompatible with all other locks.
852 * ---No value is returned.
854 * \subsubsection sec2-3-2-4 Section 2.3.2.4: ObtainSharedLock _ Acquire a
858 * void ObtainSharedLock(IN struct Lock *lock)
860 * This macro obtains a shared lock on the specified lock object. Since this is
861 * a macro and not a function call, results are not predictable if the value of
862 * the lock parameter is a side-effect producing expression, as it will be
863 * evaluated multiple times in the course of the macro interpretation.
865 * Shared locks are incompatible with write and boosted shared locks, but are
866 * compatible with read locks.
868 * ---No value is returned.
870 * \subsubsection sec2-3-2-5 Section 2.3.2.5: ReleaseReadLock _ Release
874 * void ReleaseReadLock(IN struct Lock *lock)
876 * This macro releases the specified lock. The lock must have been previously
877 * read-locked. Since this is a macro and not a function call, results are not
878 * predictable if the value of the lock parameter is a side-effect producing
879 * expression, as it will be evaluated multiple times in the course of the
880 * macro interpretation. The results are also unpredictable if the lock was not
881 * previously read-locked by the thread calling ReleaseReadLock().
883 * ---No value is returned.
885 * \subsubsection sec2-3-2-6 Section 2.3.2.6: ReleaseWriteLock _ Release
889 * void ReleaseWriteLock(IN struct Lock *lock)
891 * This macro releases the specified lock. The lock must have been previously
892 * write-locked. Since this is a macro and not a function call, results are not
893 * predictable if the value of the lock parameter is a side-effect producing
894 * expression, as it will be evaluated multiple times in the course of the
895 * macro interpretation. The results are also unpredictable if the lock was not
896 * previously write-locked by the thread calling ReleaseWriteLock().
898 * ---No value is returned.
900 * \subsubsection sec2-3-2-7 Section 2.3.2.7: ReleaseSharedLock _ Release
904 * void ReleaseSharedLock(IN struct Lock *lock)
906 * This macro releases the specified lock. The lock must have been previously
907 * share-locked. Since this is a macro and not a function call, results are not
908 * predictalbe if the value of the lock parameter is a side-effect producing
909 * expression, as it will be evaluated multiple times in the course of the
910 * macro interpretation. The results are also unpredictable if the lock was not
911 * previously share-locked by the thread calling ReleaseSharedLock().
913 * ---No value is returned.
915 * \subsubsection sec2-3-2-8 Section 2.3.2.8: CheckLock _ Determine state
919 * void CheckLock(IN struct Lock *lock)
921 * This macro produces an integer that specifies the status of the indicated
922 * lock. The value will be -1 if the lock is write-locked, 0 if unlocked, or
923 * otherwise a positive integer that indicates the number of readers (threads
924 * holding read locks). Since this is a macro and not a function call, results
925 * are not predictable if the value of the lock parameter is a side-effect
926 * producing expression, as it will be evaluated multiple times in the course
927 * of the macro interpretation.
929 * ---No value is returned.
931 * \subsubsection sec2-3-2-9 Section 2.3.2.9: BoostLock _ Boost a shared
935 * void BoostLock(IN struct Lock *lock)
937 * This macro promotes ("boosts") a shared lock into a write lock. Such a boost
938 * operation guarantees that no other writer can get into the critical section
939 * in the process. Since this is a macro and not a function call, results are
940 * not predictable if the value of the lock parameter is a side-effect
941 * producing expression, as it will be evaluated multiple times in the course
942 * of the macro interpretation.
944 * ---No value is returned.
946 * \subsubsection sec2-3-2-10 Section 2.3.2.10: UnboostLock _ Unboost a
950 * void UnboostLock(IN struct Lock *lock)
952 * This macro demotes a boosted shared lock back down into a regular shared
953 * lock. Such an unboost operation guarantees that no other writer can get into
954 * the critical section in the process. Since this is a macro and not a
955 * function call, results are not predictable if the value of the lock
956 * parameter is a side-effect producing expression, as it will be evaluated
957 * multiple times in the course of the macro interpretation.
959 * ---No value is returned.
961 * \subsection sec2-3-3 Section 2.3.3: IOMGR
964 * This section covers the calling interfaces to the I/O management package.
966 * \subsubsection sec2-3-3-1 Section: 2.3.3.1: IOMGR Initialize _
967 * Initialize the package
970 * int IOMGR Initialize()
972 * This function initializes the IOMGR package. Its main task is to create the
973 * IOMGR thread itself, which runs at the lowest possible priority (0). The
974 * remainder of the lightweight processes must be running at priority 1 or
975 * greater (up to a maximum of LWP MAX PRIORITY (4)) for the IOMGR package to
976 * function correctly.
978 * -1 The LWP and/or timer package haven't been initialized.
979 * \n <misc> Any errors that may be returned by the LWP CreateProcess()
982 * \subsubsection sec2-3-3-2 Section 2.3.3.2: IOMGR finalize _ Clean up
986 * int IOMGR finalize()
988 * This routine cleans up after the IOMGR package when it is no longer needed.
989 * It releases all storage and destroys the IOMGR thread itself.
991 * <misc> Any errors that may be returned by the LWP DestroyProcess() routine.
993 * \subsubsection sec2-3-3-3 Section 2.3.3.3: IOMGR Select _ Perform a
994 * thread-level select()
997 * int IOMGR Select (IN int numfds; IN int *rfds; IN int *wfds; IN int *xfds;
998 * IN truct timeval *timeout)
1000 * This routine performs an LWP version of unix select() operation. The
1001 * parameters have the same meanings as with the unix call. However, the return
1002 * values will be simplified (see below). If this is a polling select (i.e.,
1003 * the value of timeout is null), it is done and the IOMGR Select() function
1004 * returns to the user with the results. Otherwise, the calling thread is put
1005 * to sleep. If at some point the IOMGR thread is the only runnable process, it
1006 * will awaken and collect all select requests. The IOMGR will then perform a
1007 * single select and awaken the appropriate processes. This will force a return
1008 * from the affected IOMGR Select() calls.
1010 * -1 An error occurred.
1011 * \n 0 A timeout occurred.
1012 * \n 1 Some number of file descriptors are ready.
1014 * \subsubsection sec2-3-3-4 Section 2.3.3.4: IOMGR Signal _ Associate
1015 * unix and LWP signals
1018 * int IOMGR Signal(IN int signo; IN char *event)
1020 * This function associates an LWP signal with a unix signal. After this call,
1021 * when the given unix signal signo is delivered to the (heavyweight unix)
1022 * process, the IOMGR thread will deliver an LWP signal to the event via LWP
1023 * NoYieldSignal(). This wakes up any lightweight processes waiting on the
1024 * event. Multiple deliveries of the signal may be coalesced into one LWP
1025 * wakeup. The call to LWP NoYieldSignal() will happen synchronously. It is
1026 * safe for an LWP to check for some condition and then go to sleep waiting for
1027 * a unix signal without having to worry about delivery of the signal happening
1028 * between the check and the call to LWP WaitProcess().
1030 * LWP EBADSIG The signo value is out of range.
1031 * \n LWP EBADEVENT The event pointer is null.
1033 * \subsubsection sec2-3-3-5 Section 2.3.3.5: IOMGR CancelSignal _ Cancel
1034 * unix and LWP signal association
1037 * int IOMGR CancelSignal(IN int signo)
1039 * This routine cancels the association between a unix signal and an LWP event.
1040 * After calling this function, the unix signal signo will be handled however
1041 * it was handled before the corresponding call to IOMGR Signal().
1043 * LWP EBADSIG The signo value is out of range.
1045 * \subsubsection sec2-3-3-6 Section 2.3.3.6: IOMGR Sleep _ Sleep for a
1049 * void IOMGR Sleep(IN unsigned seconds)
1051 * This function calls IOMGR Select() with zero file descriptors and a timeout
1052 * structure set up to cause the thread to sleep for the given number of
1055 * ---No value is returned.
1057 * \subsection sec2-3-4 Section 2.3.4: Timer
1060 * This section covers the calling interface to the timer package associated
1061 * with the LWP facility.
1063 * \subsubsection sec2-3-4-1 Section 2.3.4.1: TM Init _ Initialize a timer
1067 * int TM Init(IN struct TM Elem **list)
1069 * This function causes the specified timer list to be initialized. TM Init()
1070 * must be called before any other timer operations are applied to the list.
1072 * -1 A null timer list could not be produced.
1074 * \subsubsection sec2-3-4-2 Section 2.3.4.2: TM final _ Clean up a timer
1078 * int TM final(IN struct TM Elem **list)
1080 * This routine is called when the given empty timer list is no longer needed.
1081 * All storage associated with the list is released.
1083 * -1 The list parameter is invalid.
1085 * \subsubsection sec2-3-4-3 Section 2.3.4.3: TM Insert _ Insert an object
1089 * void TM Insert(IN struct TM Elem **list; IN struct TM Elem *elem)
1091 * This routine enters an new element, elem, into the list denoted by list.
1092 * Before the new element is queued, its TimeLeft field (the amount of time
1093 * before the object comes due) is set to the value stored in its TotalTime
1094 * field. In order to keep TimeLeft fields current, the TM Rescan() function
1097 * ---No return value is generated.
1099 * \subsubsection sec2-3-4-4 Section 2.3.4.4: TM Rescan _ Update all
1100 * timers in the list
1103 * int TM Rescan(IN struct TM Elem *list)
1105 * This function updates the TimeLeft fields of all timers on the given list.
1106 * This is done by checking the time-of-day clock. Note: this is the only
1107 * routine other than TM Init() that updates the TimeLeft field in the elements
1110 * Instead of returning a value indicating success or failure, TM Rescan()
1111 * returns the number of entries that were discovered to have timed out.
1113 * ---Instead of error codes, the number of entries that were discovered to
1114 * have timed out is returned.
1116 * \subsubsection sec2-3-4-5 Section 2.3.4.5: TM GetExpired _ Returns an
1120 * struct TM Elem *TM GetExpired(IN struct TM Elem *list)
1122 * This routine searches the specified timer list and returns a pointer to an
1123 * expired timer element from that list. An expired timer is one whose TimeLeft
1124 * field is less than or equal to zero. If there are no expired timers, a null
1125 * element pointer is returned.
1127 * ---Instead of error codes, an expired timer pointer is returned, or a null
1128 * timer pointer if there are no expired timer objects.
1130 * \subsubsection sec2-3-4-6 Section 2.3.4.6: TM GetEarliest _ Returns
1131 * earliest unexpired timer
1134 * struct TM Elem *TM GetEarliest(IN struct TM Elem *list)
1136 * This function returns a pointer to the timer element that will be next to
1137 * expire on the given list. This is defined to be the timer element with the
1138 * smallest (positive) TimeLeft field. If there are no timers on the list, or
1139 * if they are all expired, this function will return a null pointer.
1141 * ---Instead of error codes, a pointer to the next timer element to expireis
1142 * returned, or a null timer object pointer if they are all expired.
1144 * \subsubsection sec2-3-4-7 Section 2.3.4.7: TM eql _ Test for equality
1148 * bool TM eql(IN struct timemval *t1; IN struct timemval *t2)
1150 * This function compares the given timestamps, t1 and t2, for equality. Note
1151 * that the function return value, bool, has been set via typedef to be
1152 * equivalent to unsigned char.
1154 * 0 If the two timestamps differ.
1155 * \n 1 If the two timestamps are identical.
1157 * \subsection sec2-3-5 Section 2.3.5: Fast Time
1159 * This section covers the calling interface to the fast time package
1160 * associated with the LWP facility.
1162 * \subsubsection sec2-3-5-1 Section 2.3.5.1: FT Init _ Initialize the
1166 * int FT Init(IN int printErrors; IN int notReally)
1168 * This routine initializes the fast time package, mapping in the kernel page
1169 * containing the time-of-day variable. The printErrors argument, if non-zero,
1170 * will cause any errors in initalization to be printed to stderr. The
1171 * notReally parameter specifies whether initialization is really to be done.
1172 * Other calls in this package will do auto-initialization, and hence the
1173 * option is offered here.
1175 * -1 Indicates that future calls to FT GetTimeOfDay() will still work, but
1176 * will not be able to access the information directly, having to make a
1177 * kernel call every time.
1179 * \subsubsection sec2-3-5-2 Section 2.3.5.2: FT GetTimeOfDay _ Initialize
1180 * the fast time package
1183 * int FT GetTimeOfDay(IN struct timeval *tv; IN struct timezone *tz)
1185 * This routine is meant to mimic the parameters and behavior of the unix
1186 * gettimeofday() function. However, as implemented, it simply calls
1187 * gettimeofday() and then does some bound-checking to make sure the value is
1190 * <misc> Whatever value was returned by gettimeofday() internally.
1192 * \subsection sec2-3-6 Section 2.3.6: Preemption
1194 * This section covers the calling interface to the preemption package
1195 * associated with the LWP facility.
1197 * \subsubsection sec2-3-6-1 Section 2.3.6.1: PRE InitPreempt _ Initialize
1198 * the preemption package
1201 * int PRE InitPreempt(IN struct timeval *slice)
1203 * This function must be called to initialize the preemption package. It must
1204 * appear sometime after the call to LWP InitializeProcessSupport() and
1205 * sometime before the first call to any other preemption routine. The slice
1206 * argument specifies the time slice size to use. If the slice pointer is set
1207 * to null in the call, then the default time slice, DEFAULTSLICE (10
1208 * milliseconds), will be used. This routine uses the unix interval timer and
1209 * handling of the unix alarm signal, SIGALRM, to implement this timeslicing.
1211 * LWP EINIT The LWP package hasn't been initialized.
1212 * \n LWP ESYSTEM Operations on the signal vector or the interval timer have
1215 * \subsubsection sec2-3-6-2 Section 2.3.6.2: PRE EndPreempt _ finalize
1216 * the preemption package
1219 * int PRE EndPreempt()
1221 * This routine finalizes use of the preemption package. No further preemptions
1222 * will be made. Note that it is not necessary to make this call before exit.
1223 * PRE EndPreempt() is provided only for those applications that wish to
1224 * continue after turning off preemption.
1226 * LWP EINIT The LWP package hasn't been initialized.
1227 * \n LWP ESYSTEM Operations on the signal vector or the interval timer have
1230 * \subsubsection sec2-3-6-3 Section 2.3.6.3: PRE PreemptMe _ Mark thread
1234 * int PRE PreemptMe()
1236 * This macro is used to signify the current thread as a candidate for
1237 * preemption. The LWP InitializeProcessSupport() routine must have been called
1238 * before PRE PreemptMe().
1240 * ---No return code is generated.
1242 * \subsubsection sec2-3-6-4 Section 2.3.6.4: PRE BeginCritical _ Enter
1243 * thread critical section
1246 * int PRE BeginCritical()
1248 * This macro places the current thread in a critical section. Upon return, and
1249 * for as long as the thread is in the critical section, involuntary
1250 * preemptions of this LWP will no longer occur.
1252 * ---No return code is generated.
1254 * \subsubsection sec2-3-6-5 Section 2.3.6.5: PRE EndCritical _ Exit
1255 * thread critical section
1258 * int PRE EndCritical()
1260 * This macro causes the executing thread to leave a critical section
1261 * previously entered via PRE BeginCritical(). If involuntary preemptions were
1262 * possible before the matching PRE BeginCritical(), they are once again
1265 * ---No return code is generated.
1267 * \page chap3 Chapter 3 -- Rxkad
1270 * \section sec3-1 Section 3.1: Introduction
1273 * The rxkad security module is offered as one of the built-in Rx
1274 * authentication models. It is based on the Kerberos system developed by MIT's
1275 * Project Athena. Readers wishing detailed information regarding Kerberos
1276 * design and implementation are directed to [2]. This chapter is devoted to
1277 * defining how Kerberos authentication services are made available as Rx
1278 * components, and assumes the reader has some familiarity with Kerberos.
1279 * Included are descriptions of how client-side and server-side Rx security
1280 * objects (struct rx securityClass; see Section 5.3.1.1) implementing this
1281 * protocol may be generated by an Rx application. Also, a description appears
1282 * of the set of routines available in the associated struct rx securityOps
1283 * structures, as covered in Section 5.3.1.2. It is strongly recommended that
1284 * the reader become familiar with this section on struct rx securityOps before
1287 * \section sec3-2 Section 3.2: Definitions
1290 * An important set of definitions related to the rxkad security package is
1291 * provided by the rxkad.h include file. Determined here are various values for
1292 * ticket lifetimes, along with structures for encryption keys and Kerberos
1293 * principals. Declarations for the two routines required to generate the
1294 * different rxkad security objects also appear here. The two functions are
1295 * named rxkad NewServerSecurityObject() and rxkad NewClientSecurityObject().
1296 * In addition, type field values, encryption levels, security index
1297 * operations, and statistics structures may be found in this file.
1298 * \section sec3-3 Section 3.3: Exported Objects
1300 * To be usable as an Rx security module, the rxkad facility exports routines
1301 * to create server-side and client-side security objects. The server
1302 * authentication object is incorporated into the server code when calling rx
1303 * NewService(). The client authentication object is incorporated into the
1304 * client code every time a connection is established via rx NewConnection().
1305 * Also, in order to implement these security objects, the rxkad module must
1306 * provide definitions for some subset of the generic security operations as
1307 * defined in the appropriate struct rx securityOps variable.
1309 * \subsection sec3-3-1 Section 3.3.1: Server-Side Mechanisms
1311 * \subsubsection sec3-3-1-1 Section 3.3.1.1: Security Operations
1314 * The server side of the rxkad module fills in all but two of the possible
1315 * routines associated with an Rx security object, as described in Section
1319 * static struct rx_securityOps rxkad_server_ops = {
1321 * rxkad_NewConnection,
1322 * rxkad_PreparePacket, /* Once per packet creation */
1323 * 0, /* Send packet (once per retrans) */
1324 * rxkad_CheckAuthentication,
1325 * rxkad_CreateChallenge,
1326 * rxkad_GetChallenge,
1328 * rxkad_CheckResponse, /* Check data packet */
1329 * rxkad_DestroyConnection,
1335 * The rxkad service does not need to take any special action each time a
1336 * packet belonging to a call in an rxkad Rx connection is physically
1337 * transmitted. Thus, a routine is not supplied for the op SendPacket()
1338 * function slot. Similarly, no preparatory work needs to be done previous to
1339 * the reception of a response packet from a security challenge, so the op
1340 * GetResponse() function slot is also empty.
1342 * \subsubsection sec3-3-1-2 Section 3.3.1.2: Security Object
1345 * The exported routine used to generate an rxkad-specific server-side security
1346 * class object is named rxdad NewServerSecurityObject(). It is declared with
1347 * four parameters, as follows:
1350 * struct rx_securityClass *
1351 * rxkad_NewServerSecurityObject(a_level, a_getKeyRockP, a_getKeyP, a_userOKP)
1352 * rxkad_level a_level; /* Minimum level */
1353 * char *a_getKeyRockP; /* Rock for get_key implementor */
1354 * int (*a_getKeyP)(); /* Passed kvno & addr(key) to fill */
1355 * int (*a_userOKP)(); /* Passed name, inst, cell => bool */
1359 * The first argument specifies the desired level of encryption, and may take
1360 * on the following values (as defined in rxkad.h):
1361 * \li rxkad clear: Specifies that packets are to be sent entirely in the
1362 * clear, without any encryption whatsoever.
1363 * \li rxkad auth: Specifies that packet sequence numbers are to be encrypted.
1364 * \li rxkad crypt: Specifies that the entire data packet is to be encrypted.
1367 * The second and third parameters represent, respectively, a pointer to a
1368 * private data area, sometimes called a "rock", and a procedure reference that
1369 * is called with the key version number accompanying the Kerberos ticket and
1370 * returns a pointer to the server's decryption key. The fourth argument, if
1371 * not null, is a pointer to a function that will be called for every new
1372 * connection with the client's name, instance, and cell. This routine should
1373 * return zero if the user is not acceptable to the server.
1375 * \subsection sec3-3-2 Section 3.3.2: Client-Side Mechanisms
1377 * \subsubsection sec3-3-2-1 Section 3.3.2.1: Security Operations
1380 * The client side of the rxkad module fills in relatively few of the routines
1381 * associated with an Rx security object, as demonstrated below. The general Rx
1382 * security object, of which this is an instance, is described in detail in
1386 * static struct rx_securityOps rxkad_client_ops = {
1388 * rxkad_NewConnection, /* Every new connection */
1389 * rxkad_PreparePacket, /* Once per packet creation */
1390 * 0, /* Send packet (once per retrans) */
1394 * rxkad_GetResponse, /* Respond to challenge packet */
1396 * rxkad_CheckPacket, /* Check data packet */
1397 * rxkad_DestroyConnection,
1406 * As expected, routines are defined for use when someone destroys a security
1407 * object (rxkad Close()) and when an Rx connection using the rxkad model
1408 * creates a new connection (rxkad NewConnection()) or deletes an existing one
1409 * (rxkad DestroyConnection()). Security-specific operations must also be
1410 * performed in behalf of rxkad when packets are created (rxkad
1411 * PreparePacket()) and received (rxkad CheckPacket()). finally, the client
1412 * side of an rxkad security object must also be capable of constructing
1413 * responses to security challenges from the server (rxkad GetResponse()) and
1414 * be willing to reveal statistics on its own operation (rxkad GetStats()).
1416 * \subsubsection sec3-3-2-2 Section 3.3.2.2: Security Object
1419 * The exported routine used to generate an rxkad-specific client-side security
1420 * class object is named rxkad NewClientSecurityObject(). It is declared with
1421 * five parameters, specified below:
1424 * struct rx_securityClass * rxkad_NewClientSecurityObject(
1431 * rxkad_level a_level;
1432 * struct ktc_encryptionKey *a_sessionKeyP;
1439 * The first parameter, a level, specifies the level of encryption desired for
1440 * this security object, with legal choices being identical to those defined
1441 * for the server-side security object described in Section 3.3.1.2. The second
1442 * parameter, a sessionKeyP, provides the session key to use. The ktc
1443 * encryptionKey structure is defined in the rxkad.h include file, and consists
1444 * of an array of 8 characters. The third parameter, a kvno, provides the key
1445 * version number associated with a sessionKeyP. The fourth argument, a
1446 * ticketLen, communicates the length in bytes of the data stored in the fifth
1447 * parameter, a ticketP, which points to the Kerberos ticket to use for the
1448 * principal for which the security object will operate.
1450 * \page chap4 Chapter 4 -- Rx Support Packages
1452 * \section sec4-1 Section 4.1: Introduction
1454 * This chapter documents three packages defined directly in support of the Rx
1456 * \li rx queue: Doubly-linked queue package.
1457 * \li rx clock: Clock package, using the 4.3BSD interval timer.
1458 * \li rx event: Future events package.
1460 * References to constants, structures, and functions defined by these support
1461 * packages will appear in the following API chapter.
1463 * \section sec4-2 Section 4.2: The rx queue Package
1466 * This package provides a doubly-linked queue structure, along with a full
1467 * suite of related operations. The main concern behind the coding of this
1468 * facility was efficiency. All functions are implemented as macros, and it is
1469 * suggested that only simple expressions be used for all parameters.
1471 * The rx queue facility is defined by the rx queue.h include file. Some macros
1472 * visible in this file are intended for rx queue internal use only. An
1473 * understanding of these "hidden" macros is important, so they will also be
1474 * described by this document.
1476 * \subsection sec4-2-1 Section 4.2.1: struct queue
1479 * The queue structure provides the linkage information required to maintain a
1480 * queue of objects. The queue structure is prepended to any user-defined data
1481 * type which is to be organized in this fashion.
1483 * \li struct queue *prev - Pointer to the previous queue header.
1484 * \li struct queue *next - Pointer to the next queue header.
1486 * Note that a null Rx queue consists of a single struct queue object whose
1487 * next and previous pointers refer to itself.
1489 * \subsection sec4-2-2 Section 4.2.2: Internal Operations
1492 * This section describes the internal operations defined for Rx queues. They
1493 * will be referenced by the external operations documented in Section 4.2.3.
1495 * \subsection sec4-2-2-1 Section 4.2.2.1: Q(): Coerce type to a queue
1499 * \#define _Q(x) ((struct queue *)(x))
1501 * This operation coerces the user structure named by x to a queue element. Any
1502 * user structure using the rx queue package must have a struct queue as its
1505 * \subsubsection sec4-2-2-2 Section 4.2.2.2: QA(): Add a queue element
1506 * before/after another element
1509 * \#define _QA(q,i,a,b) (((i->a=q->a)->b=i)->b=q, q->a=i)
1511 * This operation adds the queue element referenced by i either before or after
1512 * a queue element represented by q. If the (a, b) argument pair corresponds to
1513 * an element's (next, prev) fields, the new element at i will be linked after
1514 * q. If the (a, b) argument pair corresponds to an element's (prev, next)
1515 * fields, the new element at i will be linked before q.
1517 * \subsubsection sec4-2-2-3 QR(): Remove a queue element
1520 * \#define _QR(i) ((_Q(i)->prev->next=_Q(i)->next)->prev=_Q(i)->prev)
1522 * This operation removes the queue element referenced by i from its queue. The
1523 * prev and next fields within queue element i itself is not updated to reflect
1524 * the fact that it is no longer part of the queue.
1526 * \subsubsection sec4-2-2-4 QS(): Splice two queues together
1529 * \#define _QS(q1,q2,a,b) if (queue_IsEmpty(q2)); else
1530 * ((((q2->a->b=q1)->a->b=q2->b)->a=q1->a, q1->a=q2->a), queue_Init(q2))
1532 * This operation takes the queues identified by q1 and q2 and splices them
1533 * together into a single queue. The order in which the two queues are appended
1534 * is determined by the a and b arguments. If the (a, b) argument pair
1535 * corresponds to q1's (next, prev) fields, then q2 is appended to q1. If the
1536 * (a, b) argument pair corresponds to q1's (prev, next) fields, then q is
1539 * This internal QS() routine uses two exported queue operations, namely queue
1540 * Init() and queue IsEmpty(), defined in Sections 4.2.3.1 and 4.2.3.16
1541 * respectively below.
1543 * \subsection sec4-2-3 Section 4.2.3: External Operations
1545 * \subsubsection sec4-2-3-1 Section 4.2.3.1: queue Init(): Initialize a
1549 * \#define queue_Init(q) (_Q(q))->prev = (_Q(q))->next = (_Q(q))
1551 * The queue header referred to by the q argument is initialized so that it
1552 * describes a null (empty) queue. A queue head is simply a queue element.
1554 * \subsubsection sec4-2-3-2 Section 4.2.3.2: queue Prepend(): Put element
1555 * at the head of a queue
1558 * \#define queue_Prepend(q,i) _QA(_Q(q),_Q(i),next,prev)
1560 * Place queue element i at the head of the queue denoted by q. The new queue
1561 * element, i, should not currently be on any queue.
1563 * \subsubsection sec4-2-3-3 Section 4.2.3.3: queue Append(): Put an
1564 * element a the tail of a queue
1567 * \#define queue_Append(q,i) _QA(_Q(q),_Q(i),prev,next)
1569 * Place queue element i at the tail of the queue denoted by q. The new queue
1570 * element, i, should not currently be on any queue.
1572 * \subsection sec4-2-3-4 Section 4.2.3.4: queue InsertBefore(): Insert a
1573 * queue element before another element
1576 * \#define queue_InsertBefore(i1,i2) _QA(_Q(i1),_Q(i2),prev,next)
1578 * Insert queue element i2 before element i1 in i1's queue. The new queue
1579 * element, i2, should not currently be on any queue.
1581 * \subsubsection sec4-2-3-5 Section 4.2.3.5: queue InsertAfter(): Insert
1582 * a queue element after another element
1585 * \#define queue_InsertAfter(i1,i2) _QA(_Q(i1),_Q(i2),next,prev)
1587 * Insert queue element i2 after element i1 in i1's queue. The new queue
1588 * element, i2, should not currently be on any queue.
1590 * \subsubsection sec4-2-3-6 Section: 4.2.3.6: queue SplicePrepend():
1591 * Splice one queue before another
1594 * \#define queue_SplicePrepend(q1,q2) _QS(_Q(q1),_Q(q2),next,prev)
1596 * Splice the members of the queue located at q2 to the beginning of the queue
1597 * located at q1, reinitializing queue q2.
1599 * \subsubsection sec4-2-3-7 Section 4.2.3.7: queue SpliceAppend(): Splice
1600 * one queue after another
1603 * \#define queue_SpliceAppend(q1,q2) _QS(_Q(q1),_Q(q2),prev,next)
1605 * Splice the members of the queue located at q2 to the end of the queue
1606 * located at q1, reinitializing queue q2. Note that the implementation of
1607 * queue SpliceAppend() is identical to that of queue SplicePrepend() except
1608 * for the order of the next and prev arguments to the internal queue splicer,
1611 * \subsubsection sec4-2-3-8 Section 4.2.3.8: queue Replace(): Replace the
1612 * contents of a queue with that of another
1615 * \#define queue_Replace(q1,q2) (*_Q(q1) = *_Q(q2),
1616 * \n _Q(q1)->next->prev = _Q(q1)->prev->next = _Q(q1),
1617 * \n queue_Init(q2))
1619 * Replace the contents of the queue located at q1 with the contents of the
1620 * queue located at q2. The prev and next fields from q2 are copied into the
1621 * queue object referenced by q1, and the appropriate element pointers are
1622 * reassigned. After the replacement has occurred, the queue header at q2 is
1625 * \subsubsection sec4-2-3-9 Section 4.2.3.9: queue Remove(): Remove an
1626 * element from its queue
1629 * \#define queue_Remove(i) (_QR(i), _Q(i)->next = 0)
1631 * This function removes the queue element located at i from its queue. The
1632 * next field for the removed entry is zeroed. Note that multiple removals of
1633 * the same queue item are not supported.
1635 * \subsubsection sec4-2-3-10 Section 4.2.3.10: queue MoveAppend(): Move
1636 * an element from its queue to the end of another queue
1639 * \#define queue_MoveAppend(q,i) (_QR(i), queue_Append(q,i))
1641 * This macro removes the queue element located at i from its current queue.
1642 * Once removed, the element at i is appended to the end of the queue located
1645 * \subsubsection sec4-2-3-11 Section 4.2.3.11: queue MovePrepend(): Move
1646 * an element from its queue to the head of another queue
1649 * \#define queue_MovePrepend(q,i) (_QR(i), queue_Prepend(q,i))
1651 * This macro removes the queue element located at i from its current queue.
1652 * Once removed, the element at i is inserted at the head fo the queue located
1655 * \subsubsection sec4-2-3-12 Section 4.2.3.12: queue first(): Return the
1656 * first element of a queue, coerced to a particular type
1659 * \#define queue_first(q,s) ((struct s *)_Q(q)->next)
1661 * Return a pointer to the first element of the queue located at q. The
1662 * returned pointer value is coerced to conform to the given s structure. Note
1663 * that a properly coerced pointer to the queue head is returned if q is empty.
1665 * \subsubsection sec4-2-3-13 Section 4.2.3.13: queue Last(): Return the
1666 * last element of a queue, coerced to a particular type
1669 * \#define queue_Last(q,s) ((struct s *)_Q(q)->prev)
1671 * Return a pointer to the last element of the queue located at q. The returned
1672 * pointer value is coerced to conform to the given s structure. Note that a
1673 * properly coerced pointer to the queue head is returned if q is empty.
1675 * \subsubsection sec4-2-3-14 Section 4.2.3.14: queue Next(): Return the
1676 * next element of a queue, coerced to a particular type
1679 * \#define queue_Next(i,s) ((struct s *)_Q(i)->next)
1681 * Return a pointer to the queue element occuring after the element located at
1682 * i. The returned pointer value is coerced to conform to the given s
1683 * structure. Note that a properly coerced pointer to the queue head is
1684 * returned if item i is the last in its queue.
1686 * \subsubsection sec4-2-3-15 Section 4.2.3.15: queue Prev(): Return the
1687 * next element of a queue, coerced to a particular type
1690 * \#define queue_Prev(i,s) ((struct s *)_Q(i)->prev)
1692 * Return a pointer to the queue element occuring before the element located at
1693 * i. The returned pointer value is coerced to conform to the given s
1694 * structure. Note that a properly coerced pointer to the queue head is
1695 * returned if item i is the first in its queue.
1697 * \subsubsection sec4-2-3-16 Section 4.2.3.16: queue IsEmpty(): Is the
1698 * given queue empty?
1701 * \#define queue_IsEmpty(q) (_Q(q)->next == _Q(q))
1703 * Return a non-zero value if the queue located at q does not have any elements
1704 * in it. In this case, the queue consists solely of the queue header at q
1705 * whose next and prev fields reference itself.
1707 * \subsubsection sec4-2-3-17 Section 4.2.3.17: queue IsNotEmpty(): Is the
1708 * given queue not empty?
1711 * \#define queue_IsNotEmpty(q) (_Q(q)->next != _Q(q))
1713 * Return a non-zero value if the queue located at q has at least one element
1714 * in it other than the queue header itself.
1716 * \subsubsection sec4-2-3-18 Section 4.2.3.18: queue IsOnQueue(): Is an
1717 * element currently queued?
1720 * \#define queue_IsOnQueue(i) (_Q(i)->next != 0)
1722 * This macro returns a non-zero value if the queue item located at i is
1723 * currently a member of a queue. This is determined by examining its next
1724 * field. If it is non-null, the element is considered to be queued. Note that
1725 * any element operated on by queue Remove() (Section 4.2.3.9) will have had
1726 * its next field zeroed. Hence, it would cause a non-zero return from this
1729 * \subsubsection sec4-2-3-19 Section 4.2.3.19: queue Isfirst(): Is an
1730 * element the first on a queue?
1733 * \#define queue_Isfirst(q,i) (_Q(q)->first == _Q(i))
1735 * This macro returns a non-zero value if the queue item located at i is the
1736 * first element in the queue denoted by q.
1738 * \subsubsection sec4-2-3-20 Section 4.2.3.20: queue IsLast(): Is an
1739 * element the last on a queue?
1742 * \#define queue_IsLast(q,i) (_Q(q)->prev == _Q(i))
1744 * This macro returns a non-zero value if the queue item located at i is the
1745 * last element in the queue denoted by q.
1747 * \subsubsection sec4-2-3-21 Section 4.2.3.21: queue IsEnd(): Is an
1748 * element the end of a queue?
1751 * \#define queue_IsEnd(q,i) (_Q(q) == _Q(i))
1753 * This macro returns a non-zero value if the queue item located at i is the
1754 * end of the queue located at q. Basically, it determines whether a queue
1755 * element in question is also the queue header structure itself, and thus does
1756 * not represent an actual queue element. This function is useful for
1757 * terminating an iterative sweep through a queue, identifying when the search
1758 * has wrapped to the queue header.
1760 * \subsubsection sec4-2-3-22 Section 4.2.3.22: queue Scan(): for loop
1761 * test for scanning a queue in a forward direction
1764 * \#define queue_Scan(q, qe, next, s)
1765 * \n (qe) = queue_first(q, s), next = queue_Next(qe, s);
1766 * \n !queue_IsEnd(q, qe);
1767 * \n (qe) = (next), next = queue_Next(qe, s)
1769 * This macro may be used as the body of a for loop test intended to scan
1770 * through each element in the queue located at q. The qe argument is used as
1771 * the for loop variable. The next argument is used to store the next value for
1772 * qe in the upcoming loop iteration. The s argument provides the name of the
1773 * structure to which each queue element is to be coerced. Thus, the values
1774 * provided for the qe and next arguments must be of type (struct s *).
1776 * An example of how queue Scan() may be used appears in the code fragment
1777 * below. It declares a structure named mystruct, which is suitable for
1778 * queueing. This queueable structure is composed of the queue pointers
1779 * themselves followed by an integer value. The actual queue header is kept in
1780 * demoQueue, and the currItemP and nextItemP variables are used to step
1781 * through the demoQueue. The queue Scan() macro is used in the for loop to
1782 * generate references in currItemP to each queue element in turn for each
1783 * iteration. The loop is used to increment every queued structure's myval
1791 * struct queue demoQueue;
1792 * struct mystruct *currItemP, *nextItemP;
1794 * for (queue_Scan(&demoQueue, currItemP, nextItemP, mystruct)) {
1795 * currItemP->myval++;
1800 * Note that extra initializers can be added before the body of the queue
1801 * Scan() invocation above, and extra expressions can be added afterwards.
1803 * \subsubsection sec4-2-3-23 Section 4.2.3.23: queue ScanBackwards(): for
1804 * loop test for scanning a queue in a reverse direction
1807 * #define queue_ScanBackwards(q, qe, prev, s)
1808 * \n (qe) = queue_Last(q, s), prev = queue_Prev(qe, s);
1809 * \n !queue_IsEnd(q, qe);
1810 * \n (qe) = prev, prev = queue_Prev(qe, s)
1812 * This macro is identical to the queue Scan() macro described above in Section
1813 * 4.2.3.22 except for the fact that the given queue is scanned backwards,
1814 * starting at the last item in the queue.
1816 * \section sec4-3 Section 4.3: The rx clock Package
1819 * This package maintains a clock which is independent of the time of day. It
1820 * uses the unix 4.3BSD interval timer (e.g., getitimer(), setitimer()) in
1821 * TIMER REAL mode. Its definition and interface may be found in the rx clock.h
1824 * \subsection sec4-3-1 Section 4.3.1: struct clock
1827 * This structure is used to represent a clock value as understood by this
1828 * package. It consists of two fields, storing the number of seconds and
1829 * microseconds that have elapsed since the associated clock Init() routine has
1833 * \n long sec -Seconds since call to clock Init().
1834 * \n long usec -Microseconds since call to clock Init().
1836 * \subsection sec4-3-2 Section 4.3.12: clock nUpdates
1839 * The integer-valued clock nUpdates is a variable exported by the rx clock
1840 * facility. It records the number of times the clock value is actually
1841 * updated. It is bumped each time the clock UpdateTime() routine is called, as
1842 * described in Section 4.3.3.2.
1844 * \subsection sec4-3-3 Section 4.3.3: Operations
1846 * \subsubsection sec4-3-3-1 Section 4.3.3.1: clock Init(): Initialize the
1850 * This routine uses the unix setitimer() call to initialize the unix interval
1851 * timer. If the setitimer() call fails, an error message will appear on
1852 * stderr, and an exit(1) will be executed.
1854 * \subsubsection sec4-3-3-2 Section 4.3.3.2: clock UpdateTime(): Compute
1858 * The clock UpdateTime() function calls the unix getitimer() routine in order
1859 * to update the current time. The exported clock nUpdates variable is
1860 * incremented each time the clock UpdateTime() routine is called.
1862 * \subsubsection sec4-3-3-3 Section 4.3.3.3: clock GetTime(): Return the
1863 * current clock time
1866 * This macro updates the current time if necessary, and returns the current
1867 * time into the cv argument, which is declared to be of type (struct clock *).
1868 * 4.3.3.4 clock Sec(): Get the current clock time, truncated to seconds
1869 * This macro returns the long value of the sec field of the current time. The
1870 * recorded time is updated if necessary before the above value is returned.
1872 * \subsubsection sec4-3-3-5 Section 4.3.3.5: clock ElapsedTime(): Measure
1873 * milliseconds between two given clock values
1876 * This macro returns the elapsed time in milliseconds between the two clock
1877 * structure pointers provided as arguments, cv1 and cv2.
1879 * \subsubsection sec4-3-3-6 Section 4.3.3.6: clock Advance(): Advance the
1880 * recorded clock time by a specified clock value
1883 * This macro takes a single (struct clock *) pointer argument, cv, and adds
1884 * this clock value to the internal clock value maintined by the package.
1886 * \subsubsection sec4-3-3-7 Section 4.3.3.7: clock Gt(): Is a clock value
1887 * greater than another?
1890 * This macro takes two parameters of type (struct clock *), a and b. It
1891 * returns a nonzero value if the a parameter points to a clock value which is
1892 * later than the one pointed to by b.
1894 * \subsubsection sec4-3-3-8 Section 4.3.3.8: clock Ge(): Is a clock value
1895 * greater than or equal to another?
1898 * This macro takes two parameters of type (struct clock *), a and b. It
1899 * returns a nonzero value if the a parameter points to a clock value which is
1900 * greater than or equal to the one pointed to by b.
1902 * \subsubsection sec4-3-3-9 Section 4.3.3.9: clock Gt(): Are two clock
1906 * This macro takes two parameters of type (struct clock *), a and b. It
1907 * returns a non-zero value if the clock values pointed to by a and b are
1910 * \subsubsection sec4.3.3.10 Section 4.3.3.10: clock Le(): Is a clock
1911 * value less than or equal to another?
1914 * This macro takes two parameters of type (struct clock *), a and b. It
1915 * returns a nonzero value if the a parameter points to a clock value which is
1916 * less than or equal to the one pointed to by b.
1918 * \subsubsection sec4-3-3-11 Section 4.3.3.11: clock Lt(): Is a clock
1919 * value less than another?
1922 * This macro takes two parameters of type (struct clock *), a and b. It
1923 * returns a nonzero value if the a parameter points to a clock value which is
1924 * less than the one pointed to by b.
1926 * \subsubsection sec4-3-3-12 Section 4.3.3.12: clock IsZero(): Is a clock
1930 * This macro takes a single parameter of type (struct clock *), c. It returns
1931 * a non-zero value if the c parameter points to a clock value which is equal
1934 * \subsubsection sec4-3-3-13 Section 4.3.3.13: clock Zero(): Set a clock
1938 * This macro takes a single parameter of type (struct clock *), c. It sets the
1939 * given clock value to zero.
1940 * \subsubsection sec4-3-3-14 Section 4.3.3.14: clock Add(): Add two clock
1943 * This macro takes two parameters of type (struct clock *), c1 and c2. It adds
1944 * the value of the time in c2 to c1. Both clock values must be positive.
1946 * \subsubsection sec4-3-3-15 Section 4.3.3.15: clock Sub(): Subtract two
1950 * This macro takes two parameters of type (struct clock *), c1 and c2. It
1951 * subtracts the value of the time in c2 from c1. The time pointed to by c2
1952 * should be less than the time pointed to by c1.
1954 * \subsubsection sec4-3-3-16 Section 4.3.3.16: clock Float(): Convert a
1955 * clock time into floating point
1958 * This macro takes a single parameter of type (struct clock *), c. It
1959 * expresses the given clock value as a floating point number.
1961 * \section sec4-4 Section 4.4: The rx event Package
1964 * This package maintains an event facility. An event is defined to be
1965 * something that happens at or after a specified clock time, unless cancelled
1966 * prematurely. The clock times used are those provided by the rx clock
1967 * facility described in Section 4.3 above. A user routine associated with an
1968 * event is called with the appropriate arguments when that event occurs. There
1969 * are some restrictions on user routines associated with such events. first,
1970 * this user-supplied routine should not cause process preemption. Also, the
1971 * event passed to the user routine is still resident on the event queue at the
1972 * time of invocation. The user must not remove this event explicitly (via an
1973 * event Cancel(), see below). Rather, the user routine may remove or schedule
1974 * any other event at this time.
1976 * The events recorded by this package are kept queued in order of expiration
1977 * time, so that the first entry in the queue corresponds to the event which is
1978 * the first to expire. This interface is defined by the rx event.h include
1981 * \subsection sec4-4-1 Section 4.4.1: struct rxevent
1984 * This structure defines the format of an Rx event record.
1987 * \n struct queue junk -The queue to which this event belongs.
1988 * \n struct clock eventTime -The clock time recording when this event comes
1990 * \n int (*func)() -The user-supplied function to call upon expiration.
1991 * \n char *arg -The first argument to the (*func)() function above.
1992 * \n char *arg1 -The second argument to the (*func)() function above.
1994 * \subsection sec4-4-2 Section 4.4.2: Operations
1997 * This section covers the interface routines provided for the Rx event
2000 * \subsubsection sec4-4-2-1 Section 4.4.2.1: rxevent Init(): Initialize
2004 * The rxevent Init() routine takes two arguments. The first, nEvents, is an
2005 * integer-valued parameter which specifies the number of event structures to
2006 * allocate at one time. This specifies the appropriate granularity of memory
2007 * allocation by the event package. The second parameter, scheduler, is a
2008 * pointer to an integer-valued function. This function is to be called when an
2009 * event is posted (added to the set of events managed by the package) that is
2010 * scheduled to expire before any other existing event.
2012 * This routine sets up future event allocation block sizes, initializes the
2013 * queues used to manage active and free event structures, and recalls that an
2014 * initialization has occurred. Thus, this function may be safely called
2017 * \subsubsection sec4-4-2-2 Section 4.4.2.2: rxevent Post(): Schedule an
2021 * This function constructs a new event based on the information included in
2022 * its parameters and then schedules it. The rxevent Post() routine takes four
2023 * parameters. The first is named when, and is of type (struct clock *). It
2024 * specifies the clock time at which the event is to occur. The second
2025 * parameter is named func and is a pointer to the integer-valued function to
2026 * associate with the event that will be created. When the event comes due,
2027 * this function will be executed by the event package. The next two arguments
2028 * to rxevent Post() are named arg and arg1, and are both of type (char *).
2029 * They serve as the two arguments thath will be supplied to the func routine
2030 * when the event comes due.
2032 * If the given event is set to take place before any other event currently
2033 * posted, the scheduler routine established when the rxevent Init() routine
2034 * was called will be executed. This gives the application a chance to react to
2035 * this new event in a reasonable way. One might expect that this scheduler
2036 * routine will alter sleep times used by the application to make sure that it
2037 * executes in time to handle the new event.
2039 * \subsubsection sec4-4-2-3 Section 4.4.2.3: rxevent Cancel 1(): Cancel
2040 * an event (internal use)
2043 * This routine removes an event from the set managed by this package. It takes
2044 * a single parameter named ev of type (struct rxevent *). The ev argument
2045 * identifies the pending event to be cancelled.
2047 * The rxevent Cancel 1() routine should never be called directly. Rather, it
2048 * should be accessed through the rxevent Cancel() macro, described in Section
2051 * \subsubsection sec4-4-2-4 Section 4.4.2.4: rxevent Cancel(): Cancel an
2052 * event (external use)
2055 * This macro is the proper way to call the rxevent Cancel 1() routine
2056 * described in Section 4.4.2.3 above. Like rxevent Cancel 1(), it takes a
2057 * single argument. This event ptr argument is of type (struct rxevent *), and
2058 * identi#es the pending event to be cancelled. This macro #rst checks to see
2059 * if event ptr is null. If not, it calls rxevent Cancel 1() to perform the
2060 * real work. The event ptr argument is zeroed after the cancellation operation
2063 * \subsubsection sec4-4-2-5 Section 4.4.2.4: rxevent RaiseEvents():
2064 * Initialize the event package
2067 * This function processes all events that have expired relative to the current
2068 * clock time maintained by the event package. Each qualifying event is removed
2069 * from the queue in order, and its user-supplied routine (func()) is executed
2070 * with the associated arguments.
2072 * The rxevent RaiseEvents() routine takes a single output parameter named
2073 * next, defined to be of type (struct clock *). Upon completion of rxevent
2074 * RaiseEvents(), the relative time to the next event due to expire is placed
2075 * in next. This knowledge may be used to calculate the amount of sleep time
2076 * before more event processing is needed. If there is no recorded event which
2077 * is still pending at this point, rxevent RaiseEvents() returns a zeroed clock
2080 * \subsubsection sec4-4-2-6 Section 4.4.2.6: rxevent TimeToNextEvent():
2081 * Get amount of time until the next event expires
2084 * This function returns the time between the current clock value as maintained
2085 * by the event package and the the next event's expiration time. This
2086 * information is placed in the single output argument,interval, defined to be
2087 * of type (struct clock *). The rxevent TimeToNextEvent() function returns
2088 * integer-valued quantities. If there are no scheduled events, a zero is
2089 * returned. If there are one or more scheduled events, a 1 is returned. If
2090 * zero is returned, the interval argument is not updated.
2092 * \page chap5 Chapter 5 -- Programming Interface
2094 * \section sec5-1 Section 5.1: Introduction
2097 * This chapter documents the API for the Rx facility. Included are
2098 * descriptions of all the constants, structures, exported variables, macros,
2099 * and interface functions available to the application programmer. This
2100 * interface is identical regardless of whether the application lives within
2101 * the unix kernel or above it.
2103 * This chapter actually provides more information than what may be strictly
2104 * considered the Rx API. Many objects that were intended to be opaque and for
2105 * Rx internal use only are also described here. The reason driving the
2106 * inclusion of this "extra" information is that such exported Rx interface
2107 * files as rx.h make these objects visible to application programmers. It is
2108 * prefereable to describe these objects here than to ignore them and leave
2109 * application programmers wondering as to their meaning.
2111 * An example application illustrating the use of this interface, showcasing
2112 * code from both server and client sides, appears in the following chapter.
2114 * \section sec5-2 Section 5.2: Constants
2117 * This section covers the basic constant definitions of interest to the Rx
2118 * application programmer. Each subsection is devoted to describing the
2119 * constants falling into the following categories:
2120 * \li Configuration quantities
2121 * \li Waiting options
2122 * \li Connection ID operations
2123 * \li Connection flags
2124 * \li Connection types
2128 * \li Packet header flags
2131 * \li Packet classes
2132 * \li Conditions prompting ack packets
2135 * \li Debugging values
2137 * An attempt has been made to relate these constant definitions to the objects
2138 * or routines that utilize them.
2140 * \subsection sec5-2-1 Section 5.2.1: Configuration Quantities
2143 * These definitions provide some basic Rx configuration parameters, including
2144 * the number of simultaneous calls that may be handled on a single connection,
2145 * lightweight thread parameters, and timeouts for various operations.
2152 * Default idle dead time for connections, in seconds.
2159 * The maximum number of Rx services that may be installed within one
2163 * RX PROCESS MAXCALLS
2167 * The maximum number of asynchronous calls active simultaneously on any given
2168 * Rx connection. This value must be set to a power of two.
2171 * RX DEFAULT STACK SIZE
2175 * Default lightweight thread stack size, measured in bytes. This value may be
2176 * overridden by calling the rx_SetStackSize() macro.
2179 * RX PROCESS PRIORITY
2181 * LWP NORMAL PRIORITY
2183 * This is the priority under which an Rx thread should run. There should not
2184 * generally be any reason to change this setting.
2187 * RX CHALLENGE TIMEOUT
2191 * The number of seconds before another authentication request packet is
2199 * Maximum number of individual acknowledgements that may be carried in an Rx
2200 * acknowledgement packet.
2202 * \subsection sec5-2-2 Section 5.2.2: Waiting Options
2205 * These definitions provide readable values indicating whether an operation
2206 * should block when packet buffer resources are not available.
2213 * Wait until the associated operation completes.
2220 * Don't wait if the associated operation would block.
2222 * \subsection sec5-2-3 Section 5.2.3: Connection ID Operations
2225 * These values assist in extracting the call channel number from a connection
2226 * identifier. A call channel is the index of a particular asynchronous call
2227 * structure within a single Rx connection.
2234 * Number of bits to right-shift to isolate a connection ID. Must be set to
2235 * the log (base two) of RX MAXCALLS.
2242 * Mask used to isolate a call channel from a connection ID field.
2249 * Mask used to isolate the connection ID from its field, masking out the call
2250 * channel information.
2252 * \subsection sec5-2-4 Section 5.2.4: Connection Flags
2255 * The values defined here appear in the flags field of Rx connections, as
2256 * defined by the rx connection structure described in Section 5.3.2.2.
2259 * RX CONN MAKECALL WAITING
2263 * rx MakeCall() is waiting for a channel.
2266 * RX CONN DESTROY ME
2270 * Destroy this (client) connection after its last call completes.
2273 * RX CONN USING PACKET CKSUM
2277 * This packet is using security-related check-summing (a non-zero header,
2278 * spare field has been seen.)
2280 * \subsection sec5-2-5 Section 5.2.5: Connection Types
2283 * Rx stores different information in its connection structures, depending on
2284 * whether the given connection represents the server side (the one providing
2285 * the service) or the client side (the one requesting the service) of the
2286 * protocol. The type field within the connection structure (described in
2287 * Section 5.3.2.2) takes on the following values to differentiate the two
2288 * types of connections, and identifies the fields that are active within the
2289 * connection structure.
2292 * RX CLIENT CONNECTION
2296 * This is a client-side connection.
2303 * This is a server-side connection.
2305 * \subsection sec5-2-6 Section 5.2.6: Call States
2308 * An Rx call on a particular connection may be in one of several states at any
2309 * instant in time. The following definitions identify the range of states that
2310 * a call may assume.
2317 * The call structure has never been used, and is thus still completely
2325 * A call is not yet in progress, but packets have arrived for it anyway. This
2326 * only applies to calls within server-side connections.
2333 * This call is fully active, having an attached lightweight thread operating
2341 * The call structure is "dallying" after its lightweight thread has completed
2342 * its most recent call. This is a "hot-standby" condition, where the call
2343 * structure preserves state from the previous call and thus optimizes the
2344 * arrival of further, related calls.
2346 * \subsection sec5-2-7 Section 5.2.7: Call Flags:
2349 * These values are used within the flags field of a variable declared to be of
2350 * type struct rx call, as described in Section 5.3.2.4. They provide
2351 * additional information as to the state of the given Rx call, such as the
2352 * type of event for which it is waiting (if any) and whether or not all
2353 * incoming packets have been received in support of the call.
2356 * RX CALL READER WAIT
2360 * Reader is waiting for next packet.
2363 * RX CALL WAIT WINDOW ALLOC
2367 * Sender is waiting for a window so that it can allocate buffers.
2370 * RX CALL WAIT WINDOW SEND
2374 * Sender is waiting for a window so that it can send buffers.
2377 * RX CALL WAIT PACKETS
2381 * Sender is waiting for packet buffers.
2384 * RX CALL RECEIVE DONE
2388 * The call is waiting for a lightweight thread to be assigned to the operation
2389 * it has just received.
2392 * RX CALL RECEIVE DONE
2396 * All packets have been received on this call.
2403 * The receive queue has been cleared when in precall state.
2405 * \subsection sec5-2-8 Section 5.2.8: Call Modes
2408 * These values define the modes of an Rx call when it is in the RX STATE
2409 * ACTIVE state, having a lightweight thread assigned to it.
2416 * We are sending or ready to send.
2423 * We are receiving or ready to receive.
2430 * Something went wrong in the current conversation.
2437 * The server side has flushed (or the client side has read) the last reply
2440 * \subsection sec5-2-9 Section 5.2.9: Packet Header Flags
2443 * Rx packets carry a flag field in their headers, providing additional
2444 * information regarding the packet's contents. The Rx packet header's flag
2445 * field's bits may take the following values:
2448 * RX CLIENT INITIATED
2452 * Signifies that a packet has been sent/received from the client side of the
2460 * The Rx calls' peer entity requests an acknowledgement.
2467 * This is the final packet from this side of the call.
2474 * There are more packets following this, i.e., the next sequence number seen
2475 * by the receiver should be greater than this one, rather than a
2476 * retransmission of an earlier sequence number.
2481 * (RX CLIENT INITIATED | RX LAST PACKET)
2483 * This flag is preset once per Rx packet. It doesn't change on retransmission
2486 * \subsection sec5-3-10 Section 5.2.10: Packet Sizes
2489 * These values provide sizing information on the various regions within Rx
2490 * packets. These packet sections include the IP/UDP headers and bodies as well
2491 * Rx header and bodies. Also covered are such values as different maximum
2492 * packet sizes depending on whether they are targeted to peers on the same
2493 * local network or a more far-flung network. Note that the MTU term appearing
2494 * below is an abbreviation for Maximum Transmission Unit.
2501 * The number of bytes taken up by IP/UDP headers.
2504 * RX MAX PACKET SIZE
2506 * (1500 - RX IPUDP SIZE)
2508 * This is the Ethernet MTU minus IP and UDP header sizes.
2513 * sizeof (struct rx header)
2515 * The number of bytes in an Rx packet header.
2518 * RX MAX PACKET DATA SIZE
2520 * (RX MAX PACKET SIZE RX - HEADER SIZE)
2522 * Maximum size in bytes of the user data in a packet.
2525 * RX LOCAL PACKET SIZE
2527 * RX MAX PACKET SIZE
2529 * Packet size in bytes to use when being sent to a host on the same net.
2532 * RX REMOTE PACKET SIZE
2534 * (576 - RX IPUDP SIZE)
2536 * Packet size in bytes to use when being sent to a host on a different net.
2538 * \subsection sec5-2-11 Section 5.2.11: Packet Types
2541 * The following values are used in the packetType field within a struct rx
2542 * packet, and define the different roles assumed by Rx packets. These roles
2543 * include user data packets, different flavors of acknowledgements, busies,
2544 * aborts, authentication challenges and responses, and debugging vehicles.
2547 * RX PACKET TYPE DATA
2551 * A user data packet.
2554 * RX PACKET TYPE ACK
2558 * Acknowledgement packet.
2561 * RX PACKET TYPE BUSY
2565 * Busy packet. The server-side entity cannot accept the call at the moment,
2566 * but the requestor is encouraged to try again later.
2569 * RX PACKET TYPE ABORT
2573 * Abort packet. No response is needed for this packet type.
2576 * RX PACKET TYPE ACKALL
2580 * Acknowledges receipt of all packets on a call.
2583 * RX PACKET TYPE CHALLENGE
2587 * Challenge the client's identity, requesting credentials.
2590 * RX PACKET TYPE RESPONSE
2594 * Response to a RX PACKET TYPE CHALLENGE authentication challenge packet.
2597 * RX PACKET TYPE DEBUG
2601 * Request for debugging information.
2608 * The number of Rx packet types defined above. Note that it also includes
2609 * packet type 0 (which is unused) in the count.
2612 * The RX PACKET TYPES definition provides a mapping of the above values to
2613 * human-readable string names, and is exported by the rx packetTypes variable
2614 * catalogued in Section 5.4.9.
2629 * \subsection sec5-2-12 Section 5.2.12: Packet Classes
2632 * These definitions are used internally to manage alloction of Rx packet
2633 * buffers according to quota classifications. Each packet belongs to one of
2634 * the following classes, and its buffer is derived from the corresponding
2638 * RX PACKET CLASS RECEIVE
2642 * Receive packet for user data.
2645 * RX PACKET CLASS SEND
2649 * Send packet for user data.
2652 * RX PACKET CLASS SPECIAL
2656 * A special packet that does not hold user data, such as an acknowledgement or
2657 * authentication challenge.
2660 * RX N PACKET CLASSES
2664 * The number of Rx packet classes defined above.
2666 * \subsection sec5-2-13 Section 5.2.13: Conditions Prompting Ack Packets
2669 * Rx acknowledgement packets are constructed and sent by the protocol
2670 * according to the following reasons. These values appear in the Rx packet
2671 * header of the ack packet itself.
2678 * The peer has explicitly requested an ack on this packet.
2685 * A duplicate packet has been received.
2688 * RX ACK OUT OF SEQUENCE
2692 * A packet has arrived out of sequence.
2695 * RX ACK EXCEEDS WINDOW
2699 * A packet sequence number higher than maximum value allowed by the call's
2700 * window has been received.
2707 * No packet buffer space is available.
2714 * Acknowledgement for keep-alive purposes.
2717 * RX ACK PING RESPONSE
2721 * Response to a RX ACK PING packet.
2728 * An ack generated due to a period of inactivity after normal packet
2731 * \subsection 5-2-14 Section 5.2.14: Acknowledgement Types
2734 * These are the set of values placed into the acks array in an Rx
2735 * acknowledgement packet, whose data format is defined by struct rx ackPacket.
2736 * These definitions are used to convey positive or negative acknowledgements
2737 * for a given range of packets.
2744 * Receiver doesn't currently have the associated packet; it may never hae been
2745 * received, or received and then later dropped before processing.
2752 * Receiver has the associated packet queued, although it may later decide to
2755 * \subsection sec5-2-15 Section 5.2.15: Error Codes
2758 * Rx employs error codes ranging from -1 to -64. The Rxgen stub generator may
2759 * use other error codes less than -64. User programs calling on Rx, on the
2760 * other hand, are expected to return positive error codes. A return value of
2761 * zero is interpreted as an indication that the given operation completed
2769 * A connection has been inactive past Rx's tolerance levels and has been shut
2773 * RX INVALID OPERATION
2777 * An invalid operation has been attempted, including such protocol errors as
2778 * having a client-side call send data after having received the beginning of a
2779 * reply from its server-side peer.
2786 * The (optional) timeout value placed on this call has been exceeded (see
2787 * Sections 5.5.3.4 and 5.6.5).
2794 * Unexpected end of data on a read operation.
2801 * An unspecified low-level Rx protocol error has occurred.
2808 * A generic user abort code, used when no more specific error code needs to be
2809 * communicated. For example, Rx clients employing the multicast feature (see
2810 * Section 1.2.8) take advantage of this error code.
2812 * \subsection sec5-2-16 Section 5.2.16: Debugging Values
2815 * Rx provides a set of data collections that convey information about its
2816 * internal status and performance. The following values have been defined in
2817 * support of this debugging and statistics-collection feature.
2819 * \subsubsection sec5-3-16-1 Section 5.2.16.1: Version Information
2822 * Various versions of the Rx debugging/statistics interface are in existance,
2823 * each defining different data collections and handling certain bugs. Each Rx
2824 * facility is stamped with a version number of its debugging/statistics
2825 * interface, allowing its clients to tailor their requests to the precise data
2826 * collections that are supported by a particular Rx entity, and to properly
2827 * interpret the data formats received through this interface. All existing Rx
2828 * implementations should be at revision M.
2831 * RX DEBUGI VERSION MINIMUM
2835 * The earliest version of Rx statistics available.
2842 * The latest version of Rx statistics available.
2845 * RX DEBUGI VERSION W SECSTATS
2849 * Identifies the earliest version in which statistics concerning Rx security
2850 * objects is available.
2853 * RX DEBUGI VERSION W GETALLCONN
2857 * The first version that supports getting information about all current Rx
2858 * connections, as specified y the RX DEBUGI GETALLCONN debugging request
2859 * packet opcode described below.
2862 * RX DEBUGI VERSION W RXSTATS
2866 * The first version that supports getting all the Rx statistics in one
2867 * operation, as specified by the RX DEBUGI RXSTATS debugging request packet
2868 * opcode described below.
2871 * RX DEBUGI VERSION W UNALIGNED CONN
2875 * There was an alignment problem discovered when returning Rx connection
2876 * information in older versions of this debugging/statistics interface. This
2877 * identifies the last version that exhibited this alignment problem.
2879 * \subsubsection sec5-2-16-2 Section 5.2.16.2: Opcodes
2882 * When requesting debugging/statistics information, the caller specifies one
2883 * of the following supported data collections:
2886 * RX DEBUGI GETSTATS
2890 * Get basic Rx statistics.
2897 * Get information on all Rx connections considered "interesting" (as defined
2898 * below), and no others.
2901 * RX DEBUGI GETALLCONN
2905 * Get information on all existing Rx connection structures, even
2906 * "uninteresting" ones.
2913 * Get all available Rx stats.
2916 * An Rx connection is considered "interesting" if it is waiting for a call
2917 * channel to free up or if it has been marked for destruction. If neither is
2918 * true, a connection is still considered interesting if any of its call
2919 * channels is actively handling a call or in its preparatory pre-call state.
2920 * Failing all the above conditions, a connection is still tagged as
2921 * interesting if any of its call channels is in either of the RX MODE SENDING
2922 * or RX MODE RECEIVING modes, which are not allowed when the call is not
2925 * \subsubsection sec5-2-16-3 Section 5.2.16.3: Queuing
2928 * These two queueing-related values indicate whether packets are present on
2929 * the incoming and outgoing packet queues for a given Rx call. These values
2930 * are only used in support of debugging and statistics-gathering operations.
2937 * Packets available in in queue.
2944 * Packets available in out queue.
2946 * \section sec5-3 Section 5.3: Structures
2949 * This section describes the major exported Rx data structures of interest to
2950 * application programmers. The following categories are utilized for the
2951 * purpose of organizing the structure descriptions:
2952 * \li Security objects
2953 * \li Protocol objects
2954 * \li Packet formats
2955 * \li Debugging and statistics
2958 * Please note that many fields described in this section are declared to be
2959 * VOID. This is defined to be char, and is used to get around some compiler
2961 * \subsection sec5-3-1 Section 5.3.1: Security Objects
2964 * As explained in Section 1.2.1, Rx provides a modular, extensible security
2965 * model. This allows Rx applications to either use one of the built-in
2966 * security/authentication protocol packages or write and plug in one of their
2967 * own. This section examines the various structural components used by Rx to
2968 * support generic security and authentication modules.
2970 * \subsubsection sec5-3-1-1 Section 5.3.1.1: struct rx securityOps
2973 * As previously described, each Rx security object must export a fixed set of
2974 * interface functions, providing the full set of operations defined on the
2975 * object. The rx securityOps structure defines the array of functions
2976 * comprising this interface. The Rx facility calls these routines at the
2977 * appropriate times, without knowing the specifics of how any particular
2978 * security object implements the operation.
2980 * A complete description of these interface functions, including information
2981 * regarding their exact purpose, parameters, and calling conventions, may be
2982 * found in Section 5.5.7.
2985 * \li int (*op Close)() - React to the disposal of a security object.
2986 * \li int (*op NewConnection)() - Invoked each time a new Rx connection
2987 * utilizing the associated security object is created.
2988 * \li int (*op PreparePacket)() - Invoked each time an outgoing Rx packet is
2989 * created and sent on a connection using the given security object.
2990 * \li int (*op SendPacket)() - Called each time a packet belonging to a call
2991 * in a connection using the security object is physically transmitted.
2992 * \li int (*op CheckAuthentication)() - This function is executed each time it
2993 * is necessary to check whether authenticated calls are being perfomed on a
2994 * connection using the associated security object.
2995 * \li int (*op CreateChallenge)() - Invoked each time a server-side challenge
2996 * event is created by Rx, namely when the identity of the principal associated
2997 * with the peer process must be determined.
2998 * \li int (*op GetChallenge)() - Called each time a client-side packet is
2999 * constructed in response to an authentication challenge.
3000 * \li int (*op GetResponse)() - Executed each time a response to a challenge
3001 * event must be received on the server side of a connection.
3002 * \li int (*op CheckResponse)() - Invoked each time a response to an
3003 * authentication has been received, validating the response and pulling out
3004 * the required authentication information.
3005 * \li int (*op CheckPacket) () - Invoked each time an Rx packet has been
3006 * received, making sure that the packet is properly formatted and that it
3007 * hasn't been altered.
3008 * \li int (*op DestroyConnection)() - Called each time an Rx connection
3009 * employing the given security object is destroyed.
3010 * \li int (*op GetStats)() - Executed each time a request for statistics on
3011 * the given security object has been received.
3012 * \li int (*op Spare1)()-int (*op Spare3)() - Three spare function slots,
3013 * reserved for future use.
3015 * \subsubsection sec5-3-1-2 Section 5.2.1.2: struct rx securityClass
3018 * Variables of type struct rx securityClass are used to represent
3019 * instantiations of a particular security model employed by Rx. It consists of
3020 * a pointer to the set of interface operations implementing the given security
3021 * object, along with a pointer to private storage as necessary to support its
3022 * operations. These security objects are also reference-counted, tracking the
3023 * number of Rx connections in existance that use the given security object. If
3024 * the reference count drops to zero, the security module may garbage-collect
3025 * the space taken by the unused security object.
3028 * \li struct rx securityOps *ops - Pointer to the array of interface functions
3029 * for the security object.
3030 * \li VOID *privateData - Pointer to a region of storage used by the security
3031 * object to support its operations.
3032 * \li int refCount - A reference count on the security object, tracking the
3033 * number of Rx connections employing this model.
3035 * \subsubsection sec5-3-1-3 Section 5.3.1.3: struct rx
3036 * securityObjectStats
3039 * This structure is used to report characteristics for an instantiation of a
3040 * security object on a particular Rx connection, as well as performance
3041 * figures for that object. It is used by the debugging portions of the Rx
3042 * package. Every security object defines and manages fields such as level and
3043 * flags differently.
3046 * \li char type - The type of security object being implemented. Existing
3048 * \li 0: The null security package.
3049 * \li 1: An obsolete Kerberos-like security object.
3050 * \li 2: The rxkad discipline (see Chapter 3).
3051 * \li char level - The level at which encryption is utilized.
3052 * \li char sparec[10] - Used solely for alignment purposes.
3053 * \li long flags - Status flags regarding aspects of the connection relating
3054 * to the security object.
3055 * \li u long expires - Absolute time when the authentication information
3056 * cached by the given connection expires. A value of zero indicates that the
3057 * associated authentication information is valid for all time.
3058 * \li u long packetsReceived - Number of packets received on this particular
3059 * connection, and thus the number of incoming packets handled by the
3060 * associated security object.
3061 * \li u long packetsSent - Number of packets sent on this particular
3062 * connection, and thus the number of outgoing packets handled by the
3063 * associated security object.
3064 * \li u long bytesReceived - Overall number of "payload" bytes received (i.e.,
3065 * packet bytes not associated with IP headers, UDP headers, and the security
3066 * module's own header and trailer regions) on this connection.
3067 * \li u long bytesSent - Overall number of "payload" bytes sent (i.e., packet
3068 * bytes not associated with IP headers, UDP headers, and the security module's
3069 * own header and trailer regions) on this connection.
3070 * \li short spares[4] - Several shortword spares, reserved for future use.
3071 * \li long sparel[8] - Several longword spares, reserved for future use.
3073 * \subsection sec5-3-2 Section 5.3.2: Protocol Objects
3076 * The structures describing the main abstractions and entities provided by Rx,
3077 * namely services, peers, connections and calls are covered in this section.
3079 * \subsubsection sec5-3-2-1 Section 5.3.2.1: struct rx service
3082 * An Rx-based server exports services, or specific RPC interfaces that
3083 * accomplish certain tasks. Services are identified by (host-address,
3084 * UDP-port, serviceID) triples. An Rx service is installed and initialized on
3085 * a given host through the use of the rx NewService() routine (See Section
3086 * 5.6.3). Incoming calls are stamped with the Rx service type, and must match
3087 * an installed service to be accepted. Internally, Rx services also carry
3088 * string names for purposes of identification. These strings are useful to
3089 * remote debugging and statistics-gathering programs. The use of a service ID
3090 * allows a single server process to export multiple, independently-specified
3093 * Each Rx service contains one or more security classes, as implemented by
3094 * individual security objects. These security objects implement end-to-end
3095 * security protocols. Individual peer-to-peer connections established on
3096 * behalf of an Rx service will select exactly one of the supported security
3097 * objects to define the authentication procedures followed by all calls
3098 * associated with the connection. Applications are not limited to using only
3099 * the core set of built-in security objects offered by Rx. They are free to
3100 * define their own security objects in order to execute the specific protocols
3103 * It is possible to specify both the minimum and maximum number of lightweight
3104 * processes available to handle simultaneous calls directed to an Rx service.
3105 * In addition, certain procedures may be registered with the service and
3106 * called at set times in the course of handling an RPC request.
3109 * \li u short serviceId - The associated service number.
3110 * \li u short servicePort - The chosen UDP port for this service.
3111 * \li char *serviceName - The human-readable service name, expressed as a
3113 * \li string. osi socket socket - The socket structure or file descriptor used
3115 * \li u short nSecurityObjects - The number of entries in the array of
3116 * supported security objects.
3117 * \li struct rx securityClass **securityObjects - The array of pointers to the
3119 * vice's security class objects.
3120 * \li long (*executeRequestProc)() - A pointer to the routine to call when an
3121 * RPC request is received for this service.
3122 * \li VOID (*destroyConnProc)() - A pointer to the routine to call when one of
3123 * the server-side connections associated with this service is destroyed.
3124 * \li VOID (*newConnProc)() - A pointer to the routine to call when a
3125 * server-side connection associated with this service is created.
3126 * \li VOID (*beforeProc)() - A pointer to the routine to call before an
3127 * individual RPC call on one of this service's connections is executed.
3128 * \li VOID (*afterProc)() - A pointer to the routine to call after an
3129 * individual RPC call on one of this service's connections is executed.
3130 * \li short nRequestsRunning - The number of simultaneous RPC calls currently
3131 * in progress for this service.
3132 * \li short maxProcs - This field has two meanings. first, maxProcs limits the
3133 * total number of requests that may execute in parallel for any one service.
3134 * It also guarantees that this many requests may be handled in parallel if
3135 * there are no active calls for any other service.
3136 * \li short minProcs - The minimum number of lightweight threads (hence
3137 * requests) guaranteed to be simultaneously executable.
3138 * \li short connDeadTime - The number of seconds until a client of this
3139 * service will be declared to be dead, if it is not responding to the RPC
3141 * \li short idleDeadTime - The number of seconds a server-side connection for
3142 * this service will wait for packet I/O to resume after a quiescent period
3143 * before the connection is marked as dead.
3145 * \subsubsection sec5-3-2-2 Section 5.3.2.2: struct rx connection
3148 * An Rx connection represents an authenticated communication path, allowing
3149 * multiple asynchronous conversations (calls). Each connection is identified
3150 * by a connection ID. The low-order bits of the connection ID are reserved so
3151 * they may be stamped with the index of a particular call channel. With up to
3152 * RX MAXCALLS concurrent calls (set to 4 in this implementation), the bottom
3153 * two bits are set aside for this purpose. The connection ID is not sufficient
3154 * by itself to uniquely identify an Rx connection. Should a client crash and
3155 * restart, it may reuse a connection ID, causing inconsistent results. In
3156 * addition to the connection ID, the epoch, or start time for the client side
3157 * of the connection, is used to identify a connection. Should the above
3158 * scenario occur, a different epoch value will be chosen by the client,
3159 * differentiating this incarnation from the orphaned connection record on the
3162 * Each connection is associated with a parent service, which defines a set of
3163 * supported security models. At creation time, an Rx connection selects the
3164 * particular security protocol it will implement, referencing the associated
3165 * service. The connection structure maintains state about the individual calls
3166 * being simultaneously handled.
3169 * \li struct rx connection *next - Used for internal queueing.
3170 * \li struct rx peer *peer - Pointer to the connection's peer information (see
3172 * \li u long epoch - Process start time of the client side of the connection.
3173 * \li u long cid - Connection identifier. The call channel (i.e., the index
3174 * into the connection's array of call structures) may appear in the bottom
3176 * \li VOID *rock - Pointer to an arbitrary region of memory in support of the
3177 * connection's operation. The contents of this area are opaque to the Rx
3178 * facility in general, but are understood by any special routines used by this
3180 * \li struct rx call *call[RX MAXCALLS] - Pointer to the call channel
3181 * structures, describing up to RX MAXCALLS concurrent calls on this
3183 * \li u long callNumber[RX MAXCALLS] - The set of current call numbers on each
3184 * of the call channels.
3185 * \li int timeout - Obsolete; no longer used.
3186 * \li u char flags - Various states of the connection; see Section 5.2.4 for
3187 * individual bit definitions.
3188 * \li u char type - Whether the connection is a server-side or client-side
3189 * one. See Section 5.2.5 for individual bit definitions.
3190 * \li u short serviceId - The service ID that should be stamped on requests.
3191 * This field is only used by client-side instances of connection structures.
3192 * \li struct rx service *service - A pointer to the service structure
3193 * associated with this connection. This field is only used by server-side
3194 * instances of connection structures.
3195 * \li u long serial - Serial number of the next outgoing packet associated
3196 * with this connection.
3197 * \li u long lastSerial - Serial number of the last packet received in
3198 * association with this connection. This field is used in computing packet
3200 * \li u short secondsUntilDead - Maximum numer of seconds of silence that
3201 * should be tolerated from the connection's peer before calls will be
3202 * terminated with an RX CALL DEAD error.
3203 * \li u char secondsUntilPing - The number of seconds between "pings"
3204 * (keep-alive probes) when at least one call is active on this connection.
3205 * \li u char securityIndex - The index of the security object being used by
3206 * this connection. This number selects a slot in the security class array
3207 * maintained by the service associated with the connection.
3208 * \li long error - Records the latest error code for calls occurring on this
3210 * \li struct rx securityClass *securityObject - A pointer to the security
3211 * object used by this connection. This should coincide with the slot value
3212 * chosen by the securityIndex field described above.
3213 * \li VOID *securityData - A pointer to a region dedicated to hosting any
3214 * storage required by the security object being used by this connection.
3215 * \li u short securityHeaderSize - The length in bytes of the portion of the
3216 * packet header before the user's data that contains the security module's
3218 * \li u short securityMaxTrailerSize - The length in bytes of the packet
3219 * trailer, appearing after the user's data, as mandated by the connection's
3221 * \li struct rxevent *challengeEvent -Pointer to an event that is scheduled
3222 * when the server side of the connection is challenging the client to
3223 * authenticate itself.
3224 * \li int lastSendTime - The last time a packet was sent on this connection.
3225 * \li long maxSerial - The largest serial number seen on incoming packets.
3226 * \li u short hardDeadTime - The maximum number of seconds that any call on
3227 * this connection may execute. This serves to throttle runaway calls.
3229 * \subsubsection sec5-3-2-3 Section 5.3.2.3: struct rx peer
3232 * For each connection, Rx maintains information describing the entity, or
3233 * peer, on the other side of the wire. A peer is identified by a (host,
3234 * UDP-port) pair. Included in the information kept on this remote
3235 * communication endpoint are such network parameters as the maximum packet
3236 * size supported by the host, current readings on round trip time to
3237 * retransmission delays, and packet skew (see Section 1.2.7). There are also
3238 * congestion control fields, ranging from descriptions of the maximum number
3239 * of packets that may be sent to the peer without pausing and retransmission
3240 * statistics. Peer structures are shared between connections whenever
3241 * possible, and hence are reference-counted. A peer object may be
3242 * garbage-collected if it is not actively referenced by any connection
3243 * structure and a sufficient period of time has lapsed since the reference
3244 * count dropped to zero.
3247 * \li struct rx peer *next - Use to access internal lists.
3248 * \li u long host - Remote IP address, in network byte order
3249 * \li u short port - Remote UDP port, in network byte order
3250 * \li short packetSize - Maximum packet size for this host, if known.
3251 * \li u long idleWhen - When the refCount reference count field (see below)
3253 * \li short refCount - Reference count for this structure
3254 * \li u char burstSize - Reinitialization size for the burst field (below).
3255 * \li u char burst - Number of packets that can be transmitted immediately
3257 * \li struct clock burstWait - Time delay until new burst aimed at this peer
3259 * \li struct queue congestionQueue - Queue of RPC call descriptors that are
3260 * waiting for a non-zero burst value.
3261 * \li int rtt - Round trip time to the peer, measured in milliseconds.
3262 * \li struct clock timeout - Current retransmission delay to the peer.
3263 * \li int nSent - Total number of distinct data packets sent, not including
3265 * \li int reSends - Total number of retransmissions for this peer since the
3266 * peer structure instance was created.
3267 * \li u long inPacketSkew - Maximum skew on incoming packets (see Section
3269 * \li u long outPacketSkew - Peer-reported maximum skew on outgoing packets
3270 * (see Section 1.2.7).
3272 * \subsubsection sec5-3-2-4 Section 5.3.2.4: struct rx call
3275 * This structure records the state of an active call proceeding on a given Rx
3276 * connection. As described above, each connection may have up to RX MAXCALLS
3277 * calls active at any one instant, and thus each connection maintains an array
3278 * of RX MAXCALLS rx call structures. The information contained here is
3279 * specific to the given call; "permanent" call state, such as the call number,
3280 * is maintained in the connection structure itself.
3283 * \li struct queue queue item header - Queueing information for this
3285 * \li struct queue tq - Queue of outgoing ("transmit") packets.
3286 * \li struct queue rq - Queue of incoming ("receive") packets.
3287 * \li char *bufPtr - Pointer to the next byte to fill or read in the call's
3288 * current packet, depending on whether it is being transmitted or received.
3289 * \li u short nLeft - Number of bytes left to read in the first packet in the
3290 * reception queue (see field rq).
3291 * \li u short nFree - Number of bytes still free in the last packet in the
3292 * transmission queue (see field tq).
3293 * \li struct rx packet *currentPacket - Pointer to the current packet being
3294 * assembled or read.
3295 * \li struct rx connection *conn - Pointer to the parent connection for this
3297 * \li u long *callNumber - Pointer to call number field within the call's
3299 * \li u char channel - Index within the parent connection's call array that
3300 * describes this call.
3301 * \li u char dummy1, dummy2 - These are spare fields, reserved for future use.
3302 * \li u char state - Current call state. The associated bit definitions appear
3304 * \li u char mode - Current mode of a call that is in RX STATE ACTIVE state.
3305 * The associated bit definitions appear in Section 5.2.8.
3306 * \li u char flags - Flags pertaining to the state of the given call. The
3307 * associated bit definitions appear in Section 5.2.7.
3308 * \li u char localStatus - Local user status information, sent out of band.
3309 * This field is currently not in use, set to zero.
3310 * \li u char remoteStatus - Remote user status information, received out of
3311 * band. This field is currently not in use, set to zero.
3312 * \li long error - Error condition for this call.
3313 * \li u long timeout - High level timeout for this call
3314 * \li u long rnext - Next packet sequence number expected to be received.
3315 * \li u long rprev - Sequence number of the previous packet received. This
3316 * number is used to decide the proper sequence number for the next packet to
3317 * arrive, and may be used to generate a negative acknowledgement.
3318 * \li u long rwind - Width of the packet receive window for this call. The
3319 * peer must not send packets with sequence numbers greater than or equal to
3321 * \li u long tfirst - Sequence number of the first unacknowledged transmit
3322 * packet for this call.
3323 * \li u long tnext - Next sequence number to use for an outgoing packet.
3324 * \li u long twind - Width of the packet transmit window for this call. Rx
3325 * cannot assign a sequence number to an outgoing packet greater than or equal
3326 * to tfirst + twind.
3327 * \li struct rxevent *resendEvent - Pointer to a pending retransmission event,
3329 * \li struct rxevent *timeoutEvent - Pointer to a pending timeout event, if
3331 * \li struct rxevent *keepAliveEvent - Pointer to a pending keep-alive event,
3332 * if this is an active call.
3333 * \li struct rxevent *delayedAckEvent - Pointer to a pending delayed
3334 * acknowledgement packet event, if any. Transmission of a delayed
3335 * acknowledgement packet is scheduled after all outgoing packets for a call
3336 * have been sent. If neither a reply nor a new call are received by the time
3337 * the delayedAckEvent activates, the ack packet will be sent.
3338 * \li int lastSendTime - Last time a packet was sent for this call.
3339 * \li int lastReceiveTime - Last time a packet was received for this call.
3340 * \li VOID (*arrivalProc)() - Pointer to the procedure to call when reply is
3342 * \li VOID *arrivalProcHandle - Pointer to the handle to pass to the
3343 * arrivalProc as its first argument.
3344 * \li VOID *arrivalProcArg - Pointer to an additional argument to pass to the
3345 * given arrivalProc.
3346 * \li u long lastAcked - Sequence number of the last packet "hard-acked" by
3347 * the receiver. A packet is considered to be hard-acked if an acknowledgement
3348 * is generated after the reader has processed it. The Rx facility may
3349 * sometimes "soft-ack" a windowfull of packets before they have been picked up
3351 * \li u long startTime - The time this call started running.
3352 * \li u long startWait - The time that a server began waiting for input data
3355 * \subsection sec5-3-3 Section 5.3.3: Packet Formats
3358 * The following sections cover the different data formats employed by the
3359 * suite of Rx packet types, as enumerated in Section 5.2.11. A description of
3360 * the most commonly-employed Rx packet header appears first, immediately
3361 * followed by a description of the generic packet container and descriptor.
3362 * The formats for Rx acknowledgement packets and debugging/statistics packets
3363 * are also examined.
3365 * \subsubsection sec5-3-3-1 Section 5.3.3.1: struct rx header
3368 * Every Rx packet has its own header region, physically located after the
3369 * leading IP/UDP headers. This header contains connection, call, security, and
3370 * sequencing information. Along with a type identifier, these fields allow the
3371 * receiver to properly interpret the packet. In addition, every client relates
3372 * its "epoch", or Rx incarnation date, in each packet. This assists in
3373 * identifying protocol problems arising from reuse of connection identifiers
3374 * due to a client restart. Also included in the header is a byte of
3375 * user-defined status information, allowing out-of-band channel of
3376 * communication for the higher-level application using Rx as a transport
3380 * \li u long epoch - Birth time of the client Rx facility.
3381 * \li u long cid - Connection identifier, as defined by the client. The last
3382 * RX CIDSHIFT bits in the cid field identify which of the server-side RX
3383 * MAXCALLS call channels is to receive the packet.
3384 * \li u long callNumber - The current call number on the chosen call channel.
3385 * \li u long seq - Sequence number of this packet. Sequence numbers start with
3386 * 0 for each new Rx call.
3387 * \li u long serial - This packet's serial number. A new serial number is
3388 * stamped on each packet transmitted (or retransmitted).
3389 * \li u char type - What type of Rx packet this is; see Section 5.2.11 for the
3390 * list of legal definitions.
3391 * \li u char flags - Flags describing this packet; see Section 5.2.9 for the
3392 * list of legal settings.
3393 * \li u char userStatus - User-defined status information, uninterpreted by
3394 * the Rx facility itself. This field may be easily set or retrieved from Rx
3395 * packets via calls to the rx GetLocalStatus(), rx SetLocalStatus(), rx
3396 * GetRemoteStatus(), and rx SetRemoteStatus() macros.
3397 * \li u char securityIndex - Index in the associated server-side service class
3398 * of the security object used by this call.
3399 * \li u short serviceId - The server-provided service ID to which this packet
3401 * \li u short spare - This field was originally a true spare, but is now used
3402 * by the built-in rxkad security module for packet header checksums. See the
3403 * descriptions of the related rx IsUsingPktChecksum(), rx GetPacketCksum(),
3404 * and rx SetPacketCksum() macros.
3406 * \subsubsection sec5-3-3-2 Section 5.3.3.2: struct rx packet
3409 * This structure is used to describe an Rx packet, and includes the wire
3410 * version of the packet contents, where all fields exist in network byte
3411 * order. It also includes acknowledgement, length, type, and queueing
3415 * \li struct queue queueItemHeader - field used for internal queueing.
3416 * \li u char acked - If non-zero, this field indicates that this packet has
3417 * been tentatively (soft-) acknowledged. Thus, the packet has been accepted by
3418 * the rx peer entity on the other side of the connection, but has not yet
3419 * necessarily been passed to the true reader. The sender is not free to throw
3420 * the packet away, as it might still get dropped by the peer before it is
3421 * delivered to its destination process.
3422 * \li short length - Length in bytes of the user data section.
3423 * \li u char packetType - The type of Rx packet described by this record. The
3424 * set of legal choices is available in Section 5.2.11.
3425 * \li struct clock retryTime - The time when this packet should be
3426 * retransmitted next.
3427 * \li struct clock timeSent - The last time this packet was transmitted.
3428 * \li struct rx header header - A copy of the internal Rx packet header.
3429 * \li wire - The text of the packet as it appears on the wire. This structure
3430 * has the following sub-fields:
3431 * \li u long head[RX HEADER SIZE/sizeof(long)] The wire-level contents of
3432 * IP, UDP, and Rx headers.
3433 * \li u long data[RX MAX PACKET DATA SIZE/sizeof(long)] The wire form of
3434 * the packet's "payload", namely the user data it carries.
3436 * \subsubsection sec5-3-3-3 Section 5.3.3.3: struct rx ackPacket
3439 * This is the format for the data portion of an Rx acknowledgement packet,
3440 * used to inform a peer entity performing packet transmissions that a subset
3441 * of its packets has been properly received.
3444 * \li u short bufferSpace - Number of packet buffers available. Specifically,
3445 * the number of packet buffers that the ack packet's sender is willing to
3446 * provide for data on this or subsequent calls. This number does not have to
3447 * fully accurate; it is acceptable for the sender to provide an estimate.
3448 * \li u short maxSkew - The maximum difference seen between the serial number
3449 * of the packet being acknowledged and highest packet yet received. This is an
3450 * indication of the degree to which packets are arriving out of order at the
3452 * \li u long firstPacket - The serial number of the first packet in the list
3453 * of acknowledged packets, as represented by the acks field below.
3454 * \li u long previousPacket - The previous packet serial number received.
3455 * \li u long serial - The serial number of the packet prompted the
3457 * \li u char reason - The reason given for the acknowledgement; legal values
3458 * for this field are described in Section 5.2.13.
3459 * \li u char nAcks - Number of acknowledgements active in the acks array
3460 * immediately following.
3461 * \li u char acks[RX MAXACKS] - Up to RX MAXACKS packet acknowledgements. The
3462 * legal values for each slot in the acks array are described in Section
3463 * 5.2.14. Basically, these fields indicate either positive or negative
3467 * All packets with serial numbers prior to firstPacket are implicitly
3468 * acknowledged by this packet, indicating that they have been fully processed
3469 * by the receiver. Thus, the sender need no longer be concerned about them,
3470 * and may release all of the resources that they occupy. Packets with serial
3471 * numbers firstPacket + nAcks and higher are not acknowledged by this ack
3472 * packet. Packets with serial numbers in the range [firstPacket, firstPacket +
3473 * nAcks) are explicitly acknowledged, yet their sender-side resources must not
3474 * yet be released, as there is yet no guarantee that the receiver will not
3475 * throw them away before they can be processed there.
3477 * There are some details of importance to be noted. For one, receiving a
3478 * positive acknowlegement via the acks array does not imply that the
3479 * associated packet is immune from being dropped before it is read and
3480 * processed by the receiving entity. It does, however, imply that the sender
3481 * should stop retransmitting the packet until further notice. Also, arrival of
3482 * an ack packet should prompt the transmitter to immediately retransmit all
3483 * packets it holds that have not been explicitly acknowledged and that were
3484 * last transmitted with a serial number less than the highest serial number
3485 * acknowledged by the acks array.
3486 * Note: The fields in this structure are always kept in wire format, namely in
3487 * network byte order.
3489 * \subsection sec5-3-4 Section 5.3.4: Debugging and Statistics
3492 * The following structures are defined in support of the debugging and
3493 * statistics-gathering interfaces provided by Rx.
3495 * \subsubsection sec5-3-4-1 Section 5.3.4.1: struct rx stats
3498 * This structure maintains Rx statistics, and is gathered by such tools as the
3499 * rxdebug program. It must be possible for all of the fields placed in this
3500 * structure to be successfully converted from their on-wire network byte
3501 * orderings to the host-specific ordering.
3504 * \li int packetRequests - Number of packet allocation requests processed.
3505 * \li int noPackets[RX N PACKET CLASSES] - Number of failed packet requests,
3506 * organized per allocation class.
3507 * \li int socketGreedy - Whether the SO GREEDY setting succeeded for the Rx
3509 * \li int bogusPacketOnRead - Number of inappropriately short packets
3511 * \li int bogusHost - Contains the host address from the last bogus packet
3513 * \li int noPacketOnRead - Number of attempts to read a packet off the wire
3514 * when there was actually no packet there.
3515 * \li int noPacketBuffersOnRead - Number of dropped data packets due to lack
3516 * of packet buffers.
3517 * \li int selects - Number of selects waiting for a packet arrival or a
3519 * \li int sendSelects - Number of selects forced when sending packets.
3520 * \li int packetsRead[RX N PACKET TYPES] - Total number of packets read,
3521 * classified by type.
3522 * \li int dataPacketsRead - Number of unique data packets read off the wire.
3523 * \li int ackPacketsRead - Number of ack packets read.
3524 * \li int dupPacketsRead - Number of duplicate data packets read.
3525 * \li int spuriousPacketsRead - Number of inappropriate data packets.
3526 * \li int packetsSent[RX N PACKET TYPES] - Number of packet transmissions,
3527 * broken down by packet type.
3528 * \li int ackPacketsSent - Number of ack packets sent.
3529 * \li int pingPacketsSent - Number of ping packets sent.
3530 * \li int abortPacketsSent - Number of abort packets sent.
3531 * \li int busyPacketsSent - Number of busy packets sent.
3532 * \li int dataPacketsSent - Number of unique data packets sent.
3533 * \li int dataPacketsReSent - Number of retransmissions.
3534 * \li int dataPacketsPushed - Number of retransmissions pushed early by a
3535 * negative acknowledgement.
3536 * \li int ignoreAckedPacket - Number of packets not retransmitted because they
3537 * have already been acked.
3538 * \li int struct clock totalRtt - Total round trip time measured for packets,
3539 * used to compute average time figure.
3540 * \li struct clock minRtt - Minimum round trip time measured for packets.
3541 * struct clock maxRtt - Maximum round trip time measured for packets.
3542 * \li int nRttSamples - Number of round trip samples.
3543 * \li int nServerConns - Number of server connections.
3544 * \li int nClientConns - Number of client connections.
3545 * \li int nPeerStructs - Number of peer structures.
3546 * \li int nCallStructs - Number of call structures physically allocated (using
3547 * the internal storage allocator routine).
3548 * \li int nFreeCallStructs - Number of call structures which were pulled from
3549 * the free queue, thus avoiding a call to the internal storage allocator
3551 * \li int spares[10] - Ten integer spare fields, reserved for future use.
3553 * \subsubsection sec5-3-4-2 Section 5.3.4.2: struct rx debugIn
3556 * This structure defines the data format for a packet requesting one of the
3557 * statistics collections maintained by Rx.
3560 * \li long type - The specific data collection that the caller desires. Legal
3561 * settings for this field are described in Section 5.2.16.2.
3562 * \li long index - This field is only used when gathering information on Rx
3563 * connections. Choose the index of the server-side connection record of which
3564 * we are inquiring. This field may be used as an iterator, stepping through
3565 * all the connection records, one per debugging request, until they have all
3568 * \subsubsection sec5-3-4-3 Section 5.3.4.3: struct rx debugStats
3571 * This structure describes the data format for a reply to an RX DEBUGI
3572 * GETSTATS debugging request packet. These fi
git://git.openafs.org / openafs.git / blob