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, <
<http://www.ietf.org/internet-drafts/draft-ietf-forces-mod
el-03.txt>. >.
[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]