idnits 2.17.1 draft-jhs-forces-tmlapi-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1.a on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 297. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 274. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 281. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 287. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: 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 becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (Feb 2005) is 7009 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 ForCES Working Group J. Hadi Salim 2 Internet-Draft Znyx Networks 3 Expires: August 5, 2005 Feb 2005 5 ForCES TML API 6 draft-jhs-forces-tmlapi-00.txt 8 Status of this Memo 10 This document is an Internet-Draft and is subject to all provisions 11 of Section 3 of RFC 3667. By submitting this Internet-Draft, each 12 author represents that any applicable patent or other IPR claims of 13 which he or she is aware have been or will be disclosed, and any of 14 which he or she become aware will be disclosed, in accordance with 15 RFC 3668. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as 20 Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on August 5, 2005. 35 Copyright Notice 37 Copyright (C) The Internet Society (2005). 39 Abstract 41 This document proposes an API between the ForCES PL and TML layer 42 with an end goal of reducing the effort of implementation of forces 43 PL level (and therefore expediting the deployment of multiple TMLs). 45 Conventions used in this document 47 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 48 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 49 document are to be interpreted as described in [RFC2119]. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 3. API objectives . . . . . . . . . . . . . . . . . . . . . . . . 6 56 4. Interface calls . . . . . . . . . . . . . . . . . . . . . . . 7 57 4.1 open() . . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 4.1.1 callback() . . . . . . . . . . . . . . . . . . . . . . 7 59 4.2 close() . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 4.3 ioctl() . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 4.4 send() . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 4.5 recv() . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 5. Theory of Operation . . . . . . . . . . . . . . . . . . . . . 10 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 10 66 Intellectual Property and Copyright Statements . . . . . . . . 11 68 1. Introduction 70 The ForCES protocol infrastructure constitutes of two components: 72 1. The Protocol Layer (PL) which is defined by the ForCES Protocol. 73 2. The Transport Mapping Layer (TML), which is a layer below the PL 74 that interconnects peering PL layers. 75 The diagram below shows the relationship between the two. On 76 transmit, the PL layer delivers its messages to the TML layer. The 77 TML layer delivers the message to the destination TML layer(s). On 78 receive, the TML delivers the message to its destination PL layer(s). 80 +------------------------------------------------ 81 | CE PL layer | 82 +------------------------------------------------ 83 | CE TML layer | 84 +------------------------------------------------ 85 ^ 86 | 87 ForCES | (i.e Forces data + control 88 PL | packets ) 89 messages | 90 over | 91 specific | 92 TML | 93 encaps | 94 and | 95 transport | 96 | 97 v 98 +------------------------------------------------ 99 | FE TML layer | 100 +------------------------------------------------ 101 | FE PL layer | 102 +------------------------------------------------ 104 Both the PL and TML layers are standardized by the IETF. despite 105 only one PL layer being defined, different TMLs are expected to be 106 standardized. To interoperate the TML layer at the CE and FE are 107 expected to be of the same definition. 109 While several TMLs maybe standardized by the IETF, the interface 110 between them is left upto the implementors. This implies that for 111 every new TML, the implementor of the PL will have to write an 112 interface to that TML. It is also possible that the implementors of 113 the TML and PL maybe from different organizations. 115 This document attempts to define an API between the TML and PL to 116 fill in the above gap. A socket like interface between the TML and 117 PL is defined. 119 2. Definitions 121 TBA 123 3. API objectives 125 There are several basic design objectives: 126 1. Support for unicast, multicast and broadcast PL level mechanisms. 127 2. support for both reliable and unreliable delivery. 128 3. Support for in-order or agnostic delivery. 129 4. Support for timeliness requirements. 130 5. Support for both synchronous and asynchronous operations. 131 6. Support for events from the PL to the TML. 133 4. Interface calls 135 4.1 open() 137 The PL connects to the TML by invoking the open call. The PL passes 138 a callback function which is used for asynchronous notification. It 139 is thought that as a first simple step, the callback is necessary. 140 In the long run, asynchronous calls such as poll() or select() will 141 be provided. 143 The return from open will be an signed 32 bit handle. When the 144 handle is negative, it will imply that an error occured and the 145 handle value will be reflective of the nature of error. A positive 146 valued handle implies a succesful registration. 148 4.1.1 callback() 150 The callback is used for asynchronous activities such as packet 151 arrivals as well as events. As was described above, this may be 152 latter deprecated and replaced by standard posix asynchronous 153 mechanisms such as poll() and select(). 155 4.2 close() 157 In this call, the PL disconmnects from the TML. The handle acquired 158 in the open() call is passed. 160 4.3 ioctl() 162 The ioctl interface is used by the PL to control the behavior of the 163 TML. It is thought that in the case of a socket interface this call 164 is replaced by set/getsockopt() call. 166 Several interfaces are defined. All are passed a control type and a 167 set of parameters needed by that ioctl. In all but the event calls, 168 a PL header filter is used in the parameter list. 170 When a PL level header is used as the filter, then any fields in the 171 header that are of not interest are set to 0. As an example, if the 172 version was not of interest, then setting it to 0 implies that all 173 versions of the PL protocol apply. 175 By providing the filter to the TML the PL is indicating how it wants 176 PDUs which match that header to be treated. As an example, if a 177 header with a Config message type and an ACK flag is passed to the 178 TML as something requiring reliability, then it implies that whenever 179 such a message is received by the TML from the PL it should be 180 treated as one that must be delivered reliably to the target TML(s). 182 Editorial note: [There are other alternatives to this scheme 183 referenced in appendix 1 of the protocol draft - for now this scheme 184 is listed here because it has been validated by an implementation.] 186 Editorial note: [We could pass more than the PL header fields (LFB 187 selector and operation may be of value as well - that will be 188 considered in later revisions] 190 Parameters are required to be unique within a ioctl type and handle. 191 The same parameters (such as PL headers) can be repeated on different 192 ioctl calls. 193 1. MCAST ADD/DEL/GET register/unregister/retrieve PL level 194 multicast. The PL level PID of interest is described in the PL 195 header passed. The PID must be within acceptable boundaries as 196 defined by the protocol. 197 2. RELIABLE ADD/DEL/GET register/unregister/retrieve PL level 198 reliability of certain messages. The PL passes to the TML a PL 199 header that highlights the header fields of interest. Any 200 messages from the PL which do not match a list of headers passed 201 via this call are not guaranteed to be delivered reliably. 202 3. TIMELINESS ADD/DEL/GET register/unregister/retrieve PL level 203 timeliness. The PL passes to the TML a PL header that highlights 204 the header fields of interest as well as a timeout parameter at 205 which messages matching those headers should be purged. 206 4. EVENT ADD/DEL/GET register/unregister/retrieve PL level 207 timeliness. 208 5. Describe all events in details after draft-00 (peer died, peer 209 left, new mcast member, mcast member left, reliable msg failed to 210 deliver, message obsoleted due to timing constraints, TML 211 transport migration). 213 4.4 send() 215 In this call, the PL sends a message to one or more peer PLs. The PL 216 message and handle acquired in the open() call are passed. A flag 217 maybe considered in later revisions of this draft for specifying 218 parameters such as blocking or scatter gather. The return code is a 219 positive number which indicates the number of bytes sent, or a 220 negative number if an error occurs. The following errors may occur 221 (borrowed from socket API send()): 222 1. EBADF - An invalid handle/descriptor was specified. 223 2. ENOMEM - No memory available. 225 4.5 recv() 227 This call is to complement the callback() that was described earlier 228 and varies slightly from the socket recv() in that it is always 229 blocking. It exists to provide a synchronous call for receiving 230 messages. In this call, the PL blocks and waits for a PL message 231 (not an event). A flag set may be considered later for defining what 232 if any signals can interupt this call etc. The message and handle 233 acquired in the open() call are passed. The following errors may 234 occur (borrowed from socket API send()): 235 1. EBADF - An invalid handle/descriptor was specified. 236 2. ENOMEM - No memory available. 238 5. Theory of Operation 240 TBA: open() with callback(), followed by ioctls(). Then show how 241 messages and events are received. And finally show a close() 243 6. References 245 [ForCES_Model] 246 Yang, L., Halpern, J., Gopal, R., DeKok, A., Haraszti, Z. 247 and S. Blake, "ForCES Forwarding Element Model", October 248 2003, < 249 . >. 252 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 253 Requirement Levels", BCP 14, RFC 2119, March 1997. 255 Author's Address 257 Jamal Hadi Salim 258 Znyx Networks 259 195 Stafford Rd. West 260 Ottawa, Ontario 261 Canada 263 Email: hadi@znyx.com 265 Intellectual Property Statement 267 The IETF takes no position regarding the validity or scope of any 268 Intellectual Property Rights or other rights that might be claimed to 269 pertain to the implementation or use of the technology described in 270 this document or the extent to which any license under such rights 271 might or might not be available; nor does it represent that it has 272 made any independent effort to identify any such rights. Information 273 on the procedures with respect to rights in RFC documents can be 274 found in BCP 78 and BCP 79. 276 Copies of IPR disclosures made to the IETF Secretariat and any 277 assurances of licenses to be made available, or the result of an 278 attempt made to obtain a general license or permission for the use of 279 such proprietary rights by implementers or users of this 280 specification can be obtained from the IETF on-line IPR repository at 281 http://www.ietf.org/ipr. 283 The IETF invites any interested party to bring to its attention any 284 copyrights, patents or patent applications, or other proprietary 285 rights that may cover technology that may be required to implement 286 this standard. Please address the information to the IETF at 287 ietf-ipr@ietf.org. 289 Disclaimer of Validity 291 This document and the information contained herein are provided on an 292 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 293 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 294 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 295 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 296 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 297 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 299 Copyright Statement 301 Copyright (C) The Internet Society (2005). This document is subject 302 to the rights, licenses and restrictions contained in BCP 78, and 303 except as set forth therein, the authors retain all their rights. 305 Acknowledgment 307 Funding for the RFC Editor function is currently provided by the 308 Internet Society.