RFC 5810
Forwarding and Control Element Separation (ForCES) Protocol Specification
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 4.3.1.1) 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 4.3.1.1 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 4.3.1.2.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 4.3.1.2.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., 1.2.3.4). 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 Addressing7. 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.
(page 56 continued on part 4)
