ForCES Working Group J. Hadi Salim Internet-Draft Znyx Networks Expires: August 5, 2005 Feb 2005 ForCES TML API draft-jhs-forces-tmlapi-00.txt Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on August 5, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document proposes an API between the ForCES PL and TML layer with an end goal of reducing the effort of implementation of forces PL level (and therefore expediting the deployment of multiple TMLs). Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", Hadi Salim Expires August 5, 2005 [Page 1] Internet-Draft ForCES TML API Feb 2005 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. API objectives . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Interface calls . . . . . . . . . . . . . . . . . . . . . . . 7 4.1 open() . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.1.1 callback() . . . . . . . . . . . . . . . . . . . . . . 7 4.2 close() . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.3 ioctl() . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.4 send() . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.5 recv() . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5. Theory of Operation . . . . . . . . . . . . . . . . . . . . . 10 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 10 Intellectual Property and Copyright Statements . . . . . . . . 11 Hadi Salim Expires August 5, 2005 [Page 2] Internet-Draft ForCES TML API Feb 2005 1. Introduction The ForCES protocol infrastructure constitutes of two components: 1. The Protocol Layer (PL) which is defined by the ForCES Protocol. 2. The Transport Mapping Layer (TML), which is a layer below the PL that interconnects peering PL layers. The diagram below shows the relationship between the two. On transmit, the PL layer delivers its messages to the TML layer. The TML layer delivers the message to the destination TML layer(s). On receive, the TML delivers the message to its destination PL layer(s). +------------------------------------------------ | CE PL layer | +------------------------------------------------ | CE TML layer | +------------------------------------------------ ^ | ForCES | (i.e Forces data + control PL | packets ) messages | over | specific | TML | encaps | and | transport | | v +------------------------------------------------ | FE TML layer | +------------------------------------------------ | FE PL layer | +------------------------------------------------ Both the PL and TML layers are standardized by the IETF. despite only one PL layer being defined, different TMLs are expected to be standardized. To interoperate the TML layer at the CE and FE are expected to be of the same definition. While several TMLs maybe standardized by the IETF, the interface between them is left upto the implementors. This implies that for every new TML, the implementor of the PL will have to write an interface to that TML. It is also possible that the implementors of the TML and PL maybe from different organizations. Hadi Salim Expires August 5, 2005 [Page 3] Internet-Draft ForCES TML API Feb 2005 This document attempts to define an API between the TML and PL to fill in the above gap. A socket like interface between the TML and PL is defined. Hadi Salim Expires August 5, 2005 [Page 4] Internet-Draft ForCES TML API Feb 2005 2. Definitions TBA Hadi Salim Expires August 5, 2005 [Page 5] Internet-Draft ForCES TML API Feb 2005 3. API objectives There are several basic design objectives: 1. Support for unicast, multicast and broadcast PL level mechanisms. 2. support for both reliable and unreliable delivery. 3. Support for in-order or agnostic delivery. 4. Support for timeliness requirements. 5. Support for both synchronous and asynchronous operations. 6. Support for events from the PL to the TML. Hadi Salim Expires August 5, 2005 [Page 6] Internet-Draft ForCES TML API Feb 2005 4. Interface calls 4.1 open() The PL connects to the TML by invoking the open call. The PL passes a callback function which is used for asynchronous notification. It is thought that as a first simple step, the callback is necessary. In the long run, asynchronous calls such as poll() or select() will be provided. The return from open will be an signed 32 bit handle. When the handle is negative, it will imply that an error occured and the handle value will be reflective of the nature of error. A positive valued handle implies a succesful registration. 4.1.1 callback() The callback is used for asynchronous activities such as packet arrivals as well as events. As was described above, this may be latter deprecated and replaced by standard posix asynchronous mechanisms such as poll() and select(). 4.2 close() In this call, the PL disconmnects from the TML. The handle acquired in the open() call is passed. 4.3 ioctl() The ioctl interface is used by the PL to control the behavior of the TML. It is thought that in the case of a socket interface this call is replaced by set/getsockopt() call. Several interfaces are defined. All are passed a control type and a set of parameters needed by that ioctl. In all but the event calls, a PL header filter is used in the parameter list. When a PL level header is used as the filter, then any fields in the header that are of not interest are set to 0. As an example, if the version was not of interest, then setting it to 0 implies that all versions of the PL protocol apply. By providing the filter to the TML the PL is indicating how it wants PDUs which match that header to be treated. As an example, if a header with a Config message type and an ACK flag is passed to the TML as something requiring reliability, then it implies that whenever such a message is received by the TML from the PL it should be treated as one that must be delivered reliably to the target TML(s). Hadi Salim Expires August 5, 2005 [Page 7] Internet-Draft ForCES TML API Feb 2005 Editorial note: [There are other alternatives to this scheme referenced in appendix 1 of the protocol draft - for now this scheme is listed here because it has been validated by an implementation.] Editorial note: [We could pass more than the PL header fields (LFB selector and operation may be of value as well - that will be considered in later revisions] Parameters are required to be unique within a ioctl type and handle. The same parameters (such as PL headers) can be repeated on different ioctl calls. 1. MCAST ADD/DEL/GET register/unregister/retrieve PL level multicast. The PL level PID of interest is described in the PL header passed. The PID must be within acceptable boundaries as defined by the protocol. 2. RELIABLE ADD/DEL/GET register/unregister/retrieve PL level reliability of certain messages. The PL passes to the TML a PL header that highlights the header fields of interest. Any messages from the PL which do not match a list of headers passed via this call are not guaranteed to be delivered reliably. 3. TIMELINESS ADD/DEL/GET register/unregister/retrieve PL level timeliness. The PL passes to the TML a PL header that highlights the header fields of interest as well as a timeout parameter at which messages matching those headers should be purged. 4. EVENT ADD/DEL/GET register/unregister/retrieve PL level timeliness. 5. Describe all events in details after draft-00 (peer died, peer left, new mcast member, mcast member left, reliable msg failed to deliver, message obsoleted due to timing constraints, TML transport migration). 4.4 send() In this call, the PL sends a message to one or more peer PLs. The PL message and handle acquired in the open() call are passed. A flag maybe considered in later revisions of this draft for specifying parameters such as blocking or scatter gather. The return code is a positive number which indicates the number of bytes sent, or a negative number if an error occurs. The following errors may occur (borrowed from socket API send()): 1. EBADF - An invalid handle/descriptor was specified. 2. ENOMEM - No memory available. 4.5 recv() This call is to complement the callback() that was described earlier and varies slightly from the socket recv() in that it is always blocking. It exists to provide a synchronous call for receiving Hadi Salim Expires August 5, 2005 [Page 8] Internet-Draft ForCES TML API Feb 2005 messages. In this call, the PL blocks and waits for a PL message (not an event). A flag set may be considered later for defining what if any signals can interupt this call etc. The message and handle acquired in the open() call are passed. The following errors may occur (borrowed from socket API send()): 1. EBADF - An invalid handle/descriptor was specified. 2. ENOMEM - No memory available. Hadi Salim Expires August 5, 2005 [Page 9] Internet-Draft ForCES TML API Feb 2005 5. Theory of Operation TBA: open() with callback(), followed by ioctls(). Then show how messages and events are received. And finally show a close() 6. References [ForCES_Model] Yang, L., Halpern, J., Gopal, R., DeKok, A., Haraszti, Z. and S. Blake, "ForCES Forwarding Element Model", October 2003, < . >. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Author's Address Jamal Hadi Salim Znyx Networks 195 Stafford Rd. West Ottawa, Ontario Canada Email: hadi@znyx.com Hadi Salim Expires August 5, 2005 [Page 10] Internet-Draft ForCES TML API Feb 2005 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Hadi Salim Expires August 5, 2005 [Page 11]