ForCES Protocol Extensions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

This document reiterates the terminology defined by the ForCES architecture in various documents for the sake of clarity. FE Model - The FE model is designed to model the logical processing functions of an FE. The FE model proposed in this document includes three components; the LFB modeling of individual Logical Functional Block (LFB model), the logical interconnection between LFBs (LFB topology), and the FE-level attributes, including FE capabilities. The FE model provides the basis to define the information elements exchanged between the CE and the FE in the ForCES protocol. LFB (Logical Functional Block) Class (or type) - A template that represents a fine-grained, logically separable aspect of FE processing. Most LFBs relate to packet processing in the data path. LFB classes are the basic building blocks of the FE model. LFB Instance - As a packet flows through an FE along a data path, it flows through one or multiple LFB instances, where each LFB is an instance of a specific LFB class. Multiple instances of the same LFB class can be present in an FE's data path. Note that we often refer to LFBs without distinguishing between an LFB class and LFB instance when we believe the implied reference is obvious for the given context. LFB Model - The LFB model describes the content and structures in an LFB, plus the associated data definition. XML is used to provide a formal definition of the necessary structures for the modeling. Four types of information are defined in the LFB model. The core part of the LFB model is the LFB class definitions; the other three types of information define constructs associated with and used by the class definition. These are reusable data types, supported frame (packet) formats, and metadata. LFB Metadata - Metadata is used to communicate per-packet state from one LFB to another, but is not sent across the network. The FE model defines how such metadata is identified, produced, and consumed by the LFBs, but not how the per-packet state is implemented within actual hardware. Metadata is sent between the FE and the CE on redirect packets. ForCES Component - A ForCES Component is a well-defined, uniquely identifiable and addressable ForCES model building block. A component has a 32-bit ID, name, type, and an optional synopsis description. These are often referred to simply as components. LFB Component - An LFB component is a ForCES component that defines the Operational parameters of the LFBs that must be visible to the CEs. ForCES Protocol - Protocol that runs in the Fp reference points in the ForCES Framework. ForCES Protocol Layer (ForCES PL) - A layer in the ForCES protocol architecture that defines the ForCES protocol messages, the protocol state transfer scheme, and the ForCES protocol architecture itself as defined in the ForCES Protocol Specification. ForCES Protocol Transport Mapping Layer (ForCES TML) - A layer in ForCES protocol architecture that uses the capabilities of existing transport protocols to specifically address protocol message transportation issues, such as how the protocol messages are mapped to different transport media (like TCP, IP, ATM, Ethernet, etc.), and how to achieve and implement reliability, ordering, etc. the ForCES SCTP TML describes a TML that is mandated for ForCES.

Experience in implementing and deploying ForCES architecture has demonstrated need for a few small extensions both to ease programmability and to improve wire efficiency of some transactions. This document describes a few extensions to the ForCES Protocol Specification semantics to achieve that end goal. This document describes and justifies the need for 2 small extensions which are backward compatible. The document also clarifies on top of how dumping of large components is achieved. A table range operation to allow a controller or control application to request an arbitrary range of table rows. Improved Error codes returned to the controller (or control application) to improve granularity of existing defined error codes. FE response to a GET request (example to a large table) may not fit in one PL message, for example due to limited TLV space.

In this section we present sample use cases to illustrate the challenge being addressed.

Consider, for the sake of illustration, an FE table with 1 million reasonably sized table rows which are sparsely populated. Assume, again for the sake of illustration, that there are 2000 table rows sparsely populated between the row indices 23-10023. ForCES GET and DEL requests sent from a controller (or control app) are prepended with a path to a component and sent to the FE. In the case of indexed tables, the component path can either be to a table or a table row index. The approaches for retrieving or deleting a sizeable number of table rows is at the programmatically level (from an application point of view) unfriendly, tedious, and abusive of both compute and bandwidth resources. As an example, a control application attempting to retrieve the first 2000 table rows appearing between row indices 23 and 10023 can achieve its goal in one of: Dump the whole table and filter for the needed 2000 table rows. Send upto 10000 ForCES PL requests with monotonically incrementing indices and stop when the needed 2000 entries are retrieved. If the application had knowledge of which table rows existed (not unreasonable given the controller is supposed to be aware of state within an NE), then the application could take advantage of ForCES batching to send fewer large messages (each with different path entries for a total of two thousand). As argued, while the above options exist - all are tedious.

has defined a generic set of error codes that are to be returned to the CE from an FE. Deployment experience has shown that it would be useful to have more fine grained error codes. As an example, the error code E_NOT_SUPPORTED could be mapped to many FE error source possibilities that need to be then interpreted by the caller based on some understanding of the nature of the sent request. This makes debugging more time consuming.

This section describes proposals to update the protocol for issues discussed in

We propose to add a Table-range TLV (type ID 0x117) that will be associated with the PATH-DATA TLV in the same manner the KEYINFO-TLV is.

