RFC 5812
Forwarding and Control Element Separation (ForCES) Forwarding Element Model
Forwarding and Control Element Separation (ForCES) Forwarding Element Model 💖
okay bestie, this is RFC 5812, a Standards Track doc from the IETF 🌸 It was published in March 2010 and its ISSN is 2070-1721. The authors are J. Halpern (Self) and J. Hadi Salim (Znyx Networks) 🧚 It's an official IETF Standards Track document, so it's the real deal, no cap ✨
Abstract ✨
okay so this doc defines the forwarding element (FE) model used in the ForCES protocol 💅 The model describes the capabilities, state, and configuration of forwarding elements so that control elements (CEs) can control the FEs properly 🫶 It's giving organization. It lays out the logical functions inside an FE, what each function can do, and how those functions are or can be connected to each other 🔥 The whole point is to meet the model requirements set out in RFC 3654, so it's literally built to check RFC 3654's boxes 🎀
Status of This Memo 🦋
This is an Internet Standards Track document.
It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community 👑 It went through public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check out Section 2 of RFC 5741 📚
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc5812 🌈
Copyright Notice 💜
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please read these carefully, because they spell out your rights and restrictions for this doc 🙈 Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License.
Table of Contents 🍓
1. Introduction ....................................................5
1.1. Requirements on the FE Model ...............................5
1.2. The FE Model in Relation to FE Implementations .............6
1.3. The FE Model in Relation to the ForCES Protocol ............6
1.4. Modeling Language for the FE Model .........................7
1.5. Document Structure .........................................8
2. Definitions .....................................................8
3. ForCES Model Concepts ..........................................10
3.1. ForCES Capability Model and State Model ...................12
3.1.1. FE Capability Model and State Model ................12
3.1.2. Relating LFB and FE Capability and State Model .....14
3.2. Logical Functional Block (LFB) Modeling ...................14
3.2.1. LFB Outputs ........................................18
3.2.2. LFB Inputs .........................................21
3.2.3. Packet Type ........................................24
3.2.4. Metadata ...........................................24
3.2.5. LFB Events .........................................27
3.2.6. Component Properties ...............................28
3.2.7. LFB Versioning .....................................29
3.2.8. LFB Inheritance ....................................29
3.3. ForCES Model Addressing ...................................30
3.3.1. Addressing LFB Components: Paths and Keys ..........32
3.4. FE Data Path Modeling .....................................32
3.4.1. Alternative Approaches for Modeling FE Data Paths ..33
3.4.2. Configuring the LFB Topology .......................37
4. Model and Schema for LFB Classes ...............................41
4.1. Namespace .................................................42
4.2. <LFBLibrary> Element ......................................42
4.3. <load> Element ............................................44
4.4. <frameDefs> Element for Frame Type Declarations ...........45
4.5. <dataTypeDefs> Element for Data Type Definitions ..........45
4.5.1. <typeRef> Element for Renaming Existing
Data Types .........................................49
4.5.2. <atomic> Element for Deriving New Atomic Types .....49
4.5.3. <array> Element to Define Arrays ...................50
4.5.4. <struct> Element to Define Structures ..............54
4.5.5. <union> Element to Define Union Types ..............56
4.5.6. <alias> Element ....................................56
4.5.7. Augmentations ......................................57
4.6. <metadataDefs> Element for Metadata Definitions ...........58
4.7. <LFBClassDefs> Element for LFB Class Definitions ..........59
4.7.1. <derivedFrom> Element to Express LFB Inheritance ...62
4.7.2. <inputPorts> Element to Define LFB Inputs ..........62
4.7.3. <outputPorts> Element to Define LFB Outputs ........65
4.7.4. <components> Element to Define LFB
Operational Components .............................67
4.7.5. <capabilities> Element to Define LFB
Capability Components ..............................70
4.7.6. <events> Element for LFB Notification Generation ...71
4.7.7. <description> Element for LFB Operational
Specification ......................................79
4.8. Properties ................................................79
4.8.1. Basic Properties ...................................79
4.8.2. Array Properties ...................................81
4.8.3. String Properties ..................................81
4.8.4. Octetstring Properties .............................82
4.8.5. Event Properties ...................................83
4.8.6. Alias Properties ...................................87
4.9. XML Schema for LFB Class Library Documents ................88
5. FE Components and Capabilities .................................99
5.1. XML for FEObject Class Definition .........................99
5.2. FE Capabilities ..........................................106
5.2.1. ModifiableLFBTopology .............................106
5.2.2. SupportedLFBs and SupportedLFBType ................106
5.3. FE Components ............................................110
5.3.1. FEState ...........................................110
5.3.2. LFBSelectors and LFBSelectorType ..................110
5.3.3. LFBTopology and LFBLinkType .......................110
5.3.4. FENeighbors and FEConfiguredNeighborType ..........111
6. Satisfying the Requirements on the FE Model ...................111
7. Using the FE Model in the ForCES Protocol .....................112
7.1. FE Topology Query ........................................115
7.2. FE Capability Declarations ...............................116
7.3. LFB Topology and Topology Configurability Query ..........116
7.4. LFB Capability Declarations ..............................116
7.5. State Query of LFB Components ............................118
7.6. LFB Component Manipulation ...............................118
7.7. LFB Topology Reconfiguration .............................118
8. Example LFB Definition ........................................119
8.1. Data Handling ............................................126
8.1.1. Setting Up a DLCI .................................127
8.1.2. Error Handling ....................................127
8.2. LFB Components ...........................................128
8.3. Capabilities .............................................128
8.4. Events ...................................................129
9. IANA Considerations ...........................................130
9.1. URN Namespace Registration ...............................130
9.2. LFB Class Names and LFB Class Identifiers ................130
10. Authors Emeritus .............................................132
11. Acknowledgments ..............................................132
12. Security Considerations ......................................132
13. References ...................................................132
13.1. Normative References ....................................132
13.2. Informative References ..................................1331. Introduction 🦋
okay so RFC 3746 [RFC3746] sets up a framework where control elements (CEs) can configure and manage one or more separate forwarding elements (FEs) inside a network element (NE), using the ForCES protocol 💖 The ForCES architecture lets forwarding elements with different functionality join a ForCES network element. The catch is that CEs can only make minimal assumptions about what each FE can do ✨ So before CEs can configure and control how FEs forward packets, they need to query and discover the capabilities and states of those FEs 🌸 RFC 3654 [RFC3654] requires that capabilities, states, and configuration information be expressed as an FE model 👑
RFC 3444 [RFC3444] pointed out that information models (IMs) and data models (DMs) are different because they serve different purposes 💅 In its words, "The main purpose of an IM is to model managed objects at a conceptual level, independent of any specific implementations or protocols used". And "DMs, conversely, are defined at a lower level of abstraction and include many details. They are intended for implementors and include protocol-specific constructs". Honestly the line between the two is sometimes blurry 🙈 The FE model in this doc is mainly an information model, but it also has some data model stuff, like explicit definitions of the LFB (Logical Functional Block) class schema and FE schema 🎀 The plan is for this FE model to be the basis for the payload of information exchanged between the CE and FE in the ForCES protocol 🫶
1.1. Requirements on the FE Model 🌈
RFC 3654 [RFC3654] defines the requirements a ForCES FE model must satisfy. To sum it up, an FE model must define:
- Logically separable and distinct packet forwarding operations in an FE data path (Logical Functional Blocks or LFBs);
- The possible topological relationships (and hence the sequence of packet forwarding operations) between the various LFBs;
- The possible operational capabilities (e.g., capacity limits, constraints, optional features, granularity of configuration) of each type of LFB; and
- The possible configurable parameters (e.g., components) of each type of LFB; and
- Metadata that may be exchanged between LFBs.
1.2. The FE Model in Relation to FE Implementations 💅
okay so the FE model is built on Logical Functional Blocks (LFBs) 🧩 which are hooked up in a directed graph. They receive, process, modify, and transmit packets along with metadata, and it's giving very organized Lego vibes ✨. The FE model is designed, and any defined LFB classes should be designed, so that different implementations of the forwarding data path can be logically mapped onto the model with the functionality and sequence of operations correctly captured 🦋. BUT the model is not meant to directly address how a particular implementation maps to an LFB topology. That part is left to the forwarding plane vendors to define how their FE functionality is represented using the FE model 🫶. Our goal is to make the FE model flexible enough to accommodate most common implementations, bestie 🌈.
The LFB topology model for a particular data path implementation must correctly capture the sequence of operations on the packet. Metadata generation by certain LFBs MUST always precede any use of that metadata by subsequent LFBs in the topology graph 💜. This is required for logically consistent operation, no cap. Further, modification of packet fields that are subsequently used as inputs for further processing MUST occur in the order specified in the model for that particular implementation to ensure correctness 🔥.
1.3. The FE Model in Relation to the ForCES Protocol 🎀
The ForCES base protocol [RFC5810] is used by the CEs and FEs to maintain the communication channel between the CEs and FEs 🌸. The ForCES protocol may be used to query and discover the intra-FE topology 🔍. The details of a particular data path implementation inside an FE, including the LFB topology, along with the operational capabilities and attributes of each individual LFB, are conveyed to the CE within information elements in the ForCES protocol. The model of an LFB class should define all of the information that needs to be exchanged between an FE and a CE for the proper configuration and management of that LFB 💖.
Specifying the various payloads of the ForCES messages in a systematic fashion is kind of hard without a formal definition of the objects being configured and managed (the FE and the LFBs within) 😭. So the FE model document defines a set of classes and components for describing and manipulating the state of the LFBs within an FE ✨. These class definitions themselves will generally not appear in the ForCES protocol. Instead, ForCES protocol operations will reference classes defined in this model, including relevant components and the defined operations 🧚.
Section 7 provides more detailed discussion on how the FE model should be used by the ForCES protocol 👑.
1.4. Modeling Language for the FE Model 🦋
Even though not absolutely required, it is beneficial to use a formal data modeling language to represent the conceptual FE model described in this document 💅. Using a formal language can help to enforce consistency and logical compatibility among LFBs, which is so important 🫶. A full specification will be written using such a data modeling language. The formal definition of the LFB classes may facilitate the eventual automation of some of the code generation process and the functional validation of arbitrary LFB topologies ⭐. These class definitions form the LFB library. Documents that describe LFB classes are therefore referred to as LFB library documents 📚.
Human readability was the most important factor considered when selecting the specification language 💜, whereas encoding, decoding, and transmission performance were not a selection factor. The encoding method for over-the-wire transport is not dependent on the specification language chosen, and it is outside the scope of this document and up to the ForCES protocol to define 🌈.
XML is chosen as the specification language in this document, because XML has the advantage of being both human and machine readable with widely available tools support 🍓. This document uses an XML schema to define the structure of the LFB library documents, as defined in [RFC3470] and [Schema1] and [Schema2] 🎀. While these LFB class definitions are not sent in the ForCES protocol, these definitions comply with the recommendations in RFC 3470 [RFC3470] on the use of XML in IETF protocols 💖.
By using an XML schema to define the structure for the LFB library documents, we have a very clear set of syntactic restrictions to go with the desired semantic descriptions and restrictions covered in this document ✨. As a corollary to that, if it is determined that a change in the syntax is needed, then a new schema will be required. This would be identified by a different URN to identify the namespace for such a new schema 🔥.
1.5. Document Structure 🗺️
Section 3 provides a conceptual overview of the FE model, laying the foundation for the more detailed discussion and specifications in the sections that follow 🌸. Section 4 and Section 5 constitute the core of the FE model, detailing the two major aspects of the FE model: a general LFB model and a definition of the FE Object LFB, with its components, including FE capabilities and LFB topology information 🧠. Section 6 directly addresses the model requirements imposed by the ForCES requirements defined in RFC 3654 [RFC3654], while Section 7 explains how the FE model should be used in the ForCES protocol 💅.
2. Definitions ✨
The use of compliance terminology (MUST, SHOULD, MAY, MUST NOT) is used in accordance with RFC 2119 [RFC2119] 🫶. Such terminology is used in describing the required behavior of ForCES forwarding elements or control elements in supporting or manipulating information described in this model 🔥.
Terminology associated with the ForCES requirements is defined in RFC 3654 [RFC3654] and is not copied here. The following list of terminology relevant to the FE model is defined in this section 🍓.
- 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 [RFC5810] 🧩.
- Data Path: A conceptual path taken by packets within the forwarding plane inside an FE. Note that more than one data path can exist within an FE 🌊.
- 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 📐.
- Element: Element is generally used in this document in accordance with the XML usage of the term. It refers to an XML tagged part of an XML document. For a precise definition, please see the full set of XML specifications from the W3C. This term is included in this list for completeness because the ForCES formal model uses XML 🏷️.
- Attribute: Attribute is used in the ForCES formal modeling in accordance with standard XML usage of the term, i.e., to provide attribute information included in an XML tag 🎟️.
- 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 👀.
- Structure Component: A ForCES component that is part of a complex data structure to be used in LFB data definitions. The individual parts that make up a structured set of data are referred to as structure components. These can themselves be of any valid data type, including tables and structures 🏗️.
- Property: ForCES components have properties associated with them, such as readability. Other examples include lengths for variable-sized components. These properties are accessed by the CE for reading (or, where appropriate, writing.) Details on the ForCES properties are found in Section 4.8 🔐.
- LFB Topology: LFB topology is a representation of the logical interconnection and the placement of LFB instances along the data path within one FE. Sometimes this representation is called intra-FE topology, to be distinguished from inter-FE topology. LFB topology is outside of the LFB model, but is part of the FE model 🗺️.
- FE Topology: FE topology is a representation of how multiple FEs within a single network element (NE) are interconnected. Sometimes this is called inter-FE topology, to be distinguished from intra-FE topology (i.e., LFB topology). An individual FE might not have the global knowledge of the full FE topology, but the local view of its connectivity with other FEs is considered to be part of the FE model. The FE topology is discovered by the ForCES base protocol or by some other means 🌐.
- Inter-FE Topology: See FE Topology 🔗.
- Intra-FE Topology: See LFB Topology 🔗.
- LFB Class Library: The LFB class library is a set of LFB classes that has been identified as the most common functions found in most FEs and hence should be defined first by the ForCES Working Group 📚🌈.
3. ForCES Model Concepts ✨
okay so this section is where we meet the big ideas the rest of the doc is built on 🫶 we've got the capability and state abstraction, how FE and LFB models get constructed, and how every piece of the model gets its own unique address 🎀 the deep dives are in Section 4 and Section 5, but this part is the friendly overview so everything after it makes sense bestie 💖
The ForCES FE model has two sides: a capability abstraction and a state abstraction 💅
- The FE/LFB capability model describes what an FE/LFB can do and how much it can handle 🦋 it lists the functions it supports and any limits on them. Capacity is the limit on a specific component, like how big a table can get 📏
- The state model describes what the FE/LFB looks like right now 🌸 that means the instantaneous values and how it's behaving at the moment.
Section 3.1 breaks down the difference between capability and state, and shows how the two come together in the FE model 🔥
The ForCES model lets an FE share info about its structure so it can be operated on 🧚 you can think of this as two layers: the FE-level stuff, and the info about each individual LFB instance the FE is running ✨
- The ForCES model has the constructions for defining the classes of Logical Functional Blocks (LFBs) an FE may support 💜 those classes get defined in this doc and in others. Each class definition gives the info needed to monitor and control instances of that class for ForCES purposes 👑 every LFB model class formally defines its operational LFB components, LFB capabilities, and LFB events. Basically, Section 3.2 is where LFBs show up as the basic functional building blocks of the model 🧱
- The FE model also has the constructions needed to monitor and control the FE as a whole 🎀 for consistency and simplicity, this info is represented as an LFB too: the FE Object LFB class, with one single LFB instance of that class, defined using the LFB model 💅 The FE Object class defines the components that give FE-level info, especially the FE's capabilities at a coarse level 🌈 so not every possible capability or every detail about them, just the big picture. Part of the FE-level info is the LFB topology, which expresses how the LFB instances are logically connected along the data path(s) inside the FE 🦋 Section 3.3 talks about the LFB topology. The FE Object also includes info about which LFB classes the FE can support 🌸
The ForCES model lets every construct it defines be uniquely identified 🔐 that covers the LFB classes, the LFB instances inside those classes, and the components inside those instances 💖
The ForCES protocol [RFC5810] wraps up target address(es) so the CE can eventually reach a fine-grained entity it's referencing 🧚 the addressing hierarchy goes like this:
- An FE is uniquely identified by a 32-bit FEID. 🫶
- Each class of LFB is uniquely identified by a 32-bit LFB ClassID. The LFB ClassIDs are global within the network element and may be issued by IANA. 🌐
- Within an FE, there can be multiple instances of each LFB class. Each LFB class instance is identified by a 32-bit identifier that is unique within a particular LFB class on that FE. 🍓
- All the components within an LFB instance are further defined using 32-bit identifiers. ✨
Refer to Section 3.3 for more details on addressing 💅
3.1. ForCES Capability Model and State Model 🦋
okay capability and state modeling works for both the FE and the LFB abstraction 🫶
Figure 1 shows how FE state, capabilities, and configuration fit together in CE-FE communication over the ForCES protocol 💜
+-------+ +-------+
| | FE capabilities: what it can/cannot do. | |
| |<-----------------------------------------| |
| | | |
| CE | FE state: what it is now. | FE |
| |<-----------------------------------------| |
| | | |
| | FE configuration: what it should be. | |
| |----------------------------------------->| |
+-------+ +-------+
Figure 1: Illustration of FE capabilities, state, and configuration
exchange in the context of CE-FE communication via ForCES.3.1.1. FE Capability Model and State Model 🌸
conceptually, the FE capability model tells the CE which states are allowed on an FE 🔥 the capacity info covers certain quantitative limits or constraints. So the CE gets the general picture of which configurations apply to a particular FE 🧚
3.1.1.1. FE Capability Model 💅
The FE capability model can describe an FE at a coarse level 🎀 for example, an FE might be defined like this:
- the FE can handle IPv4 and IPv6 forwarding;
- the FE can perform classification based on the following fields: source IP address, destination IP address, source port number, destination port number, etc.;
- the FE can perform metering;
- the FE can handle up to N queues (capacity); and
- the FE can add and remove encapsulating headers of types including IPsec, GRE, L2TP.
ngl building a full object model to represent every FE capability is a huge undertaking, and other efforts found that out the hard way 😭 the real pain is describing detailed limits, like the max number of classifiers, queues, buffer pools, and meters the FE can provide 💀 we think a good balance of simplicity and flexibility comes from pairing coarse capability reporting with error reporting 🫶 so if the CE tries to set up some specific behavior the FE can't support, the FE sends back an error saying what went wrong 🙈 similar approaches show up in the Diffserv PIB RFC 3317 [RFC3317] and the framework PIB RFC 3318 [RFC3318] 🌈
3.1.1.2. FE State Model 🦋
the FE state model gives the CE a snapshot view of the FE ✨ for example, the FE might be described to its CE like this:
- on a given port, the packets are classified using a given classification filter;
- the given classifier results in packets being metered in a certain way and then marked in a certain way;
- the packets coming from specific markers are delivered into a shared queue for handling, while other packets are delivered to a different queue; and
- a specific scheduler with specific behavior and parameters will service these collected queues.
3.1.1.3. LFB Capability and State Model 💜
both LFB capability and state info get defined formally using the LFB modeling XML schema 👑
LFB-level capability info is an integral part of the LFB model, and it's seriously powerful 🧚 for example, when certain features of an LFB class are optional, the CE needs to be able to tell whether a given LFB instance supports them 🙈 the schema for defining LFB classes gives a way to identify those components 💖
State info gets defined formally using LFB component constructs 🫶
3.1.2. Relating LFB and FE Capability and State Model ✨
okay so bestie, capability info at the FE level tells the CE which LFB classes the FE can make, how many instances of each it can create, and what linkage limits apply between those LFB instances 🧩 Section 5 defines the FE-level components, capability info included. Everything is represented as LFBs, so all of this lives in a single instance of the FE Object LFB class 💅 Because it's one instance with a known LFB class and a known instance identification, the ForCES protocol lets a CE access this info whenever it needs to, even while it's still establishing control of the FE 🫶
once the FE capability is described to the CE, the FE state info shows up at two levels 👑 level one is the logically separable and distinct packet processing functions, called LFBs 🎀 level two describes how those individual LFBs are ordered and placed along the data path so you get a complete forwarding plane service 🦋 that ordering and interconnection is called LFB topology 🌈 Section 3.2 covers the high-level LFB concepts, and Section 3.3 covers LFB topology issues 🧚 this topology info is represented as components of the FE Object LFB instance, so the CE can fetch and manipulate it 💖
3.2. Logical Functional Block (LFB) Modeling ✨
each LFB does a well-defined action or computation on the packets passing through it 🌸 once it finishes its job, either the packets get modified in certain ways (like a decapsulator or a marker), or some results get generated and stored, often as metadata (like a classifier) 💜 each LFB typically does a single action 🍓 classifiers, shapers, and meters are all examples of these 🫶 modeling LFBs at such a fine granularity means we can use a small number of LFBs to express the bigger FE functions (like an IPv4 forwarder) precisely 🔥 which in turn can describe more complex networking functions and vendor implementations of both software and hardware 😭 these fine-grained LFBs will get defined in detail in one or more documents published separately, using the material in this model 📚
it's also the case that some LFBs exist to give the CE a set of components for controlling FE operation (aka a locus of control) 🎀 that control isn't tied to specific packets or specific parts of the data path 🦋 the FE Object is a great example, since it gives the CE info about the FE as a whole and lets the FE control some aspects of itself, like the data path itself ✨ these LFBs won't have the packet-oriented properties described in this section 💅
in general, multiple LFBs live inside one FE, as shown in Figure 2, and they all share the same ForCES protocol (Fp) termination point that runs the ForCES protocol logic and keeps the communication channel to and from the CE 🌈
+-----------+
| CE |
+-----------+
^
| Fp reference point
|
+--------------------------|-----------------------------------+
| FE | |
| v |
| +----------------------------------------------------------+ |
| | ForCES protocol | |
| | termination point | |
| +----------------------------------------------------------+ |
| ^ ^ |
| : : Internal control |
| : : |
| +---:----------+ +---:----------| |
| | :LFB1 | | : LFB2 | |
| =====>| v |============>| v |======>...|
| Inputs| +----------+ |Outputs | +----------+ | |
| (P,M) | |Components| |(P',M') | |Components| |(P",M") |
| | +----------+ | | +----------+ | |
| +--------------+ +--------------+ |
| |
+--------------------------------------------------------------+Figure 2: Generic LFB diagram. 🖼️
okay so an LFB, as shown in Figure 2, may have inputs, outputs, and components that the CE can query and manipulate via an Fp reference point (defined in RFC 3746 [RFC3746]) and the ForCES protocol termination point 💖 the horizontal axis is the forwarding plane, connecting the inputs and outputs of LFBs within the same FE 🌸 P (with marks to indicate modification) is a data packet, and M (with marks to indicate modification) is the metadata associated with that packet 🧁 the vertical axis between the CE and the FE is the Fp reference point, where bidirectional communication happens 🔁 CE-to-FE traffic is for configuration, control, and packet injection, while FE-to-CE traffic is for packet redirection to the control plane, reporting monitoring and accounting info, reporting errors, and so on 📡 also, the interaction between the CE and the LFB is only abstract and indirect 🫠 the result is that the CE manipulates the components of the LFB instances ✨
an LFB can have one or more inputs 🎀 each input takes a pair of a packet and its associated metadata 💜 depending on the LFB input port definition, the packet or the metadata may be allowed to be empty (or equivalently, not provided) 🌙 when input arrives at an LFB, either the packet or its associated metadata must be non-empty, or there is effectively no input 🙈 (LFB operation can generally be triggered by input arrival, by timers, or by other system state 🕰️ it's only when the goal is to have input drive operation that the input must be non-empty 🔥)
the LFB processes the input and produces one or more outputs, and each output is a pair of a packet and its associated metadata 🦋 again, depending on the LFB output port definition, either the packet or the metadata may be allowed to be empty (or equivalently, absent) 🌈 metadata attached to packets on output may be metadata that was received, or it may be info about the packet processing that later LFBs in the FE's packet processing might use 🧚
a namespace is used to associate a unique name and ID with each LFB class 🏷️ the namespace MUST be extensible so a new LFB class can be added later to accommodate future innovation in the forwarding plane 🚀 (yes, MUST, bestie, that one's a big deal 😤)
LFB operation is specified in the model so the CE can understand the behavior of the forwarding data path 🧠 for example, the CE needs to know at what point in the data path the FE decrements the IPv4 header TTL 🕒 that way it knows whether a control packet could be delivered to it before or after that point 📬 the CE also needs to understand where and what type of header modifications happen (like tunnel header append or strip) 🎀 and it works to verify that the various LFBs along a data path within an FE are compatible to link together 🔗 connecting incompatible LFB instances produces a non-working data path 💀 so the model is designed to give the CE enough info to make that call 💅
selecting the right granularity for describing LFB functions is a really important part of this model ⭐ vendors win if LFB operation can be expressed in enough detail that physical devices implementing different LFB functions can be integrated easily into an FE design 🧩 however, the model and its associated library of LFBs must not be so detailed and so specific that they significantly constrain implementations 🫧 so a semi-formal specification is needed: a human-readable text description of LFB operation, but specific and unambiguous enough to allow conformance testing and efficient design, so that interoperability between different CEs and FEs can be achieved 🤝
the LFB class model specifies the following, among other info:
- number of inputs and outputs (and whether they are configurable)
- metadata read/consumed from inputs
- metadata produced at the outputs
- packet types accepted at the inputs and emitted at the outputs
- packet content modifications (including encapsulation or decapsulation)
- packet routing criteria (when multiple outputs on an LFB are present)
- packet timing modifications
- packet flow ordering modifications
- LFB capability information components
- events that can be detected by the LFB, with notification to the CE
- LFB operational components
Section 4 of this document gives a detailed discussion of the LFB model with a formal specification of the LFB class schema 📐 the rest of Section 3.2 only aims to give a conceptual overview of some important issues in LFB modeling, without covering every specific detail 🌷
3.2.1. LFB Outputs ✨
okay so an LFB output is basically a conceptual port on an LFB that can send info over to another LFB 📮. What goes out that port is a pair: a packet plus its associated metadata, and one of those two is allowed to be empty 🫶. (If both were empty there'd be nothing to send at all, so it wouldn't even be an output 💀.)
A single LFB output can only be connected to one LFB input. This is required to make the packet flow through the LFB topology unambiguous 🦋.
Some LFBs have just a single output, like in Figure 3.a 👇
+---------------+ +-----------------+
| | | |
| | | OUT +-->
... OUT +--> ... |
| | | EXCEPTIONOUT +-->
| | | |
+---------------+ +-----------------+
a. One output b. Two distinct outputs
+---------------+ +-----------------+
| | | EXCEPTIONOUT +-->
| OUT:1 +--> | |
... OUT:2 +--> ... OUT:1 +-->
| ... +... | OUT:2 +-->
| OUT:n +--> | ... +...
+---------------+ | OUT:n +-->
+-----------------+
c. One output group d. One output and one output group
Figure 3: Examples of LFBs with various output combinations.To handle a non-trivial LFB topology, you need multiple LFB outputs so an LFB class can fork the data path 🍴. There are two mechanisms for forking: multiple singleton outputs and output groups, and they can be combined in the same LFB class 🌈.
Multiple separate singleton outputs are defined in an LFB class to model a predetermined number of semantically different outputs. Basically, the LFB class definition MUST include the number of outputs, which implies the number is known when the LFB class is defined. Additional singleton outputs can't be created at LFB instantiation time, and they can't be created on the fly after the LFB is instantiated either 🙅♀️.
For example, an IPv4 LPM (Longest-Prefix-Matching) LFB may have one output (OUT) that sends the packets where the LPM look-up was successful, passing a META_ROUTEID as metadata. It can also have another output (EXCEPTIONOUT) for exception packets when the LPM look-up failed 😤. This is shown in Figure 3.b. The packets from these two outputs need different downstream treatment, since they come from two different conditions in the LFB, and each output carries different metadata. This concept assumes the number of distinct outputs is known when the LFB class is defined. For each singleton output, the LFB class definition specifies the types of frames (packets) and metadata that output emits 📋.
An output group, on the other hand, is for when a flow of similar packets with an identical set of permitted metadata needs to be split into multiple paths 🪄. Here, the number of paths is not known when the LFB class is defined, because it isn't an inherent property of the class. An output group is made of several outputs, called the output instances of the group, and all of them share the same frame (packet) and metadata emission definitions (see Figure 3.c). Each output instance can connect to a different downstream LFB, just like separate singleton outputs would, but the number of output instances can differ between LFB instances of the same LFB class 💅. The class definition may include a lower and/or an upper limit on the number of outputs. On top of that, for configurable FEs, the FE capability information may define further limits on the number of instances in specific output groups for certain LFBs. The actual number of output instances in a group is a component of the LFB instance, and it's read-only for static topologies but read-write for dynamic topologies. The output instances in a group are numbered sequentially, from 0 to N-1, and they're addressable from within the LFB. To use output port groups, the LFB needs a built-in mechanism to select one specific output instance for each packet. That mechanism is described in the textual definition of the class and is typically configurable via some attributes of the LFB 🎀.
Let's look at an example: a redirector LFB, whose only job is to direct packets to one of N downstream paths based on one of the metadata associated with each arriving packet. This LFB is super versatile and can be used in lots of different places in a topology 🧚. For instance, given LFBs that record the type of packet in a FRAMETYPE metadatum, or a packet rate class in a COLOR metadatum, you can use those metadata for branching. A redirector can split the data path into an IPv4 and an IPv6 path based on a FRAMETYPE metadatum (N=2), or fork into rate-specific paths after metering using the COLOR metadatum (red, yellow, green; N=3), and so on ✨.
Using an output group in the above LFB class gives you the flexibility to adapt each instance of that class to the operation you need 💖. The metadata used as the selector for the output instance is a property of the LFB. For each packet, the value of the specified metadata may be used as a direct index to the output instance. Or, the LFB may have a configurable selector table that maps a metadatum value to an output instance 🗺️.
Note that other LFBs can also use the output group concept to build similar adaptive forking capability 🌸. For example, a classifier LFB with one input and N outputs can be defined easily by using the output group concept. Alternatively, a classifier LFB with one singleton output combined with an explicit N-output re-director LFB models the same processing behavior. Whether to use the output group model for a certain LFB class is left up to the LFB class designers 🤷♀️.
The model lets an output group be combined with other singleton output(s) in the same class, as shown in Figure 3.d. This LFB has two types of outputs: OUT, for normal packet output, and EXCEPTIONOUT, for packets that triggered some exception. The normal OUT has multiple instances, so it's an output group 🔥.
In summary, the LFB class may define one output, multiple singleton outputs, one or more output groups, or a combination of these 👑. Multiple singleton outputs should be used when the LFB must provide for forking the data path and at least one of the following conditions holds:
- the number of downstream directions is inherent from the definition of the class and hence fixed
- the frame type and set of permitted metadata emitted on any of the outputs are different from what is emitted on the other outputs (i.e., they cannot share their frametype and permitted metadata definitions)
An output group is appropriate when the LFB must provide for forking the data path and at least one of the following conditions holds:
- the number of downstream directions is not known when the LFB class is defined
- the frame type and set of metadata emitted on these outputs are sufficiently similar or, ideally, identical, such that they can share the same output definition
3.2.2. LFB Inputs ✨
Okay so an LFB input is a conceptual port on an LFB, basically the spot where the LFB can receive info from other LFBs 📥💖 That info is usually a pair: a packet plus its metadata. For some LFBs in some situations, either the packet or the metadata can be empty, but not both, bestie, because then there's literally no input 💀
When an LFB gets packets from more than one other LFB instance (that's fan-in 🦋), the model gives you three ways to handle it. All three are supported, and you can mix them all in the same LFB 🫶
- Implicit multiplexing via a single input
- Explicit multiplexing via multiple singleton inputs
- Explicit multiplexing via a group of inputs (input group)
The simplest version is a singleton input (Figure 4.a). Most LFBs only have one singleton input 🌸 Multiplexing into a single input works because the model lets more than one LFB output connect to the same LFB input. This applies to any LFB input with no special provisions in the LFB class. It makes sense when the upstream packets are similar in frametype and accompanying metadata, and need similar processing. Just know that this model doesn't say how contention gets handled when multiple packets show up at the same time 😬 If you need contention handling to be modeled explicitly, one of the other two solutions must be used.
The second method uses individually defined singleton inputs (Figure 4.b). This one is for when the LFB needs to handle distinct types of packet streams that need input-specific handling inside the LFB, and you already know how many of those cases there are when the LFB class gets defined. For example, an LFB that does both Layer 2 decapsulation (to Layer 3) and Layer 3 encapsulation (to Layer 2) could have two inputs: one for Layer 2 frames to decapsulate, and one for Layer 3 frames to encapsulate. This LFB type expects different frames (L2 versus L3) at its inputs, each with different sets of metadata, so it applies different processing to frames arriving at each input 🧚 This model can explicitly address packet contention by defining how the LFB class handles the contending packets ⭐
+--------------+ +------------------------+
| LFB X +---+ | |
+--------------+ | | |
| | |
+--------------+ v | |
| LFB Y +---+-->|input Meter LFB |
+--------------+ ^ | |
| | |
+--------------+ | | |
| LFB Z |---+ | |
+--------------+ +------------------------+(a) An LFB connects with multiple upstream LFBs via a single input.
+--------------+ +------------------------+
| LFB X +---+ | |
+--------------+ +-->|layer2 |
+--------------+ | |
| LFB Y +------>|layer3 LFB |
+--------------+ +------------------------+(b) An LFB connects with multiple upstream LFBs via two separate singleton inputs.
+--------------+ +------------------------+
| Queue LFB #1 +---+ | |
+--------------+ | | |
| | |
+--------------+ +-->|in:0 \ |
| Queue LFB #2 +------>|in:1 | input group |
+--------------+ |... | |
+-->|in:N-1 / |
... | | |
+--------------+ | | |
| Queue LFB #N |---+ | Scheduler LFB |
+--------------+ +------------------------+(c) A Scheduler LFB uses an input group to differentiate which queue LFB packets are coming from.
Figure 4: Examples of LFBs with various input combinations.
The third method uses an input group 🎀 It's similar to the output group from the last section, and it's shown in Figure 4.c. An input group is a bunch of input instances that all share the same properties (same frame and metadata expectations). The instances are numbered 0 to N-1. From the outside they look like normal inputs, so any compatible upstream LFB can connect its output to one of them. When a packet shows up at a particular input instance, the LFB knows which index it arrived on, and it can use that in its internal processing. For example, the index can work as a table selector, or as an explicit precedence selector to resolve contention. Same as with output groups, the number of input instances in a group isn't defined in the LFB class, though the class definition can put restrictions on the range of possible values. And if an FE supports configurable topologies, it can add further limits on how many instances a particular port group of a particular LFB class can have. Within those limits, different instances of the same class can have different numbers of input instances 💅
The number of actual input instances in the group is a component defined in the LFB class. It's read-only for static topologies and read-write for configurable topologies.
Think of the Scheduler LFB in Figure 4.c as the example here. It gets packets from a bunch of Queue LFBs through its input instances, and it uses the input index to control contention resolution and scheduling 👑
So, the big summary: an LFB class can define one input, multiple singleton inputs, one or more input groups, or any combination of those 🌈 Any input allows implicit multiplexing, since you can connect multiple outputs to the same input. Explicit multiple singleton inputs are useful when contention handling has to be explicit, or when the LFB class has to receive and process a known number of distinct types of packet streams. An input group is the move when contention handling must be modeled explicitly but the number of inputs isn't inherent to the class (so it isn't known when the class is defined), or when it's critical for LFB operation to know exactly which input the packet came in on 🔥
3.2.3. Packet Type 🦋
When LFB classes are defined, the input and output packet formats (e.g., IPv4, IPv6, Ethernet) MUST be specified. These are the types of packets a given LFB input can receive and process, or that a given LFB output can produce. The model requires that distinct packet types be uniquely labeled with a symbolic name and/or ID 🏷️
Quick note: each LFB has a set of packet types it operates on, but it doesn't care whether the underlying implementation is passing along a bigger portion of the packets. For example, an IPv4 LFB might only operate on IPv4 packets, while the underlying implementation may or may not be stripping the L2 header before handing the packet over. Whether that's happening is opaque to the CE 🙈
3.2.4. Metadata 🧚
Metadata is state that gets passed from one LFB to another alongside a packet. It helps the later LFBs process that packet 💜
The ForCES model defines metadata as precise atomic definitions in the form of label, value pairs. It also gives LFB class authors a way to formally define how metadata gets created, modified, read, and consumed (deleted) 🫶
Inter-FE metadata (metadata crossing FEs) is likely to be semantically similar to this metadata, but it's out of scope for this document 🙃
Section 4 has informal details on metadata 📖
3.2.4.1. Metadata Lifecycle within the ForCES Model 🌸
Each metadatum is modeled as a <label, value> pair. The label identifies the type of information (e.g., "color"), and its value holds the actual information (e.g., "red"). The label is shown here as a textual label, but for protocol processing it's associated with a unique numeric value (identifier) 🔢
To keep LFBs interoperable, the LFB class specification must define what metadata the LFB class "reads" or "consumes" on its input(s), and what metadata it "produces" on its output(s). For maximum extensibility, this definition should specify neither which LFBs the metadata is expected to come from for a consumer LFB, nor which LFBs are expected to consume metadata for a given producer LFB 🦋
3.2.4.2. Metadata Production and Consumption 💅
For a given metadatum on a given packet path, there MUST be at least one producer LFB that creates that metadatum, and there SHOULD be at least one consumer LFB that needs that metadatum ✨
In the ForCES model, the producer and consumer LFBs of a metadatum don't have to be adjacent. Plus, there can be multiple producers and multiple consumers for the same metadatum. When a packet path involves multiple producers of the same metadatum, the subsequent producers overwrite that metadatum's value 🌀
The metadata an LFB produces is specified by the LFB class definition on a per-output-port-group basis. A producer may always generate the metadata on that port group, or it may only generate it under certain conditions. We call the first kind "unconditional" metadata, and the second kind "conditional" metadata 🎀 For example, a deep packet inspection LFB might produce several pieces of metadata about a packet. The first one might be the IP protocol being carried (TCP, UDP, SCTP, ...). The two additional items might be the source and destination port numbers. Those two are conditional on the value of the first metadatum (the carried IP protocol), since they only get produced for protocols that use port numbers 🔍 For conditional metadata, it should be possible to tell from the LFB definition when that metadata gets produced.
The consumer behavior of an LFB, meaning the metadata it needs for its operation, is defined in the LFB class definition on a per-input-port-group basis. An input port group may "require" a given metadatum, or it may treat it as "optional" information. For optional metadata, the LFB class definition MUST explicitly define what happens if that metadata isn't provided. One approach is to specify a default value for each optional metadatum, and then assume that default value gets used for any metadata that isn't provided with the packet 🍓
Last but not least: when you're specifying the metadata tags, some harmonization effort has to happen, so the producer LFB class uses the same tag as its intended consumer(s) 🫶💖
3.2.4.3. LFB Operations on Metadata ✨
okay so bestie, when a packet is being processed by an LFB (aka between the moment it comes in and the moment the LFB forwards it on), that LFB may perform read, write, and/or consume operations on any active metadata attached to the packet 🎀. If the LFB is treated as a black box, then one of these operations happens to each active metadatum 👀:
IGNORE: ignores and forwards the metadatumREAD: reads and forwards the metadatumREAD/RE-WRITE: reads, over-writes, and forwards the metadatumWRITE: writes and forwards the metadatum (can also be used to create new metadata)READ-AND-CONSUME: reads and consumes the metadatumCONSUME: consumes the metadatum without reading it
The last two operations end the metadatum's life-cycle 💀. That means the metadatum does NOT ride along with the packet when it gets sent to the next LFB 🧳. So if it's consumed, it's gone, no cap.
In the ForCES model, a brand new metadatum shows up when an LFB applies a WRITE to a metadata type that wasn't there when the packet arrived at that LFB ✨. This kind of implicit creation might be totally unintentional, because the LFB could apply the WRITE without knowing or caring whether that metadatum already existed 🙈. If it existed, it gets over-written. If it didn't, it gets created. Either way, the LFB doesn't have to check first, which is lowkey iconic 💅.
For LFBs that insert packets into the model, WRITE is the only meaningful metadata operation 🌸.
For LFBs that remove the packet from the model, they can either READ-AND-CONSUME (read) or CONSUME (ignore) each active metadatum attached to the packet 🧚. Honestly, that's giving clean exit energy.
3.2.5. LFB Events
okay this part is about things that happen while the thing is running 🦋. Stuff like a link failing, a restart, or a timer going off in a special purpose LFB can all be detected by LFBs. Sometimes the CE wants to know when these things happen, so it can be notified ✨. How those messages get sent and what they look like is covered in the Forwarding and Control Element Separation (ForCES) protocol [RFC5810] document 📜. This model's job is to explain how those conditions are understood 🧠.
Events get declared in the LFB class definition 🎀. An LFB event declaration has:
- a unique 32-bit identifier.
- An LFB component that is used to trigger the event. This entity is known as the event target.
- A condition that will happen to the event target and will result in an event being generated to the CE. Examples of a condition include something getting created or deleted, a config change, etc.
- What should be reported to the CE by the FE if the declared condition is met.
So basically, the declaration of an event inside an LFB class tells you which part of the LFB components need watching for events, what condition the FE should detect on that monitored component to trigger the event, and what to send to the CE when it fires 👑.
Even though events are declared in the class definition, what actually happens at runtime is controlled by built-in event properties, which use the LFB component properties (more on those in Section 3.2.6) 🔥. A CE subscribes to the events on an LFB class instance by setting an event property for subscription. Every event has a subscription property that is off by default 🙅♀️. So if a CE wants to get a specific event, it has to turn on that subscription property at runtime, bestie.
Event properties also handle runtime event filtering 🌈. A CE can set an event property to further suppress events it has already subscribed to. The LFB model defines filters like threshold values, hysteresis, time intervals, number of events, etc. ✨
The contents of event reports are designed to carry the common, closely related info that the CE can be strongly expected to need in order to react to the event 💖. They are NOT meant to carry info the CE already has, huge volumes of info, or info that's related in complicated ways 😭.
Conceptually, at runtime, event processing is split into four steps 🦋:
- Detection of something happening to the event target (declared during the LFB class definition). The next step only happens if the CE subscribed (at runtime) to the event.
- Checking the condition (declared during the LFB class definition) on the LFB event target. If the condition is met, move on to the next step.
- Checking the runtime-set event filters, if they exist, to see whether the event should be reported or suppressed. If it's to be reported, move on to the next step.
- Submitting the declared report to the CE.
Section 4.7.6 goes into events in more detail 🌸.
3.2.6. Component Properties
LFBs and structures are made up of components, which hold the info the CE needs to see and/or change about how the LFB works 🧩. As described in detail in Section 4.7, these components can be basic values, complex structures (which contain multiple components themselves, each one a value, structure, or table), or tables (which contain values, structures, or tables) 💅. Components can be defined so that their appearance in LFB instances is optional 🫶. Components may be readable or writable, depending on what the FE implementation decides 🎀. The CE needs to know these properties. On top of that, certain kinds of components (arrays / tables, aliases, and events) have extra property info that the CE may need to read or write 👑. This model defines the structure of the property info for all defined data types ✨.
Section 4.8 goes into properties in more detail 🦋.
3.2.7. LFB Versioning
LFB class versioning is a way to let LFB classes evolve bit by bit 🌱. In general, an FE is NOT allowed to contain LFB instances for more than one version of a particular class 🙅♀️. Inheritance (coming up next, in Section 3.2.8) has special rules 👀. If an FE data path model contains an LFB instance of a class C, and at the same time also contains an LFB instance of a class C' that was inherited from class C, then C could have a different version than C'. Plot twist, bestie 🧚.
LFB class versioning works by requiring a version string in the class definition 🏷️. CEs may support multiple versions of a particular LFB class to provide backward compatibility, but FEs MUST NOT support more than one version of a particular class 🚫. Only the CE gets to be a multi-version queen here 👑.
Versioning isn't limited to backward-compatible changes 🔥. It's specifically expected to be used for changes that can't be represented by inheritance. Often this is to correct errors, so it may not be backward compatible 🙈. It can also be used to remove components that aren't considered useful, especially if they used to be mandatory and were therefore an implementation impediment 🧹.
3.2.8. LFB Inheritance
LFB class inheritance is supported in the FE model as a way to define new LFB classes ✨. It also lets FE vendors add vendor-specific extensions to standardized LFBs 🎀. An LFB class specification MUST specify the base class and version number it inherits from (the default is the base LFB class) 📋. Multiple inheritance is NOT allowed, though, to avoid unnecessary complexity 🙅♀️. Keep it simple, bestie.
Inheritance should be used only when there is significant reuse of the base LFB class definition 🌸. A separate LFB class should be defined if little or no reuse is possible between the derived class and the base LFB class 💜.
Now, an interesting issue with class inheritance is backward compatibility between a descendant and an ancestor class 🤔. Picture this hypothetical scenario 🎬: a standardized LFB class "L1" exists. Vendor A builds an FE that implements LFB "L1", and vendor B builds a CE that can recognize and operate on LFB "L1". Now say a new LFB class, "L2", gets defined based on the existing "L1" class by extending its capabilities incrementally. Let's look at the FE backward-compatibility issue by asking what happens if vendor B upgrades its FE from "L1" to "L2" while vendor C's CE stays the same 😳. The old L1-based CE can interoperate with the new L2-based FE, but only if the derived LFB class "L2" really is backward compatible with the base class "L1" ✨.
The reverse scenario is way less problematic 🌈. That's when CE vendor B upgrades to the new LFB class "L2" but the FE doesn't get upgraded. As long as the CE can work with older LFB classes, this problem doesn't affect the model, so from here on, "backward compatibility" refers to the first scenario, the one about FE backward compatibility 💖.
Backward compatibility can be built into the inheritance model by constraining LFB inheritance so the derived class is a functional superset of the base class (meaning the derived class can only add functions to the base class, not remove any) 🧁. On top of that, the following mechanisms are required to support FE backward compatibility 🫶:
- When detecting an LFB instance of an LFB type that is unknown to the CE, the CE MUST be able to query the base class of that LFB from the FE 🔍.
- The LFB instance on the FE SHOULD support a backward-compatibility mode (meaning the LFB instance reverts itself back to the base class instance), and the CE SHOULD be able to configure the LFB to run in such a mode 🔄.
3.3. ForCES Model Addressing ✨
Okay bestie, Figure 5 is the glow-up of how all the ForCES model entities fit together 🦋. The ForCES protocol gives you a way to uniquely identify any LFB class instance component, and it's honestly iconic.
FE Address = FE01
+--------------------------------------------------------------+
| |
| +--------------+ +--------------+ |
| | LFB ClassID 1| |LFB ClassID 91| |
| | InstanceID 3 |============>|InstanceID 3 |======>... |
| | +----------+ | | +----------+ | |
| | |Components| | | |Components| | |
| | +----------+ | | +----------+ | |
| +--------------+ +--------------+ |
| |
+--------------------------------------------------------------+
Figure 5: FE entity hierarchy.At the very top of the addressing hierarchy is the FE identifier 👑. In the example, the 32-bit FE identifier is shown with the nickname FE01. The next entity selector is the 32-bit LFB ClassID. The picture has two LFB classes, with identifiers 1 and 91, and each of them has one instance. The 32-bit LFB class instance identifier only has meaning within its own LFB class, so to really drive that home, both class 1 and class 91 have an instance numbered 3 🌈.
So with this addressing scheme, a message could be sent to FE01, LFB ClassID 1, LFB InstanceID 3, using the ForCES protocol. But ngl, a message like that only becomes useful if it targets the entities inside an LFB 🧚. Those entities could be carrying state, capabilities, and so on. Figure 6 zooms in on them.
LFB Class ID 1,InstanceID 3 Components
+-------------------------------------+
| |
| LFB ComponentID 1 |
| +----------------------+ |
| | | |
| +----------------------+ |
| |
| LFB ComponentID 31 |
| +----------------------+ |
| | | |
| +----------------------+ |
| |
| LFB ComponentID 51 |
| +----------------------+ |
| | LFB ComponentID 89 | |
| | +-----------------+ | |
| | | | | |
| | +-----------------+ | |
| +----------------------+ |
| |
| |
+-------------------------------------+
Figure 6: LFB hierarchy.Figure 6 is basically the glam closeup of the components living inside LFB Class ID 1, LFB InstanceID 3, which is the one we spotted in Figure 5 💅.
The example has three components with 32-bit component identifiers: 1, 31, and 51. LFB ComponentID 51 is a complex structure, and inside of it is an entity with LFB ComponentID 89. Honestly, ComponentID 89 could be a complex structure too, but the example keeps it simple so it's easier to read 🎀.
3.3.1. Addressing LFB Components: Paths and Keys
Remember how LFB components can be complex structures? Like a table, or a table whose cells are also tables, and so on 🍓. The ForCES model XML schema (Section 4) lets you uniquely identify anything that complicated, using dot-annotated static paths plus content addressing of paths that are derived from keys. For example, if LFB ComponentID 51 is a structure, then the path to LFB ComponentID 89 above is 51.89.
Now, LFB ComponentID 51 might be a table (an array). In that case, if you want the LFB component with ID 89 from inside the 7th entry of that table, you'd use the path 51.7.89 💜. The model supports explicit table element selection by putting an index in the dotted path. It also lets you find table elements by what they contain, and that's called using keys, or key indexing 🔥. So if ComponentID 51 is a table that can be key indexed, the CE can pass a key describing the content, along with the path 51 to pick the table, and then the path 89 to pick the table structure element. Once the FE computes that, it resolves to LFB ComponentID 89 within the matching table entry. Main character energy, literally 👑.
3.4. FE Data Path Modeling
Okay so packets come in from the ingress ports and usually flow through one or more LFBs before they leave through the egress ports 🦋. How an FE handles a packet depends on a bunch of stuff, like what type of packet it is (IPv4, IPv6, or MPLS, for example), header values, arrival time, and more. The result of LFB processing can also change how that packet gets treated by the LFBs downstream. That difference in downstream treatment can be pictured as having alternative data paths inside the FE ✨. For instance, a 6-tuple classification done by a classifier LFB could decide which rate meter a rate meter LFB, further along the data path, applies to the packet 💖.
LFB topology is a directed graph of the logical data paths inside an FE. The nodes are the LFB instances, and each directed link shows which way the packet flows from one LFB to the next 🌸. Section 3.4.1 talks about how FE data paths can be modeled as LFB topology, and Section 3.4.2 digs into the issues around reconfiguring that LFB topology 🫶.
3.4.1. Alternative Approaches for Modeling FE Data Paths
There are two basic ways to express the differences in packet treatment inside an FE 🌈. The first one shows the data path directly and visually, which is the topological approach. The second one uses metadata, which is the encoded state approach.
- Topological Approach
With this approach, the different packet treatments get expressed by splitting the LFB topology into alternative paths. Put another way, if an LFB's result controls how the packet is processed next, that LFB gets separate output ports, one for each alternative treatment. Each port connects to its own sub-graph, and each sub-graph shows the matching treatment further downstream 💅.
- Encoded State Approach
The other way to show different treatment is by using metadata. An LFB's result can be encoded into a metadatum, which travels with the packet to the downstream LFBs. A downstream LFB can then look at that metadata and its value (for example, using it as an index into some table) to figure out how to treat the packet 🧚.
In theory, either approach could replace the other, so you could just pick one pure approach to describe every data path in an FE. But ngl, neither one is the best representation for every practical case 💀. Depending on the approach, the same FE with the same logical data paths can end up with very different-looking LFB topology graphs. The topological approach alone might need a huge graph with lots of links, paths, and nodes (LFB instances) to show every alternative data path 😭. The encoded state approach alone would be stuck as a straight string of LFBs, which is not a very intuitive way to describe different data paths, like MPLS versus IPv4 🙈. So a mix of these two approaches will likely be what a practical model uses. And as we'll see below, the two approaches can even be mixed within the same LFB 🎀.
Let's look at a simple example: a classifier with N classification outputs that feed into other LFBs. Figure 7.a shows what the LFB topology looks like with the pure topological approach. Each output of the classifier goes to one of the N LFBs, and no metadata is needed. Honestly, the topological approach is simple, straightforward, and easy to picture ✨. But if N is large, and the N nodes after the classifier (LFB#1, LFB#2, ..., LFB#N) are all the same LFB type (like meter) with their own independent components, the encoded state approach gives a much simpler topology, shown in Figure 7.b 🦋. With that approach, the Meter node itself has to hold a table of N rows of meter components, where each row holds the attributes for one meter instance. A metadatum M also travels with packet P from the classifier to the meter. The meter uses M as a look-up key (an index) to find the right row of attributes for each particular packet P 💖.
What if those N nodes (LFB#1, LFB#2, ..., LFB#N) are not the same type? Say LFB#1 is a queue while the rest are all meters. What's the best way to show those data paths? Pure topological and pure encoded state are both still possible, but the natural combo of the two seems to be the best option 🌸. Figure 7.c shows two different functional data paths using the topological approach, while the N-1 meter instances are distinguished only by metadata 🫶.
+----------+
P | LFB#1 |
+--------->|(Compon-1)|
+-------------+ | +----------+
| 1|-----+ P +----------+
| 2|---------------->| LFB#2 |
| classifier 3| |(Compon-2)|
| ...|... +----------+
| N|-----+ ...
+-------------+ | P +----------+
+--------->| LFB#N |
|(Compon-N)|
+----------+
(a) Using pure topological approach
+-------------+ +-------------+
| 1| | Meter |
| 2| (P, M) | (Compon-1) |
| 3|---------------->| (Compon-2) |
| ...| | ... |
| N| | (Compon-N) |
+-------------+ +-------------+
(b) Using pure encoded state approach to represent the LFB
topology in 5(a), if LFB#1, LFB#2, ..., and LFB#N are of the
same type (e.g., meter).
+-------------+
+-------------+ (P, M) | queue |
| 1|------------>| (Compon-1) |
| 2| +-------------+
| 3| (P, M) +-------------+
| ...|------------>| Meter |
| N| | (Compon-2) |
+-------------+ | ... |
| (Compon-N) |
+-------------+
(c) Using a combination of the two, if LFB#1, LFB#2, ..., and
LFB#N are of different types (e.g., queue and meter).
Figure 7: An example of how to model FE data paths.okay so this example shows why each approach slays in a different situation 💅 With the encoded state approach, you usually need fewer connections between a fan-out node and its next LFB instances of the same type, because each packet carries metadata that the following nodes can read and then apply a different packet treatment 🎀 For those cases, a pure topological approach makes you build elaborate graphs with way more connections, and honestly it gets super unwieldy 😭 A topological approach is still the most intuitive way to represent functionally different data paths ✨
For complex topologies, a combo of the two is the most flexible 🦋 There's a general design guideline that tells you which approach fits a particular situation. The topological approach should primarily be used when the packet data path forks to distinct LFB classes (not just distinct parameterizations of the same LFB class), and when the fan-outs don't need changes, like adding or removing LFB outputs, or only need very infrequent changes 💀
Configuration info that needs to change frequently should be expressed using the internal attributes of one or more LFBs (and so using the encoded state approach) 🌸
+---------------------------------------------+
| |
+----------+ V +----------+ +------+ |
| | | | |if IP-in-IP| | |
---->| ingress |->+----->|classifier|---------->|Decap.|---->---+
| ports | | |---+ | |
+----------+ +----------+ |others +------+
|
V
(a) The LFB topology with a logical loop
+-------+ +-----------+ +------+ +-----------+
| | | |if IP-in-IP | | | |
--->|ingress|-->|classifier1|----------->|Decap.|-->+classifier2|->
| ports | | |----+ | | | |
+-------+ +-----------+ |others +------+ +-----------+
|
V
(b) The LFB topology without the loop utilizing two independent
classifier instances.
Figure 8: An LFB topology example.okay so the LFB topology here is the logical topology, not the physical layout of the FE hardware 🧠 That said, the actual implementation can still influence how the functionality gets mapped onto the LFB topology 👀 Figure 8 shows one simple FE example. An IP-in-IP packet from an IPsec application like a VPN might go to the classifier first, where it gets classified based on the outer IP header. Once it's classified as an IP-in-IP packet, it's sent to a decapsulator to strip off the outer IP header, and then to a classifier again to classify on the inner IP header 🫶 If the same classifier hardware or software is used for both the outer and inner IP header classification with the same set of filtering rules, a logical loop is naturally present in the LFB topology, as shown in Figure 8.a 🔁 But if the classification is done by two different pieces of hardware or software with different filters (one set of filters for the outer IP header and another for the inner IP header), then it's more natural to model them as two different instances of the classifier LFB, as shown in Figure 8.b 💖
3.4.2. Configuring the LFB Topology ✨
While there's little doubt that an individual LFB must be configurable, the configurability question gets more complicated for the LFB topology 🌈 Since the LFB topology is really the graphic representation of the data paths within an FE, configuring the LFB topology means dynamically changing the data paths. That includes changing the LFBs along the data paths on an FE (e.g., creating/instantiating, updating, or deleting LFBs), and setting up or deleting interconnections between outputs of upstream LFBs and inputs of downstream LFBs 🔧
So why would the data paths on an FE ever change dynamically? 🤔 The data paths on an FE are set up by the CE to provide certain data plane services (e.g., Diffserv, VPN) to the network element's (NE) customers. The whole point of reconfiguring the data paths is to let the CE customize the services the NE delivers at run time 💅 The CE needs to change the data paths when service requirements change, like adding a new customer or when an existing customer changes their service. Note that not every data path change results in a change to the LFB topology graph, though 👀 Whether the graph changes depends on the approach used to map the data paths into the LFB topology. As discussed in Section 3.4.1, the topological approach and the encoded state approach can produce very different looking LFB topologies for the same data paths. In general, an LFB topology based on a pure topological approach is likely to see more frequent topology reconfiguration than one based on an encoded state approach. Even an LFB topology built entirely on an encoded state approach may still have to change its topology sometimes, for example to bypass some LFBs or insert new ones 🦋 Since a mix of these two approaches is used to model the data paths, LFB topology reconfiguration is considered an important aspect of the FE model 💜
We want to point out that allowing a configurable LFB topology in the FE model does not mandate that all FEs have this capability 🙈 Even if an FE supports a configurable LFB topology, the FE may impose limitations on what can actually be configured. Performance-optimized hardware implementations may have zero or very limited configurability, while FE implementations running on network processors may offer more flexibility and configurability. It's entirely up to the FE designers to decide whether the FE implements reconfiguration at all and, if so, how much 🛠️ Whether a simple runtime switch is used to enable or disable (i.e., bypass) certain LFBs, or more flexible software reconfiguration is used, is an implementation detail internal to the FE and outside the scope of the FE model. In either case, the CE(s) MUST be able to learn the FE's configuration capabilities 🚨 Therefore, the FE model MUST provide a mechanism for describing the LFB topology configuration capabilities of an FE. These capabilities may include (see Section 5 for full details):
- Which LFB classes the FE can instantiate
- The maximum number of instances of the same LFB class that can be created
- Any topological limitations, for example:
- The maximum number of instances of the same class, or any class, that can be created on any given branch of the graph
- Ordering restrictions on LFBs (e.g., any instance of LFB class A must always be downstream of any instance of LFB class B)
The CE needs some programming help to cope with the range of complexity 🧚 In other words, even when the CE is allowed to configure the LFB topology for the FE, the CE isn't expected to interpret an arbitrary LFB topology and figure out which specific service or application (e.g., VPN, Diffserv) the FE supports. However, once the CE understands the coarse capability of an FE, the CE MUST configure the LFB topology to implement the network service the NE is supposed to provide. So the mapping the CE has to understand goes from the high-level NE service to a specific LFB topology, not the other way around 🎯 The CE isn't expected to have the ultimate intelligence to translate any high-level service policy into configuration data for the FEs. It is conceivable, though, that within a given network service domain, a certain amount of intelligence can be programmed into the CE so it has a general understanding of the LFBs involved, allowing the translation from a high-level service policy to low-level FE configuration to happen automatically. This is considered an implementation issue internal to the control plane and outside the scope of the FE model, so it isn't discussed any further in this document 🌸
+----------+ +-----------+
---->| Ingress |---->|classifier |--------------+
| | |chip | |
+----------+ +-----------+ |
v
+-------------------------------------------+
+--------+ | Network Processor |
<----| Egress | | +------+ +------+ +-------+ |
+--------+ | |Meter | |Marker| |Dropper| |
^ | +------+ +------+ +-------+ |
| | |
+----------+-------+ |
| | |
| +---------+ +---------+ +------+ +---------+ |
| |Forwarder|<------|Scheduler|<--|Queue | |Counter | |
| +---------+ +---------+ +------+ +---------+ |
+--------------------------------------------------------------+
Figure 9: The capability of an FE as reported to the CE.Figure 9 shows an example of a QoS-enabled (quality-of-service) router with several line cards, each with a few ingress and egress ports, a specialized classification chip, and a network processor holding code for FE blocks like meter, marker, dropper, counter, queue, scheduler, and IPv4 forwarder 🍓 Some of the LFB topology is already fixed and has to stay static because of the physical layout of the line cards. For example, all of the ingress ports might be hardwired into the classification chip, so every packet flows from the ingress port into the classification engine. On the other hand, the LFBs on the network processor and their execution order are programmable 🤩 However, certain capacity limits and linkage constraints could exist between these LFBs. Examples of the capacity limits might be:
- 8 meters
- 16 queues in one FE
- The scheduler can handle at most 16 queues
The linkage constraints might dictate that:
- The classification engine may be followed by:
- A meter
- A marker
- A dropper
- A counter
- A queue or IPv4 forwarder, but not a scheduler
- Queues can only be followed by a scheduler
- A scheduler must be followed by the IPv4 forwarder
- The last LFB in the data path before going into the egress ports must be the IPv4 forwarder 💅✨
+-----+ +-------+ +---+
| A|--->|Queue1 |--------------------->| |
------>| | +-------+ | | +---+
| | | | | |
| | +-------+ +-------+ | | | |
| B|--->|Meter1 |----->|Queue2 |------>| |->| |
| | | | +-------+ | | | |
| | | |--+ | | | |
+-----+ +-------+ | +-------+ | | +---+
classifier +-->|Dropper| | | IPv4
+-------+ +---+ Fwd.
Scheduler
Figure 10: An LFB topology as configured
by the CE and accepted by the FE.okay so once the FE reports its capabilities and capacity limits to the CE, it's literally up to the CE to turn the QoS policy into a configuration that works well for the FE 💅✨. Figure 9 shows the FE capability, while Figure 10 and Figure 11 show two different topologies that the CE may request the FE to configure 🦋. Note that Figure 11 isn't fully drawn, because the inter-LFB links are there to hint at complexity without drawing in the endpoints of every single one 🕸️.
Queue1
+---+ +--+
| A|------------------->| |--+
+->| | | | |
| | B|--+ +--+ +--+ +--+ |
| +---+ | | | | | |
| Meter1 +->| |-->| | |
| | | | | |
| +--+ +--+ | IPv4
| Counter1 Dropper1 Queue2| +--+ Fwd.
+---+ | +--+ +--->|A | +-+
| A|---+ | |------>|B | | |
------>| B|------------------------------>| | +-->|C |->| |->
| C|---+ +--+ | +>|D | | |
| D|-+ | | | +--+ +-+
+---+ | | +---+ Queue3 | |Scheduler
Classifier1 | | | A|------------> +--+ | |
| +->| | | |-+ |
| | B|--+ +--+ +-------->| | |
| +---+ | | | | +--+ |
| Meter2 +->| |-+ |
| | | |
| +--+ Queue4 |
| Marker1 +--+ |
+---------------------------->| |---+
| |
+--+
Figure 11: Another LFB topology as configured
by the CE and accepted by the FE.Note that both the ingress and egress are omitted in Figure 10 and Figure 11 to keep things simple 🧚. The topology in Figure 11 is considerably more complex than Figure 10, but both are feasible within the FE capabilities, so the FE should accept either configuration request from the CE 💖.
4. Model and Schema for LFB Classes ✨
The main goal of the FE model is to give us an abstract, generic, modular, implementation-independent way to represent the FEs 🎀. This is done with the idea of LFBs, which are instantiated from LFB classes. LFB classes and their associated definitions are provided in a collection of XML documents. That collection is called an LFB class library, and each document in it is called an LFB class library document (or library document, for short). Each of the library documents MUST conform to the schema presented in this section. The schema here, and the rules for conforming to it, are the ones defined by the W3C in the definitions of XML schema in XML schema [Schema1] and XML schema DataTypes [Schema2]. The root element of the library document is the <LFBLibrary> element 👑.
It is not expected that library documents will be exchanged between FEs and CEs "over-the-wire" 🙈. But the model is an important reference for designing and developing the CEs (software) and FEs (mostly the software part) 💜. It will also serve as a design input when specifying the ForCES protocol elements for CE-FE communication 🌈.
The following sections describe the portions of an LFBLibrary XML document. The descriptions mainly give the semantic info you need to understand what the XML elements mean and how they're used 📖. The XML schema below gives the final definition of which elements are permitted and their base syntax. Unfortunately, because of the limits of English and XML, some constraints are described in the semantic sections and aren't fully captured in the XML schema, so you need both sets of info to build a compliant library document 😭.
4.1. Namespace
A namespace is needed to uniquely identify the LFB type in the LFB class library. The reference to the namespace definition is contained in Section 9, IANA Considerations 🍓.
4.2. <LFBLibrary> Element
The <LFBLibrary> element is the root element of all library documents 🌸. A library document contains a sequence of top-level elements. Here's the list of every element that can occur directly in the <LFBLibrary> element. If they occur, they have to occur in the order listed 💅.
<description>providing a text description of the purpose of the library document,<load>for loading information from other library documents,<frameDefs>for the frame declarations,<dataTypeDefs>for defining common data types,<metadataDefs>for defining metadata, and<LFBClassDefs>for defining LFB classes.
Each element is optional ✨. One library document may contain only metadata definitions, another may contain only LFB class definitions, and yet another may contain all of the above 🦋.
A library document can import other library documents if it needs to refer to definitions in the included document 🫶. This is kind of like the "#include" directive in the C programming language 🧚. Importing is expressed with <load> elements, which have to come before all of the above elements in the document. For unique referencing, each LFBLibrary instance document has a unique label defined in the "provide" attribute of the LFBLibrary element 🔥. Note that this is a ForCES inclusion, not an XML inclusion. The semantic content of the library referenced by the <load> element is included, not the XML content 💜. Also, when we conceptually process <load> elements, the whole set of documents loaded is treated as a single document for processing. A given document is included in this set only once, even if several <load> elements reference it, even from several different files 🎀. Because processing LFBLibrary information is not order dependent, the order for processing loaded elements is up to the implementor, as long as the total effect is as if all of the information from all the files were available for referencing when needed 🌈. Note that this kind of computer processing of ForCES model library documents may be helpful for various implementations, but it is not required to define the libraries, or for the actual operation of the protocol itself 🙈.
The following is a skeleton of a library document:
<?xml version="1.0" encoding="UTF-8"?>
<LFBLibrary xmlns="urn:ietf:params:xml:ns:forces:lfbmodel:1.0"
provides="this_library">
<description>
</description>
<!-- Loading external libraries (optional) -->
<load library="another_library"/>
...
<!-- FRAME TYPE DEFINITIONS (optional) -->
<frameDefs>
...
</frameDefs>
<!-- DATA TYPE DEFINITIONS (optional) -->
<dataTypeDefs>
...
</dataTypeDefs>
<!-- METADATA DEFINITIONS (optional) -->
<metadataDefs>
...
</metadataDefs>
<!--
-
-
LFB CLASS DEFINITIONS (optional) -->
<LFBCLassDefs>
</LFBCLassDefs>
</LFBLibrary>4.3. <load> Element
This element is used to refer to another LFB library document 🎀. Just like the "#include" directive in C, it makes the objects (metadata types, data types, etc.) defined in the referred library document available for referencing in the current document ✨.
The load element MUST contain the label of the library document to be included and MAY contain a URL to specify where the library can be retrieved. The load element can be repeated unlimited times. Here are three examples of <load> elements 💖:
<load library="a_library"/>
<load library="another_library" location="another_lib.xml"/>
<load library="yetanother_library"
location="http://www.example.com/forces/1.0/lfbmodel/lpm.xml"/>4.4. <frameDefs> Element for Frame Type Declarations
Frame names are used in the LFB definition to define the types of frames the LFB expects at its input port(s) and emits at its output port(s) 🦋. The optional <frameDefs> element in the library document contains one or more <frameDef> elements, each declaring one frame type 🌸.
Each frame definition MUST contain a unique name (NMTOKEN) and a brief synopsis. In addition, an optional detailed description MAY be provided.
Uniqueness of frame types MUST be ensured among frame types defined in the same library document and in all directly or indirectly included library documents. 🔥
The following example defines two frame types 🧚:
<frameDefs>
<frameDef>
<name>ipv4</name>
<synopsis>IPv4 packet</synopsis>
<description>
This frame type refers to an IPv4 packet.
</description>
</frameDef>
<frameDef>
<name>ipv6</name>
<synopsis>IPv6 packet</synopsis>
<description>
This frame type refers to an IPv6 packet.
</description>
</frameDef>
...
</frameDefs>4.5. <dataTypeDefs> Element for Data Type Definitions ✨
okay so the (optional) <dataTypeDefs> element is where you define data types that everyone keeps reaching for 💅 It holds one or more <dataTypeDef> elements, and each one defines a data type with a unique name. Those types can then show up in a couple of places in the library documents:
- Defining other data types
- Defining components of LFB classes
It's basically the shared header file of the whole thing 🧚
Each <dataTypeDef> element MUST contain a unique name (NMTOKEN), a brief synopsis, and a type definition element. The name MUST be unique among all data types defined in the same library document and in any directly or indirectly included library documents. The <dataTypeDef> element MAY also include an optional longer description, for example:
<dataTypeDefs>
<dataTypeDef>
<name>ieeemacaddr</name>
<synopsis>48-bit IEEE MAC address</synopsis>
... type definition ...
</dataTypeDef>
<dataTypeDef>
<name>ipv4addr</name>
<synopsis>IPv4 address</synopsis>
... type definition ...
</dataTypeDef>
...
</dataTypeDefs>There are two kinds of data types: atomic and compound. Atomic data types are the ones for single-value variables (think integer, string, byte array) 🌸
The following built-in atomic data types are provided. You can also make more atomic data types with the <typeRef> and <atomic> elements 🎀
<name> Meaning
---- -------
char 8-bit signed integer
uchar 8-bit unsigned integer
int16 16-bit signed integer
uint16 16-bit unsigned integer
int32 32-bit signed integer
uint32 32-bit unsigned integer
int64 64-bit signed integer
uint64 64-bit unsigned integer
boolean A true / false value where
0 = false, 1 = true
string[N] A UTF-8 string represented in at most
N octets
string A UTF-8 string without a configured
storage length limit
byte[N] A byte array of N bytes
octetstring[N] A buffer of N octets, which MAY
contain fewer than N octets. Hence
the encoded value will always have
a length.
float32 32-bit IEEE floating point number
float64 64-bit IEEE floating point numberThese built-in types are great for metadata or LFB attributes, but they're also the building blocks for brand new types 🦋 The boolean type gets its own spot because it's so common, even though you could build it by sub-ranging the uchar type, which is covered under atomic types (Section 4.5.2).
Compound data types can build on atomic types and on other compound types. There are four ways to define one 💖 It can be an array of components of some compound or atomic type. It can be a structure of named components of compound or atomic types (cf. C structures). It can be a union of named components of compound or atomic types (cf. C unions). Or it can be an augmentation (explained in Section 4.5.7) of an existing compound type.
Since the ForCES protocol is going to be getting and setting component values, every atomic type used here must be able to be conveyed in the ForCES protocol. The protocol also needs a way to convey compound types. The details of those representations are for the ForCES protocol [RFC5810] document to define, not the model document 🫶 Strings and octetstrings have to be conveyed with their length, because they aren't delimited, the value doesn't include its own length, and these items are variable length.
About strings: this model sets a small set of restrictions and definitions on how they're structured 🧸 String and octetstring length limits can be specified in the LFB class definitions. The component properties for string and octetstring components also hold actual lengths and length limits. Having the limits in both places is on purpose, so implementations can use smaller limits than the maximums in the LFB class definition. In every case, lengths are in octets, not characters. In terms of protocol operation, as long as the specified length is within what the FE supports, the FE stores the string contents exactly as the CE provided them, and hands those same contents back when asked. The FE doesn't do any canonicalization, transformations, or equivalences ✨ Components of type string (or string[n]) MAY be used to hold identifiers for correlation with components in other LFBs. In that case, an exact octet-for-octet match is used, and neither the FE nor the CE uses any equivalences when matching. The ForCES protocol [RFC5810] doesn't perform or require validation of UTF-8 string content. Still, UTF-8 strings SHOULD be encoded in the shortest form, to avoid the potential security issues described in [UNICODE] 🚨 Any entity displaying these strings is expected to do its own validation (for example, checking for correct multi-byte characters, and making sure the string doesn't end in the middle of a multi-byte sequence). Specific LFB class definitions MAY restrict the valid contents of a string to suit the particular usage. For example, a component that holds a DNS name would only be allowed to hold octets valid in such a name. FEs should validate the contents of SET requests for such restricted components at the time the set is performed, the same way range checks are done for range-limited components. The ForCES protocol behavior defines the normative processing for requests using that protocol.
For the actual type in a <dataTypeDef> element, you can use these elements: <typeRef>, <atomic>, <array>, <struct>, and <union>.
The predefined type alias sits somewhere between atomic and compound types 🔥 Alias lets a component inside an LFB be an indirect reference to another component, inside the same or a different LFB class or instance. The alias component behaves like a structure where one component has special behavior. Because that special behavior is tied to the other parts of the structure, the compound result gets treated as a predefined construct.
4.5.1. <typeRef> Element for Renaming Existing Data Types
The <typeRef> element refers to an existing data type by its name 🍓 The referred data type MUST be defined either in the same library document or in one of the included library documents. If the referred data type is atomic, the newly defined type is also regarded as atomic. If the referred data type is compound, the new type is also compound. Here are some usage examples:
<dataTypeDef>
<name>short</name>
<synopsis>Alias to int16</synopsis>
<typeRef>int16</typeRef>
</dataTypeDef>
<dataTypeDef>
<name>ieeemacaddr</name>
<synopsis>48-bit IEEE MAC address</synopsis>
<typeRef>byte[6]</typeRef>
</dataTypeDef>4.5.2. <atomic> Element for Deriving New Atomic Types
The <atomic> element lets you define a new atomic type from an existing atomic type, by applying range restrictions and/or giving special enumerated values 💜 Heads up: the <atomic> element can only use atomic types as base types, and its result MUST be another atomic type ⭐
For example, this snippet defines a new "dscp" data type:
<dataTypeDef>
<name>dscp</name>
<synopsis>Diffserv code point.</synopsis>
<atomic>
<baseType>uchar</baseType>
<rangeRestriction>
<allowedRange min="0" max="63"/>
</rangeRestriction>
<specialValues>
<specialValue value="0">
<name>DSCP-BE</name>
<synopsis>Best Effort</synopsis>
</specialValue>
...
</specialValues>
</atomic>
</dataTypeDef>4.5.3. <array> Element to Define Arrays ✨
okay bestie, the <array> element is how you make a brand new compound data type that's basically a list of something 📋 The something can be a compound or an atomic type. People in these docs call arrays "tables" or "arrays" interchangeably, and it doesn't mean anything different 💅 The entry type can be either a type you already named (using <typeRef>), or an unnamed type you define right inside the <array> using any of <atomic>, <array>, <struct>, or <union> 🎀
Your array can be "fixed-size" or "variable-size", and you pick that with the type attribute on <array>. The default is "variable-size" 🌸 For variable-size arrays you can add an optional maxlength attribute to set the max length. Here's the tea: maxlength is for encoding semantic limits, not implementation limits 💀 Implementation stuff should be handled by capability components of LFB classes, and it should never be put in as the maxlength of a data type array that's supposed to be unlimited in size 🙈
For fixed-size arrays, a length attribute MUST be provided that sets the constant size of the array 💖
No matter what, the result is always a compound type, even if the array only has a fixed size of 1 🧚
Arrays MUST only be subscripted by integers, and they're presumed to start at index 0 🔢
On top of subscripts, arrays MAY be declared to have content keys 🔑 Declaring them does a couple of things:
- Any declared key can be used in the ForCES protocol to pick out a component for operations. For the full details, check the ForCES protocol [RFC5810] 🦋
- In any instance of the array, each declared key MUST be unique within that instance. So no two components of an array can have the same values across all the fields that make up a key 👑
Each key gets a keyID so the ForCES protocol [RFC5810] can use it, and the unique key is made by combining one or more specified key fields 💜 If you've got an array of an atomic type with unique values and you want to reference entries by those values, the key field identifier MAY be "", which means the array entry *is the key ✨ If the value type of the array is a structure or another array, the key is one or more components of that value type, and each one gets identified by name 🌈 Since the field MAY be a component of the contained structure, or a component of a component, or nested even deeper, the field name is really a sequence of component identifiers joined together with decimal points (".") 🫶 The syntax for key field identification comes right after the array examples, so hang tight 🍓
Here's a fixed-size array with a predefined data type as the content type 💅
<dataTypeDef>
<name>dscp-mapping-table</name>
<synopsis>
A table of 64 DSCP values, used to re-map code space.
</synopsis>
<array type="fixed-size" length="64">
<typeRef>dscp</typeRef>
</array>
</dataTypeDef>Next up is a variable-size array with an upper limit on its size 🎀
<dataTypeDef>
<name>mac-alias-table</name>
<synopsis>A table with up to 8 IEEE MAC addresses</synopsis>
<array type="variable-size" maxlength="8">
<typeRef>ieeemacaddr</typeRef>
</array>
</dataTypeDef>Now an array with a local, unnamed content type definition 🧚
<dataTypeDef>
<name>classification-table</name>
<synopsis>
A table of classification rules and result opcodes.
</synopsis>
<array type="variable-size">
<struct>
<component componentID="1">
<name>rule</name>
<synopsis>The rule to match</synopsis>
<typeRef>classrule</typeRef>
</component>
<component componentID="2">
<name>opcode</name>
<synopsis>The result code</synopsis>
<typeRef>opcode</typeRef>
</component>
</struct>
</array>
</dataTypeDef>In that last one, every entry of the array is a <struct> with two components, "rule" and "opcode" 🌸
And here's a table of IP prefix info that you can get to with a multi-field content key built from the IP address, the prefix length, and the information source 🔥 That means in any instance of this table, no two entries can share the same IP address, prefix length, and information source 😭
<dataTypeDef>
<name>ipPrefixInfo_table</name>
<synopsis>
A table of information about known prefixes
</synopsis>
<array type="variable-size">
<struct>
<component componentID="1">
<name>address-prefix</name>
<synopsis>the prefix being described</synopsis>
<typeRef>ipv4Prefix</typeRef>
</component>
<component componentID="2">
<name>source</name>
<synopsis>
the protocol or process providing this information
</synopsis>
<typeRef>uint16</typeRef>
</component>
<component componentID="3">
<name>prefInfo</name>
<synopsis>the information we care about</synopsis>
<typeRef>hypothetical-info-type</typeRef>
</component>
</struct>
<contentKey contentKeyID="1">
<contentKeyField> address-prefix.ipv4addr</contentKeyField>
<contentKeyField> address-prefix.prefixlen</contentKeyField>
<contentKeyField> source</contentKeyField>
</contentKey>
</array>
</dataTypeDef>Quick side note: the keyField elements could also have just been address-prefix and source, since every field of address-prefix is being used anyway 🙈
4.5.3.1. Key Field References 🔑
okay so to use key declarations, you have to refer to components that might be nested inside other components of the array 🪆 If there are nested arrays, you could even use an array element as a key, but you'd need to be extra careful to make sure it stays unique 😬
The key is the combination of the values of each field declared in a keyField element 💜
So the value of a keyField element MUST be a sequence of field identifiers joined together with a "." (period) character 💅 Whitespace is allowed and gets ignored 🌸
What counts as a valid string for a single field identifier depends on the current context 🧠 At the very start, in an array key declaration, the context is the type of the array. After that, the context keeps moving to whatever type the field identifiers processed so far have selected in the current key field declaration 🦋
If the current context is an array (say you're declaring a key for an array whose content is itself an array), then the only valid value for the field identifier is an explicit number 🔢
If the current context is a structure, the valid field identifiers are the names of that structure's components 🎀 There's a special case: when you're declaring a key for an array that holds an atomic type, and that content is unique and gets used as the key, the value "*" MUST be used as the single key field identifier ✨
When you reference array or structure elements, it's possible to build keyFields that don't actually exist 💀 You SHOULD never reference optional structure components in a keyField 🙅♀️ For references to array elements, you have to make sure the array elements you need actually exist when you create or modify the overall array element. If you don't, FEs will return errors on the creation attempt 😭
4.5.4. <struct> Element to Define Structures 🧱
A structure is made up of a collection of data components 🫧 Each data component has a data type (either an atomic type or an existing compound type) and gets a name that's unique within the scope of the compound data type being defined 💖 These are basically the same thing as "struct" in C, etc. 🌷 The components get defined using <component> elements 🎀 A <struct> element MAY contain an optional derivation indication, which is a <derivedFrom> element 🌈 The structure definition MUST contain a sequence of one or more <component> elements 👑
The actual type of a component can be defined by referring to an existing type (using <typeRef>), or it can be a locally defined, unnamed type made with any of <atomic>, <array>, <struct>, or <union> 🧚
The <component> element MUST include a componentID attribute 🔢 That gives the numeric ID for this component, which the protocol uses 🦋 The <component> MUST contain a component name and a synopsis 📝 It MAY contain a <description> element with a textual description of the component 💜 The definition MAY also include an <optional> element, which marks the component as optional 🌸 And the definition MUST contain elements that define the component's data type, as described above 💅
For a dataTypeDef of a struct, the structure definition MAY be inherited from, and augment, a previously defined structured type 🪆 You do this by including the optional derivedFrom attribute in the struct declaration before the definition of the augmenting or replacing components 🍓 Section 4.5.7 walks through how this works in more detail 🙌
The componentID attribute for different components in a structure (or in an LFB) MUST be distinct 🔑 They don't have to be in order, and they don't have to be sequential 🫶 For human readability and easier maintenance, it's usual to define at least sequential sets of values, but that's for human ease, not a model or protocol requirement 🤓
The result is always a compound type, even when the <struct> only has one field 💅
Here's an example 🎀
<dataTypeDef>
<name>ipv4prefix</name>
<synopsis>
IPv4 prefix defined by an address and a prefix length
</synopsis>
<struct>
<component componentID="1">
<name>address</name>
<synopsis>Address part</synopsis>
<typeRef>ipv4addr</typeRef>
</component>
<component componentID="2">
<name>prefixlen</name>
<synopsis>Prefix length part</synopsis>
<atomic>
<baseType>uchar</baseType>
<rangeRestriction>
<allowedRange min="0" max="32"/>
</rangeRestriction>
</atomic>
</component>
</struct>
</dataTypeDef>4.5.5. <union> Element to Define Union Types 🫧
This one's giving C vibes 🌈 Like the union declaration in C, this construct lets you define overlay types 💜 Its format is identical to the <struct> element 🎀
No matter what, the result is always a compound type, even when the union only has one element 👑
4.5.6. <alias> Element 🦋
okay so sometimes a component in an LFB or structure needs to point at information (a component) living in other LFBs 👀 like, an ARP LFB can share the IP->MAC Address table with the local transmission LFB without making a copy, which is so efficient it's giving 💅. same energy for a traffic measurement LFB sharing its info with a traffic enforcement LFB 🔥. the <alias> declaration is what builds all this ✨. it tells the CE and FE that any manipulation of the defined data is actually manipulation of data that's defined to exist in some specified part of some other LFB instance 🫶
the content of an <alias> element MUST be a named type 🎀. whatever component the alias references (which gets determined by the alias component properties, as we'll see below) has to be the same type as the one declared for the alias 💖. that's how the CE or FE knows what type of info comes back when they dereference the alias component 🧚. the type can be a base type or a derived type 🌈. the actual value an alias points to is called its target 🎯. when a GET or SET operation references the alias element, the target's value is returned or replaced 🍓. write access to an alias element is permitted only if write access to both the alias and the target is permitted 🔒
the target of a component declared by an <alias> element is determined by the info in the component's properties 📋. like all components, the properties include the support / read / write permission for the alias 💜. on top of that, there are a few fields (components) in the alias properties that define the target: the ID of the LFB class of the target, the ID of the LFB instance of the target, and a sequence of integers representing the path within the target LFB instance to the target component 🦋. the type of the target element must match the declared type of the alias 🌸. details on the alias property structure are in Section 4.8 of this document, on properties 📚
ngl, the read / write property of the alias refers to the value 👀. the CE can only figure out whether it can write the target selection properties of the alias by actually attempting that write operation 🙈. (property components don't have properties of their own, so no nesting here 💅)
4.5.7. Augmentations ✨
compound types can also be defined as augmentations of existing compound types 🧩. if the existing compound type is a structure, augmentation MAY add new elements to the type 🌷. the type of an existing component MAY be replaced in the definition of an augmenting structure, but it MAY only be replaced with an augmentation derived from the current type of that existing component 💫. an existing component cannot be deleted 🚫. if the existing compound type is an array, augmentation means augmenting the array element type 🎀
augmentation MUST NOT be applied to unions 🙅♀️
and this is the big payoff: augmentations stay backward compatible with the compound type they came from 👑. so they're super useful for defining components for LFB subclasses while keeping that compatibility 🫶. besides adding new components to a class, the data type of an existing component MAY be replaced by an augmentation of that component and still meet the compatibility rules for subclasses 🌈. this compatibility constraint is exactly why augmentations can't be applied to unions 💀
for example 🧁, say we have a simple base LFB class A that only has one component (comp1) of type X. one way to derive class A1 from A is to just add a second component (of any type) 🍓. another way to derive a class A2 from A is to replace the original component (comp1) of type X with one of type Y, where Y is an augmentation of X ✨. both A1 and A2 are backward compatible with class A 💖
the syntax for augmentations is to include a <derivedFrom> element in a structure definition, which says what structure type is being augmented 🎯. component names and component IDs for new components within the augmentation MUST NOT be the same as the ones in the structure type being augmented 🙅♀️. for those components where an existing component's data type is being replaced with a suitable augmenting data type, the existing component name and component ID MUST be used in the augmentation 🔁. other than that constraint on existing elements, there's no requirement that new component IDs be sequential with, greater than, or in any other specific relationship to the existing component IDs, except different 🧚. it's expected that using values that are sequential within an augmentation, and distinct from the ones already used, will be a common move to make things more human readable 📖💜
4.6. <metadataDefs> Element for Metadata Definitions 🌸
the (optional) <metadataDefs> element in the library document contains one or more <metadataDef> elements 🍓. each <metadataDef> element defines a metadatum 💅
each <metadataDef> element MUST contain a unique name (NMTOKEN) 🏷️. uniqueness is defined over all metadata defined in this library document and in all directly or indirectly included library documents 🌐. the <metadataDef> element MUST also contain a brief synopsis, the tag value to be used for this metadata, and value type definition info 🎀. only atomic data types can be used as value types for metadata 🔬. the <metadataDef> element MAY contain a detailed description element 📝
there are two forms of type definitions allowed 🦋. the first form uses the <typeRef> element to refer to an existing atomic data type that's defined in the <dataTypeDefs> element of the same library document or in one of the included library documents 💖. it's used exactly like it is in <dataTypeDef> elements, except here it can only refer to atomic types 🙈. that restriction isn't enforced by the XML schema, fyi 💀
the second form is an explicit type definition using the <atomic> element 🧩. it's used here the same way it's used in <dataTypeDef> elements ✨
here's an example showing both usages 👀
<metadataDefs>
<metadataDef>
<name>NEXTHOPID</name>
<synopsis>Refers to a Next Hop entry in NH LFB</synopsis>
<metadataID>17</metadataID>
<typeRef>int32</typeRef>
</metadataDef>
<metadataDef>
<name>CLASSID</name>
<synopsis>
Result of classification (0 means no match).
</synopsis>
<metadataID>21</metadataID>
<atomic>
<baseType>int32</baseType>
<specialValues>
<specialValue value="0">
<name>NOMATCH</name>
<synopsis>
Classification didn't result in match.
</synopsis>
</specialValue>
</specialValues>
</atomic>
</metadataDef>
</metadataDefs>4.7. <LFBClassDefs> Element for LFB Class Definitions 🎀
the (optional) <LFBClassDefs> element can be used to define one or more LFB classes using <LFBClassDef> elements 📚. each <LFBClassDef> element MUST define an LFB class and include the following elements 💖:
<name>gives the symbolic name of the LFB class. Example:"ipv4lpm"🏷️<synopsis>gives a short synopsis of the LFB class. Example:"IPv4 Longest Prefix Match Lookup LFB"✨<version>is the version indicator 🔢<derivedFrom>is the inheritance indicator 🧬<inputPorts>lists the input ports and their specs 🔌<outputPorts>lists the output ports and their specs 🔌<components>defines the operational components of the LFB ⚙️<capabilities>defines the capability components of the LFB 🌟<description>contains the operational spec of the LFB 📝- the LFBClassID attribute of the
LFBClassDefelement defines the ID for this class. these must be globally unique 🌍 <events>defines the events that instances of this LFB can generate 🔔
LFB class names must be unique 💅, so other documents can reference the classes by name and human readers can understand those references too 🧠. a complex naming structure could be created, but simplicity is preferred 🫶. as given in the IANA Considerations section of this document, IANA maintains a registry of LFB class names and class identifiers, along with a reference to the document defining the class 📜
below is a skeleton of an example LFB class definition 👀. heads up, to keep from complicating the XML schema, the order of elements in the class definition is fixed. elements, if they appear, must appear in the order shown 🙈
<LFBClassDefs>
<LFBClassDef LFBClassID="12345">
<name>ipv4lpm</name>
<synopsis>IPv4 Longest Prefix Match Lookup LFB</synopsis>
<version>1.0</version>
<derivedFrom>baseclass</derivedFrom>
<inputPorts>
...
</inputPorts>
<outputPorts>
...
</outputPorts>
<components>
...
</components>
<capabilities>
...
</capabilities>
<events>
...
</events>
<description>
This LFB represents the IPv4 longest prefix match lookup
operation.
The modeled behavior is as follows:
Blah-blah-blah.
</description>
</LFBClassDef>
...
</LFBClassDefs>the individual components and capabilities get componentIDs for use by the ForCES protocol 🦋. these parallel the componentIDs used in structs, and they're used the same way 💫. component and capability componentIDs must be unique within the LFB class definition 🔑
note that the <name>, <synopsis>, and <version> elements are required, while all other elements are optional in <LFBClassDef> 📌. however, when they're present, they must occur in the order above 🙏
the componentID attribute for different items in an LFB class definition (or components in a struct) MUST be distinct 🚫🔁. they don't need to be in order, and they don't need to be sequential 🌈. for clarity and ease of maintenance, it's usual to define at least sequential sets of values 🧁. but that's for human ease, not a model or protocol requirement, so no stress 💜
4.7.1. <derivedFrom> Element to Express LFB Inheritance 👑
the optional <derivedFrom> element can be used to indicate that this class is a derivative of some other class 🧬. the content of this element MUST be the unique name (<name>) of another LFB class 🏷️. the referred LFB class MUST be defined in the same library document or in one of the included library documents 📚. if there's no <derivedFrom>, the class is conceptually derived from the common, empty, base class 🫧
it's assumed that a derived class is backward compatible with its base class 🫶. a derived class MAY add components to a parent class, but it can't delete components 🙅♀️. this also applies to input and output ports, events, and capabilities 🔌🔔🌟
4.7.2. <inputPorts> Element to Define LFB Inputs ✨
Okay bestie, the optional <inputPorts> element is where you define your input ports 💖 An LFB class MAY have zero, one, or more inputs. If the LFB class has no input ports, the <inputPorts> element MUST be omitted 🙈 Otherwise it can hold one or more <inputPort> elements, one for each port or port group. Most LFBs will have exactly one input, so that's the main vibe 💅 Multiple inputs with the same input type get modeled as one input group. Input groups are defined the same way as input ports, using <inputPort>, and the only difference is an optional "group" attribute.
Multiple inputs with different input types should be avoided if possible (see discussion in Section 4.7.3) 🫶 Some special LFBs have no inputs at all. A packet generator is one of them, since it doesn't need an input 🧚
Single input ports and input port groups are both defined by <inputPort>, and they're only told apart by that optional "group" attribute 🦋
The <inputPort> element MUST contain the following elements:
<name>gives the symbolic name of the input. Example: "in". This symbolic name only has to be unique within the scope of the LFB class 🎀<synopsis>is a brief description of the input. Example: "Normal packet input" 🌸<expectation>lists all the allowed frame formats. Example: {"ipv4" and "ipv6"}. This list should refer to names specified in the<frameDefs>element of the same library document, or in any included library documents. The<expectation>element can also give a list of required metadata. Example: {"classid", "vpnid"}. This list should refer to names of metadata defined in the<metadataDefs>element of the same library document, or in any included library documents. For each metadatum, it must be specified whether it's required or optional. For each optional metadatum, a default value must be specified, and the LFB uses that default if the metadatum isn't provided with a packet 💜
In addition, the optional "group" attribute of the <inputPort> element can say whether the port can behave as a port group, meaning it's allowed to be instantiated. A "true" value means yes (the default is "false") ✨
Here's an example <inputPorts> element with two input ports, where the second one is an input port group:
<inputPorts>
<inputPort>
<name>in</name>
<synopsis>Normal input</synopsis>
<expectation>
<frameExpected>
<ref>ipv4</ref>
<ref>ipv6</ref>
</frameExpected>
<metadataExpected>
<ref>classid</ref>
<ref>vifid</ref>
<ref dependency="optional" defaultValue="0">vrfid</ref>
</metadataExpected>
</expectation>
</inputPort>
<inputPort group="true">
... another input port ...
</inputPort>
</inputPorts>For each <inputPort>, the frame type expectations are defined by the <frameExpected> element, using one or more <ref> elements (see the example above). When several frame types are listed, it means "one of these" is expected. A packet of any other frame type is regarded as incompatible with this input port of the LFB class. The example above lists two expected frame types: "ipv4" and "ipv6" 👑
Metadata expectations go in the <metadataExpected> element. In its simplest form, it contains a list of <ref> elements, each one referring to a metadatum. When several metadata are listed by <ref> elements, it means "all of these" must be received with each packet, except for metadata marked as "optional" with the "dependency" attribute of the matching <ref> element. For a metadatum that's specified as "optional", a default value MUST be provided using the "defaultValue" attribute. The example above lists three expected metadata: two are mandatory ("classid" and "vifid") and one is optional ("vrfid") 🍓
The schema also allows for more complex metadata expectations. For example, with the <one-of> element you can say that at least one of a list of metadata must be present with any packet. Here's how that looks:
<metadataExpected>
<one-of>
<ref>prefixmask</ref>
<ref>prefixlen</ref>
</one-of>
</metadataExpected>The example above says that either "prefixmask" or "prefixlen" must be provided with any packet 🌈
The two forms can also be combined, like this:
<metadataExpected>
<ref>classid</ref>
<ref>vifid</ref>
<ref dependency="optional" defaultValue="0">vrfid</ref>
<one-of>
<ref>prefixmask</ref>
<ref>prefixlen</ref>
</one-of>
</metadataExpected>The schema can get even more complicated for metadata expectations, but we won't go into those here 🙈
4.7.3. <outputPorts> Element to Define LFB Outputs 🔥
The optional <outputPorts> element is used to define output ports. An LFB class MAY have zero, one, or more outputs. If the LFB class has no output ports, the <outputPorts> element MUST be omitted. If it's there, the <outputPorts> element MUST contain one or more <outputPort> elements, one for each port or port group. If there are multiple outputs with the same output type, we model them as an output port group. Some special LFBs have no outputs at all (the Dropper is one) 💀
Single output ports and output port groups are both defined by the <outputPort> element. They're only told apart by an optional "group" attribute 🦋
The <outputPort> element MUST contain the following elements:
<name>gives the symbolic name of the output. Example: "out". The symbolic name only has to be unique within the scope of the LFB class 🎀<synopsis>is a brief description of the output port. Example: "Normal packet output" 🌸<product>lists the allowed frame formats. Example: {"ipv4", "ipv6"}. This list should refer to symbols specified in the<frameDefs>element of the same library document, or in any included library documents. The<product>element MAY also contain the list of emitted (generated) metadata. Example: {"classid", "color"}. This list should refer to names of metadata specified in the<metadataDefs>element of the same library document, or in any included library documents. For each generated metadatum, it should be specified whether it's always generated or only generated under certain conditions. This info is important when you're checking compatibility between LFBs 💅
In addition, the optional "group" attribute of the <outputPort> element can say whether the port can behave as a port group, meaning it's allowed to be instantiated. A "true" value means yes (the default is "false") ✨
The following example has two output ports, where the second one is an output port group:
<outputPorts>
<outputPort>
<name>out</name>
<synopsis>Normal output</synopsis>
<product>
<frameProduced>
<ref>ipv4</ref>
<ref>ipv4bis</ref>
</frameProduced>
<metadataProduced>
<ref>nhid</ref>
<ref>nhtabid</ref>
</metadataProduced>
</product>
</outputPort>
<outputPort group="true">
<name>exc</name>
<synopsis>Exception output port group</synopsis>
<product>
<frameProduced>
<ref>ipv4</ref>
<ref>ipv4bis</ref>
</frameProduced>
<metadataProduced>
<ref availability="conditional">errorid</ref>
</metadataProduced>
</product>
</outputPort>
</outputPorts>The frame types and metadata each port produces are defined inside the <product> element of each <outputPort>. Inside <product>, the list of frame types the port produces goes in the <frameProduced> element. When more than one frame is listed, it means "one of" these frames will be produced 🌟
The metadata produced with each packet goes in the optional <metadataProduced> element of the <product>. In its simplest form, it contains a list of <ref> elements, each one referring to a metadatum type. That list means "all of" these metadata are provided with each packet, except for those listed with the optional "availability" attribute set to "conditional". Just like the <metadataExpected> element of the <inputPort>, the <metadataProduced> element supports more complex forms, which we won't dig into here 🦋
4.7.4. <components> Element to Define LFB Operational Components ✨
okay so the LFB components are basically the operational parameters the CEs need to be able to see 👀 think flags, single-value args, complex args, and tables. just know this is ONLY the stuff the CEs actually need to see. any internal variables the implementation keeps to itself aren't components and aren't covered here 🫶
some examples of LFB components, bestie:
- Configurable flags and switches that pick between operational modes of the LFB 🔥
- Number of inputs or outputs in a port group 🦋
- Various configurable lookup tables, like interface tables, prefix tables, classification tables, DSCP mapping tables, MAC address tables, etc. 🗂️
- Packet and byte counters 💜
- Various event counters 📈
- Number of current inputs or outputs for each input or output group 🌸
the ForCES model lets you set access permission restrictions on what the CE can do with an LFB component. the model supports these categories:
- No-access components. This is useful for completeness, and for defining objects that other things use but that the CE can't directly reference. It's also useful for an FE that's reporting certain defined (and usually accessible) components as not supported for CE access. 🙈
- Read-only components. 👀
- Read-write components. 💅
- Write-only components. This could be any configurable data where the CEs don't get read capability (for example, the security key information). 🔐
- Read-reset components. The CE can read and reset this resource, but it can't set it to an arbitrary value. Example: Counters. 🧼
- Firing-only components. A write attempt to this resource triggers some specific actions in the LFB, but the value that was actually written gets ignored. 🚀
the LFB class MUST define only one possible access mode for a given component. no mixing and matching, periodt 💅
the components of the LFB class are listed in the <components> element. each component gets its own <component> element. a <component> element contains some or all of the following elements, and some of them are mandatory:
<name>MUST occur, and it defines the name of the component. this name must be unique among the components of the LFB class. Example: "version". 🏷️<synopsis>is also mandatory, and it gives a brief description of what the component is for. ✨<optional/>is an optional element, and if it's present it means this component is optional. 🎀- The data type of the component can be defined either by referring to a predefined data type or by giving a local definition of the type. The first one uses the
<typeRef>element, which MUST NOT be confused with a local definition 💖 (wait, I'm kidding, the original just says it must refer to the unique name of an existing data type). It must refer to the unique name of an existing data type defined in the<dataTypeDefs>element in the same library document, or in any of the included library documents. When the data type is defined locally (an unnamed type), you can use one of these:<atomic>,<array>,<struct>, or<union>. They work exactly the same way they do inside<dataTypeDef>elements (see Section 4.5). Some form of data type definition MUST be included in the component definition. 🧩 - The
<defaultValue>element is optional, and if it's present it's used to specify a default value for a component. If a default value is specified, the FE must ensure the component has that value when the LFB is initialized or reset. If no default value is specified for a component, the CE MUST make no assumptions about what the value of the component will be upon initialization. If the CE needs to know what it is, it must either read the value or set the value. 🤷♀️ - The
<description>element MAY also appear. If it's included, it gives a longer description of the meaning or usage of the particular component being defined. 📝
the <component> element also MUST have a componentID attribute, which is a numeric value used by the ForCES protocol. 🔢
on top of the elements above, the <component> element has an optional "access" attribute. it can take any of these values: "read-only", "read-write", "write-only", "read-reset", and "trigger-only". the default access mode is "read-write". 💖
the CE can figure out whether optional components are supported, and whether read-write components can actually be written, by reading the property information of that component for a given LFB instance. an access control setting of "trigger-only" means the component is only included for use in event detection. 🚨
the following example defines two components for an LFB:
<components>
<component access="read-only" componentID="1">
<name>foo</name>
<synopsis>number of things</synopsis>
<typeRef>uint32</typeRef>
</component>
<component access="read-write" componentID="2">
<name>bar</name>
<synopsis>number of this other thing</synopsis>
<atomic>
<baseType>uint32</baseType>
<rangeRestriction>
<allowedRange min="10" max="2000"/>
</rangeRestriction>
</atomic>
<defaultValue>10</defaultValue>
</component>
</components>so the first component ("foo") is a read-only 32-bit unsigned integer, defined by referring to the built-in "uint32" atomic type 🌈 the second one ("bar") is also an integer, but it uses the <atomic> element to add range restrictions. it has a read-write access mode, so it can be both read and written. bar gets a default value of 10. even though bar is read-write, some implementations MAY offer only more restrictive access, and that would be reported in the component properties. 🎀
not every component is going to exist at all times in a particular implementation. the capabilities will often show that a component doesn't exist, but CEs may still try to reference non-existent or non-permitted components anyway. the ForCES protocol mechanisms should include appropriate error indicators for this case. 🚫
the mechanism above for non-supported components can also apply when someone tries to reference non-existent array elements or to set read-only components. 🙌
4.7.5. <capabilities> Element to Define LFB Capability Components ✨
the LFB class spec gives the FE implementation some flexibility in how the LFB class gets implemented. for example, an instance might have some limitations that aren't inherent to the class definition, and are just the result of implementation limitations. some of these limitations are captured by the property information of the LFB components. the model also allows for the idea of additional capability information. 🧠
that capability-related info is expressed by the capability components of the LFB class. capability components are always read-only attributes, and they're listed in a separate <capabilities> element inside the <LFBClassDef>. the <capabilities> element contains one or more <capability> elements, and each one defines one capability component. the format of a <capability> element is almost the same as a <component> element, with two differences: it doesn't have the access mode attribute (because it's always read-only), and it doesn't have the <defaultValue> element (because default values don't apply to read-only attributes). 💅
some examples of capability components:
- The version of the LFB class this LFB instance complies with 📌
- Supported optional features of the LFB class 🌟
- Maximum number of configurable outputs for an output group 🍓
- Metadata pass-through limitations of the LFB 🫧
- Additional range restriction on operational components 🦋
the following example lists two capability attributes:
<capabilities>
<capability componentID="3">
<name>version</name>
<synopsis>
LFB class version this instance is compliant with.
</synopsis>
<typeRef>version</typeRef>
</capability>
<capability componentID="4">
<name>limitBar</name>
<synopsis>
Maximum value of the "bar" attribute.
</synopsis>
<typeRef>uint16</typeRef>
</capability>
</capabilities>4.7.6. <events> Element for LFB Notification Generation ✨
The <events> element is where we list every occurrence that can make an instance of this LFB class send a notification up to the CE 🔔. If you want the big-picture tour first, check out Section 3.2.5. It's giving organised 💅
The <events> element holds 0 or more <event> elements, and each one declares a single event 🦋. The <event> element has an eventID attribute giving the unique (per LFB class) ID of the event. Each event will include:
<eventTarget>element indicating which LFB field (component) is tested to generate the event.<condition>element indicating what condition on the field will generate the event from a list of defined conditions.<eventReports>element indicating what values are to be reported in the notification of the event.
Okay, the example below shows all the different constructs in action 🌸
The <events> element has a baseID attribute, which normally looks like <events baseID="number"> 🎀. The baseID is the starting componentID for the path that identifies events. It must not be the same as the componentID of any top-level components (including capabilities) of the LFB class. In derived LFBs (i.e., ones with a <derivedFrom> element) where the parent LFB class has an events declaration, the baseID must not be present in the derived LFB <events> element. Instead, the baseID value from the parent LFB class is used. In the example shown, the baseID is 7 💜
<events baseID="7">
<event eventID="7">
<name>Foochanged</name>
<synopsis>
An example event for a scalar
</synopsis>
<eventTarget>
<eventField>foo</eventField>
</eventTarget>
<eventChanged/>
<eventReports>
<!-- report the new state -->
<eventReport>
<eventField>foo</eventField>
</eventReport>
</eventReports>
</event>
<event eventID="8">
<name>Goof1changed</name>
<synopsis>
An example event for a complex structure
</synopsis>
<eventTarget>
<!-- target is goo.f1 -->
<eventField>goo</eventField>
<eventField>f1</eventField>
</eventTarget>
<eventChanged/>
<eventReports>
<!-- report the new state of goo.f1 -->
<eventReport>
<eventField>goo</eventField>
<eventField>f1</eventField>
</eventReport>
</eventReports>
</event>
<event eventID="9">
<name>NewbarEntry</name>
<synopsis>
Event for a new entry created on table bar
</synopsis>
<eventTarget>
<eventField>bar</eventField>
<eventSubscript>_barIndex_</eventSubscript>
</eventTarget>
<eventCreated/>
<eventReports>
<eventReport>
<eventField>bar</eventField>
<eventSubscript>_barIndex_</eventSubscript>
</eventReport>
<eventReport>
<eventField>foo</eventField>
</eventReport>
</eventReports>
</event>
<event eventID="10">
<name>Gah11changed</name>
<synopsis>
Event for table gah, entry index 11 changing
</synopsis>
<eventTarget>
<eventField>gah</eventField>
<eventSubscript>11</eventSubscript>
</eventTarget>
<eventChanged/>
<eventReports>
<eventReport>
<eventField>gah</eventField>
<eventSubscript>11</eventSubscript>
</eventReport>
</eventReports>
</event>
<event eventID="11">
<name>Gah10field1</name>
<synopsis>
Event for table gah, entry index 10, column field1 changing
</synopsis>
<eventTarget>
<eventField>gah</eventField>
<eventSubscript>10</eventSubscript>
<eventField>field1</eventField>
</eventTarget>
<eventChanged/>
<eventReports>
<eventReport>
<eventField>gah</eventField>
<eventSubscript>10</eventSubscript>
</eventReport>
</eventReports>
</event>
</events>4.7.6.1. <eventTarget> Element 🎯
The <eventTarget> element is how you point at the field in the LFB that you want to keep an eye on for events 👀
The <eventTarget> element contains one or more <eventField>s, and each of those MAY be followed by one or more <eventSubscript> elements. Together, each of these two elements is the textual version of a path select component of the LFB 🧚
The <eventField> element contains the name of a component in the LFB, or a component nested in an array or structure within the LFB. The name used in <eventField> MUST identify a valid component within the containing LFB context. The first element in an <eventTarget> MUST be an <eventField> element. In the example shown, four LFB components, foo, goo, bar, and gah, are used as <eventField>s 💖
In the simple case, an <eventField> identifies an atomic component. That's what's happening in the event named Foochanged ✨ But <eventField> also addresses complex components, like arrays or structures 🍓
- The first defined event, Foochanged, shows how a scalar LFB component, foo, can be monitored to trigger an event.
- The second event, Goof1changed, shows how a member of the complex structure goo can be monitored to trigger an event.
- The events named NewbarEntry, Gah11changed, and Gah10field1 represent monitoring of arrays bar and gah in differing details.
If an <eventField> identifies a complex component, then a further <eventField> MAY be used to refine the path to the target element. The defined event Goof1changed shows this off, using a second <eventField> to point to member f1 of the structure goo 🫶
If an <eventField> identifies an array, then the following rules apply 📋
<eventSubscript>elements MUST be present as the next XML element after an<eventField>that identifies an array component.<eventSubscript>MUST NOT occur other than after an array reference, as it is only meaningful in that context.- An
<eventSubscript>contains either:- A numeric value to indicate that the event applies to a specific entry (by index) of the array. As an example, the event Gah11changed shows how table gah's index 11 is being targeted for monitoring.
Or
- The more common usage is to have the event defined across all elements of the array (i.e., a wildcard for all indices). It is expected that this is the way most people will do it 🌈 In that case, the value of the
<eventSubscript>MUST be a name rather than a numeric value. That same name can then be used as the value of<eventSubscript>in<eventReport>elements, as described below. An example of a wildcard table index is shown in the event NewBarentry, where the<eventSubscript>value is named_barIndex_.
- An
<eventField>MAY follow an<eventSubscript>to further refine the path to the target element. (Note: this is the same spirit as the case where<eventField>is used to further refine<eventField>in the earlier complex structure example of Goof1changed.) The example event Gah10field1 shows how the column field1 of table gah is monitored for changes 🦋
It should be emphasized that the name in an <eventSubscript> element in the defined event NewbarEntry is not a component name. It's a variable name for use in the <eventReport> elements (described in Section 4.7.6.3) of the given LFB definition. This name MUST be distinct from any component name that can validly occur in the <eventReport> clause. Don't mix them up, bestie 🙈
4.7.6.2. <eventCondition> Element 🚦
The event condition element represents a condition that triggers a notification. The list of conditions is:
<eventCreated/>: The target must be an array, ending with a subscript indication. The event is generated when an entry in the array is created. This occurs even if the entry is created by CE direction. The event example NewbarEntry demonstrates the<eventCreated/>condition 🎉<eventDeleted/>: The target must be an array, ending with a subscript indication. The event is generated when an entry in the array is destroyed. This occurs even if the entry is destroyed by CE direction 💀<eventChanged/>: The event is generated whenever the target component changes in any way. For binary components such as up/down, this reflects a change in state. It can also be used with numeric attributes, in which case any change in value results in a detected trigger. The event examples Foochanged, Gah11changed, and Gah10field1 illustrate the<eventChanged/>condition ⭐<eventGreaterThan/>: The event is generated whenever the target component becomes greater than the threshold. The threshold is an event property 📈<eventLessThan/>: The event is generated whenever the target component becomes less than the threshold. The threshold is an event property 📉
4.7.6.3. <eventReports> Element ✨
okay bestie, the <eventReports> element is the part of an <event> that decides what info the FE sends along with the notification that the event happened 💌 it's basically the receipts 🧾
The <eventReports> element holds one or more <eventReport> elements. Each <eventReport> points at a piece of data from the LFB class that you wanna report. The notification then carries that data as if all the <eventReport> stuff was wrapped up in a structure 🎀 The syntax is exactly the same as what <eventTarget> uses (with <eventField> and <eventSubscript>), so the same rules apply, no cap. Each <eventReport> element thus MUST identify a component in the LFB class. <eventSubcript> MAY contain integers. If they contain names, they MUST be names from <eventSubscript> elements of the <eventTarget> in the event. The selection for the report uses the value for the subscript that picks out the specific element that triggered the event. This can be used to reference the component causing the event, or to reference related info in parallel tables 🦋
In the example, for the Foochanged event, the report carries the value of foo. For the NewbarEntry event acting on LFB component bar (which is an array), there are two items reported, one for each <eventReport>:
- The first <eventReport> tells you what new entry got added to table bar. Remember barIndex is declared as the event's <eventTarget> <eventSubcript>, and since it's a name instead of a number, that subscript is implied to be a wildcard and carries whatever index the new entry has 🔥
- The second <eventReport> includes the value of LFB component foo at the moment the new entry was created in bar. Reporting foo here is just showing off how flexible event reporting is 💅
This event reporting structure is built so the LFB designer can specify info that the CE probably doesn't know ahead of time but probably needs to process the event 🧚 Pointing at big blocks of info (full arrays or complex structures) is possible, but it's not recommended 🙈 Also, variable reference and subscripting in reporting only captures a small slice of the related info you might want. Chaining through index fields stored in a table, for example, is not supported. Overall, <eventReports> is an optimization for the common cases, saving the CE from having to query for the info it needs to understand the event. It does not cover every possible info need 💜
If any components referenced by the eventReport are optional, then the report MUST use a protocol format that supports optional elements and allows for the non-existence of such elements. Any components that do not exist are not reported 🌸
4.7.6.4. Runtime Control of Events
okay so the high-level view of how LFB events get declared and operated is in Section 3.2.5, so go check that if you wanna see the big picture 🌈
The <eventTarget> gives you the extra components used in the path to reference the event. The path is the baseID for events, then the ID for the specific event, then a value for each <eventSubscript> element if there is one in the <eventTarget> 🍓
The event path uniquely identifies one specific occurrence of the event in the event notification to the CE. In the example at the end of Section 4.7.6, a notification with path 7.7 uniquely identifies the event as the one caused by the change of foo, and an event with path 7.9.100 uniquely identifies the event as the one caused by creating the table bar entry with index/subscript 100 ✨
As described in Section 4.8.5, event elements have properties attached to them. These include the subscription info (whether the CE wants the FE to generate event reports for the event at all), thresholds for events related to level crossing, and filtering conditions that may reduce the set of event notifications the FE generates. The filtering conditions are covered in that section. They let the FE stop floods of events that could come from oscillation around a condition value 🌊 For FEs that don't wanna support filtering, the filter properties can be either read-only or not supported 💀
Besides identifying the event sources, the CE also uses the event path to switch the event on or off at runtime through the event properties (defined in Section 4.8.5), using the SET-PROP operation from the ForCES protocol [RFC5810] 🎀
To activate event generation on the FE, the CE issues a SET-PROP message to the FE that references the event and the event's registration property, using any prefix of the event's path. So for an event defined on the example table bar, a SET-PROP with path 7.9 subscribes the CE to all occurrences of that event on any entry of the table 🦋 This is especially handy for the <eventCreated/> and <eventDestroyed/> conditions on tables. Events using those conditions are usually defined with a field/subscript sequence that identifies an array and ends with an <eventSubscript> element, so the event notification tells you which array entry was created or destroyed 👑 A typical subscriber subscribes to the array rather than one specific entry, so it uses the shorter path.
In the example, subscribing to 7.8 implies receiving all the declared events from table bar. Subscribing to 7.8.100 implies receiving an event when the table entry with subscript/index 100 is created 💖
Threshold and filtering conditions can only be applied to individual events. For events defined on elements of an array, this specification does not allow a threshold or filtering condition to be defined on an event for all elements of an array 🙅♀️
4.7.7. <description> Element for LFB Operational Specification
the <description> element of the <LFBClass> is unstructured text (in the XML sense) that explains what the LFB does to a human user 📖
4.8. Properties
okay so components of LFBs have properties that the CE really cares about. The most important one is whether the element exists, can be read, and can be written 🔑 Depending on the type of component, other info might matter too 💅
The model defines the structure of property info. There's a base class of property info, and the array, alias, and event components each have subclasses that add more fields. The CE accesses this info (and updates it where that makes sense) through the ForCES protocol 🧚 Some property info is writeable, but there's currently no mechanism for checking the properties of a property element. The only way to check writeability is to try modifying the value 🙈
4.8.1. Basic Properties
the basic property definition, along with the scalar dataTypeDef for accessibility, is below. Heads up: this access permission info is generally read-only 👀
<dataTypeDef>
<name>accessPermissionValues</name>
<synopsis>
The possible values of component access permission
</synopsis>
<atomic>
<baseType>uchar</baseType>
<specialValues>
<specialValue value="0">
<name>None</name>
<synopsis>Access is prohibited</synopsis>
</specialValue>
<specialValue value="1">
<name> Read-Only </name>
<synopsis>
Access to the component is read only
</synopsis>
</specialValue>
<specialValue value="2">
<name>Write-Only</name>
<synopsis>
The component MAY be written, but not read
</synopsis>
</specialValue>
<specialValue value="3">
<name>Read-Write</name>
<synopsis>
The component MAY be read or written
</synopsis>
</specialValue>
</specialValues>
</atomic>
</dataTypeDef>
<dataTypeDef>
<name>baseElementProperties</name>
<synopsis>basic properties, accessibility</synopsis>
<struct>
<component componentID="1">
<name>accessibility</name>
<synopsis>
does the component exist, and
can it be read or written
</synopsis>
<typeRef>accessPermissionValues</typeRef>
</component>
</struct>
</dataTypeDef>4.8.2. Array Properties
okay so array properties add a bunch of important info, and these are read-only too 📊
<dataTypeDef>
<name>arrayElementProperties</name>
<synopsis>Array Element Properties definition</synopsis>
<struct>
<derivedFrom>baseElementProperties</derivedFrom>
<component componentID="2">
<name>entryCount</name>
<synopsis>the number of entries in the array</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="3">
<name>highestUsedSubscript</name>
<synopsis>the last used subscript in the array</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="4">
<name>firstUnusedSubscript</name>
<synopsis>
The subscript of the first unused array element
</synopsis>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>4.8.3. String Properties
the properties of a string tell you the actual octet length and the maximum octet length for the element 📏 The maximum length is included because an FE implementation MAY limit a string to be shorter than the limit in the LFB class definition 🦋
<dataTypeDef>
<name>stringElementProperties</name>
<synopsis>string Element Properties definition </synopsis>
<struct>
<derivedFrom>baseElementProperties</derivedFrom>
<component componentID="2">
<name>stringLength</name>
<synopsis>the number of octets in the string</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="3">
<name>maxStringLength</name>
<synopsis>
the maximum number of octets in the string
</synopsis>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>4.8.4. Octetstring Properties ✨
okay so octetstring properties track two lengths: the actual length and the maximum length 🧚 bc the FE MAY limit an octetstring to be shorter than the LFB class definition says. that's giving flexibility, bestie 💅
<dataTypeDef>
<name>octetstringElementProperties</name>
<synopsis>octetstring Element Properties definition
</synopsis>
<struct>
<derivedFrom>baseElementProperties</derivedFrom>
<component componentID="2">
<name>octetstringLength</name>
<synopsis>
the number of octets in the octetstring
</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="3">
<name>maxOctetstringLength</name>
<synopsis>
the maximum number of octets in the octetstring
</synopsis>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>4.8.5. Event Properties 🔔
the properties for an event come with three (usually) writeable fields, and they're the main way the CE gets its say 🫶
- the subscription field:
0means no notification is generated, and any non-zero value (typically1) means one is - the hysteresis field suppresses notifications for oscillations around a condition value, which we'll get into in Section 4.8.5.2
- the threshold field is for the
<eventGreaterThan/>and<eventLessThan/>conditions, and it holds the value the event target gets compared against
using these properties lets the CE set its level of interest 🎯 FEs that don't support setting the threshold for events will make this field read-only, so no surprises there ✨
<dataTypeDef>
<name>eventElementProperties</name>
<synopsis>event Element Properties definition</synopsis>
<struct>
<derivedFrom>baseElementProperties</derivedFrom>
<component componentID="2">
<name>registration</name>
<synopsis>
has the CE registered to be notified of this event
</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="3">
<name>threshold</name>
<synopsis> comparison value for level crossing events
</synopsis>
<optional/>
<typeRef>uint32</typeRef>
</component>
<component componentID="4">
<name>eventHysteresis</name>
<synopsis> region to suppress event recurrence notices
</synopsis>
<optional/>
<typeRef>uint32</typeRef>
</component>
<component componentID="5">
<name>eventCount</name>
<synopsis> number of occurrences to suppress
</synopsis>
<optional/>
<typeRef>uint32</typeRef>
</component>
<component componentID="6">
<name>eventInterval</name>
<synopsis> time interval in ms between notifications
</synopsis>
<optional/>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>4.8.5.1. Common Event Filtering 🧹
the event properties have values for controlling several filter conditions. support for these is optional, but all conditions SHOULD be supported ✨ events that are reliably known not to be subject to rapid occurrence or other concerns MAY not support all filter conditions, and that's totally fine 🙌
right now there are three filter condition variables: eventCount, eventInterval, and eventHysteresis. setting any of them to 0 (their default) means that condition isn't checked 💤
here's the big picture 🧠 when an event is triggered, all configured conditions get checked. if no filter conditions are triggered, OR if any trigger conditions are met, the notification gets generated. if there are filter conditions and none of them are met, no notification happens. the reset behavior is the tea ☕ if any condition passes and the notification is generated, the reset happens on all conditions, even the ones that didn't pass. this gives us a clean definition of how the conditions work together, and I'm obsessed 😭
an example makes it click 🎀 say an event has eventCount set to 5 and eventInterval set to 500 milliseconds. then a burst of occurrences shows up at the FE:
- the first occurrence sends a notification to the CE
- if four more show up rapidly (less than 0.5 seconds), they don't result in notifications
- if two more show up, the second of those gets a notification
- or, if more than 500 milliseconds have passed since the notification and an occurrence is detected, that gets a notification too
either way, the count and time interval suppression resets, no matter which condition actually caused the notification 💅
4.8.5.2. Event Hysteresis Filtering 🌀
events with numeric conditions can have hysteresis filters applied, and the hysteresis level is set by a property of the event. this lets the FE tell the CE what hysteresis is applied, and if it wants to, the FE can let the CE change it 🫶 this applies to <eventChanged/> for a numeric field, and to <eventGreaterThan/> and <eventLessThan/>. the content of a <variance> element is a numeric value.
when supporting hysteresis, the FE MUST track the value of the element and make sure the condition has become untrue by at least the hysteresis from the event property. to be specific, if the hysteresis is V, then:
- for an
<eventChanged/>condition, if the last notification was for value X, the<changed/>notification MUST NOT be generated until the value reaches X +/- V 🎯 - for an
<eventGreaterThan/>condition with threshold T, once the event has been generated at least once, it MUST NOT be generated again until the field first becomes less than or equal to T - V, and then exceeds T 📈 - for an
<eventLessThan/>condition with threshold T, once the event has been generated at least once, it MUST NOT be generated again until the field first becomes greater than or equal to T + V, and then becomes less than T 📉
4.8.5.3. Event Count Filtering 🔢
events MAY have a count filtering condition. this property, if set to a non-zero value, says how many occurrences of the event should be considered redundant and not result in a notification 🙈 so if it's set to 1 and no other conditions apply, then every other detected occurrence gets a notification. this particular meaning was chosen so the value 1 is clearly different from the value 0, which is iconic of them 💜
a conceptual implementation (not required) could be an internal suppression counter 🧮 whenever an event gets triggered, the counter is checked. if the counter is 0, a notification is generated. whether or not a notification is generated, the counter gets incremented. if the counter goes over the configured value, it's set back to 0.
4.8.5.4. Event Time Filtering ⏱️
events MAY have a time filtering condition. this property is the minimum time interval (when no other filtering condition is passing) between generating notifications of detected events 🕰️ this condition MUST only be passed if the time since the last notification of the event is longer than the configured interval in milliseconds.
conceptually, you can think of this as a stored timestamp that gets compared with the detection time, or as a timer that's running and resets a suppression flag 🧚 either way, if a notification is generated because any condition was passed, then the time interval detection MUST be restarted. no cap, it's that simple 🫶
4.8.6. Alias Properties 🪞
the properties for an alias come with three (usually) writeable fields, and they work together to identify the target component that the subject alias refers to 🦋
<dataTypeDef>
<name>aliasElementProperties</name>
<synopsis>alias Element Properties definition</synopsis>
<struct>
<derivedFrom>baseElementProperties</derivedFrom>
<component componentID="2">
<name>targetLFBClass</name>
<synopsis>the class ID of the alias target</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="3">
<name>targetLFBInstance</name>
<synopsis>the instance ID of the alias target</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="4">
<name>targetComponentPath</name>
<synopsis>
the path to the component target
each 4 octets is read as one path element,
using the path construction in the ForCES protocol,
[2].
</synopsis>
<typeRef>octetstring[128]</typeRef>
</component>
</struct>
</dataTypeDef>4.9. XML Schema for LFB Class Library Documents 📜
okay bestie, we're picking up right where we left off in 4.9 💖 this part is the XML schema for LFB class library documents, so the code below is copied exactly, character for character 🎀
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:forces:lfbmodel:1.0"
xmlns:lfb="urn:ietf:params:xml:ns:forces:lfbmodel:1.0"
targetNamespace="urn:ietf:params:xml:ns:forces:lfbmodel:1.0"
attributeFormDefault="unqualified"
elementFormDefault="qualified">
<xsd:annotation>
<xsd:documentation xml:lang="en">
Schema for Defining LFB Classes and associated types (frames,
data types for LFB attributes, and metadata).
</xsd:documentation>
</xsd:annotation>
<xsd:element name="description" type="xsd:string"/>
<xsd:element name="synopsis" type="xsd:string"/>
<!-- Document root element: LFBLibrary -->
<xsd:element name="LFBLibrary">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="description" minOccurs="0"/>
<xsd:element name="load" type="loadType" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:element name="frameDefs" type="frameDefsType"
minOccurs="0"/>
<xsd:element name="dataTypeDefs" type="dataTypeDefsType"
minOccurs="0"/>
<xsd:element name="metadataDefs" type="metadataDefsType"
minOccurs="0"/>
<xsd:element name="LFBClassDefs" type="LFBClassDefsType"
minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="provides" type="xsd:Name" use="required"/>
</xsd:complexType>
<!-- Uniqueness constraints -->
<xsd:key name="frame">
<xsd:selector xpath="lfb:frameDefs/lfb:frameDef"/>
<xsd:field xpath="lfb:name"/>
</xsd:key>
<xsd:key name="dataType">
<xsd:selector xpath="lfb:dataTypeDefs/lfb:dataTypeDef"/>
<xsd:field xpath="lfb:name"/>
</xsd:key>
<xsd:key name="metadataDef">
<xsd:selector xpath="lfb:metadataDefs/lfb:metadataDef"/>
<xsd:field xpath="lfb:name"/>
</xsd:key>
<xsd:key name="LFBClassDef">
<xsd:selector xpath="lfb:LFBClassDefs/lfb:LFBClassDef"/>
<xsd:field xpath="lfb:name"/>
</xsd:key>
</xsd:element>
<xsd:complexType name="loadType">
<xsd:attribute name="library" type="xsd:Name" use="required"/>
<xsd:attribute name="location" type="xsd:anyURI" use="optional"/>
</xsd:complexType>
<xsd:complexType name="frameDefsType">
<xsd:sequence>
<xsd:element name="frameDef" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element ref="description" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="dataTypeDefsType">
<xsd:sequence>
<xsd:element name="dataTypeDef" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element ref="description" minOccurs="0"/>
<xsd:group ref="typeDeclarationGroup"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<!--
Predefined (built-in) atomic data-types are:
char, uchar, int16, uint16, int32, uint32, int64, uint64,
string[N], string, byte[N], boolean, octetstring[N],
float32, float64
-->
<xsd:group name="typeDeclarationGroup">
<xsd:choice>
<xsd:element name="typeRef" type="typeRefNMTOKEN"/>
<xsd:element name="atomic" type="atomicType"/>
<xsd:element name="array" type="arrayType"/>
<xsd:element name="struct" type="structType"/>
<xsd:element name="union" type="structType"/>
<xsd:element name="alias" type="typeRefNMTOKEN"/>
</xsd:choice>
</xsd:group>
<xsd:simpleType name="typeRefNMTOKEN">
<xsd:restriction base="xsd:token">
<xsd:pattern value="\c+"/>
<xsd:pattern value="string\[\d+\]"/>
<xsd:pattern value="byte\[\d+\]"/>
<xsd:pattern value="octetstring\[\d+\]"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="atomicType">
<xsd:sequence>
<xsd:element name="baseType" type="typeRefNMTOKEN"/>
<xsd:element name="rangeRestriction"
type="rangeRestrictionType" minOccurs="0"/>
<xsd:element name="specialValues" type="specialValuesType"
minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="rangeRestrictionType">
<xsd:sequence>
<xsd:element name="allowedRange" maxOccurs="unbounded">
<xsd:complexType>
<xsd:attribute name="min" type="xsd:integer"
use="required"/>
<xsd:attribute name="max" type="xsd:integer"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="specialValuesType">
<xsd:sequence>
<xsd:element name="specialValue" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
</xsd:sequence>
<xsd:attribute name="value" type="xsd:token"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="arrayType">
<xsd:sequence>
<xsd:group ref="typeDeclarationGroup"/>
<xsd:element name="contentKey" minOccurs="0"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="contentKeyField" maxOccurs="unbounded"
type="xsd:string"/>
</xsd:sequence>
<xsd:attribute name="contentKeyID" use="required"
type="xsd:integer"/>
</xsd:complexType>
<!--declare keys to have unique IDs -->
<xsd:key name="contentKeyID">
<xsd:selector xpath="lfb:contentKey"/>
<xsd:field xpath="@contentKeyID"/>
</xsd:key>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="type" use="optional"
default="variable-size">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="fixed-size"/>
<xsd:enumeration value="variable-size"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="length" type="xsd:integer" use="optional"/>
<xsd:attribute name="maxLength" type="xsd:integer"
use="optional"/>
</xsd:complexType>
<xsd:complexType name="structType">
<xsd:sequence>
<xsd:element name="derivedFrom" type="typeRefNMTOKEN"
minOccurs="0"/>
<xsd:element name="component" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element ref="description" minOccurs="0"/>
<xsd:element name="optional" minOccurs="0"/>
<xsd:group ref="typeDeclarationGroup"/>
</xsd:sequence>
<xsd:attribute name="componentID" use="required"
type="xsd:unsignedInt"/>
</xsd:complexType>
<!-- key declaration to make componentIDs unique in a struct
-->
<xsd:key name="structComponentID">
<xsd:selector xpath="lfb:component"/>
<xsd:field xpath="@componentID"/>
</xsd:key>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="metadataDefsType">
<xsd:sequence>
<xsd:element name="metadataDef" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element name="metadataID" type="xsd:integer"/>
<xsd:element ref="description" minOccurs="0"/>
<xsd:choice>
<xsd:element name="typeRef" type="typeRefNMTOKEN"/>
<xsd:element name="atomic" type="atomicType"/>
</xsd:choice>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="LFBClassDefsType">
<xsd:sequence>
<xsd:element name="LFBClassDef" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element name="version" type="versionType"/>
<xsd:element name="derivedFrom" type="xsd:NMTOKEN"
minOccurs="0"/>
<xsd:element name="inputPorts" type="inputPortsType"
minOccurs="0"/>
<xsd:element name="outputPorts" type="outputPortsType"
minOccurs="0"/>
<xsd:element name="components" type="LFBComponentsType"
minOccurs="0"/>
<xsd:element name="capabilities"
type="LFBCapabilitiesType" minOccurs="0"/>
<xsd:element name="events"
type="eventsType" minOccurs="0"/>
<xsd:element ref="description" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="LFBClassID" use="required"
type="xsd:unsignedInt"/>
</xsd:complexType>
<!-- Key constraint to ensure unique attribute names within
a class:
-->
<xsd:key name="components">
<xsd:selector xpath="lfb:components/lfb:component"/>
<xsd:field xpath="lfb:name"/>
</xsd:key>
<xsd:key name="capabilities">
<xsd:selector xpath="lfb:capabilities/lfb:capability"/>
<xsd:field xpath="lfb:name"/>
</xsd:key>
<xsd:key name="componentIDs">
<xsd:selector xpath="lfb:components/lfb:component"/>
<xsd:field xpath="@componentID"/>
</xsd:key>
<xsd:key name="capabilityIDs">
<xsd:selector xpath="lfb:capabilities/lfb:capability"/>
<xsd:field xpath="@componentID"/>
</xsd:key>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="versionType">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:pattern value="[1-9][0-9]*\.([1-9][0-9]*|0)"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="inputPortsType">
<xsd:sequence>
<xsd:element name="inputPort" type="inputPortType"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="inputPortType">
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element name="expectation" type="portExpectationType"/>
<xsd:element ref="description" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="group" type="xsd:boolean" use="optional"
default="0"/>
</xsd:complexType>
<xsd:complexType name="portExpectationType">
<xsd:sequence>that's the schema up to the start of portExpectationType 🧚 more to come, so the vibes keep going ✨
<xsd:element name="frameExpected" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<!-- ref must refer to a name of a defined frame type -->
<xsd:element name="ref" type="xsd:string"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="metadataExpected" minOccurs="0">
<xsd:complexType>
<xsd:choice maxOccurs="unbounded">
<!-- ref must refer to a name of a defined metadata -->
<xsd:element name="ref" type="metadataInputRefType"/>
<xsd:element name="one-of"
type="metadataInputChoiceType"/>
</xsd:choice>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="metadataInputChoiceType">
<xsd:choice minOccurs="2" maxOccurs="unbounded">
<!-- ref must refer to a name of a defined metadata -->
<xsd:element name="ref" type="xsd:NMTOKEN"/>
<xsd:element name="one-of" type="metadataInputChoiceType"/>
<xsd:element name="metadataSet" type="metadataInputSetType"/>
</xsd:choice>
</xsd:complexType>
<xsd:complexType name="metadataInputSetType">
<xsd:choice minOccurs="2" maxOccurs="unbounded">
<!-- ref must refer to a name of a defined metadata -->
<xsd:element name="ref" type="metadataInputRefType"/>
<xsd:element name="one-of" type="metadataInputChoiceType"/>
</xsd:choice>
</xsd:complexType>
<xsd:complexType name="metadataInputRefType">
<xsd:simpleContent>
<xsd:extension base="xsd:NMTOKEN">
<xsd:attribute name="dependency" use="optional"
default="required">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="required"/>
<xsd:enumeration value="optional"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="defaultValue" type="xsd:token"
use="optional"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:complexType name="outputPortsType">
<xsd:sequence>
<xsd:element name="outputPort" type="outputPortType"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="outputPortType">
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element name="product" type="portProductType"/>
<xsd:element ref="description" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="group" type="xsd:boolean" use="optional"
default="0"/>
</xsd:complexType>
<xsd:complexType name="portProductType">
<xsd:sequence>
<xsd:element name="frameProduced">
<xsd:complexType>
<xsd:sequence>
<!-- ref must refer to a name of a defined frame type
-->
<xsd:element name="ref" type="xsd:NMTOKEN"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="metadataProduced" minOccurs="0">
<xsd:complexType>
<xsd:choice maxOccurs="unbounded">
<!-- ref must refer to a name of a defined metadata
-->
<xsd:element name="ref" type="metadataOutputRefType"/>
<xsd:element name="one-of"
type="metadataOutputChoiceType"/>
</xsd:choice>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="metadataOutputChoiceType">
<xsd:choice minOccurs="2" maxOccurs="unbounded">
<!-- ref must refer to a name of a defined metadata -->
<xsd:element name="ref" type="xsd:NMTOKEN"/>
<xsd:element name="one-of" type="metadataOutputChoiceType"/>
<xsd:element name="metadataSet" type="metadataOutputSetType"/>
</xsd:choice>
</xsd:complexType>
<xsd:complexType name="metadataOutputSetType">
<xsd:choice minOccurs="2" maxOccurs="unbounded">
<!-- ref must refer to a name of a defined metadata -->
<xsd:element name="ref" type="metadataOutputRefType"/>
<xsd:element name="one-of" type="metadataOutputChoiceType"/>
</xsd:choice>
</xsd:complexType>
<xsd:complexType name="metadataOutputRefType">
<xsd:simpleContent>
<xsd:extension base="xsd:NMTOKEN">
<xsd:attribute name="availability" use="optional"
default="unconditional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="unconditional"/>
<xsd:enumeration value="conditional"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:complexType name="LFBComponentsType">
<xsd:sequence>
<xsd:element name="component" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element ref="description" minOccurs="0"/>
<xsd:element name="optional" minOccurs="0"/>
<xsd:group ref="typeDeclarationGroup"/>
<xsd:element name="defaultValue" type="xsd:token"
minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="access" use="optional"
default="read-write">
<xsd:simpleType>
<xsd:list itemType="accessModeType"/>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="componentID" use="required"
type="xsd:unsignedInt"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="accessModeType">
<xsd:restriction base="xsd:NMTOKEN">
<xsd:enumeration value="read-only"/>
<xsd:enumeration value="read-write"/>
<xsd:enumeration value="write-only"/>
<xsd:enumeration value="read-reset"/>
<xsd:enumeration value="trigger-only"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="LFBCapabilitiesType">
<xsd:sequence>
<xsd:element name="capability" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element ref="description" minOccurs="0"/>
<xsd:element name="optional" minOccurs="0"/>
<xsd:group ref="typeDeclarationGroup"/>
</xsd:sequence>
<xsd:attribute name="componentID" use="required"
type="xsd:integer"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="eventsType">
<xsd:sequence>
<xsd:element name="event" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:NMTOKEN"/>
<xsd:element ref="synopsis"/>
<xsd:element name="eventTarget" type="eventPathType"/>
<xsd:element ref="eventCondition"/>
<xsd:element name="eventReports" type="eventReportsType"
minOccurs="0"/>
<xsd:element ref="description" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="eventID" use="required"
type="xsd:integer"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="baseID" type="xsd:integer"
use="optional"/>
</xsd:complexType>
<!-- the substitution group for the event conditions -->
<xsd:element name="eventCondition" abstract="true"/>
<xsd:element name="eventCreated"
substitutionGroup="eventCondition"/>
<xsd:element name="eventDeleted"
substitutionGroup="eventCondition"/>
<xsd:element name="eventChanged"
substitutionGroup="eventCondition"/>
<xsd:element name="eventGreaterThan"
substitutionGroup="eventCondition"/>
<xsd:element name="eventLessThan"
substitutionGroup="eventCondition"/>
<xsd:complexType name="eventPathType">
<xsd:sequence>
<xsd:element ref="eventPathPart" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<!-- the substitution group for the event path parts -->
<xsd:element name="eventPathPart" type="xsd:string"
abstract="true"/>
<xsd:element name="eventField" type="xsd:string"
substitutionGroup="eventPathPart"/>
<xsd:element name="eventSubscript" type="xsd:string"
substitutionGroup="eventPathPart"/>
<xsd:complexType name="eventReportsType">
<xsd:sequence>
<xsd:element name="eventReport" type="eventPathType"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="booleanType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="0"/>
<xsd:enumeration value="1"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>5. FE Components and Capabilities ✨
okay so a ForCES forwarding element (FE) is the one doing the actual traffic handling 🚚 on behalf of a ForCES control element (CE) 💅. The standards will describe the protocol and the mechanisms for this control, but different implementations and different instances can have different capabilities 🎀. The CE MUST be able to figure out what each instance it's responsible for is actually capable of doing 🧠. As stated previously, this is an approximation 🙈. So the CE is expected to be ready to cope with errors in requests and with variations in detail that the capabilities information doesn't capture 🫶.
Besides capabilities, an FE also has information that helps you understand and control its forwarding operations 🔍. Some of this information is read-only 🔒, while other parts may also be writeable ✍️.
To make the FE information easy to get to, the information is represented in an LFB 🦋. This LFB has a class called FEObject 💖. The LFBClassID for this class is 1. Only one instance of this class will ever be present in an FE, and the instance ID of that instance in the protocol is 1 👑. So by referencing the components of class:1, instance:1, a CE can get the general information about the FE 🌸. The FEObject LFB class is described in this section ✨.
There will also be an FEProtocol LFB class 🧚. LFBClassID 2 is reserved for that class 💜. There will be only one instance of that class as well 💅. Details of that class are defined in the ForCES protocol [RFC5810] document 📖.
5.1. XML for FEObject Class Definition 💖
Okay so this is where the schema really starts to look like a whole vibe 💅 Here's the first chunk of the LFB library XML, the dataTypeDefs with all the structs and enums 🎀
<?xml version="1.0" encoding="UTF-8"?>
<LFBLibrary xmlns="urn:ietf:params:xml:ns:forces:lfbmodel:1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
provides="FEObject">
<dataTypeDefs>
<dataTypeDef>
<name>LFBAdjacencyLimitType</name>
<synopsis>Describing the Adjacent LFB</synopsis>
<struct>
<component componentID="1">
<name>NeighborLFB</name>
<synopsis>ID for that LFB class</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="2">
<name>ViaPorts</name>
<synopsis>
the ports on which we can connect
</synopsis>
<array type="variable-size">
<typeRef>string</typeRef>
</array>
</component>
</struct>
</dataTypeDef>
<dataTypeDef>
<name>PortGroupLimitType</name>
<synopsis>
Limits on the number of ports in a given group
</synopsis>
<struct>
<component componentID="1">
<name>PortGroupName</name>
<synopsis>Group Name</synopsis>
<typeRef>string</typeRef>
</component>
<component componentID="2">
<name>MinPortCount</name>
<synopsis>Minimum Port Count</synopsis>
<optional/>
<typeRef>uint32</typeRef>
</component>
<component componentID="3">
<name>MaxPortCount</name>
<synopsis>Max Port Count</synopsis>
<optional/>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>
<dataTypeDef>
<name>SupportedLFBType</name>
<synopsis>table entry for supported LFB</synopsis>
<struct>
<component componentID="1">
<name>LFBName</name>
<synopsis>
The name of a supported LFB class
</synopsis>
<typeRef>string</typeRef>
</component>
<component componentID="2">
<name>LFBClassID</name>
<synopsis>the id of a supported LFB class</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="3">
<name>LFBVersion</name>
<synopsis>
The version of the LFB class used
by this FE.
</synopsis>
<typeRef>string</typeRef>
</component>
<component componentID="4">
<name>LFBOccurrenceLimit</name>
<synopsis>
the upper limit of instances of LFBs of this class
</synopsis>
<optional/>
<typeRef>uint32</typeRef>
</component>
<!-- For each port group, how many ports can exist
-->
<component componentID="5">
<name>PortGroupLimits</name>
<synopsis>Table of Port Group Limits</synopsis>
<optional/>
<array type="variable-size">
<typeRef>PortGroupLimitType</typeRef>
</array>
</component>
<!-- for the named LFB Class, the LFB Classes it may follow -->
<component componentID="6">
<name>CanOccurAfters</name>
<synopsis>
List of LFB classes that this LFB class can follow
</synopsis>
<optional/>
<array type="variable-size">
<typeRef>LFBAdjacencyLimitType</typeRef>
</array>
</component>
<!-- for the named LFB Class, the LFB Classes that may follow it
-->
<component componentID="7">
<name>CanOccurBefores</name>
<synopsis>
List of LFB classes that can follow this LFB class
</synopsis>
<optional/>
<array type="variable-size">
<typeRef>LFBAdjacencyLimitType</typeRef>
</array>
</component>
<component componentID="8">
<name>UseableParentLFBClasses</name>
<synopsis>
List of LFB classes from which this class has
inherited, and which the FE is willing to allow
for references to instances of this class.
</synopsis>
<optional/>
<array type="variable-size">
<typeRef>uint32</typeRef>
</array>
</component>
</struct>
</dataTypeDef>
<dataTypeDef>
<name>FEStateValues</name>
<synopsis>The possible values of status</synopsis>
<atomic>
<baseType>uchar</baseType>
<specialValues>
<specialValue value="0">
<name>AdminDisable</name>
<synopsis>
FE is administratively disabled
</synopsis>
</specialValue>
<specialValue value="1">
<name>OperDisable</name>
<synopsis>FE is operatively disabled</synopsis>
</specialValue>
<specialValue value="2">
<name>OperEnable</name>
<synopsis>FE is operating</synopsis>
</specialValue>
</specialValues>
</atomic>
</dataTypeDef>
<dataTypeDef>
<name>FEConfiguredNeighborType</name>
<synopsis>Details of the FE's Neighbor</synopsis>
<struct>
<component componentID="1">
<name>NeighborID</name>
<synopsis>Neighbors FEID</synopsis>
<typeRef>uint32</typeRef>The schema keeps going from right here ✨ so stay tuned, bestie 🦋
</component>
<component componentID="2">
<name>InterfaceToNeighbor</name>
<synopsis>
FE's interface that connects to this neighbor
</synopsis>
<optional/>
<typeRef>string</typeRef>
</component>
<component componentID="3">
<name>NeighborInterface</name>
<synopsis>
The name of the interface on the neighbor to
which this FE is adjacent. This is required
in case two FEs are adjacent on more than
one interface.
</synopsis>
<optional/>
<typeRef>string</typeRef>
</component>
</struct>
</dataTypeDef>
<dataTypeDef>
<name>LFBSelectorType</name>
<synopsis>
Unique identification of an LFB class-instance
</synopsis>
<struct>
<component componentID="1">
<name>LFBClassID</name>
<synopsis>LFB Class Identifier</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="2">
<name>LFBInstanceID</name>
<synopsis>LFB Instance ID</synopsis>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>
<dataTypeDef>
<name>LFBLinkType</name>
<synopsis>
Link between two LFB instances of topology
</synopsis>
<struct>
<component componentID="1">
<name>FromLFBID</name>
<synopsis>LFB src</synopsis>
<typeRef>LFBSelectorType</typeRef>
</component>
<component componentID="2">
<name>FromPortGroup</name>
<synopsis>src port group</synopsis>
<typeRef>string</typeRef>
</component>
<component componentID="3">
<name>FromPortIndex</name>
<synopsis>src port index</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="4">
<name>ToLFBID</name>
<synopsis>dst LFBID</synopsis>
<typeRef>LFBSelectorType</typeRef>
</component>
<component componentID="5">
<name>ToPortGroup</name>
<synopsis>dst port group</synopsis>
<typeRef>string</typeRef>
</component>
<component componentID="6">
<name>ToPortIndex</name>
<synopsis>dst port index</synopsis>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>
</dataTypeDefs>
<LFBClassDefs>
<LFBClassDef LFBClassID="1">
<name>FEObject</name>
<synopsis>Core LFB: FE Object</synopsis>
<version>1.0</version>
<components>
<component access="read-write" componentID="1">
<name>LFBTopology</name>
<synopsis>the table of known Topologies</synopsis>
<array type="variable-size">
<typeRef>LFBLinkType</typeRef>
</array>
</component>
<component access="read-write" componentID="2">
<name>LFBSelectors</name>
<synopsis>
table of known active LFB classes and
instances
</synopsis>
<array type="variable-size">
<typeRef>LFBSelectorType</typeRef>
</array>
</component>
<component access="read-write" componentID="3">
<name>FEName</name>
<synopsis>name of this FE</synopsis>
<typeRef>string[40]</typeRef>
</component>
<component access="read-write" componentID="4">
<name>FEID</name>
<synopsis>ID of this FE</synopsis>
<typeRef>uint32</typeRef>
</component>
<component access="read-only" componentID="5">
<name>FEVendor</name>
<synopsis>vendor of this FE</synopsis>
<typeRef>string[40]</typeRef>
</component>
<component access="read-only" componentID="6">
<name>FEModel</name>
<synopsis>model of this FE</synopsis>
<typeRef>string[40]</typeRef>
</component>
<component access="read-only" componentID="7">
<name>FEState</name>
<synopsis>State of this FE</synopsis>
<typeRef>FEStateValues</typeRef>
</component>
<component access="read-write" componentID="8">
<name>FENeighbors</name>
<synopsis>table of known neighbors</synopsis>
<optional/>
<array type="variable-size">
<typeRef>FEConfiguredNeighborType</typeRef>
</array>
</component>
</components>
<capabilities>
<capability componentID="30">
<name>ModifiableLFBTopology</name>
<synopsis>
Whether Modifiable LFB is supported
</synopsis>
<optional/>
<typeRef>boolean</typeRef>
</capability>
<capability componentID="31">
<name>SupportedLFBs</name>
<synopsis>List of all supported LFBs</synopsis>
<optional/>
<array type="variable-size">
<typeRef>SupportedLFBType</typeRef>
</array>
</capability>
</capabilities>
</LFBClassDef>
</LFBClassDefs>
</LFBLibrary>5.2. FE Capabilities ✨
okay so the FE's capability info lives in the capabilities element of the class definition 💅 and, as we covered earlier, capability info is always read-only, no edits allowed, periodt 🔒. The capabilities that exist right now are ModifiableLFBTopology and SupportedLFBs. If you want to know which components of the FEObject LFB are supported, you look that up in the properties info for those components 🫶
5.2.1. ModifiableLFBTopology 🦋
this component holds a boolean that says whether the CE is allowed to change the FE's LFB topology 🧚 if it's absent, the default is true, so the CE assumes the topology can be changed. if it's present and set to false, the topology is fixed. when the topology is fixed, the SupportedLFBs element is allowed to be left out, because the CE can work out the supported LFBs from the topology info itself. and if the list of supported LFBs IS provided while ModifiableLFBTopology is false, then the CanOccurBefore and CanOccurAfter info should be omitted 🙈
5.2.2. SupportedLFBs and SupportedLFBType 🌈
one capability the FE should include is the list of supported LFB classes 💖 the SupportedLFBs component is an array that holds info about each supported LFB class, and the array's structure type is the SupportedLFBType dataTypeDef.
each entry in the SupportedLFBs array describes an LFB class the FE supports. just saying "yep, we support this class" is only part of the story though. FEs with modifiable LFB topology SHOULD include info about how LFBs of that class may be connected to other LFBs 🔗 that info SHOULD describe which LFB classes the class may succeed or precede in the LFB topology. the FE SHOULD include info about which port groups may be connected to the given adjacent LFB class. if port group info is left out, it is assumed that all port groups may be used. and this capability info about the acceptable ordering and connection of LFBs MAY be omitted if the implementor concludes that the actual constraints are such that the info would be misleading for the CE 🫠
5.2.2.1. LFBName
this component's value is the name of the LFB class being described 🎀
5.2.2.2. LFBClassID
LFBClassID is the numeric ID of the LFB class being described 🔢 yes, it's conceptually redundant with the LFB name, but both are included for clarity and to allow consistency checking. very thorough, very iconic 👑
5.2.2.3. LFBVersion
LFBVersion is the version string that specifies the LFB class version supported by this FE. as we covered above in versioning, an FE can support only a single version of a given LFB class 📌
5.2.2.4. LFBOccurrenceLimit
this component, if present, indicates the largest number of instances of this LFB class the FE can support 🌸 for FEs that can't create or destroy LFB instances, this can either be omitted or be the same as the number of LFB instances of this class contained in the LFB list attribute. no drama, just math 🧮
5.2.2.5. PortGroupLimits and PortGroupLimitType 🍓
the PortGroupLimits component is an array of info about the port groups supported by the LFB class. the structure of the port group limit info is defined by the PortGroupLimitType dataTypeDef.
each PortGroupLimits array entry describes a single port group of the LFB class. every entry has three parts: the name of the port group in the PortGroupName component, the fewest number of ports that can exist in the group in the MinPortCount component, and the largest number of ports that can exist in the group in the MaxPortCount component. min and max, bestie, that's the whole vibe 💜
5.2.2.6. CanOccurAfters and LFBAdjacencyLimitType
okay so CanOccurAfters is the list of LFBs that the described class can occur after 🦋 The array entries are defined in the LFBAdjacencyLimitType dataTypeDef 💅
each entry describes a permissible spot for the described LFB class, which we're calling the SupportedLFB 🌸 basically, each entry names an LFB that can topologically come before that class. so the SupportedLFB can have an input port hooked up to an output port of an LFB listed in CanOccurAfters ✨ the LFB class it can follow is named by the NeighborLFB component (of LFBAdjacencyLimitType) in that entry 🫶 and if that neighbor can only plug into certain input port groups, the viaPort component shows up too. it's an array with one entry for each input port group of the SupportedLFB that can connect to an output port of the NeighborLFB 🎀
(for example, inside a SupportedLFBs entry, each entry in the CanOccurAfters array needs its own unique NeighborLFB 😭 and within each of those entries, every viaPort has to be a distinct, valid input port group of the SupportedLFB. the LFB class definition schema doesn't enforce these uniqueness rules 🙈)
5.2.2.7. CanOccurBefores and LFBAdjacencyLimitType
the CanOccurBefores array tells you which LFB classes can come after the described class 🍓 it's structured like CanOccurAfters and uses the same type for its entries, so it's giving déjà vu, but in the opposite direction 🔄
each entry lists an LFB class that the SupportedLFB may come before in the topology ✨ in this one, the viaPort entries are the output port groups of the SupportedLFB that may connect to the NeighborLFB 💜 just like with CanOccurAfters, viaPort can have several entries if more than one output port can legitimately connect to that NeighborLFB class 🌈
(and the same kind of uniqueness constraints apply to the CanOccurBefore clauses, even though an LFB can appear in both CanOccurAfter and CanOccurBefore 💅)
5.2.2.8. UseableParentLFBClasses
the UseableParentLFBClasses array is optional 🧚 if it's there, it holds a list of parent LFB class IDs. every entry has to be an ID of a class that the SupportedLFB class being described has inherited from, either directly or through an intermediate parent 🌸 (if an FE puts improper values in this list, improper manipulations by the CE are likely, and operational failures are likely 💀) and by including a class in this list, the FE is telling the CE that the parent class can be used to manipulate an instance of this supported LFB class 👑
this substitution is a big deal 🔥 it means an instantiated LFB can be of a class the CE doesn't know about, but the CE can still manipulate it anyway 🫶 the hope is that situations like this are rare, but it's still desirable to support them ✨ it can happen if an FE locally defines certain LFB instances, or if an earlier CE configured some LFB instances. it can also happen if the FE would rather instantiate a newer, more specific and suitable LFB class instead of a common parent 🦋
here's the catch: to make this work, the FE MUST be more restrained in assigning LFB instance IDs 🙈 normally, instance IDs are qualified by the LFB class. but if two LFB classes share a parent, and that parent is listed in the UseableParentLFBClasses for both specific classes, then all the instances of both (or any, if multiple classes list the common parent) MUST use distinct instances 😭 this is what lets the FE figure out which LFB instance the CE meant in a manipulation operation, even when a parent class is used 💖
5.2.2.9. LFBClassCapabilities
ngl, it would be nice to include class-capability-level information 🥺 but it isn't in the model. that info belongs in the FE Object in the supported class table, but its contents would be class specific 🌷 the encoding structures we currently expect for moving information between the CE and FE mean that allowing completely unspecified information would likely cause parse errors 💀 we could say the info gets encoded in an octetstring, but then we'd have to define the internal format of that octetstring too, and that's a whole thing 😩
there also aren't any currently defined LFB class-level capabilities that the FE needs to report, so this information isn't present right now 🍰 it may be added in a future version of the FE object. (this is an example of when versioning, rather than inheritance, would be needed, since the FE object must have class ID 1 and instance ID 1 so the protocol behavior can start by finding this object 🧚)
5.3. FE Components
the <components> element is included if the class definition contains the definition of the FE object components that aren't considered "capabilities" 🎀 some of these are writeable and some are read-only, and you can tell which is which by checking the property information of the components 👀
5.3.1. FEState
this component carries the overall state of the FE 💅 the possible values are the strings AdminDisable, OperDisable, and OperEnable ✨ the starting state is OperDisable, and the transition to OperEnable is controlled by the FE. the CE controls the transition from OperEnable to/from AdminDisable 🫶 for the details, check out the ForCES protocol document [RFC5810] 📚
5.3.2. LFBSelectors and LFBSelectorType
the LFBSelectors component is an array of info about the LFBs that are currently accessible via ForCES in the FE 🦋 the structure of that LFB info is defined by the LFBSelectorType dataTypeDef 🌈
each entry in the array describes a single LFB instance in the FE 💜 the entry holds the numeric class ID of that instance's class, plus the numeric instance ID for the instance itself ✨
5.3.3. LFBTopology and LFBLinkType
the optional LFBTopology component holds info about each inter-LFB link inside the FE, and each link is described in an LFBLinkType dataTypeDef 🌸 LFBLinkType has enough info to pin down the exact end points of a link 🎯 the FromLFBID and ToLFBID components name the LFB instances at each end of the link, and they MUST reference LFBs in the LFB instance table 🙌 the FromPortGroup and ToPortGroup MUST identify output and input port groups defined in the LFB classes of the instances named by FromLFBID and ToLFBID 💖 the FromPortIndex and ToPortIndex components pick the entries from those port groups that the link connects 🍓
all links are uniquely identified by FromLFBID, FromPortGroup, and FromPortIndex 🔑 multiple links can share the same ToLFBID, ToPortGroup, and ToPortIndex, because this model supports fan-in of inter-LFB links but not fan-out 🙈
5.3.4. FENeighbors and FEConfiguredNeighborType
the FENeighbors component is an array of info about manually configured adjacencies between this FE and other FEs 🫶 its content is defined by the FEConfiguredNeighborType dataTypeDef 💅
this array is meant to capture info that can be configured on the FE and is needed by the CE, with one array entry for each configured neighbor ✨ note that this array is not meant to represent the results of any discovery protocols, since those will have their own LFBs 🦋 this component is optional 🌷
there are lots of ways to configure neighbors, but the FE-ID is the best way for the CE to correlate entities 💜 and the interface identifier (name string) is the best correlator 🎀 the CE can figure out the IP address and media-level info about the neighbor straight from the neighbor itself 🧚 leaving that info out of this table avoids the risk of incorrect double configuration 🙅♀️
info about the intended forms of exchange with a given neighbor isn't captured here 🌸 only the adjacency info is included 💅
5.3.4.1. NeighborID
this is the ID, in some space meaningful to the CE, for the neighbor 🍓
5.3.4.2. InterfaceToNeighbor
this identifies the interface through which the neighbor is reached 🛣️
5.3.4.3. NeighborInterface
this identifies the interface on the neighbor through which the neighbor is reached 🦋 the interface identification is needed when either only one side of the adjacency has configuration info, or when the two FEs are adjacent on more than one interface 🌈
6. Satisfying the Requirements on the FE Model ✨
this section explains how the proposed FE model meets the requirements outlined in Section 5 of RFC 3654 [RFC3654] 📖 the requirements split into general requirements (Section 5, 5.1 - 5.4) and the specification of the minimal set of logical functions that the FE model must support (Section 5.5) 💜
the general requirement on the FE model is that it can express the logical packet processing capability of the FE, through both a capability model and a state model 🫶 on top of that, the FE model is expected to allow flexible implementations and be extensible so new logical functions can be defined 🚀
a major component of the proposed FE model is the Logical Functional Block (LFB) model 🧩 each distinct logical function in an FE is modeled as an LFB. operational parameters of the LFB that must be visible to the CE are conceptualized as LFB components 🎀 these components express the capability of the FE and support flexible implementations by letting an FE specify which optional features it supports 🌷 they also indicate whether the CE can configure them for an LFB class 🔧 configurable components give the CE some flexibility in specifying how an LFB behaves 💅 when multiple LFBs from the same LFB class are instantiated on an FE, each one could be configured with different component settings 🍓 by querying the settings of the components for an instantiated LFB, the CE can figure out that LFB's state 🔍
instantiated LFBs are interconnected in a directed graph that describes the ordering of the functions within an FE 🌊 that directed graph is described by the topology model ✨ the combo of the components of the instantiated LFBs and the topology describes the packet processing functions available on the FE (current state) 👑
another key piece of the FE model is the FE components 🦋 they're mainly used to describe the capabilities of the FE, but they also convey info about the FE state 🌈
the FE model only includes the definition of the FE Object LFB itself 🧚 meeting the full set of working group requirements takes other LFBs, and the class definitions for those will be provided in other documents 📚🫶
7. Using the FE Model in the ForCES Protocol 💅
okay so the CE needs to figure out what the forwarding plane in an NE actually looks like, and the only way it learns that is by chatting with the FEs (or some other means) 🦋 Most of that chatter happens after association, in the post-association phase, using the ForCES protocol [RFC5810]. These are the types of info that must get swapped between CEs and FEs via ForCES 🎀
- FE topology query,
- FE capability declaration,
- LFB topology (per FE) and configuration capabilities query,
- LFB capability declaration,
- State query of LFB components,
- Manipulation of LFB components, and
- LFB topology reconfiguration.
Items 1 through 5 are all query exchanges, so the info mostly flows from the FEs to the CEs 🌸 Items 1 through 4 usually get asked by the CE(s) right at the start of the post-association (PA) phase, though they can be asked again whenever during the PA phase. Item 5 (state query) also kicks off at the start of the PA phase, and it gets hammered a lot during the PA phase too, especially when it's pulling statistical counters 📊
Items 6 and 7 are the "command" types, where the info flows from the CEs to the FEs 💜 Item 6 (the LFB re-configuration commands) is expected to be used a lot. Item 7 (LFB topology re-configuration) is only needed if the FEs support dynamic LFB topologies, and it's expected to be used pretty rarely ✨
Now the inter-FE topology (that's Item 1 up there) can be figured out by the CE in lots of different ways 🧚 Neither this document nor the ForCES protocol [RFC5810] document mandates one specific mechanism. The LFB class definition does have the capability for an FE to be configured with, and to tell the CE when asked, the identity of its neighbors. There may also be specific LFB classes and protocols defined for neighbor discovery. Routing protocols can be used by the CE for adjacency determination, and the CE may also just be configured with the relevant information 🔥
Here's how the FE model and those seven post-association messages relate, visualized in Figure 12 💖
+--------+
..........-->| CE |
/----\ . +--------+
\____/ FE Model . ^ |
| |................ (1),2 | | 6, 7
| | (off-line) . 3, 4, 5 | |
\____/ . | v
. +--------+
e.g., RFCs ..........-->| FE |
+--------+
Figure 12: Relationship between the FE model and the ForCES protocol
messages, where (1) is part of the ForCES base protocol, and the
rest are defined by the FE model.The actual encoding of these messages is defined by the ForCES protocol [RFC5810] document, which is beyond the scope of the FE model 🫶 Their discussion still matters here though, for a few reasons:
- These PA model components have a big impact on the FE model. For example, some of the info above can be represented as components of the LFBs, and if so, those components must be defined in the LFB classes.
- Understanding what kind of info has to flow between the FEs and CEs can help when choosing the right protocol format and the actual encoding method (such as XML, TLVs).
- Understanding how often these types of messages happen should influence the choice of protocol format (efficiency considerations).
The remaining sub-sections of this section address each of the seven message types 🌈
7.1. FE Topology Query
An FE may contain zero, one, or more external ingress ports. Similarly, an FE may contain zero, one, or more external egress ports. In other words, not every FE has to contain any external ingress or egress interfaces 🍓 For example, Figure 13 shows two cascading FEs. FE #1 has one external ingress interface but no external egress interface, while FE #2 has one external egress interface but no ingress interface. You can connect these two FEs together through their internal interfaces to get the complete ingress-to-egress packet processing function. This gives you the flexibility to spread the functions across multiple FEs and interconnect them later for certain applications 😭
While the inter-FE communication protocol is out of scope for ForCES, it's up to the CE to query and figure out how multiple FEs are interconnected to perform a complete ingress-egress packet processing function, like the one in Figure 13 💅 The inter-FE topology info may be provided by the FEs, may be hard-coded into the CE, or may be provided by some other entity (for example, a bus manager) that's independent of the FEs. So while the ForCES protocol [RFC5810] supports FE topology query from FEs, it is optional for the CE to use it, assuming the CE has other ways to gather that topology info 🙈
+-----------------------------------------------------+
| +---------+ +------------+ +---------+ |
input| | | | | | output |
---+->| Ingress |-->|Header |-->|IPv4 |---------+--->+
| | port | |Decompressor| |Forwarder| FE | |
| +---------+ +------------+ +---------+ #1 | |
+-----------------------------------------------------+ V
|
+-----------------------<-----------------------------+
|
| +----------------------------------------+
V | +------------+ +----------+ |
| input | | | | output |
+->--+->|Header |-->| Egress |---------+-->
| |Compressor | | port | FE |
| +------------+ +----------+ #2 |
+----------------------------------------+
Figure 13: An example of two FEs connected together.Once the CE has discovered the inter-FE topology with this query, the inter-FE topology is assumed to stay static 🦋 Still, an FE can go down while the NE is running, or a board can be inserted and a new FE activated, and then the inter-FE topology gets affected. It's up to the ForCES protocol to give the CE a mechanism to detect those events and deal with the change in FE topology. FE topology is outside the scope of the FE model 💜
7.2. FE Capability Declarations
FEs come with plenty of limitations 🎀 Some of those limitations have to be expressed to the CEs as part of the capability model, and the CEs must be able to query those capabilities on a per-FE basis. Examples include:
- Metadata passing capabilities of the FE. Understanding these helps the CE evaluate whether an LFB topology is feasible, and so decide whether certain services are available at all 🧠
- Global resource query limitations (applicable to all LFBs of the FE).
- LFB supported by the FE.
- LFB class instantiation limit.
- LFB topological limitations (linkage constraint, ordering, etc.).
7.3. LFB Topology and Topology Configurability Query
The ForCES protocol must provide the means for CEs to discover the current set of LFB instances in an FE, and the interconnections between those LFBs within the FE 🌸 On top of that, sufficient info should be available to determine whether the FE supports any CE-initiated (dynamic) changes to the LFB topology and, if it does, to figure out which topologies are allowed. Topology configurability can also be considered as part of the FE capability query described in Section 7.2 ✨
7.4. LFB Capability Declarations
LFB class specifications define a generic set of capabilities 💖 When an LFB instance gets implemented (instantiated) on a vendor's FE, some extra limitations may show up. We're only talking about the limitations that sit within the flexibility of the LFB class specification here. That means the LFB instance still stays compliant with the LFB class specification despite these limitations 🦋 For example, certain features of an LFB class may be optional, in which case the CE must be able to tell whether a given LFB instance supports that optional feature or not. Also, LFB class definitions will probably have very few quantitative limits (like table sizes), since those limits are usually imposed by the implementation. So quantitative limitations should always be expressed by capability arguments 🔥
LFB instances in the model of a particular FE implementation will have limitations on the capabilities defined in the corresponding LFB class. The LFB class specifications must define a set of capability arguments, and the CE must be able to query the actual capabilities of the LFB instance by querying the value of those arguments. The capability query will typically happen when the CE first detects the LFB 🎀 Capabilities don't need to be re-queried when the limitations are static. In some cases, though, capabilities can change over time (for example, when other LFBs are added or removed, or when some other LFB's components get configured while they share physical resources). In those cases, additional mechanisms must be implemented to inform the CE about the changes 😭
There are two broad types of limitations that will exist:
- Qualitative restrictions. For example, a standardized multi-field classifier LFB class may define a large number of classification fields, but a given FE may only support a subset of them 💅
- Quantitative restrictions, such as the maximum size of tables, etc.
The capability parameters that can be queried on a given LFB class will be part of the LFB class specification 🌈 Those capability parameters should be regarded as special components of the LFB, so their actual values can be obtained using the same component query mechanisms used for other LFB components 🧚
Capability components are read-only arguments. In cases where some implementations allow CE modification of the value, the info must be represented as an operational component, not a capability component 🙈
Assuming capabilities won't change frequently, the efficiency of the protocol/schema/encoding is only a secondary concern 🍓
Much of this restrictive info is captured by the component property information, so it can be accessed uniformly for all information within the model 💜
7.5. State Query of LFB Components 🔍
Okay so this one is a must for every FE 💅. The ForCES protocol and the data schema/encoding it carries have to work together so that querying the state of LFB components is smooth and efficient. Here's what they need to hit:
- FE selection 🎯: it has to be possible to pick a single FE. Targeting a group of FEs (or all of them) can be supported too, but that part is optional.
- LFB instance selection 🧚: it has to be possible to pick a single LFB instance on an FE. Addressing a group of LFBs (or all of them) is optional.
- Component addressing 🎀: you have to be able to address individual components inside an LFB.
- Efficient encoding and decoding ✨: the addressing info and the configured data have to be encoded and decoded efficiently.
- Efficient transmission 🚀: component state has to go over the wire efficiently, so we don't clog up the CE-FE link.
7.6. LFB Component Manipulation 🧩
Okay, the FE model lets you define LFB classes, and every class gets a globally unique identifier 🆔. Whatever info lives inside a class is represented as components, and each component gets an identifier that's scoped to its class. The model also says that LFB class instances have identifiers too 🙌.
So the protocol references LFB information using a combo of three things: the class identifier, the instance identifier, and the component identifier. That trio is what shows up in the protocol operations 💖.
7.7. LFB Topology Reconfiguration 🕸️
Okay, here are the operations you'll need to reconfigure LFB topology 🪄:
- Create a new instance of a given LFB class on a given FE 🐣.
- Connect a given output of LFB
xto the given input of LFBy🔌. - Disconnect: remove a link between a given output of an LFB and a given input of another LFB ✂️.
- Delete a given LFB, which automatically removes all interconnects to and from that LFB 🗑️. Bye bye, links 👋.
8. Example LFB Definition 🍓
Okay, this section has an example LFB definition 🎬. The FE Object LFB already shows some LFB properties, but this one is all about how a data plane LFB might actually be built. The example is totally fictional: it's an interface supporting a coarse WDM optical interface that carries frame relay traffic 🌈. The statistical info, including error stats, is left out, so no stats drama here 🙈.
Some later bits of the example mention protocol operations. Those are operations the protocol needs to support. The exact format and fields are purely informational here, because the ForCES protocol [RFC5810] document is the one that actually defines the precise syntax and semantics of its operations 📖. So this is just vibes, the real rules live in [RFC5810] 💅.
<?xml version="1.0" encoding="UTF-8"?>
<LFBLibrary xmlns="urn:ietf:params:xml:ns:forces:lfbmodel:1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
provides="LaserFrameLFB">
<frameDefs>
<frameDef>
<name>FRFrame</name>
<synopsis>
A frame relay frame, with DLCI without
stuffing)
</synopsis>
</frameDef>
<frameDef>
<name>IPFrame</name>
<synopsis>An IP Packet</synopsis>
</frameDef>
</frameDefs>
<dataTypeDefs>
<dataTypeDef>
<name>frequencyInformationType</name>
<synopsis>
Information about a single CWDM frequency
</synopsis>
<struct>
<component componentID="1">
<name>LaserFrequency</name>
<synopsis>encoded frequency(channel)</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="2">
<name>FrequencyState</name>
<synopsis>state of this frequency</synopsis>
<typeRef>PortStatusValues</typeRef>
</component>
<component componentID="3">
<name>LaserPower</name>
<synopsis>current observed power</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="4">
<name>FrameRelayCircuits</name>
<synopsis>
Information about circuits on this Frequency
</synopsis>
<array>
<typeRef>frameCircuitsType</typeRef>
</array>
</component>
</struct>
</dataTypeDef>
<dataTypeDef>
<name>frameCircuitsType</name>
<synopsis>
Information about a single Frame Relay Circuit
</synopsis>
<struct>
<component componentID="1">
<name>DLCI</name>
<synopsis>DLCI of the circuit</synopsis>
<typeRef>uint32</typeRef>
</component>
<component componentID="2">
<name>CircuitStatus</name>
<synopsis>state of the circuit</synopsis>
<typeRef>PortStatusValues</typeRef>
</component>
<component componentID="3">
<name>isLMI</name>
<synopsis>is this the LMI circuit</synopsis>
<typeRef>boolean</typeRef>
</component>
<component componentID="4">
<name>associatedPort</name>
<synopsis>
which input / output port is associated
with this circuit
</synopsis>
<typeRef>uint32</typeRef>
</component>
</struct>
</dataTypeDef>
<dataTypeDef>
<name>PortStatusValues</name>
<synopsis>
The possible values of status. Used for both
administrative and operational status
</synopsis>
<atomic>
<baseType>uchar</baseType>
<specialValues>
<specialValue value="0">
<name>Disabled </name>
<synopsis>the component is disabled</synopsis>
</specialValue>
<specialValue value="1">
<name>Enabled</name>
<synopsis>FE is operatively enabled</synopsis>
</specialValue>
</specialValues>
</atomic>
</dataTypeDef>
</dataTypeDefs>
<metadataDefs>
<metadataDef>
<name>DLCI</name>
<synopsis>The DLCI the frame arrived on</synopsis>
<metadataID>12</metadataID>
<typeRef>uint32</typeRef>
</metadataDef>
<metadataDef>
<name>LaserChannel</name>
<synopsis>The index of the laser channel</synopsis>
<metadataID>34</metadataID>
<typeRef>uint32</typeRef>
</metadataDef>
</metadataDefs>
<LFBClassDefs>
<!-- dummy classid, but needs to be a valid value -->
<LFBClassDef LFBClassID="255">
<name>FrameLaserLFB</name>
<synopsis>Fictional LFB for Demonstrations</synopsis>
<version>1.0</version>
<inputPorts>
<inputPort group="true">
<name>LMIfromFE</name>
<synopsis>
Ports for LMI traffic, for transmission
</synopsis>
<expectation>
<frameExpected>
<ref>FRFrame</ref>
</frameExpected>
<metadataExpected>
<ref>DLCI</ref>
<ref>LaserChannel</ref>
</metadataExpected>
</expectation>
</inputPort>
<inputPort>
<name>DatafromFE</name>
<synopsis>
Ports for data to be sent on circuits
</synopsis>
<expectation>
<frameExpected>
<ref>IPFrame</ref>
</frameExpected>
<metadataExpected>
<ref>DLCI</ref>
<ref>LaserChannel</ref>
</metadataExpected>
</expectation>
</inputPort>
</inputPorts>
<outputPorts>
<outputPort group="true">
<name>LMItoFE</name>
<synopsis>
Ports for LMI traffic for processing
</synopsis>
<product>
<frameProduced>
<ref>FRFrame</ref>
</frameProduced>
<metadataProduced>
<ref>DLCI</ref>
<ref>LaserChannel</ref>
</metadataProduced>
</product>
</outputPort>
<outputPort group="true">
<name>DatatoFE</name>
<synopsis>
Ports for Data traffic for processing
</synopsis>
<product>
<frameProduced>
<ref>IPFrame</ref>
</frameProduced>
<metadataProduced>
<ref>DLCI</ref>
<ref>LaserChannel</ref>
</metadataProduced>
</product>
</outputPort>
</outputPorts>
<components>
<component access="read-write" componentID="1">
<name>AdminPortState</name>
<synopsis>is this port allowed to function</synopsis>
<typeRef>PortStatusValues</typeRef>
</component>
<component access="read-write" componentID="2">
<name>FrequencyInformation</name>
<synopsis>
table of information per CWDM frequency
</synopsis>
<array type="variable-size">
<typeRef>frequencyInformationType</typeRef>
</array>
</component>
</components>
<capabilities>
<capability componentID="31">
<name>OperationalState</name>
<synopsis>
whether the port over all is operational
</synopsis>
<typeRef>PortStatusValues</typeRef>
</capability>
<capability componentID="32">
<name>MaximumFrequencies</name>
<synopsis>
how many laser frequencies are there
</synopsis>
<typeRef>uint16</typeRef>
</capability>
<capability componentID="33">
<name>MaxTotalCircuits</name>
<synopsis>
Total supportable Frame Relay Circuits, across
all laser frequencies
</synopsis> <optional/> <typeRef>uint32</typeRef> </capability> </capabilities> <events baseID="61"> <event eventID="1"> <name>FrequencyState</name> <synopsis> The state of a frequency has changed </synopsis> <eventTarget> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>FrequencyState</eventField> </eventTarget> <eventChanged/> <eventReports> <!-- report the new state --> <eventReport> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>FrequencyState</eventField> </eventReport> </eventReports> </event> <event eventID="2"> <name>CreatedFrequency</name> <synopsis>A new frequency has appeared</synopsis> <eventTarget> <eventField>FrequencyInformation></eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> </eventTarget> <eventCreated/> <eventReports> <eventReport> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>LaserFrequency</eventField> </eventReport> </eventReports> </event> <event eventID="3"> <name>DeletedFrequency</name> <synopsis> A frequency Table entry has been deleted </synopsis> <eventTarget>
<eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> </eventTarget> <eventDeleted/> </event> <event eventID="4"> <name>PowerProblem</name> <synopsis> there are problems with the laser power level </synopsis> <eventTarget> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>LaserPower</eventField> </eventTarget> <eventLessThan/> <eventReports> <eventReport> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>LaserPower</eventField> </eventReport> <eventReport> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>LaserFrequency</eventField> </eventReport> </eventReports> </event> <event eventID="5"> <name>FrameCircuitChanged</name> <synopsis> the state of an Fr circuit on a frequency has changed </synopsis> <eventTarget> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>FrameRelayCircuits</eventField> <eventSubscript>FrameCircuitIndex</eventSubscript> <eventField>CircuitStatus</eventField> </eventTarget> <eventChanged/> <eventReports> <eventReport> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>FrameRelayCircuits</eventField> <eventSubscript>FrameCircuitIndex</eventSubscript> <eventField>CircuitStatus</eventField> </eventReport> <eventReport> <eventField>FrequencyInformation</eventField> <eventSubscript>_FrequencyIndex_</eventSubscript> <eventField>FrameRelayCircuits</eventField> <eventSubscript>FrameCircuitIndex</eventSubscript> <eventField>DLCI</eventField> </eventReport> </eventReports> </event> </events> </LFBClassDef> </LFBClassDefs> </LFBLibrary>
## 8.1. Data Handling 🌐✨
<pink>Okay so</pink> this LFB is built to handle data packets coming in from the outside world or heading back out to it 📡 It's not a full port and it's missing a bunch of useful stats, but it shows off a lot of the important behaviors 💅 The next paragraphs walk through a possible real device and how it could use this LFB definition 🎀
Packets that arrive without error from the physical interface come in on a frame relay DLCI on a laser channel 🔦 The LFB uses those two values to look up how to handle the packet 🔍 If the handling says the packet is LMI, the output index picks an LFB port from the LMItoFE port group 💌 The packet gets sent as a full frame relay frame (no bit or byte stuffing!) on that port. The laser channel and DLCI get sent along as metadata, even though the DLCI is still sitting inside the packet too 🫶
Good packets that aren't LMI and have a frame relay type indicator of IP get sent out as IP packets on the port in the DatatoFE port group 🦋 They use the same index field from the table, based on the laser channel and DLCI. The channel and DLCI get attached as metadata for other stuff, like classifiers 🧚
<lavender>The current definition doesn't say what to do if the frame relay type information isn't IP</lavender> 🤷 That's just not specified, bestie.
Packets arriving on input ports come in with the laser channel and frame relay DLCI as metadata 🏷️ So technically a single input port could have done the job! With the structure that's defined (which mirrors the output side), the selection of channel and DLCI could be limited by the arriving input port group (LMI vs. data) and port index 🚪 As an alternative LFB design, the structures could require a 1-1 relationship between DLCI and the LFB port, in which case no metadata would be needed. Ngl, that would be super complex and noisy 😵💫 This middle level of structure lets input and output run in parallel without needing excessive ports 👑
---
### 8.1.1. Setting Up a DLCI 📨
<cyan>When a CE chooses to establish a DLCI on a specific laser channel</cyan>, it sends a SET request directed to this LFB 💫 The request might look like this:
T = SET T = PATH-DATA Path: flags = none, length = 4, path = 2, channel, 4, entryIdx DataRaw: DLCI, Enabled(1), false, out-idx
This would establish the DLCI as enabled, with traffic going to a specific entry of the output port group DatatoFE 🎯 (The CE would make sure the output port is connected to the right place before sending this request 🔌)
The response would confirm the creation of the specified entry 🎉 This table is structured to use separate internal indices and DLCIs. An alternative design could have used the DLCI as the index, trading off complexities ⚖️
One could also imagine that the FE has an LMI LFB 🧠 Such an LFB would be connected to the LMItoFE and LMIfromFE port groups, and it would process LMI information. It might be the LFB's job to set up the frame relay circuits 🔧 The LMI LFB would have an alias entry that points to the frame relay circuits table it manages, so that it can manipulate those entities 🎀
### 8.1.2. Error Handling 🚨
The LFB will receive invalid packets over the wire, no cap 😤 Many of these will simply result in incrementing counters. The LFB designer might also specify some error rate measures. This puts more work on the FE, but it allows for way more meaningful alarms 💯
There may be some error conditions that should cause parts of the packet to be sent to the CE 📦 The error itself is not something that can cause an event in the LFB. There are two ways this can be handled 💁
<mint>One way</mint> is to define a specific component to count the error, and a component in the LFB to hold the required portion of the packet 🗂️ The component could be defined to hold the portion of the packet from the most recent error. Then one could define an event that occurs whenever the error count changes, and declare that reporting the event includes the LFB field with the packet portion. For rare but extremely critical errors, this is an effective solution 🛡️ It ensures reliable delivery of the notification, and it allows the CE to control whether it wants the notification 🫶
<mint>Another approach</mint> is for the LFB to have a port that connects to a redirect sink 🪣 The LFB would attach the laser channel, the DLCI, and the error indication as metadata, and ship the packet to the CE 🚀
Other aspects of error handling are discussed under events below 👀
---
## 8.2. LFB Components 🧩
This LFB is defined to have two top-level components. <peach>One reflects the administrative state of the LFB.</peach> This allows the CE to disable the LFB completely 🛑
The other component is the table of information about the laser channels 📊 It is a variable-sized array. Each array entry contains an identifier for what laser frequency this entry is associated with, whether that frequency is operational, the power of the laser at that frequency, and a table of information about frame relay circuits on this frequency 💜 There is no administrative status since a CE can disable an entry simply by removing it 🙅 (Frequency and laser power of a non-operational channel are not particularly useful, tbh. Knowledge about what frequencies can be supported would be a table in the capabilities section 📚)
The frame relay circuit information contains the DLCI, the operational circuit status, whether this circuit is to be treated as carrying LMI information, and which port in the output port group of the LFB traffic is to be sent to 🎯 As mentioned above, the circuit index could, in some designs, be combined with the DLCI 🧠
---
## 8.3. Capabilities 📶
The capability information for this LFB includes whether the underlying interface is operational, how many frequencies are supported, and how many total circuits, across all channels, are permitted 🌈 The maximum number for a given laser channel can be determined from the properties of the FrameRelayCircuits table 🔍 A `GET-PROP` on path `2.channel.4` will give the CE the properties of that FrameRelayCircuits array, which include the number of entries used, the first available entry, and the maximum number of entries permitted 💖
# 8.4. Events ✨
okay so this LFB can generate several events the CE might care about 👀 There are events for changes in the operational state of frequencies and for creation and deletion of frequency entries. There's also an event for status changes on individual frame relay circuits. So an event notification of `61.5.3.11` would mean there was a circuit status change on subscript 11 of the circuit table in subscript 3 of the frequency table 💅 The event report would include the circuit's new status and its DLCI. Arguably the DLCI is redundant, since the CE presumably knows the DLCI from the circuit index 🙈 It's included anyway to show how an event report can carry two pieces of info.
As described above, the event declaration defines the event target, the event condition, and the event report content. The event properties say whether the CE is subscribed to the event, what the specific threshold is, and any filter conditions 🎀
Another event is a <red>laser power problem</red> 🔥 It gets generated whenever the laser falls below the specified threshold. So a CE can register for laser power loss on all circuits. It would do that like this:
T = SET-PROP Path-TLV: flags=0, length = 2, path = 61.4 Path-TLV: flags = property-field, length = 1, path = 2 Content = 1 (register) Path-TLV: flags = property-field, length = 1, path = 3 Content = 15 (threshold)
This sets the registration for the event on all entries in the table 💖 It also sets the threshold, so reporting kicks in if the power falls below 15. (Presumably the CE knows what the scale for power is, and picked 15 as a meaningful problem level 🧚)
If a laser oscillates in power near the 15 mark, you could get a LOT of notifications 😭 (If it flips between 14 and 15, every flip down generates an event.) So say the CE wants to calm that down a bit on laser channel 5. It can set the hysteresis property on that event, and the request would look like this:
T = SET-PROP Path-TLV: flags=0, length = 3, path = 61.4.5 Path-TLV: flags = property-field, length = 1, path = 4 Content = 2 (hysteresis)
Setting the hysteresis to 2 suppresses a lot of spurious notifications 🦋 When the level first falls below 10, a notification is generated. If the power then rises to 10 or 11 and falls back below 10, no event gets generated. The power has to recover to at least 12 and then fall back below 10 before another event shows up 💜 One common cause of this kind of oscillation is when the real value sits right on the border. If it's really 9.5, tiny changes can flip it between 9 and 10. A hysteresis level of 1 suppresses that sort of thing. Lots of other events wiggle over a wider range, so bigger hysteresis settings work better for those 🌈
# 9. IANA Considerations 🎀
okay the ForCES model needs a unique XML namespace for ForCES library definition usage, plus unique class names and numeric class identifiers 🌸
## 9.1. URN Namespace Registration
IANA has registered a new XML namespace, per the guidelines in RFC 3688 [RFC3688] 🍓
The URI for this namespace is `urn:ietf:params:xml:ns:forces:lfbmodel:1.0`
Registrant Contact: IESG
XML: none, this is an XML namespace
## 9.2. LFB Class Names and LFB Class Identifiers
So to get well-defined ForCES LFB Classes and well-defined identifiers for them, IANA created a registry of LFB class names, their class identifiers, and the document that defines each LFB class ✨ The registry policy for LFB class names is first come, first served (FCFS) 💅 For LFB class identifiers, identifiers less than 65536 are reserved for assignment by IETF Standards-Track RFCs. Identifiers equal to or above 65536, in the 32-bit class ID space, are available on a first come, first served basis. Every registry entry must be documented in a stable, publicly available form 🫶
Since this registry hands out part of the class identifier space on an FCFS basis, we need rules for naming those classes 👑 Anyone can define them, so the rule is to keep FCFS class names from colliding with IETF-defined class names. That's why all FCFS class names <hotpink>MUST</hotpink> start with the string "Ext-" 🔥
Table 1 tabulates the above information.
IANA has created a registry of ForCES LFB Class Names and the corresponding ForCES LFB Class Identifiers, along with the location of the definition of each ForCES LFB Class, following the rules in this table:
+----------------+------------+---------------+---------------------+
| LFB Class Name | LFB Class | Place Defined | Description |
|---|---|---|---|
| Identifier |
+----------------+------------+---------------+---------------------+
| Reserved | 0 | RFC 5812 | Reserved |
|---|---|---|---|
| FE Object | 1 | RFC 5812 | Defines ForCES |
| Forwarding Element | |||
| information | |||
| FE Protocol | 2 | [2] | Defines parameters |
| Object | for the ForCES | ||
| protocol operation | |||
| IETF defined | 3-65535 | Standards | Reserved for IETF |
| LFBs | Track RFCs | defined RFCs | |
| ForCES LFB | >65535 | Any Publicly | First Come, First |
| Class names | Available | Served for any use | |
| beginning EXT- | Document |
+----------------+------------+---------------+---------------------+
Table 1
# 10. Authors Emeritus 🧚
These are the authors who were instrumental in creating earlier releases of this document 🌷
- Ellen Delganes, Intel Corp.
- Lily Yang, Intel Corp.
- Ram Gopal, Nokia Research Center
- Alan DeKok, Infoblox, Inc.
- Zsolt Haraszti, Clovis Solutions
# 11. Acknowledgments 🫶
Tons of colleagues at our companies and participants on the ForCES mailing list gave invaluable input to this work 💖 Special thanks to Evangelos Haleplidis for help getting the XML right 👑
# 12. Security Considerations 💀
Okay, this part is serious bestie 😭 The FE model describes how data sets and components in the FEs are represented and organized. The ForCES framework document [RFC3746] provides a comprehensive security analysis for the whole ForCES architecture. For example, ForCES protocol entities must be authenticated per the ForCES requirements before they can access the information elements described in this document via ForCES. Access to the information in the FE model happens through the ForCES protocol, which is defined in separate documents, so the security issues get addressed there 🔒✨
# 13. References 📚
## 13.1. Normative References
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC5810] Doria, A., Ed., Hadi Salim, J., Ed., Haas, R., Ed., Khosravi, H., Ed., Wang, W., Ed., Dong, L., Gopal, R., and J. Halpern, "Forwarding and Control Element Separation (ForCES) Protocol Specification", RFC 5810, March 2010.
- [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
- [Schema1] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML Schema Part 1: Structures", W3C REC-xmlschema-1, `http://www.w3.org/TR/xmlshcema-1/`, May 2001.
- [Schema2] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes", W3C REC-xmlschema-2, `http://www.w3.org/TR/xmlschema-2/`, May 2001.
## 13.2. Informative References
- [RFC3654] Khosravi, H. and T. Anderson, "Requirements for Separation of IP Control and Forwarding", RFC 3654, November 2003.
- [RFC3746] Yang, L., Dantu, R., Anderson, T., and R. Gopal, "Forwarding and Control Element Separation (ForCES) Framework", RFC 3746, April 2004.
- [RFC3317] Chan, K., Sahita, R., Hahn, S., and K. McCloghrie, "Differentiated Services Quality of Service Policy Information Base", RFC 3317, March 2003.
- [RFC3318] Sahita, R., Hahn, S., Chan, K., and K. McCloghrie, "Framework Policy Information Base", RFC 3318, March 2003.
- [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between Information Models and Data Models", RFC 3444, January 2003.
- [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols", BCP 70, RFC 3470, January 2003.
- [UNICODE] Davis, M. and M. Suignard, "UNICODE Security Considerations", `http://www.unicode.org/reports/tr36/tr36-3.html ` , July 2005.
# Authors' Addresses 🌸
Joel Halpern Self P.O. Box 6049 Leesburg, VA 20178 USA
Phone: +1 703 371 3043 EMail: jmh@joelhalpern.com
Jamal Hadi Salim Znyx Networks Ottawa, Ontario Canada
EMail: hadi@mojatatu.com
📦 where this page comes from
- ietf: rfc5812 2010-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms