Return-Path: Received: from F.GP.CS.CMU.EDU by N3.SP.CS.CMU.EDU id aa10363; 22 Jul 96 8:57:42 EDT Received: from N3.SP.CS.CMU.EDU by F.GP.CS.CMU.EDU id aa05652; 22 Jul 96 8:56:12 EDT Date: Mon, 22 Jul 96 08:54:48 EDT From: Hui.Zhang@N3.SP.CS.CMU.EDU To: garth+nasd-video@cs.cmu.edu Subject: Intel RSVP API Sender: garth@F.GP.CS.CMU.EDU Status: RO From: Raj Yavatkar Subject: Re: Windows NT Cc: rsvp@ISI.EDU X-Attachments: F:\RAJ\WORD\APIANNEX.ANS; Sender: owner-rsvp@ISI.EDU Precedence: bulk Status: RO --=====================_824924040==_ Content-Type: text/plain; charset="us-ascii" Intel has an implementation of RSVP under winsock2 for botn NT and Win95. We plan to release a beta version of our implementation by March 31st (incl. possibility of source code release to interested stack vendors and ISVs). Our implementation supports an extended version of Winsock2 QoS API (I have attached an ascii text version of API below) and will also support generic QoS API through a layered service provider. Please contact me if you would like to participate in the beta program. Raj --=====================_824924040==_ Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable 2/21/96 1 RSVP Introduction This section covers extensions to WinSock 2 that are specific to RSVP protocol. These extensions are needed to allow applications to request an enhanced quality-of-service (QoS) for their data flows using the RSVP protocol. The document assumes that the reader is familiar with the RSVP protocol as defined in the RSVP version 1 specification (Internet draft draft-ietf- rsvp-spec-08 available from ftp://www.isi.edu/internet- drafts/draft-ietf-rsvp-spec-08.ps). Address comments or questions regarding this material to: Raj Yavatkar Intel Corporation yavatkar@ibeam.intel.com Fast Facts: Protocol RSVP (ReSerVation setup Name(s) Protocol) Description RSVP is a signaling or network control protocol that allows applications to reserve network resources for simplex, unicast/multicast data flows. Address AF_INET Family Header File WS2RSVP.H RSVP Overview RSVP protocol version 1, an IETF proposed standard, is a resource reservation setup protocol designed for an integrated services Internet. It provides support for reservation of resources for simplex, multicast or unicast data flows. An application uses the RSVP protocol to identify a data flow and to request a specific quality of service (QoS) from the network. RSVP is a simplex protocol (i.e., it reserves resources in one direction) and the receiver(s) of a data flow are responsible for the initiation of resource reservation. RSVP operates on top of the Internet Protocol (IPv4 or IPv6) and is a control protocol similar to ICMP and routing protocols. RSVP is identified as a separate protocol (IP protocol id 46) within the AF_INET domain. RSVP Reservation Model Under RSVP, requests for reservation are handled separately from the data transfer. Thus, an application establishes a data flow using an AF_INET socket (datagram or stream) in a conventional way and uses the data socket for transferring data over a unicast or multicast flow. In addition, for multicast applications, the application must specify appropriate options for the data socket to join/leave a multicast group. All the resource reservation transactions for a data flow must, however, be carried out using a separate, non-blocking RSVP socket (a SOCK_DGRAM socket with protocol id IPPROTO_RSVP)1. All data packets addressed to the same destination belong to the same RSVP session, where the destination is defined by an IP destination (unicast or multicast) address, IP protocol identifier (i.e., UDP or TCP), and a port number. A given session may have several senders and, in the case of a multicast session, may also have multiple receivers; a sender or a receiver in a session is identified by an IP address and a port number. Under RSVP, resource reservation requests are made by the data receivers. A reservation request contains a flowspec together with a filterspec. The flowspec specifies the desired QoS and the filterspec specifies which packets are to receive the specified QoS (e.g., based on the identity of a sender of data packets). RSVP Data Structures The data structures used in conjunction with WSAIoctl() call are defined in WS2RSVP.H (included at the end of the annex). These data structures describe the formats for session addresses, flowspecs, and filterspecs. RSVP Controls Due to the asynchronous nature of interaction between sender(s) and receivers in a RSVP session, all the RSVP calls are performed over the RSVP socket in a non-blocking mode. The RSVP API consists of a set of RSVP-specific control opcodes (dwIoControlCode parameter) specified as part of WSAIoctl() or WSPIoctl() calls over the RSVP socket as described below. It should be noted that an application may use a single RSVP socket to perform RSVP-related operations for multiple sessions and it need not open a separate RSVP socket for each data socket. The soft-state nature of RSVP reservations inside the network requires end-systems to periodically generate refresh messages (PATH and RESERVE) and these messages can trigger errors or status notifications from the network at any time during a session. An application is notified of such status notifications and other changes in traffic or QoS specifications via FD_QOS event understood by WSAEventSelect and WSAAsyncSelect calls. Ioctls The following table describes RSVP-specific control codes and their meaning in the WSAIoctl()/WSPIoctl() call. The parameters lpOverlapped and lpCompletionRoutine are ignored in all the calls. An application must ensure that the lpvOutBuffer parameter contains address of the output buffer of appropriate size depending on the call. On successful return from the WSAIoctl() call, lpvOutBuffer is ignored unless specified otherwise in the following table. In case of an error in the WSAIoctl call, error-specific information is returned using the RSVP_ERROR structure in the output buffer lpvOutBuffer. In the case of retrieve and query_ QOS calls, the output buffer passed should be of size RSVP_RETURN_SIZE (defined in rsvp.h). dwIoControlCo lpvInBuffer lpvOutBuffer Meaning de contents =20 SIO_RSVP_REGI REGISTER_DATA If error, Create a RSVP STER object contains session. RSVP_ERROR object. SIO_RSVP_SEND SENDER_DATA If error, Specify a ER object contains sender=92s RSVP_ERROR Tpsec and object. other characteristi cs. SIO_RSVP_RESE RESERVE_DATA If error, Request RVE object contains resource RSVP_ERROR reservations object. in a session. SIO_RSVP_REL_ REL_SENDER_DAT If error, Cease being a SENDER A object contains sender. RSVP_ERROR object. SIO_RSVP_REL_ REL_RESERVE_DA If error, Tear down RESERVE TA object contains reservation RSVP_ERROR for a object. session. SIO_RSVP_RETR None RSVP_RETURN Obtain IEVE object on currently success and active RSVP_ERROR Tspec(s) or object if flowpsecs in error a session or retrieve information about errors in a session. SIO_RSVP_ QUERY_ if successful Obtain the QUERY_ QOS QOS_DATA then RSVP_ current object QOSLIST flowspec(s) object else for a RSVP_ERROR session. object. RSVP_REGISTER An RSVP sender or receiver must register with RSVP to create a RSVP session before it can make any QoS- related requests for the session. As part of the call, an application must indicate whether it wishes to be a sender or a receiver or both. =20 =20 RSVP_SENDER A sender uses the call to specify its traffic specifications (Tspec). The sender of a data flow is identified by its source address (IP address and port number binding in its data socket) and must be specified as a parameter. Other optional parameters include a policy object and an IP TTL (Time To Live) scope for the data packets. =20 RSVP_RESERVE A receiver initiates resource reservation(s) using this call. In case of a multi-homed host, the receiver may specify the interface address over which the requested reservation needs to be made. In the case of shared explicit and fixed filter style of reservations, several flow descriptors (one per reservation) may be supplied. An optional parameter includes a policy object. RSVP_REL_SENDER A sender uses the call to leave a session. RSVP_REL_RECEIVER A receiver uses this call to tear down one or more reservations for the session. For example, a receiver can tear down its reservations over a particular interface (host address), or tear down a particular reservation based on a filter specification. RSVP_RETRIEVE An application makes this call when it receives a FD_QOS event notification. FD_QOS event is signaled when events such as receipt of new traffic specifications, errors in reservation, or changes in installed flow specifications have occurred. An application passes a pointer to RSVP_RETURN structure in outBuffer argument for the call to retrieve the cause of the event and more details about the event. The RSVP SP returns the relevant information as part of a RSVP_RETURN structure. RSVP_RETURN structure identifies the type of event and provide event-specific information (see the data structure definition in the header file). When the call is made, it is possible that more than one event notification is pending for the session. In that case, RSVP SP returns information about one event at a time and the application should make repeated retrieve calls to retrieve information about each event. The retrieve call returns WSAEWOULDBLOCK if no more event notifications are pending. Information returned in a RSVP_RETURN structure may contain pointers to descriptors allocated by RSVP SP; these pointers point to areas separately allocated per session (and per socket) and are valid only until the next RSVP-specific ioctl call is made for the session. An application must be careful in using this information and must copy it to its own data area if it intends to use it beyond a single retrieve call. RSVP_QUERY_ QOS The call is used to retrieve flow specifications (i.e., Tspecs and Rspecs) for one or more current senders in a session. Application passes a pointer to the RSVP_ QOSLIST structure in the argument outBuffer to retrieve the information. If number of filter specifications supplied (noFilts parameter) is zero in the Query_ QOS_DATA argument, the call returns the flow descriptors for all the current senders. Otherwise, the flow descriptors that match the specified filterspecs are returned. As in the case of the retrieve call, the RSVP_ QOSLIST returned in OutBuffer may contain pointers to descriptors allocated by SP and such pointers are valid only until the next RSVP- specific ioctl call is made for the session. Policy Object To allow policy-based input to the admission control process, RSVP assumes a policy component at each node. As input to the policy-based admission decision, RSVP messages may carry a policy object that includes information such as user credentials, account numbers, quotas, and so on. An application may pass a policy object as an optional argument to the RSVP_SENDER and RSVP_RESERVE calls. RSVP Status Notifications An RSVP application can expect to receive the following status notifications in an asynchronous manner. It should be noted that these status notifications should not be treated as fatal errors. Instead, they should be viewed as advisory messages about the state of the reservation. For instance, a reservation error may simply indicate that the reservation you requested could not be installed (resulting in best effort service) and repeating the request with different parameter values may install the reservation. =B7 ResvErr - notification to a receiver is generated when a RESV request fails inside the network typically due to an admission control failure. =B7 PathErr - notification to a sender is generated in case of an error in propagation or installation of a PATH message from the sender. =B7 PathTear - notification arrives at a receiver when a sender initiates a teardown or a router on the path initiates a teardown as a result of state timeout. =B7 Confirm - notification arrives at a receiver in response to its reservation request. The notification is not necessarily a confirmation that the requested reservation is installed successfully at all the routers along the path of a reservation. Instead, it only indicates that the reservation request successfully reached some router along the path and was not rejected at the point when the conformation was sent. =B7 PathChange - a receiver is notified when new traffic specifications arrive from a sender. =B7 ResvChange - a receiver is notified when a previously installed reservation changes due to merging of multiple reservations from different receivers. RSVP Header File /* ** WS2RSVP.H - WinSock2 Extension for RSVP protocol ** ** This file contains RSVP specific information for use ** by WinSock2 compatible applications. ** */ //////////////////////////////////////////////////////////// ///////////////////// // // $Workfile: ws2rsvp.h $ // $Revision: 1.0 $ // // // DESCRIPTION: // The API header file // //////////////////////////////////////////////////////////// //////////////////// #ifndef _W2RSVPAPI #define _W2RSVPAPI #ifndef _WINSOCK2SPI #include #endif // RSVP protocol specific number #define IPPROTO_RSVP 0x2e // Protocol specific commands for WSAIoctl() #define SIO_RSVP_REGISTER 0xd02e0001 #define SIO_RSVP_SENDER 0xd02e0002 #define SIO_RSVP_RESERVE 0xd02e0003 #define SIO_RSVP_REL_SENDER 0xd02e0004 #define SIO_RSVP_REL_RESERVE 0xd02e0005 #define SIO_RSVP_RETRIEVE 0xd02e0006 #define SIO_RSVP_QUERY_ QOS 0xd02e0007 // IP version 4 addr typedef struct tag_AddrIPv4 { struct in_addr addr; u_short srcport; } ADDR_IPv4; // Sender Template Strcuture typedef struct tag_tmpl { ADDR_IPV4 tmpl; }RSVP_TEMPLATE; // Filter Spec Structure typedef struct tag_rsvpFilt { ADDR_IPv4 ipv4Filt; } RSVP_FILTERSPEC; // Session structure typedef struct tag_sess { struct in_addr addr; u_short destPort; BYTE protId; } RSVP_SESSION; // Policy structure typedef struct tag_policy { char polType[256]; }RSVP_POLICY; // FLOWSPEC and QoS are defined in winsock2.h #define RSVP_FLOWSPEC QoS //Tspec strcuture typedef struct tag_tspec { FLOWSPEC options; int32 minPoliced; int32 maxPktSize; } RSVP_TSPEC; //Rspec strcuture typedef struct tag_rspec { FLOWSPEC options; int32 slackTerm; } RSVP_RSPEC; // Adspec structure typedef struct tag_adspec { int gLevel; int32 errTermC; int32 errTermD; int clLevel; } RSVP_ADSPEC; // Flowdesc Structure typedef struct tag_flowdesc { RSVP_FLOWSPEC flow; RSVP_POLICY policy; int numFilts; RSVP_FILTERSPEC FiltsList[]; }RSVP_FLOWDESC; // Structure to be used while calling WSAIoctl() // with SIO_RSVP_REGISTER typedef struct tag_register { RSVP_SESSION sess; u_short regopt; }REGISTER_DATA; #define RSVP_SENDER 0x01 #define RSVP_RECEIVER 0x02 #define RSVP_SENRECV 0x03 // Structure to be used while calling WSAIoctl() // with SIO_RSVP_SENDER as command typedef struct tag_sender { RSVP_SESSION sess; struct in_addr hostAddr; u_short hostPort; RSVP_TSPEC tspec; RSVP_POLICY policy; //Optional int dataTTL; //Optional }SENDER_DATA; // Structure to be used while calling WSAIoctl() // with SIO_RSVP_RESERVE as command typedef struct tag_reserve { RSVP_SESSION sess; struct in_addr hostAddr; //Optional RSVP_POLICY policy; //Optional int style; int numFds; RSVP_FLOWDESC fdList[]; // Required if style is SE, FF }RESERVE_DATA; // Structure to be used while calling WSAIoctl() // with SIO_RSVP_RELEASE as command typedef struct tag_relsender { RSVP_SESSION sess; RSVP_TEMPLATE tmpl; } REL_SENDER_DATA; // Structure to be used while calling WSAIoctl() // with SIO_RSVP_RELEASE as command typedef struct tag_relreserve { RSVP_SESSION sess; struct in_addr hostAddr; //Optional int style; int numFilts; RSVP_FILTERSPEC filtList[]; } REL_RESERVE_DATA; // Structure to be used while calling WSAIoctl() // with SIO_RSVP_QUERY_ QOS as command typedef struct tag_queryQOS { RSVP_SESSION sess; int numFilts ; //Optional, if NULL, all filterspecs RSVP_FILTERSPEC filtList[]; //for the session are returned } QUERY_ QOS_DATA; // Error Structure typedef struct tag_error { RSVP_SESSION sess; int errCode; }RSVP_ERROR; #define RSVP_RETURN_SIZE (sizeof(RSVP_ERROR)) // Return Structure. Used by service provider // to return information to the application. This could be information about a // path, path err,path tear, resv err, resv change typedef struct tag_return { int infoType; union { RSVP_SNDDESC *rsdesc; // for a path or path tear RSVP_PATHERR rpatherr; RSVP_RESVERR *rresverr; RSVP_FLOWDESC *rresvchg; } } RSVP_RETURN; // Sender Descriptor structure typedef struct tag_snddesc { RSVP_SESSION sess; RSVP_TMPL tmpl; RSVP_TSPEC tspec; RSVP_ADSPEC adspec; } RSVP_SNDDESC; typedef struct tag_patherr { BYTE ecode; int evalue; ADDR_IPv4 enodeadr; RSVP_TMPL esnd; RSVP_POLICY epolicy; }RSVP_PATHERR; typedef struct tag_resverr { BYTE ecode; int evalue; ADDR_IPv4 enodeadr; RSVP_FLOWDESC rfds; }RSVP_RESVERR; // QOS List Structure typedef struct taq_QOSlist { int numFds; RSVP_FLOWDESC *fdList; }RSVP_ QOSLIST; // Error Codes. #define RS_OK 01 #define RS_ADM_DELAY 02 #define RS_ADM_BW 03 #define RS_ADM_SERC 04 #define RS_ADM_SERU 05 #define RS_ADM_UNR 06 #define RS_POLICY_CRED 07 #define RS_POLICY_LAR 08 #define RS_POLICY_QUOTA 09 #define RS_POLICY_PREMPT 10 #define RS_PATH 11 #define RS_SENDER 12 #define RS_AMB 13 #define RS_FILT 14 #define RS_STYLE 15 #define RS_DSTP 16 #define RS_SRCP 17 #define RS_MISS_SESS 18 #define RS_MISS_STMPL 19 #define RS_MISS_STSPEC 20 #define RS_MISS_STYLE 21 #define RS_MISS_FLOW 22 #define RS_UNKN_SESS 23 #define RS_UNKN_STYLE 24 #define RS_UNKN_FLOWSPEC 25 #define RS_UNKN_FILT 26 #define RS_UNKN_STMPL 27 #define RS_UNKN_STSPEC 28 #define RS_UNKN_ADSPEC 29 #define RS_UNKN_POLICY 30 #define RS_UNKN_INTGR 31 #define RS_TC 32 #define RS_SYS 33 #define RS_ADMINC 34 // Explanation of the error codes mentioned above // RS_OK Message interpreted succesfully. // // RS_ADM_DELAY Admission control failure. This is returned when the // reservation is rejected by admission control because the // delay cannot be met. // RS_ADM_BW Admission control failure.Returned when Requested bw not available // RS_ADM_SERC Admission control failure.Returned when Service conflicts // RS_ADM_SERU Admission control failure.Returned when Service is unsupported // RS_ADM_UNR Admission control failure.Returned when there is an unreasonable request // // RS_POLICY_CRED Administrative Rejection, returned when the error is rejected // for policy or administrative reason and the Required credentials // are not present // RS_POLICY_LAR Administrative Rejection, returned when Request is too large for // policy reasons // RS_POLICY_QUOTA Administrative Rejection, returned when there is Insufficient quota // or balance (accouting) // RS_POLICY_PREMPT Administrative Rejection, returned when there is Administrative preemption // // // RS_PATH No Path Information for this RESV, returned after a // reservation is requested and RSVP waits for a certain timeout // to receive PATH information. // // RS_SENDER No sender information for this RESV. returned when the there // is path state but it does not include the sender specfied in // one of the Filterspecs. // // RS_AMB Ambigous Path, Sender port appears to be both zero and non zero // in the same session. // // RS_FILT Ambigous FilterSpec, Filterspec matches more than one sender // in a style that requires a unique match. // // RS_STYLE Conflicting or Unknown Style,Reservation style conflicts with // the style of an exixting reservation or it is an unknown style. // // RS_DSTP Conflicting dest. port. Sessions for the same destination // address and protocol have appeared with both zero and // non zero dest. port fields. // // RS_SRCP Conflicting source port, the source port is non zero in a // filterspec or a sender template for a destination with port // zero. // // RS_MISS_SESS Missing a required object, RSVP was unable to construct a message // since a required object,SESSION was missing. // RS_MISS_STSPEC Missing a required object, RSVP was unable to construct a message // since a required object,sender TSPEC was missing // RS_MISS_STMPL For a multihomed host, the hostaddr field was missing. // RS_MISS_STYLE The reserve message did not contain a style // RS_MISS_FLOW The reserve message did not contain a FLOWSPEC object // RS_UNKN_SESS Unknown object, RSVP cannot recognise a field sent in the message // or there is an error in one of the fields.Unknown SESSION // RS_UNKN_STYLE Unknown object,STYLE // RS_UNKN_FLOW Unknown object,FLOWSPEC // RS_UNKN_FILT Unknown object,FILTERSPEC // RS_UNKN_STMPL Unknown object,SENDER_TEMPLATE // RS_UNKN_STSPEC Unknown object,SENDER_TSPEC // RS_UNKN_ADSPEC Unknown object,SENDER_ADSPEC // RS_UNKN_POLICY Unknown object,POLICY // RS_UNKN_INTGR Unknown object,INTEGRITY // // // // RS_TC Error reported by traffic control module. // // RS_SYS An RSVP system error,any implementation specific error of // required. // // RS_ADMINC Reservation made is greater than requested due to merging. _______________________________ 1 A single RSVP socket may be shared among multiple sessions. --=====================_824924040==_ Content-Type: text/plain; charset="us-ascii" --=====================_824924040==_--