5. TML Requirements The requirements below are expected to be met by the TML. This text does not define how such mechanisms are delivered. As an example, the mechanisms to meet the requirements could be defined to be delivered via hardware or between 2 or more TML software processes on different CEs or FEs in protocol-level schemes. Each TML MUST describe how it contributes to achieving the listed ForCES requirements. If for any reason a TML does not provide a service listed below, a justification needs to be provided. Implementations that support the ForCES protocol specification MUST implement [RFC5811]. Note that additional TMLs might be specified in the future, and if a new TML defined in the future that meets the requirements listed here proves to be better, then the "MUST implement TML" may be redefined. 1. Reliability Various ForCES messages will require varying degrees of reliable delivery via the TML. It is the TML's responsibility to provide these shades of reliability and describe how the different ForCES messages map to reliability. The most common level of reliability is what we refer to as strict or robust reliability in which we mean no losses, corruption, or re-ordering of information being transported while ensuring message delivery in a timely fashion. Payloads such as configuration from a CE and its response from an FE are mission critical and must be delivered in a robust reliable fashion. Thus, for information of this sort, the TML MUST either provide built-in protocol mechanisms or use a reliable transport protocol for achieving robust/strict reliability.
Some information or payloads, such as redirected packets or packet sampling, may not require robust reliability (can tolerate some degree of losses). For information of this sort, the TML could define to use a mechanism that is not strictly reliable (while conforming to other TML requirements such as congestion control). Some information or payloads, such as heartbeat packets, may prefer timeliness over reliable delivery. For information of this sort, the TML could define to use a mechanism that is not strictly reliable (while conforming to other TML requirements such as congestion control). 2. Security TML provides security services to the ForCES PL. Because a ForCES PL is used to operate an NE, attacks designed to confuse, disable, or take information from a ForCES-based NE may be seen as a prime objective during a network attack. An attacker in a position to inject false messages into a PL stream can affect either the FE's treatment of the data path (for example, by falsifying control data reported as coming from the CE) or the CE itself (by modifying events or responses reported as coming from the FE). For this reason, CE and FE node authentication and TML message authentication are important. The PL messages may also contain information of value to an attacker, including information about the configuration of the network, encryption keys, and other sensitive control data, so care must be taken to confine their visibility to authorized users. * The TML MUST provide a mechanism to authenticate ForCES CEs and FEs, in order to prevent the participation of unauthorized CEs and unauthorized FEs in the control and data path processing of a ForCES NE. * The TML SHOULD provide a mechanism to ensure message authentication of PL data transferred from the CE to FE (and vice versa), in order to prevent the injection of incorrect data into PL messages. * The TML SHOULD provide a mechanism to ensure the confidentiality of data transferred from the ForCES PL, in order to prevent disclosure of PL-level information transported via the TML.
The TML SHOULD provide these services by employing TLS or IPsec. 3. Congestion control The transport congestion control scheme used by the TML needs to be defined. The congestion control mechanism defined by the TML MUST prevent transport congestive collapse [RFC2914] on either the FE or CE side. 4. Uni/multi/broadcast addressing/delivery, if any If there is any mapping between PL- and TML-level uni/multi/ broadcast addressing, it needs to be defined. 5. HA decisions It is expected that availability of transport links is the TML's responsibility. However, based upon its configuration, the PL may wish to participate in link failover schemes and therefore the TML MUST support this capability. Please refer to Section 8 for details. 6. Encapsulations used Different types of TMLs will encapsulate the PL messages on different types of headers. The TML needs to specify the encapsulation used. 7. Prioritization It is expected that the TML will be able to handle up to 8 priority levels needed by the PL and will provide preferential treatment. While the TML needs to define how this is achieved, it should be noted that the requirement for supporting up to 8 priority levels does not mean that the underlying TML MUST be capable of providing up to 8 actual priority levels. In the event that the underlying TML layer does not have support for 8 priority levels, the supported priority levels should be divided between the available TML priority levels. For example, if the TML only supports 2 priority levels, 0-3 could go in one TML priority level, while 4-7 could go in the other. The TML MUST NOT re-order config packets with the same priority.
8. Node Overload Prevention The TML MUST define mechanisms it uses to help prevent node overload. Overload results in starvation of node compute cycles and/or bandwidth resources, which reduces the operational capacity of a ForCES NE. NE node overload could be deliberately instigated by a hostile node to attack a ForCES NE and create a denial of service (DoS). It could also be created by a variety of other reasons such as large control protocol updates (e.g., BGP flaps), which consequently cause a high frequency of CE to FE table updates, HA failovers, or component failures, which migrate an FE or CE load overwhelming the new CE or FE, etc. Although the environments under which SIP and ForCES operate are different, [RFC5390] provides a good guide to generic node requirements one needs to guard for. A ForCES node CPU may be overwhelmed because the incoming packet rate is higher than it can keep up with -- in such a case, a node's transport queues grow and transport congestion subsequently follows. A ForCES node CPU may also be adversely overloaded with very few packets, i.e., no transport congestion at all (e.g., a in a DoS attack against a table hashing algorithm that overflows the table and/or keeps the CPU busy so it does not process other tasks). The TML node overload solution specified MUST address both types of node overload scenarios. 5.1. TML Parameterization It is expected that it should be possible to use a configuration reference point, such as the FEM or the CEM, to configure the TML. Some of the configured parameters may include: o PL ID o Connection Type and associated data. For example, if a TML uses IP/TCP/UDP, then parameters such as TCP and UDP port and IP addresses need to be configured. o Number of transport connections o Connection capability, such as bandwidth, etc. o Allowed/supported connection QoS policy (or congestion control policy)
6. Message Encapsulation All PL PDUs start with a common header Section 6.1 followed by one or more TLVs Section 6.2, which may nest other TLVs Section 6.2.1. All fields are in network byte order. 6.1. Common Header 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |version| rsvd | Message Type | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Destination ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Correlator[63:32] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Correlator[31:0] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Flags | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 10: Common Header The message is 32-bit aligned. Version (4 bits): Version number. Current version is 1. rsvd (4 bits): Unused at this point. A receiver should not interpret this field. Senders MUST set it to zero and receivers MUST ignore this field. Message Type (8 bits): Commands are defined in Section 7. Length (16 bits): length of header + the rest of the message in DWORDS (4-byte increments). Source ID (32 bits):
Dest ID (32 bits): * Each of the source and destination IDs are 32-bit IDs that are unique NE-wide and that identify the termination points of a ForCES PL message. * IDs allow multi/broad/unicast addressing with the following approach: a. A split address space is used to distinguish FEs from CEs. Even though in a large NE there are typically two or more orders of magnitude of more FEs than CEs, the address space is split uniformly for simplicity. b. The address space allows up to 2^30 (over a billion) CEs and the same amount of FEs. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |TS | sub-ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 11: ForCES ID Format c. The 2 most significant bits called Type Switch (TS) are used to split the ID space as follows: TS Corresponding ID range Assignment -- ---------------------- ---------- 0b00 0x00000000 to 0x3FFFFFFF FE IDs (2^30) 0b01 0x40000000 to 0x7FFFFFFF CE IDs (2^30) 0b10 0x80000000 to 0xBFFFFFFF reserved 0b11 0xC0000000 to 0xFFFFFFEF multicast IDs (2^30 - 16) 0b11 0xFFFFFFF0 to 0xFFFFFFFC reserved 0b11 0xFFFFFFFD all CEs broadcast 0b11 0xFFFFFFFE all FEs broadcast 0b11 0xFFFFFFFF all FEs and CEs (NE) broadcast Figure 12: Type Switch ID Space * Multicast or broadcast IDs are used to group endpoints (such as CEs and FEs). As an example, one could group FEs in some functional group, by assigning a multicast ID. Likewise, subgroups of CEs that act, for instance, in a back-up mode may be assigned a multicast ID to hide them from the FE.
+ Multicast IDs can be used for both source or destination IDs. + Broadcast IDs can be used only for destination IDs. * This document does not discuss how a particular multicast ID is associated to a given group though it could be done via configuration process. The list of IDs an FE owns or is part of are listed on the FE Object LFB. Correlator (64 bits): This field is set by the CE to correlate ForCES Request messages with the corresponding Response messages from the FE. Essentially, it is a cookie. The correlator is handled transparently by the FE, i.e., for a particular Request message the FE MUST assign the same correlator value in the corresponding Response message. In the case where the message from the CE does not elicit a response, this field may not be useful. The correlator field could be used in many implementations in specific ways by the CE. For example, the CE could split the correlator into a 32-bit transactional identifier and 32-bit message sequence identifier. Another example is a 64-bit pointer to a context block. All such implementation-specific uses of the correlator are outside the scope of this specification. It should be noted that the correlator is transmitted on the network as if it were a 64-bit unsigned integer with the leftmost or most significant octet (bits 63-56) transmitted first. Whenever the correlator field is not relevant, because no message is expected, the correlator field is set to 0. Flags (32 bits): Identified so far: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | | | | | | |ACK| Pri |Rsr |EM |A|TP | Reserved | | | | vd. | |T| | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 13: Header Flags - ACK: ACK indicator (2 bits)
The ACK indicator flag is only used by the CE when sending a Config message (Section 7.6.1) or an HB message (Section 7.10) to indicate to the message receiver whether or not a response is required by the sender. Note that for all other messages than the Config message or the HB message this flag MUST be ignored. The flag values are defined as follows: 'NoACK' (0b00) - to indicate that the message receiver MUST NOT send any Response message back to this message sender. 'SuccessACK'(0b01) - to indicate that the message receiver MUST send a Response message back only when the message has been successfully processed by the receiver. 'FailureACK'(0b10) - to indicate that the message receiver MUST send a Response message back only when there is failure by the receiver in processing (executing) the message. In other words, if the message can be processed successfully, the sender will not expect any response from the receiver. 'AlwaysACK' (0b11) - to indicate that the message receiver MUST send a Response message. Note that in above definitions, the term success implies a complete execution without any failure of the message. Anything else than a complete successful execution is defined as a failure for the message processing. As a result, for the execution modes (defined in Section 18.104.22.168) like execute-all-or-none, execute-until-failure, and continue-execute-on-failure, if any single operation among several operations in the same message fails, it will be treated as a failure and result in a response if the ACK indicator has been set to 'FailureACK' or 'AlwaysACK'. Also note that, other than in Config and HB messages, requirements for responses of messages are all given in a default way rather than by ACK flags. The default requirements of these messages and the expected responses are summarized below. Detailed descriptions can be found in the individual message definitions: + Association Setup message always expects a response. + Association Teardown Message, and Packet Redirect message, never expect responses. + Query message always expects a response. + Response message never expects further responses.
- Pri: Priority (3 bits) ForCES protocol defines 8 different levels of priority (0-7). The priority level can be used to distinguish between different protocol message types as well as between the same message type. The higher the priority value, the more important the PDU is. For example, the REDIRECT packet message could have different priorities to distinguish between routing protocol packets and ARP packets being redirected from FE to CE. The normal priority level is 1. The different priorities imply messages could be re-ordered; however, re-ordering is undesirable when it comes to a set of messages within a transaction and caution should be exercised to avoid this. - EM: Execution Mode (2 bits) There are 3 execution modes; refer to Section 22.214.171.124 for details. Reserved..................... (0b00) `execute-all-or-none` ....... (0b01) `execute-until-failure` ..... (0b10) `continue-execute-on-failure` (0b11) - AT: Atomic Transaction (1 bit) This flag indicates if the message is a stand-alone message or one of multiple messages that belong to 2PC transaction operations. See Section 126.96.36.199.2 for details. Stand-alone message ......... (0b0) 2PC transaction message ..... (0b1) - TP: Transaction Phase (2 bits) A message from the CE to the FE within a transaction could be indicative of the different phases the transaction is in. Refer to Section 188.8.131.52.2 for details. SOT (start of transaction) ..... (0b00) MOT (middle of transaction) .... (0b01) EOT (end of transaction) ........(0b10) ABT (abort) .....................(0b11)
6.2. Type Length Value (TLV) Structuring TLVs are extensively used by the ForCES protocol. TLVs have some very nice properties that make them a good candidate for encoding the XML definitions of the LFB class model. These are: o Providing for binary type-value encoding that is close to the XML string tag-value scheme. o Allowing for fast generalized binary-parsing functions. o Allowing for forward and backward tag compatibility. This is equivalent to the XML approach, i.e., old applications can ignore new TLVs and newer applications can ignore older TLVs. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | TLV Type | TLV Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value (Essentially the TLV Data) | ~ ~ ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 14: TLV Representation TLV Type (16): The TLV type field is 2 octets, and semantically indicates the type of data encapsulated within the TLV. TLV Length (16): The TLV length field is 2 octets, and includes the length of the TLV type (2 octets), TLV Length (2 octets), and the length of the TLV data found in the value field, in octets. Note that this length is the actual length of the value, before any padding for alignment is added. TLV Value (variable): The TLV value field carries the data. For extensibility, the TLV value may in fact be a TLV. Padding is required when the length is not a multiple of 32 bits, and is the minimum number of octets required to bring the TLV to a multiple of 32 bits. The length of the value before padding is indicated by the TLV Length field.
Note: The value field could be empty, which implies the minimal length a TLV could be is 4 (length of "T" field and length of "L" field). 6.2.1. Nested TLVs TLV values can be other TLVs. This provides the benefits of protocol flexibility (being able to add new extensions by introducing new TLVs when needed). The nesting feature also allows for a conceptual optimization with the XML LFB definitions to binary PL representation (represented by nested TLVs). 6.2.2. Scope of the T in TLV There are two global name scopes for the "Type" in the TLV. The first name scope is for OPER-TLVs and is defined in A.4 whereas the second name scope is outside OPER-TLVs and is defined in section A.2. 6.3. ILV The ILV is a slight variation of the TLV. This sets the type ("T") to be a 32-bit local index that refers to a ForCES component ID (refer to Section 6.4.1). The ILV length field is a 4-octet integer, and includes the length of the ILV type (4 octets), ILV Length (4 octets), and the length of the ILV data found in the value field, in octets. Note that, as in the case of the TLV, this length is the actual length of the value, before any padding for alignment is added. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identifier | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value | . . +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 15: ILV Representation It should be noted that the "I" values are of local scope and are defined by the data declarations from the LFB definition. Refer to Section 7.1.8 for discussions on usage of ILVs.
6.4. Important Protocol Encapsulations In this section, we review a few encapsulation concepts that are used by the ForCES protocol for its operations. We briefly re-introduce two concepts, paths, and keys, from the ForCES model [RFC5812] in order to provide context. The reader is referred to [RFC5812] for a lot of the finer details. For readability reasons, we introduce the encapsulation schemes that are used to carry content in a protocol message, namely, FULLDATA- TLV, SPARSEDATA-TLV, and RESULT-TLV. 6.4.1. Paths The ForCES model [RFC5812] defines an XML-based language that allows for a formal definition of LFBs. This is similar to the relationship between ASN.1 and SNMP MIB definition (MIB being analogous to the LFB and ASN.1 being analogous to the XML model language). Any entity that the CE configures on an FE MUST be formally defined in an LFB. These entities could be scalars (e.g., a 32-bit IPv4 address) or vectors (such as a nexthop table). Each entity within the LFB is given a numeric 32-bit identifier known as a "component id". This scheme allows the component to be "addressed" in a protocol construct. These addressable entities could be hierarchical (e.g., a table column or a cell within a table row). In order to address hierarchical data, the concept of a path is introduced by the model [RFC5812]. A path is a series of 32-bit component IDs that are typically presented in a dot-notation (e.g., 184.108.40.206). Section 7 formally defines how paths are used to reference data that is being encapsulated within a protocol message. 6.4.2. Keys The ForCES model [RFC5812] defines two ways to address table rows. The standard/common mechanism is to allow table rows to be referenced by a 32-bit index. The secondary mechanism is via keys that allow for content addressing. An example key is a multi-field content key that uses the IP address and prefix length to uniquely reference an IPv4 routing table row. In essence, while the common scheme to address a table row is via its table index, a table row's path could be derived from a key. The KEYINFO-TLV (Section 7) is used to carry the data that is used to do the lookup.
6.4.3. DATA TLVs Data from or to the FE is carried in two types of TLVs: FULLDATA-TLV and SPARSEDATA-TLV. Responses to operations executed by the FE are carried in RESULT-TLVs. In FULLDATA-TLV, the data is encoded in such a way that a receiver of such data, by virtue of being armed with knowledge of the path and the LFB definition, can infer or correlate the TLV "Value" contents. This is essentially an optimization that helps reduce the amount of description required for the transported data in the protocol grammar. Refer to Appendix C for an example of FULLDATA-TLVs. A number of operations in ForCES will need to reference optional data within larger structures. The SPARSEDATA-TLV encoding is provided to make it easier to encapsulate optionally appearing data components. Refer to Appendix C for an example of SPARSEDATA-TLV. RESULT-TLVs carry responses back from the FE based on a config issued by the CE. Refer to Appendix C for examples of RESULT-TLVs and Section 7.1.7 for layout. 6.4.4. Addressing LFB Entities Section 6.4.1 and Section 6.4.2 discuss how to target an entity within an LFB. However, the addressing mechanism used requires that an LFB type and instance are selected first. The LFB selector is used to select an LFB type and instance being targeted. Section 7 goes into more details; for our purpose, we illustrate this concept using Figure 16 below. More examples of layouts can be found reading further into the text (example: Figure 22).
main hdr (Message type: example "config") | | | +- T = LFBselect | +-- LFBCLASSID (unique per LFB defined) | | +-- LFBInstance (runtime configuration) | +-- T = An operation TLV describes what we do to an entity | //Refer to the OPER-TLV values enumerated below | //the TLVs that can be used for operations | | +--+-- one or more path encodings to target an entity | // Refer to the discussion on keys and paths | | +-- The associated data, if any, for the entity // Refer to discussion on FULL/SPARSE DATA TLVs Figure 16: Entity Addressing 7. Protocol Construction A protocol layer PDU consists of a common header (defined in Section 6.1 ) and a message body. The common header is followed by a message-type-specific message body. Each message body is formed from one or more top-level TLVs. A top-level TLV may contain one or more sub-TLVs; these sub-TLVs are described in this document as OPER-TLVs, because they describe an operation to be done.
+-------------+---------------+---------------------+---------------+ | Message | Top-Level TLV | OPER-TLV(s) | Reference | | Name | | | | +-------------+---------------+---------------------+---------------+ | Association | (LFBselect)* | REPORT | Section 7.5.1 | | Setup | | | | | Association | ASRresult-TLV | none | Section 7.5.2 | | Setup | | | | | Response | | | | | Association | ASTreason-TLV | none | Section 7.5.3 | | Teardown | | | | | Config | (LFBselect)+ | (SET | SET-PROP | | Section 7.6.1 | | | | DEL | COMMIT | | | | | | TRCOMP)+ | | | Config | (LFBselect)+ | (SET-RESPONSE | | Section 7.6.2 | | Response | | SET-PROP-RESPONSE | | | | | | DEL-RESPONSE | | | | | | COMMIT-RESPONSE)+ | | | Query | (LFBselect)+ | (GET | GET-PROP)+ | Section 7.7.1 | | Query | (LFBselect)+ | (GET-RESPONSE | | Section 7.7.2 | | Response | | GET-PROP-RESPONSE)+ | | | Event | LFBselect | REPORT | Section 7.8 | | Notifi- | | | | | cation | | | | | Packet | REDIRECT-TLV | none | Section 7.9 | | Redirect | | | | | Heartbeat | none | none | Section 7.10 | +-------------+---------------+---------------------+---------------+ Table 1 The different messages are illustrated in Table 1. The different message type numerical values are defined in Appendix A.1. All the TLV values are defined in Appendix A.2. An LFBselect TLV (refer to Section 7.1.5) contains the LFB Classid and LFB instance being referenced as well as the OPER-TLV(s) being applied to that reference. Each type of OPER-TLV is constrained as to how it describes the paths and selectors of interest. The following BNF describes the basic structure of an OPER-TLV and Table 2 gives the details for each type.
OPER-TLV := 1*PATH-DATA-TLV PATH-DATA-TLV := PATH [DATA] PATH := flags IDcount IDs [SELECTOR] SELECTOR := KEYINFO-TLV DATA := FULLDATA-TLV / SPARSEDATA-TLV / RESULT-TLV / 1*PATH-DATA-TLV KEYINFO-TLV := KeyID FULLDATA-TLV FULLDATA-TLV := encoded data component which may nest further FULLDATA-TLVs SPARSEDATA-TLV := encoded data that may have optionally appearing components RESULT-TLV := Holds result code and optional FULLDATA-TLV Figure 17: BNF of OPER-TLV o PATH-DATA-TLV identifies the exact component targeted and may have zero or more paths associated with it. The last PATH-DATA-TLV in the case of nesting of paths via the DATA construct in the case of SET, SET-PROP requests, and GET-RESPONSE/GET-PROP-RESPONSE is terminated by encoded data or response in the form of either FULLDATA-TLV or SPARSEDATA-TLV or RESULT-TLV. o PATH provides the path to the data being referenced. * flags (16 bits) are used to further refine the operation to be applied on the path. More on these later. * IDcount (16 bits): count of 32-bit IDs * IDs: zero or more 32-bit IDs (whose count is given by IDcount) defining the main path. Depending on the flags, IDs could be field IDs only or a mix of field and dynamic IDs. Zero is used for the special case of using the entirety of the containing context as the result of the path. o SELECTOR is an optional construct that further defines the PATH. Currently, the only defined selector is the KEYINFO-TLV, used for selecting an array entry by the value of a key field. The presence of a SELECTOR is correct only when the flags also indicate its presence. o A KEYINFO-TLV contains information used in content keying. * A 32-bit KeyID is used in a KEYINFO-TLV. It indicates which key for the current array is being used as the content key for array entry selection.
* The key's data is the data to look for in the array, in the fields identified by the key field. The information is encoded according to the rules for the contents of a FULLDATA-TLV, and represents the field or fields that make up the key identified by the KeyID. o DATA may contain a FULLDATA-TLV, SPARSEDATA-TLV, a RESULT-TLV, or 1 or more further PATH-DATA selections. FULLDATA-TLV and SPARSEDATA-TLV are only allowed on SET or SET-PROP requests, or on responses that return content information (GET-RESPONSE, for example). PATH-DATA may be included to extend the path on any request. * Note: Nested PATH-DATA-TLVs are supported as an efficiency measure to permit common subexpression extraction. * FULLDATA-TLV and SPARSEDATA-TLV contain "the data" whose path has been selected by the PATH. Refer to Section 7.1 for details. * The following table summarizes the applicability and restrictions of the FULL/SPARSEDATA-TLVs and the RESULT-TLV to the OPER-TLVs. +-------------------+-------------------------------+---------------+ | OPER-TLV | DATA TLV | RESULT-TLV | +-------------------+-------------------------------+---------------+ | SET | | none | | SET-PROP | (FULLDATA-TLV | | none | | | SPARSEDATA-TLV)+ | | | SET-RESPONSE | none | (RESULT-TLV)+ | | SET-PROP-RESPONSE | none | (RESULT-TLV)+ | | DEL | | none | | DEL-RESPONSE | none | (RESULT-TLV)+ | | GET | none | none | | GET-PROP | none | none | | GET-RESPONSE | (FULLDATA-TLV)+ | (RESULT-TLV)* | | GET-PROP-RESPONSE | (FULLDATA-TLV)+ | (RESULT-TLV)* | | REPORT | (FULLDATA-TLV)+ | none | | COMMIT | none | none | | COMMIT-RESPONSE | none | (RESULT-TLV)+ | | TRCOMP | none | none | +-------------------+-------------------------------+---------------+ Table 2
o RESULT-TLV contains the indication of whether the individual SET or SET-PROP succeeded. RESULT-TLV is included on the assumption that individual parts of a SET request can succeed or fail separately. In summary, this approach has the following characteristics: o There can be one or more LFB class ID and instance ID combinations targeted in a message (batch). o There can one or more operations on an addressed LFB class ID/ instance ID combination (batch). o There can be one or more path targets per operation (batch). o Paths may have zero or more data values associated (flexibility and operation specific). It should be noted that the above is optimized for the case of a single LFB class ID and instance ID targeting. To target multiple instances within the same class, multiple LFBselects are needed. 7.1. Discussion on Encoding Section 6.4.3 discusses the two types of DATA encodings (FULLDATA-TLV and SPARSEDATA-TLV) and the justifications for their existence. In this section, we explain how they are encoded. 7.1.1. Data Packing Rules The scheme for encoding data used in this document adheres to the following rules: o The Value ("V" of TLV) of FULLDATA-TLV will contain the data being transported. This data will be as was described in the LFB definition. o Variable-sized data within a FULLDATA-TLV will be encapsulated inside another FULLDATA-TLV inside the V of the outer TLV. For an example of such a setup, refer to Appendices C and D. o In the case of FULLDATA-TLVs: * When a table is referred to in the PATH (IDs) of a PATH-DATA- TLV, then the FULLDATA-TLV's "V" will contain that table's row content prefixed by its 32-bit index/subscript. On the other
hand, the PATH may contain an index pointing to a row in table; in such a case, the FULLDATA-TLV's "V" will only contain the content with the index in order to avoid ambiguity. 7.1.2. Path Flags Only bit 0, the SELECTOR Bit, is currently used in the path flags as illustrated in Figure 18. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | |S| Reserved | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 18: Path Flags The semantics of the flag are defined as follows: o SELECTOR Bit: F_SELKEY(set to 1) indicates that a KEY Selector is present following this path information, and should be considered in evaluating the path content. 7.1.3. Relation of Operational Flags with Global Message Flags Global flags, such as the execution mode and the atomicity indicators defined in the header, apply to all operations in a message. Global flags provide semantics that are orthogonal to those provided by the operational flags, such as the flags defined in path-data. The scope of operational flags is restricted to the operation. 7.1.4. Content Path Selection The KEYINFO-TLV describes the KEY as well as associated KEY data. KEYs, used for content searches, are restricted and described in the LFB definition. 7.1.5. LFBselect-TLV The LFBselect TLV is an instance of a TLV as defined in Section 6.2. The definition is as follows:
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = LFBselect | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | LFB Class ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | LFB Instance ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | OPER-TLV | . . +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ... ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | OPER-TLV | . . +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 19: PL PDU Layout Type: The type of the TLV is "LFBselect" Length: Length of the TLV including the T and L fields, in octets. LFB Class ID: This field uniquely recognizes the LFB class/type. LFB Instance ID: This field uniquely identifies the LFB instance. OPER-TLV: It describes an operation nested in the LFBselect TLV. Note that usually there SHOULD be at least one OPER-TLV present for an LFB select TLV. 7.1.6. OPER-TLV The OPER-TLV is a place holder in the grammar for TLVs that define operations. The different types are defined in Table 3, below.
+-------------------+--------+--------------------------------------+ | OPER-TLV | TLV | Comments | | | "Type" | | +-------------------+--------+--------------------------------------+ | SET | 0x0001 | From CE to FE. Used to create or | | | | add or update components | | SET-PROP | 0x0002 | From CE to FE. Used to create or | | | | add or update component properties | | SET-RESPONSE | 0x0003 | From FE to CE. Used to carry | | | | response of a SET | | SET-PROP-RESPONSE | 0x0004 | From FE to CE. Used to carry | | | | response of a SET-PROP | | DEL | 0x0005 | From CE to FE. Used to delete or | | | | remove an component | | DEL-RESPONSE | 0x0006 | From FE to CE. Used to carry | | | | response of a DEL | | GET | 0x0007 | From CE to FE. Used to retrieve an | | | | component | | GET-PROP | 0x0008 | From CE to FE. Used to retrieve an | | | | component property | | GET-RESPONSE | 0x0009 | From FE to CE. Used to carry | | | | response of a GET | | GET-PROP-RESPONSE | 0x000A | From FE to CE. Used to carry | | | | response of a GET-PROP | | REPORT | 0x000B | From FE to CE. Used to carry an | | | | asynchronous event | | COMMIT | 0x000C | From CE to FE. Used to issue a | | | | commit in a 2PC transaction | | COMMIT-RESPONSE | 0x000D | From FE to CE. Used to confirm a | | | | commit in a 2PC transaction | | TRCOMP | 0x000E | From CE to FE. Used to indicate | | | | NE-wide success of 2PC transaction | +-------------------+--------+--------------------------------------+ Table 3 Different messages use OPER-TLV and define how they are used (refer to Table 1 and Table 2). SET, SET-PROP, and GET/GET-PROP requests are issued by the CE and do not carry RESULT-TLVs. On the other hand, SET-RESPONSE, SET-PROP- RESPONSE, and GET-RESPONSE/GET-PROP-RESPONSE carry RESULT-TLVs. A GET-RESPONSE in response to a successful GET will have FULLDATA- TLVs added to the leaf paths to carry the requested data. For GET operations that fail, instead of the FULLDATA-TLV there will be a RESULT-TLV.
For a SET-RESPONSE/SET-PROP-RESPONSE, each FULLDATA-TLV or SPARSEDATA-TLV in the original request will be replaced with a RESULT-TLV in the response. If the request set the FailureACK flag, then only those items that failed will appear in the response. If the request was for AlwaysACK, then all components of the request will appear in the response with RESULT-TLVs. Note that if a SET/SET-PROP request with a structure in a FULLDATA- TLV is issued, and some field in the structure is invalid, the FE will not attempt to indicate which field was invalid, but rather will indicate that the operation failed. Note further that if there are multiple errors in a single leaf PATH-DATA/FULLDATA-TLB, the FE can select which error it chooses to return. So if a FULLDATA-TLV for a SET/SET-PROP of a structure attempts to write one field that is read only, and attempts to set another field to an invalid value, the FE can return indication of either error. A SET/SET-PROP operation on a variable-length component with a length of 0 for the item is not the same as deleting it. If the CE wishes to delete, then the DEL operation should be used whether the path refers to an array component or an optional structure component. 7.1.7. RESULT TLV The RESULT-TLV is an instance of TLV defined in Section 6.2. The definition is as follows: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = RESULT-TLV | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Result Value | Reserved | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 20: RESULT-TLV
Defined Result Values +-----------------------------+-----------+-------------------------+ | Result Value | Value | Definition | +-----------------------------+-----------+-------------------------+ | E_SUCCESS | 0x00 | Success | | E_INVALID_HEADER | 0x01 | Unspecified error with | | | | header. | | E_LENGTH_MISMATCH | 0x02 | Header length field | | | | does not match actual | | | | packet length. | | E_VERSION_MISMATCH | 0x03 | Unresolvable mismatch | | | | in versions. | | E_INVALID_DESTINATION_PID | 0x04 | Destination PID is | | | | invalid for the message | | | | receiver. | | E_LFB_UNKNOWN | 0x05 | LFB Class ID is not | | | | known by receiver. | | E_LFB_NOT_FOUND | 0x06 | LFB Class ID is known | | | | by receiver but not | | | | currently in use. | | E_LFB_INSTANCE_ID_NOT_FOUND | 0x07 | LFB Class ID is known | | | | but the specified | | | | instance of that class | | | | does not exist. | | E_INVALID_PATH | 0x08 | The specified path is | | | | impossible. | | E_COMPONENT_DOES_NOT_EXIST | 0x09 | The specified path is | | | | possible but the | | | | component does not | | | | exist (e.g., attempt to | | | | modify a table row that | | | | has not been created). | | E_EXISTS | 0x0A | The specified object | | | | exists but it cannot | | | | exist for the operation | | | | to succeed (e.g., | | | | attempt to add an | | | | existing LFB instance | | | | or array subscript). | | E_NOT_FOUND | 0x0B | The specified object | | | | does not exist but it | | | | MUST exist for the | | | | operation to succeed | | | | (e.g., attempt to | | | | delete a non-existing | | | | LFB instance or array | | | | subscript). |
| E_READ_ONLY | 0x0C | Attempt to modify a | | | | read-only value. | | E_INVALID_ARRAY_CREATION | 0x0D | Attempt to create an | | | | array with an unallowed | | | | subscript. | | E_VALUE_OUT_OF_RANGE | 0x0E | Attempt to set a | | | | parameter to a value | | | | outside of its | | | | allowable range. | | E_CONTENTS_TOO_LONG | 0x0D | Attempt to write | | | | contents larger than | | | | the target object space | | | | (i.e., exceeding a | | | | buffer). | | E_INVALID_PARAMETERS | 0x10 | Any other error with | | | | data parameters. | | E_INVALID_MESSAGE_TYPE | 0x11 | Message type is not | | | | acceptable. | | E_INVALID_FLAGS | 0x12 | Message flags are not | | | | acceptable for the | | | | given message type. | | E_INVALID_TLV | 0x13 | A TLV is not acceptable | | | | for the given message | | | | type. | | E_EVENT_ERROR | 0x14 | Unspecified error while | | | | handling an event. | | E_NOT_SUPPORTED | 0x15 | Attempt to perform a | | | | valid ForCES operation | | | | that is unsupported by | | | | the message receiver. | | E_MEMORY_ERROR | 0x16 | A memory error occurred | | | | while processing a | | | | message (no error | | | | detected in the message | | | | itself). | | E_INTERNAL_ERROR | 0x17 | An unspecified error | | | | occurred while | | | | processing a message | | | | (no error detected in | | | | the message itself). | | - | 0x18-0xFE | Reserved | | E_UNSPECIFIED_ERROR | 0xFF | Unspecified error (for | | | | when the FE cannot | | | | decide what went | | | | wrong). | +-----------------------------+-----------+-------------------------+ Table 4
7.1.8. DATA TLV A FULLDATA-TLV has "T"= FULLDATA-TLV and a 16-bit length followed by the data value/contents. Likewise, a SPARSEDATA-TLV has "T" = SPARSEDATA-TLV, a 16-bit length, followed by the data value/contents. In the case of the SPARSEDATA-TLV, each component in the Value part of the TLV will be further encapsulated in an ILV. Below are the encoding rules for the FULLDATA-TLV and SPARSEDATA- TLVs. Appendix C is very useful in illustrating these rules: 1. Both ILVs and TLVs MUST be 32-bit aligned. Any padding bits used for the alignment MUST be zero on transmission and MUST be ignored upon reception. 2. FULLDATA-TLVs may be used at a particular path only if every component at that path level is present. In example 1(c) of Appendix C, this concept is illustrated by the presence of all components of the structure S in the FULLDATA-TLV encoding. This requirement holds regardless of whether the fields are fixed or variable length, mandatory or optional. * If a FULLDATA-TLV is used, the encoder MUST lay out data for each component in the same order in which the data was defined in the LFB specification. This ensures the decoder is able to retrieve the data. To use the example 1 again in Appendix C, this implies the encoder/decoder is assumed to have knowledge of how structure S is laid out in the definition. * In the case of a SPARSEDATA-TLV, it does not need to be ordered since the "I" in the ILV uniquely identifies the component. Examples 1(a) and 1(b) in Appendix C illustrate the power of SPARSEDATA-TLV encoding. 3. Inside a FULLDATA-TLV * The values for atomic, fixed-length fields are given without any TLV encapsulation. * The values for atomic, variable-length fields are given inside FULLDATA-TLVs. * The values for arrays are in the form of index/subscript, followed by value as stated in "Data Packing Rules" (Section 7.1.1) and demonstrated by the examples in the appendices.
4. Inside a SPARSEDATA-TLV * The values of all fields MUST be given with ILVs (32-bit index, 32-bit length). 5. FULLDATA-TLVs cannot contain an ILV. 6. A FULLDATA-TLV can also contain a FULLDATA-TLV for variable-sized components. The decoding disambiguation is assumed from rule #3 above. 7.1.9. SET and GET Relationship It is expected that a GET-RESPONSE would satisfy the following: o It would have exactly the same path definitions as those sent in the GET. The only difference is that a GET-RESPONSE will contain FULLDATA-TLVs. o It should be possible to take the same GET-RESPONSE and convert it to a SET successfully by merely changing the T in the operational TLV. o There are exceptions to this rule: 1. When a KEY selector is used with a path in a GET operation, that selector is not returned in the GET-RESPONSE; instead, the cooked result is returned. Refer to the examples using KEYS to see this. 2. When dumping a whole table in a GET, the GET-RESPONSE that merely edits the T to be SET will end up overwriting the table.