shows how this new TLV is constructed.

illustrates a GET request for a range of rows 11 to 23 of a table with component path of "1/6". Path flag of F_SELTABRANGE (0x2 i.e bit 1, where bit 0 is F_SELKEY as defined in RFC 5810) is set to indicate the presence of the TABLERANGE-TLV. The pathflag bit F_SELTABRANGE can only be used in a GET or DEL and is mutually exclusive with F_SELKEY. The FE MUST enforce those constraints and reject a request with an error code of E_INVALID_TFLAGS with a description of what the problem is (refer to ). The TABLERANGE-TLV contents constitute: A 32 bit start index. An index of 0 implies the beggining of the table row. A 32 bit end index. A value of 0xFFFFFFFFFFFFFFFF implies the last entry. The response for a table range query will either be: The requested table data returned (when at least one referenced row is available); in such a case, a response with a path pointing to the table and whose data content contain the row(s) will be sent to the CE. The data content MUST be encapsulated in sparsedata TLV. The sparse data TLV content will have the "I" (in ILV) for each table row indicating the table indices. An EXTENDEDRESULT-TLV (refer to ) when: Response is to a range delete request. The Result will either be: A success if any of the requested-for rows is deleted A proper error code if none of the requested for rows can be deleted data is absent where the result code of E_EMPTY with an optional content string describing the nature of the error (refer to ). When both a path key and path table range are reflected on the the pathflags, an error code of E_INVALID_TFLAGS with an optional content string describing the nature of the error (refer to ). other standard ForCES errors (such as ACL constraints trying to retrieve contents of an unreadable table), accessing unknown components etc.

We propose several things: A new set of error codes. Allocating currently reserved codes for vendor use. A new TLV, EXTENDEDRESULT-TLV (0x118) that will carry a code (which will be a superset of what is currently specified in RFC 5812) but also an optional cause content. This is illustrated in .

EXTENDEDRESULT-TLV Result Value is 32 bits and is a superset of RFC 5810 Result TLV Result Value. The new version code space is 32 bits as opposed to the RFC 5810 code size of 8 bits. Code Mnemonic Details 0x100 E_EMPTYTable is empty 0x101 E_INVALID_TFLAGSInvalid table flags 0x102 E_INVALID_OPRequested operation is invalid 0x103 E_CONGEST_NTNode Congestion notification 0x104 E_COMPONENT_NOT_A_TABLEComponent not a table 0x105 E_PERMOperation not permitted 0x107 E_BUSYSystem is Busy 0x108 E_TIMED_OUTA time out occured while processing the message 0x106 E_UNKNOWNA generic catch all error code. Carries a string to further extrapolate what the error implies.

Codes 0x18-0xFE are reserved for use as vendor codes. Since these are freely available it is expected that the FE and CE side will both understand/interpret the semantics of any used codes.

Like all other ForCES TLVs, the EXTENDEDRESULT-TLV is expected to be 32 bit aligned. The Result Value derives and extends from the same current namespace as specified in RFC 5810, section 7.1.7. The main difference is that we now have 32 bit result value (as opposed to the old 8 bit). The optional result content is defined to further disambiguate the result value. It is expected Utf-8 values to be used. However, vendor specific error codes may choose to specify different contents. Additionally, future codes may specify cause contents to be of types other than string.. It is recommended that the maximum size of the cause string should not exceed 32 bytes. We do not propose the cause string be standardized. XXX: Backward compatibility may require that we add a FEPO capability to advertise ability to do extended results so that the CE is able to interpret the results and a FEPO compatibility flag to define what TLV setting would be used. Alternatively, the backward compatibility can be made a configuration option (which helps reduce clutter on FEPO LFB given that it is expected that in the future it makes sense for implementations to support only EXTENDEDRESULT-TLVs).

Imagine a GET request to a path that is a table i.e a table dump. Such a request is sent to the FE with a specific correlator, say X. Imagine this table to have a large number of entries at the FE. For the sake of illustration, lets say millions of rows. This requires that the FE delivers the response over multiple messages, all using the same correlator X. RFC 5810 does not describe how a GET response is to indicate "I have more messages coming for this correlator". Implementation experience indicates we can use the transaction flags to indicate that a GET response is the beginning, middle or end of a multi-part message. In other words we mirror the effect of an atomic transaction sent by a CE to an FE. XXX: Add in the next update diagram and details of how this takes place.

TBA

This document registers two new top Level TLVs and two new path flags. The following new TLVs are defined: TABLERANGE-TLV (type ID 0x117) EXTENDEDRESULT-TLV (type ID 0x118) The following new path flags are defined: F_SELTABRANGE (value 0x2 i.e bit 1) The Defined Result Values are changed: codes 0x18-0xFE are reserved for vendor use. codes 0x100-102 are defined by this document.

TBD