Internet Draft R. Braden Expiration: December 1996 ISI File: draft-ietf-rsvp-bsdapi.ps D. Hoffman Sun Microsystems RSVP Application Programming Interface (RAPI) for SunOS/BSD: V4.0 May 20, 1996 Status of Memo 1. Introduction To request enhanced QoS from the Internet, an application on an end system uses some "API" ( Application Programming Interface) to a local RSVP daemon. The RSVP daemon uses the RSVP protocol to propagate the QoS request through the routers along path(s) for the data flow. Each router may accept or deny the request, depending upon its available resources; in the case of failure, the RSVP daemon will return the decision to the requesting application via the API. This document describes a revised prototype RSVP API, known as " RAPI", that is currently running under SunOS 4.x. It is included in release 4.0 of the ISI RSVP code distribution. In this version, RSVP is implemented by a user-level RSVP daemon program, as illustrated in the schematic diagram below. An application is linked with an RSVP client library module, whose procedures form the API. These procedures interact with the local RSVP daemon program through a Unix-domain socket. Braden, Hoffman Expiration: December 1996 [Page 1] Internet Draft RSVP BSD API May 1996 H O S T . R O U T E R _____________ . | |______ . | |RSVP | . | |Client| . | Application |Lib | ____________ . _____________ | | rtns | | | . | | | |______| | RSVP | . | RSVP | | | | | Daemon | . | Daemon | |_____________| | |____________| . |_____________| | | . | . | | | USER | | . | . | | | ==================|========|===V====|=====. | | | KERNEL |_<____>_| . |___<_____>___| | |__> UNIX Pipe . RSVP packets | . . | _____V_____ . _____V______ | | . | | | Packet | . | Packet | DATA =========> | Filter & | ======> | Filter & | ==> | Scheduler | . | Scheduler | | (if any) | . | | |___________| . |____________| 1.1 Reservation Model RSVP performs the signalling necessary to provide enhanced QoS, i.e., to make a resource reservation, for a simplex data flow sent to a unicast or multicast destination address. Although RSVP distinguishes senders from receivers, the same application may (and typically will) act in both roles. RSVP assigns QoS to an individual data flow known as a "session" and defined by a particular transport protocol, IP destination address, and generalized destination port. In order to receive data packets for a particular multicast session, a host must have joined the corresponding IP multicast group using the setsockopt call IP_ADD_MEMBERSHIP. A data source, or "sender", is defined by an IP source address and a generalized source port. A given session may have multiple senders S1, S2, ... Sn, and if the destination is a multicast address, multiple "receivers" R1, R2, ... Rm. In the current version of RSVP, the generalized ports used by RSVP for defining sessions and senders are restricted to be TCP/UDP port numbers. Braden, Hoffman Expiration: December 1996 [Page 2] Internet Draft RSVP BSD API May 1996 Under RSVP, QoS requests are made by the data receivers. A QoS request contains a "flowspec" together with a "filter spec". The flowspec includes an "Rspec", which defines the desired QoS and is used to control the packet scheduling mechanism in the router or host, and also a "Tspec", which defines the traffic expected by the receiver. The filter spec controls packet classification to determine which sender(s)' data packets receive the corresponding QoS. The detailed manner in which reservations from different receivers are shared in the Internet is controlled by a reservation parameter known as the "reservation style". The RSVP Functional Specification contains a definition and explanation of the different reservation styles. 1.2 API Outline An application uses the rapi_session() library call to create an API session for a particular simplex data flow. The rapi_sender() call may then be used to register as a data sender, and the rapi_reserve() call may be used to make a QoS reservation for a data receiver. The sender and/or reserve calls may be repeated with different parameters to dynamically modify the state at any time. The application can call rapi_release() to close the session and delete all of its resource reservations. The RAPI library call rapi_getfd() returns the file descriptor of the RAPI session socket to the application. The application can use this file descriptor directly in a select call or pass it to the notifier of another library (such as XLib, tk/tcl, RPC, etc.). When an event is signalled on the file descriptor, the application should call a dispatch routine that is included in the RSVP API. This dispatch routine will drive the API and execute the callback routines if appropriate. A synchronous error in a RAPI library routine returns an appropriate error return value (see below). Asynchronous RSVP errors and certain other events are delivered to the application via a RAPI callback routine. The addresses of a callback routine may be specified in the registration call to the client library. Text messages for synchronous and asynchronous error codes will be found in the file " rapi_err.h". Referring to the earlier diagram, it will be seen that a rapi_session() call opens a Unix-domain RAPI socket to the RSVP daemon and passes the register request through the pipe; this pipe corresponds to the RAPI session. A rapi_release() call closes the Braden, Hoffman Expiration: December 1996 [Page 3] Internet Draft RSVP BSD API May 1996 Unix socket. If the application (or the daemon) crashes without properly closing the RAPI socket, the other side will be notified to perform a cleanup. Most importantly, if the user process terminates without explicitly closing the RAPI session, it will cause the daemon to delete the corresponding reservation state from the routers. Braden, Hoffman Expiration: December 1996 [Page 4] Internet Draft RSVP BSD API May 1996 2. CLIENT LIBRARY SERVICES The RSVP API provides the client library calls defined in this section. To use these calls, the application should include the file "rapi_lib.h". A. Create a Session The rapi_session call creates an API session. If it succeeds, the call returns an opaque but non-zero session handle for use in subsequent calls related to this session. If the call fails (synchronously), it returns zero (NULL_SID) and stores a RAPI error code into an integer variable pointed to by the "errnop" parameter. After a successful rapi_session call has been made, the application may receive asynchronous upcalls of type PATH_EVENT or PATH_ERROR. int rapi_session( struct sockaddr_in *Dest, /* Session: (Dst addr, port) */ int Protid, /* Protocol Id */ int flags, /* flags */ int (*Event_rtn)(), /* Address of callback rtn */ void *Event_arg, /* App argument to callback */ int *errnop /* Place to return error code*/ ) The parameters are as follows. o "Dest" This required parameter points to a sockaddr structure defining the destination IP address and UDP/TCP port number to which data will be sent. It defines the RSVP session. o "Protid" The IP protocol ID for the session. If it is omitted (zero), 17 (UDP) is assumed. o "flags" No flags are defined at this time. o "Event_rtn" Braden, Hoffman Expiration: December 1996 [Page 5] Internet Draft RSVP BSD API May 1996 This parameter is a pointer to an asynchronous callback routine for notification of errors and events, or NULL if there is no such routine. o "Event_arg" This optional parameter points to an argument that will be passed in the calls to the asynchronous callback routine. o "errnop" The address of an integer into which a RAPI error code will be stored. Braden, Hoffman Expiration: December 1996 [Page 6] Internet Draft RSVP BSD API May 1996 B. Specify Sender Parameters An application must issue a rapi_sender call if it intends to send a flow of data for which receivers may make reservations. This call defines or redefines the parameters of that flow, and may be issued more than once for the same session. If there is a synchronous error, rapi_sender() returns a RAPI error code; otherwise, it returns zero. Once a successful rapi_sender call has been made, the application may receive asynchronous upcalls of type RESV_EVENT. int rapi_sender( int Sid, /* Session ID */ int flags, /* Flags */ struct sockaddr_in *Host, /* Local host: (Src addr, port)*/ rapi_filter *SenderTemplate, /* Sender template */ rapi_tspec *SenderTspec, /* Sender Tspec */ rapi_policy *SenderPolicy, /* Sender policy data */ int TTL; /* TTL of multicast data */ ) The parameters are as follows. o "Sid" This required parameter must be a session ID returned by a successful rapi_session call. o "Host" This optional parameter may point to a sockaddr structure specifying the IP source address and the UDP source port from which data will be sent, or it may be NULL. If the IP source address is INADDR_ANY, the API will use the default IP address of the local host. This is sufficient unless the host is multihomed. The port number may be zero if the protocol for the session does not have ports. A NULL "Host" parameter indicates that the application wishes to withdraw its registration as a sender. In this case, the following parameters will all be ignored. o "flags" Braden, Hoffman Expiration: December 1996 [Page 7] Internet Draft RSVP BSD API May 1996 No flags are currently defined. o "SenderTemplate" This optional parameter may be a pointer to a structure (defined in rapi_lib.h) specifying the format of data packets to be sent, or it may be NULL. If this parameter is omitted (NULL), a sender template will be created internally from the "Dest" and "Host" parameters. If a " SenderTemplate" parameter is present, the "host" parameter will be ignored. This parameter is included as a placeholder to allow future generalization of RSVP to allow selection based upon transport layer or application layer fields other than UDP (or TCP) ports. However, THIS PARAMETER IS NOT SUPPORTED IN THE PRESENT VERSION. o "SenderTspec" This required parameter must be a pointer to a Tspec that defines the traffic that this sender will create. o "SenderPolicy" This optional parameter may be a pointer to a sender policy data structure, or it may be NULL. THIS PARAMETER IS NOT CURRENTLY SUPPORTED and will be ignored. o "TTL" This parameter specifies the IP TTL (Time-to-Live) value with which multicast data will be sent. It allows RSVP to send its control messages with the same TTL scope as the data packets. Braden, Hoffman Expiration: December 1996 [Page 8] Internet Draft RSVP BSD API May 1996 C. Make, Modify, or Delete a Reservation The rapi_reserve procedure is called to make, modify, or delete a resource reservation for a session. This call implicitly indicates to RSVP that the application will be receiving data. The call may be repeated any number of times with different parameters, allowing the application to modify or remove the reservation. Depending upon the parameters, this may or may not result in new Admission Control calls, which could fail asynchronously. If there is a synchronous error in this call, rapi_reserve() returns a RAPI error code; otherwise, it returns zero. Once this call has been successful, the application may receive an asynchronous upcall of type RESV_ERROR. An admission control failure (e.g., refusal of the QoS request) will be reported asynchronously by an reservation error callback (see below). A "No Path State" error callback indicates that RSVP state from one or more of the senders specified in "filter_list" has not (yet) propagated all the way to the receiver; it may also indicate that one or more of the specified senders has closed its API and its RSVP state has been deleted from the routers. int rapi_reserve( int Sid, /* Session ID */ int flags, struct sockaddr_in *RHost, /* Receive host addr (opt)*/ int StyleId, /* Style ID */ rapi_stylex_t *Style_ext, /* Style extension */ rapi_policy_t *Rcvr_policy, /* Receiver policy */ int FilterSpecNo, /* # of filter specs */ rapi_filter *FilterSpec_list, /* List of filter specs */ int FlowspecNo, /* # of flowspecs */ rapi_fspec *Flowspec_list /* List of flowspecs */ ) o "Sid" This required parameter must be a session ID returned by a successful rapi_session call. o "flags" Braden, Hoffman Expiration: December 1996 [Page 9] Internet Draft RSVP BSD API May 1996 No flags are currently defined. o "RHost" This optional parameter may be used to define the interface address on which data will be received. It is useful for a multi-homed host. If it is omitted or the host address is INADDR_ANY, the default interface will be assumed. o "StyleId" This required parameter specifies the reservation style id (values defined in rsvp_api.h). o "Style_Ext" This optional parameter is a pointer to a style-dependent extension to the parameter list. NO SUCH EXTENSION IS CURRENTLY DEFINED, and this parameter will be ignored. o "Rcvr_Policy" This optional parameter is a pointer to a policy data structure, or it is NULL. THIS PARAMETER IS NOT CURRENTLY SUPPORTED and will be ignored. o "FilterSpec_list", "FilterSpecNo" The "FilterSpec_list" parameter is a pointer to an area containing a sequential vector of RAPI filter spec objects. The number of objexts in this vector is specified in "FilterSpecNo". If " FilterSpecNo" is zero, the "FilterSpec_list" parameter will be ignored. o "Flowspec_list", "FlowspecNo" The "Flowspec_list" parameter is a pointer to an area containing a sequential vector of RAPI flow spec objects. The number of objects in this vector is specified in "FlowspecNo". If "FlowspecNo" is zero, the "Flowspec_list" parameter will be ignored. The format of a flowspec (rsvp_spec) is defined in "rapi_lib.h". If FlowspecNo is zero, the rapi_reserve call will remove the current reservation(s) for the specified session. Otherwise, Braden, Hoffman Expiration: December 1996 [Page 10] Internet Draft RSVP BSD API May 1996 the parameters depend upon the style, as follows. o Wildcard Filter (WF) Use "StyleId" = WILDCARD. The "Flowspec_list" parameter may be empty (to delete the reservation) or else point to a single flowspec. The "FilterSpec_list" parameter may be empty or it may point to a single filter spec containing appropriate wildcard(s). o Fixed Filter (FF) Use "StyleId" = FIXED. "FilterSpecNo" must equal " FlowspecNo"; both lists may be empty (to delete the reservation) or may be of any length. Entries in "Flowspec_list" and " FilterSpec_list" parameters will correspond in pairs. o Shared Explicit (SE) Use "StyleId" = SE. The "Flowspec_list" parameter may be empty (to delete the reservation) or else point to a single flowspec. The "FilterSpec_list" parameter may point to a list of any length. Braden, Hoffman Expiration: December 1996 [Page 11] Internet Draft RSVP BSD API May 1996 D. Remove a Session The rsvp_release call removes the reservation, if any, and removes the state corresponding to a given session handle. This call will be made implicitly if the application terminates without closing its RSVP sessions. If the session handle is invalid, the call returns a corresponding RAPI error code; otherwise, it returns zero. int rsvp_release( u_long Sid) E. Get File Descriptor The rapi_getfd call may be used by the application to obtain the file descriptor associated with the control pipe to the RSVP daemon, after a rapi_register() call has completed successfully and before the session ID has been released. When a socket event is signaled on this file descriptor, the application should call rapi_dispatch(), described below. int rapi_getfd( u_long Sid) If Sid is illegal or undefined, this call returns -1; otherwise, it returns the file descriptor. F. Dispatch API Event The application should call this routine whenever an event is signalled on the file descriptor returned by rapi_getfd(). It may be called at any time, but it will generally have no effect unless there is a pending event associated with the control pipe. Calling this routine may result in one or more callbacks to the application, from any of the open RAPI sessions. int rapi_dispatch( ) If this call encounters an error, rapi_dispatch() returns a RAPI error code; otherwise, it returns zero, G. RAPI Version int rapi_version( ) This call returns a single integer that defines the version of the interface. It may be used by an application to adapt to different versions. The returned value is composed of a major Braden, Hoffman Expiration: December 1996 [Page 12] Internet Draft RSVP BSD API May 1996 number and a minor number, encoded as 100*major + minor. The API described in this document has major version number 4. Braden, Hoffman Expiration: December 1996 [Page 13] Internet Draft RSVP BSD API May 1996 H. Asynchronous Callbacks An asynchronous callback (invoked by a call to rapi_dispatch()) executes the procedure whose address was specified by the " Event_rtn" in the rapi_register call. The following parameters are used in the callback: event_callback( int Sid, /* Session ID */ int EventType, /* Event type */ int Style, /* Resv style */ int ErrorCode, /* (error event): error code */ int ErrorValue, /* (error event): error value */ struct sockaddr_in ErrorNode, /* Node where error occurred */ u_char ErrorFlags, int Index, /* Index to bad flow descriptor */ int FilterSpecNo, /* # of filter specs supplied */ rapi_filter *FilterSpec_list, int FlowspecNo, /* # of flowspecs supplied */ rapi_spec *Flowspec_list, int AdspecNo, /* # of ADSPECs supplied */ rapi_adspec *Adspec_list, void *Event_arg /* Supplied by application */ o "Sid" This parameter must be a session ID returned by a successful rapi_register call. o "EventType" Upcall event types. The following types, defined in "rapi_lib.h", and discussed below: - Path event: RAPI_PATH_EVENT - Reservation event: RAPI_RESV_EVENT - Path error event: RAPI_PATH_ERROR - Reservation error event: RAPI_RESV_ERROR Braden, Hoffman Expiration: December 1996 [Page 14] Internet Draft RSVP BSD API May 1996 - Reservation confirmation: RAPI_RESV_CONFIRM o "Style" This parameter contains the style of the reservation; it is non-zero only for a RESV_EVENT or RESV_ERROR upcall. o "ErrorCode, ErrorValue, ErrorNode, ErrorFlags" These are set only for a path error or reservation error event. The ErrorCode values are defined in "rapi_lib.h" and corresponding text strings are defined in "rapi_err.h". o "FilterSpec_list", "FilterSpecNo" The "FilterSpec_list" parameter is a pointer to a malloc'd area containing a sequential vector of RAPI filter spec or sender template objects. The number of objexts in this vector is specified in " FilterSpecNo". If "FilterSpecNo" is zero, the " FilterSpec_list" parameter will be NULL. o "Flowspec_list", "FlowspecNo" The "Flowspec_list" parameter is a pointer to an area containing a sequential vector of RAPI flowspec or Tspec objects. The number of objects in this vector is specified in "FlowspecNo". If " FlowspecNo" is zero, the "Flowspec_list" parameter will be NULL. o "Adspec_list", "AdspecNo" The "Adspec_list" parameter is a pointer to an area containing a sequential vector of RAPI adspec objects. The number of objects in this vector is specified in "AdspecNo". If " AdspecNo" is zero, the "Adspec_list" parameter will be NULL. o "Event_arg" This is the value supplied in the rapi_register call. When the application's callback procedure returns, the API will free any areas pointed to by "Flowspec_list" or "FilterSpec_list"; the application must copy any values it wants to save. The specific parameters depend upon "EventType". Braden, Hoffman Expiration: December 1996 [Page 15] Internet Draft RSVP BSD API May 1996 o RAPI_PATH_PATH RSVP sender ("Path") state from a remote node has arrived or changed at the local node, so an end-to-end reservation can be made. "FilterSpec_list" and "Flowspec_list" will be of equal length, and corresponding entries will contain sender templates and sender Tspecs, respectively, for all senders known at this node. When there is no Tspec present, the corresponding object in "Flowspec_list" will be an empty RAPI object (see below). If there are any corresponding adspecs to be reported, then " Adspec_list" will contain entries corresponding to the other two lists, with missing adspecs indicated by empty RAPI objects. If there are no adspecs to be reported, then "AdspecNo" will be zero and "Adspec_list" will be NULL. o RAPI_RESV_EVENT Reservation state has arrived or changed at the node, imnlying that reservations are in place along the entire data path to one or more receivers. "FilterSpec_list" and "Flowspec_list" will be of equal length and corresponding entries will contain filter specs and flowspecs, respectively, for all reservations in place for data sent by this application. There will be at most one reservation per outgoing interface. If there is no filter_spec present to match a flow spec, the corresponding object in "FilterSpec_list" will be an empty RAPI object. o RAPI_PATH_ERR An asynchronous error has been found in the sender information specified in the rapi_register call. The "ErrorCode" and "ErrorValue" parameters will specify the error. "FilterSpec_list" and "Flowspec_list" will each contain one object, the sender template and corresponding sender Tspec (if any) in error. If there is no sender Tspec, the object in " Flowspec_list" will be an empty RAPI object. o RAPI_RESV_ERR An asynchronous reservation error has occurred. Braden, Hoffman Expiration: December 1996 [Page 16] Internet Draft RSVP BSD API May 1996 The "ErrorCode" and "ErrorValue" parameters will specify the error. "FilterSpec_list" and "Flowspec_list" will be the same length (currently always length 1), giving the filter spec and flowspec in error. If there is no filter_spec present to match the flowspec, the corresponding object in "FilterSpec_list" will be an empty RAPI object. Braden, Hoffman Expiration: December 1996 [Page 17] Internet Draft RSVP BSD API May 1996 3. RAPI FORMATTING ROUTINES For convenience of applications, RAPI includes standard routines for displaying the contents of a RAPI flowspec object or Tspec object. To use these routines, include the file "rapi_lib.h". A. Format a Flowspec The rapi_fmt_flowspec() call formats a given RAPI flowspec into a buffer of given address and size. The output is truncated if the size is too small. void rapi_fmt_flowspec( rapi_flowspec_t * specp, /* Addr of RAPI flowspec */ char * buffer, /* Addr of buffer */ int length /* Length of buffer */ ) B. Format a Tspec The rapi_fmt_flowspec() call formats a given RAPI flowspec into a buffer of given address and size. The output is truncated if the size is too small. void rapi_fmt_tspec( rapi_flowspec_t * tspecp, /* Addr of RAPI Tspec */ char * buffer, /* Addr of buffer */ int length /* Length of buffer */ ) C. Format an Adspec [Not implemented yet]. Braden, Hoffman Expiration: December 1996 [Page 18] Internet Draft RSVP BSD API May 1996 4. RAPI OBJECTS Flowspecs, filter specs, sender templates, and sender Tspecs are encoded as variable-length RAPI objects. Every RAPI object begins with a header consisting of two words, containing the total length of the object in bytes and the type, respectively. An empty object consists only of a header, with type zero and length 8 bytes. o Flowspecs and Sender Tspecs There are three formats for RAPI flowspecs. For more details, see "rapi_lib.h". - RAPI_FLOWSTYPE_CSZ This is a "legacy", which was included in earlier distributions of the ISI code. If this format is used, "rsvpd" will translate it into an Integrated Services Controlled Load flowspec, by ignoring the delay bound and service level parameters and by making worst-case assumptions about the Tspec parameters m and M. - RAPI_FLOWSTYPE_CSZX This is an "extended legacy" format. That is, like the CSZ format it consists of a simple list of parameters, but in the CSZX format the list includes places for all parameters needed for either Guaranteed or Controlled Load service. RAPI will map this format into an appropriate Integrated Services data structure, depending upon the service type that is included. - RAPI_FLOWSTYPE_Intserv This flowspec must be a fully formatted Integrated Services data structure. [I am currently very slightly confused about Tspecs. I'll get back to you...] o Filter Specs and Sender Templates There are two formats for these objects. - RAPI_FILTERTYPE_1 Braden, Hoffman Expiration: December 1996 [Page 19] Internet Draft RSVP BSD API May 1996 This more complex object contains both a socket address structure and a variable-length mask and value pair. Its use is not recommended. - RAPI_FILTERTYPE_2 This object consists of only a socket address structure, defining the IP address and port. It is recommended for all current applications. o Policy Data Objects (Not yet supported) Braden, Hoffman Expiration: December 1996 [Page 20]