RFC 5812
Forwarding and Control Element Separation (ForCES) Forwarding Element Model
4. Model and Schema for LFB Classes
The main goal of the FE model is to provide an abstract, generic, modular, implementation-independent representation of the FEs. This is facilitated using the concept of LFBs, which are instantiated from LFB classes. LFB classes and associated definitions will be provided
in a collection of XML documents. The collection of these XML documents is called an LFB class library, and each document 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 the schema are those 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 will serve as an important reference for the design and development of 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 primarily provide the necessary semantic information to understand the meaning and uses of the XML elements. The XML schema below provides the final definition on what elements are permitted, and their base syntax. Unfortunately, due to the limitations of English and XML, there are constraints described in the semantic sections that are not fully captured in the XML schema, so both sets of information need to be used 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 serves as a root element of all library documents. A library document contains a sequence of top-level elements. The following is a list of all the elements that can occur directly in the <LFBLibrary> element. If they occur, they must occur in the order listed. o <description> providing a text description of the purpose of the library document, o <load> for loading information from other library documents, o <frameDefs> for the frame declarations,
o <dataTypeDefs> for defining common data types, o <metadataDefs> for defining metadata, and o <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 contained in the included document. This concept is similar to the "#include" directive in the C programming language. Importing is expressed by the use of <load> elements, which must precede all 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 what this performs 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, in terms of the conceptual processing of <load> elements, the total set of documents loaded is considered to form a single document for processing. A given document is included in this set only once, even if it is referenced by <load> elements several times, even from several different files. As the processing of 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 such computer processing of ForCES model library documents may be helpful for various implementations, but 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.
Similar to the "#include" directive in C, this 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. Below
are three examples for the <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 <frameDefs> optional 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
The (optional) <dataTypeDefs> element can be used to define commonly
used data types. It contains one or more <dataTypeDef> elements,
each defining a data type with a unique name. Such data types can be
used in several places in the library documents, including:
o Defining other data types
o Defining components of LFB classes
This is similar to the concept of having a common header file for
shared data types.
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 appropriate for single-value variables (e.g., integer,
string, byte array).
The following built-in atomic data types are provided, but additional
atomic data types can be defined 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 number
These built-in data types can be readily used to define metadata or
LFB attributes, but can also be used as building blocks when defining
new data types. The boolean data type is defined here because it is
so common, even though it can be built by sub-ranging the uchar data
type, as defined under atomic types (Section 4.5.2).
Compound data types can build on atomic data types and other compound
data types. Compound data types can be defined in one of four ways.
They may be defined as an array of components of some compound or
atomic data type. They may be a structure of named components of
compound or atomic data types (cf. C structures). They may be a
union of named components of compound or atomic data types (cf. C
unions). They may also be defined as augmentations (explained in
Section 4.5.7) of existing compound data types.
Given that the ForCES protocol will be getting and setting component
values, all atomic data types used here must be able to be conveyed
in the ForCES protocol. Further, the ForCES protocol will need a
mechanism to convey compound data types. However, the details of
such representations are for the ForCES protocol [RFC5810] document
to define, not the model document. Strings and octetstrings must be
conveyed by the protocol with their length, as they are not
delimited, the value does not itself include the length, and these
items are variable length.
With regard to strings, this model defines a small set of restrictions and definitions on how they are structured. String and octetstring length limits can be specified in the LFB class definitions. The component properties for string and octetstring components also contain actual lengths and length limits. This duplication of limits is to allow for implementations with smaller limits than the maximum limits specified in the LFB class definition. In all cases, these lengths are specified in octets, not in characters. In terms of protocol operation, as long as the specified length is within the FE's supported capabilities, the FE stores the contents of a string exactly as provided by the CE, and returns those contents when requested. No canonicalization, transformations, or equivalences are performed by the FE. Components of type string (or string[n]) MAY be used to hold identifiers for correlation with components in other LFBs. In such cases, an exact octet for octet match is used. No equivalences are used by the FE or CE in performing that matching. The ForCES protocol [RFC5810] does not perform or require validation of the content of UTF-8 strings. However, UTF-8 strings SHOULD be encoded in the shortest form to avoid potential security issues described in [UNICODE]. Any entity displaying such strings is expected to perform its own validation (for example, for correct multi-byte characters, and for ensuring that the string does not end in the middle of a multi-byte sequence). Specific LFB class definitions MAY restrict the valid contents of a string as suited to the particular usage (for example, a component that holds a DNS name would be restricted to hold only 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, just as range checks for range-limited components are performed. The ForCES protocol behavior defines the normative processing for requests using that protocol. For the definition of the actual type in the <dataTypeDef> element, the following elements are available: <typeRef>, <atomic>, <array>, <struct>, and <union>. The predefined type alias is somewhere between the atomic and compound data types. Alias is used to allow a component inside an LFB to be an indirect reference to another component inside the same or a different LFB class or instance. The alias component behaves like a structure, one component of which has special behavior. Given that the special behavior is tied to the other parts of the structure, the compound result is 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 an atomic data type, the newly defined type will also be regarded as atomic. If the referred data type is a compound type, the new type will also be compound. Some usage examples follow: <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 allows the definition of a new atomic type from an existing atomic type, applying range restrictions and/or providing special enumerated values. Note that the <atomic> element can only use atomic types as base types, and its result MUST be another atomic type. For example, the following 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
The <array> element can be used to create a new compound data type as an array of a compound or an atomic data type. Depending upon context, this document and others refer to such arrays as tables or arrays interchangeably, without semantic or syntactic implication. The type of the array entry can be specified either by referring to an existing type (using the <typeRef> element) or defining an unnamed type inside the <array> element using any of the <atomic>, <array>, <struct>, or <union> elements. The array can be "fixed-size" or "variable-size", which is specified by the "type" attribute of the <array> element. The default is "variable-size". For variable-size arrays, an optional "maxlength" attribute specifies the maximum allowed length. This attribute should be used to encode semantic limitations, not implementation limitations. The latter (support for implementation constraints) should be handled by capability components of LFB classes, and should never be included as the maxlength in a data type array that is regarded as being of unlimited size. For fixed-size arrays, a "length" attribute MUST be provided that specifies the constant size of the array. The result of this construct is always a compound type, even if the array has a fixed size of 1. Arrays MUST only be subscripted by integers, and will be presumed to start with index 0. In addition to their subscripts, arrays MAY be declared to have content keys. Such a declaration has several effects: o Any declared key can be used in the ForCES protocol to select a component for operations (for details, see the ForCES protocol [RFC5810]). o In any instance of the array, each declared key MUST be unique within that instance. That is, no two components of an array may have the same values on all the fields that make up a key. Each key is declared with a keyID for use in the ForCES protocol [RFC5810], where the unique key is formed by combining one or more specified key fields. To support the case where an array of an atomic type with unique values can be referenced by those values, the key field identifier MAY be "*" (i.e., the array entry is the key). If the value type of the array is a structure or an array, then the key is one or more components of the value type, each identified by
name. Since the field MAY be a component of the contained structure,
a component of a component of a structure, or further nested, the
field name is actually a concatenated sequence of component
identifiers, separated by decimal points ("."). The syntax for key
field identification is given following the array examples.
The following example shows the definition of a fixed-size array with
a predefined data type as the array 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>
The following example defines 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>
The following example shows the definition of 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 the above example, each entry of the array is a <struct> of two
components ("rule" and "opcode").
The following example shows a table of IP prefix information that can
be accessed by a multi-field content key on the IP address, prefix
length, and information source. This means that in any instance of
this table, no two entries can have 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>
Note that the keyField elements could also have been simply address-
prefix and source, since all of the fields of address-prefix are
being used.
4.5.3.1. Key Field References
In order to use key declarations, one must refer to components that are potentially nested inside other components in the array. If there are nested arrays, one might even use an array element as a key (but great care would be needed to ensure uniqueness). The key is the combination of the values of each field declared in a keyField element. Therefore, the value of a keyField element MUST be a concatenated sequence of field identifiers, separated by a "." (period) character. Whitespace is permitted and ignored. A valid string for a single field identifier within a keyField depends upon the current context. Initially, in an array key declaration, the context is the type of the array. Progressively, the context is whatever type is selected by the field identifiers processed so far in the current key field declaration. When the current context is an array (e.g., when declaring a key for an array whose content is an array), then the only valid value for the field identifier is an explicit number. When the current context is a structure, the valid values for the field identifiers are the names of the components of the structure. In the special case of declaring a key for an array containing an atomic type, where that content is unique and is to be used as a key, the value "*" MUST be used as the single key field identifier. In reference array or structure elements, it is possible to construct keyFields that do not exist. keyField references SHOULD never reference optional structure components. For references to array elements, care must be taken to ensure that the necessary array elements exist when creating or modifying the overall array element. Failure to do so will result in FEs returning errors on the creation attempt.4.5.4. <struct> Element to Define Structures
A structure is composed of a collection of data components. Each data component has a data type (either an atomic type or an existing compound type) and is assigned a name unique within the scope of the compound data type being defined. These serve the same function as "struct" in C, etc. These components are defined using <component> elements. A <struct> element MAY contain an optional derivation indication, a <derivedFrom> element. The structure definition MUST contain a sequence of one or more <component> elements.
The actual type of the component can be defined by referring to an existing type (using the <typeRef> element), or can be a locally defined (unnamed) type created by any of the <atomic>, <array>, <struct>, or <union> elements. The <component> element MUST include a componentID attribute. This provides the numeric ID for this component, for use by the protocol. The <component> MUST contain a component name and a synopsis. It MAY contain a <description> element giving a textual description of the component. The definition MAY also include an <optional> element, which indicates that the component being defined is optional. The definition MUST contain elements to define the data type of the component, as described above. For a dataTypeDef of a struct, the structure definition MAY be inherited from, and augment, a previously defined structured type. This is indicated by including the optional derivedFrom attribute in the struct declaration before the definition of the augmenting or replacing components. Section 4.5.7 describes how this is done in more detail. The componentID attribute for different components in a structure (or in an LFB) MUST be distinct. They do not need to be in order, nor do they need to be sequential. For clarity of human readability, and ease of maintenance, it is usual to define at least sequential sets of values. But this is for human ease, not a model or protocol requirement. The result of this construct is always a compound type, even when the <struct> contains only one field.
An example is the following:
<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
Similar to the union declaration in C, this construct allows the
definition of overlay types. Its format is identical to the <struct>
element.
The result of this construct is always a compound type, even when the
union contains only one element.
4.5.6. <alias> Element
It is sometimes necessary to have a component in an LFB or structure
refer to information (a component) in other LFBs. This can, for
example, allow an ARP LFB to share the IP->MAC Address table with the
local transmission LFB, without duplicating information. Similarly,
it could allow a traffic measurement LFB to share information with a
traffic enforcement LFB. The <alias> declaration creates the
constructs for this. This construct tells the CE and FE that any
manipulation of the defined data is actually manipulation of data
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 is determined by the alias component properties, as described below), that component must be of the same type as that declared for the alias. Thus, when the CE or FE dereferences the alias component, the type of the information returned is known. The type can be a base type or a derived type. The actual value referenced by an alias is known as its target. When a GET or SET operation references the alias element, the value of the target is returned or replaced. Write access to an alias element is permitted 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 information in the component's properties. Like all components, the properties include the support / read / write permission for the alias. In addition, there are several fields (components) in the alias properties that define the target of the alias. These components are 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 of the alias property structure are described in Section 4.8 of this document, on properties. Note that the read / write property of the alias refers to the value. The CE can only determine if it can write the target selection properties of the alias by attempting such a write operation. (Property components do not themselves have properties.)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 MAY only be replaced with an augmentation derived from the current type of the existing component. An existing component cannot be deleted. If the existing compound type is an array, augmentation means augmentation of the array element type. Augmentation MUST NOT be applied to unions. One consequence of this is that augmentations are backward compatible with the compound type from which they are derived. As such, augmentations are useful in defining components for LFB subclasses with backward compatibility. In addition to 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 why augmentations cannot be applied to unions. For example, consider a simple base LFB class A that has only one component (comp1) of type X. One way to derive class A1 from A can be by simply adding a second component (of any type). Another way to derive a class A2 from A can be by replacing the original component (comp1) in A of type X with one of type Y, where Y is an augmentation of X. Both classes A1 and A2 are backward compatible with class A. The syntax for augmentations is to include a <derivedFrom> element in a structure definition, indicating what structure type is being augmented. Component names and component IDs for new components within the augmentation MUST NOT be the same as those in the structure type being augmented. For those components where the data type of an existing component is being replaced with a suitable augmenting data type, the existing component name and component ID MUST be used in the augmentation. Other than the constraint on existing elements, there is no requirement that the new component IDs be sequential with, greater than, or in any other specific relationship to the existing component IDs except different. It is expected that using values sequential within an augmentation, and distinct from the previously used values, will be a common method to enhance human readability.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 to be 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 information. Only atomic data types can be used as value types for metadata. The <metadataDef> element MAY contain a detailed description element. Two forms of type definitions are allowed. The first form uses the <typeRef> element to refer to an existing atomic data type defined in the <dataTypeDefs> element of the same library document or in one of the included library documents. The usage of the <typeRef> element is identical to how it is used in the <dataTypeDef> elements, except here it can only refer to atomic types. The latter restriction is not enforced by the XML schema.
The second form is an explicit type definition using the <atomic>
element. This element is used here in the same way as in the
<dataTypeDef> elements.
The following example shows 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:
o <name> provides the symbolic name of the LFB class. Example:
"ipv4lpm".
o <synopsis> provides a short synopsis of the LFB class. Example:
"IPv4 Longest Prefix Match Lookup LFB".
o <version> is the version indicator.
o <derivedFrom> is the inheritance indicator.
o <inputPorts> lists the input ports and their specifications.
o <outputPorts> lists the output ports and their specifications.
o <components> defines the operational components of the LFB.
o <capabilities> defines the capability components of the LFB.
o <description> contains the operational specification of the LFB.
o The LFBClassID attribute of the LFBClassDef element defines the ID
for this class. These must be globally unique.
o <events> defines the events that can be generated by instances of
this LFB.
LFB class names must be unique, in order to enable other documents to
reference the classes by name, and to enable human readers to
understand references to class names. While a complex naming
structure could be created, simplicity is preferred. As given in the
IANA Considerations section of this document, the 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. Note that in
order 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 will have componentIDs for
use by the ForCES protocol. These parallel the componentIDs used in
structs, and are 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; all other elements are optional in <LFBClassDef>. However,
when they are present, they must occur in the above order.
The componentID attribute for different items in an LFB class definition (or components in a struct) MUST be distinct. They do not need to be in order, nor do they need to be sequential. For clarity of human readability, and ease of maintenance, it is usual to define at least sequential sets of values. But this is for human ease, not a model or protocol requirement.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. In the absence of a <derivedFrom>, the class is conceptually derived from the common, empty, base class. It is assumed that a derived class is backward compatible with its base class. A derived class MAY add components to a parent class, but cannot delete components. This also applies to input and output ports, events, and capabilities.4.7.2. <inputPorts> Element to Define LFB Inputs
The optional <inputPorts> element is used to define 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. The <inputPorts> element can contain one or more <inputPort> elements, one for each port or port group. We assume that most LFBs will have exactly one input. Multiple inputs with the same input type are modeled as one input group. Input groups are defined the same way as input ports by the <inputPort> element, differentiated only by 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 will have no inputs at all. For example, a packet generator LFB does not need an input. Single input ports and input port groups are both defined by the <inputPort> element; they are differentiated only by an optional "group" attribute. The <inputPort> element MUST contain the following elements: o <name> provides the symbolic name of the input. Example: "in". Note that this symbolic name must be unique only within the scope of the LFB class.
o <synopsis> contains a brief description of the input. Example:
"Normal packet input".
o <expectation> lists all allowed frame formats. Example: {"ipv4"
and "ipv6"}. Note that 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
provide a list of required metadata. Example: {"classid",
"vpnid"}. This list should refer to names of metadata defined in
the <metadataDefs> element in the same library document or in any
included library documents. For each metadatum, it must be
specified whether the metadatum is required or optional. For each
optional metadatum, a default value must be specified, which is
used by the LFB if the metadatum is not provided with a packet.
In addition, the optional "group" attribute of the <inputPort>
element can specify if the port can behave as a port group, i.e., it
is allowed to be instantiated. This is indicated by a "true" value
(the default value is "false").
An example <inputPorts> element, defining two input ports, the second
one being an input port group is the following:
<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 example
above). When multiple frame types are listed, it means that "one of
these" frame types is expected. A packet of any other frame type is
regarded as incompatible with this input port of the LFB class. The
above example lists two frames as expected frame types: "ipv4" and
"ipv6".
Metadata expectations are specified by the <metadataExpected>
element. In its simplest form, this element can contain a list of
<ref> elements, each referring to a metadatum. When multiple
instances of metadata are listed by <ref> elements, it means that
"all of these" metadata must be received with each packet (except
metadata that are marked as "optional" by the "dependency" attribute
of the corresponding <ref> element). For a metadatum that is
specified "optional", a default value MUST be provided using the
"defaultValue" attribute. The above example lists three metadata as
expected metadata, two of which are mandatory ("classid" and
"vifid"), and one being optional ("vrfid").
The schema also allows for more complex definitions of metadata
expectations. For example, using the <one-of> element, a list of
metadata can be specified to express that at least one of the
specified metadata must be present with any packet. An example is
the following:
<metadataExpected>
<one-of>
<ref>prefixmask</ref>
<ref>prefixlen</ref>
</one-of>
</metadataExpected>
The above example specifies that either the "prefixmask" or the
"prefixlen" metadata must be provided with any packet.
The two forms can also be combined, as shown in the following
example:
<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>
Although the schema is constructed to allow even more complex
definitions of metadata expectations, we do not discuss 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. 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 (e.g., Dropper). Single output ports and output port groups are both defined by the <outputPort> element; they are differentiated only by an optional "group" attribute. The <outputPort> element MUST contain the following elements: o <name> provides the symbolic name of the output. Example: "out". Note that the symbolic name must be unique only within the scope of the LFB class. o <synopsis> contains a brief description of the output port. Example: "Normal packet output". o <product> lists the allowed frame formats. Example: {"ipv4", "ipv6"}. Note that this list should refer to symbols specified in the <frameDefs> element in 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 in the same library document or in any included library documents. For each generated metadatum, it should be specified whether the metadatum is always generated or generated only in certain conditions. This information is important when assessing compatibility between LFBs. In addition, the optional "group" attribute of the <outputPort> element can specify if the port can behave as a port group, i.e., it is allowed to be instantiated. This is indicated by a "true" value (the default value is "false"). The following example specifies two output ports, the second being 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 types of frames and metadata the port produces are defined inside
the <product> element in each <outputPort>. Within the <product>
element, the list of frame types the port produces is listed in the
<frameProduced> element. When more than one frame is listed, it
means that "one of" these frames will be produced.
The list of metadata that is produced with each packet is listed in
the optional <metadataProduced> element of the <product>. In its
simplest form, this element can contain a list of <ref> elements,
each referring to a metadatum type. The meaning of such a list is
that "all of" these metadata are provided with each packet, except
those that are listed with the optional "availability" attribute set
to "conditional". Similar to the <metadataExpected> element of the
<inputPort>, the <metadataProduced> element supports more complex
forms, which we do not discuss here further.
4.7.4. <components> Element to Define LFB Operational Components
Operational parameters of the LFBs that must be visible to the CEs are conceptualized in the model as the LFB components. These include, for example, flags, single parameter arguments, complex arguments, and tables. Note that the components here refer to only those operational parameters of the LFBs that must be visible to the CEs. Other variables that are internal to LFB implementation are not regarded as LFB components and hence are not covered. Some examples for LFB components are: o Configurable flags and switches selecting between operational modes of the LFB o Number of inputs or outputs in a port group o Various configurable lookup tables, including interface tables, prefix tables, classification tables, DSCP mapping tables, MAC address tables, etc. o Packet and byte counters o Various event counters o Number of current inputs or outputs for each input or output group The ForCES model supports the definition of access permission restrictions on what the CE can do with an LFB component. The following categories are supported by the model: o No-access components. This is useful for completeness, and to allow for defining objects that are used by other things, but not directly referencable by the CE. It is also useful for an FE that is reporting that certain defined, and typically accessible, components are not supported for CE access by a reporting FE. o Read-only components. o Read-write components. o Write-only components. This could be any configurable data for which read capability is not provided to the CEs (e.g., the security key information). o Read-reset components. The CE can read and reset this resource, but cannot set it to an arbitrary value. Example: Counters.
o Firing-only components. A write attempt to this resource will
trigger some specific actions in the LFB, but the actual value
written is ignored.
The LFB class MUST define only one possible access mode for a given
component.
The components of the LFB class are listed in the <components>
element. Each component is defined by an <component> element. A
<component> element contains some or all of the following elements,
some of which are mandatory:
o <name> MUST occur, and defines the name of the component. This
name must be unique among the components of the LFB class.
Example: "version".
o <synopsis> is also mandatory, and provides a brief description of
the purpose of the component.
o <optional/> is an optional element, and if present indicates that
this component is optional.
o The data type of the component can be defined either via a
reference to a predefined data type or by providing a local
definition of the type. The former is provided by using the
<typeRef> element, which 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 (unnamed type), one of the
following elements can be used: <atomic>, <array>, <struct>, or
<union>. Their usage is identical to how they are used inside
<dataTypeDef> elements (see Section 4.5). Some form of data type
definition MUST be included in the component definition.
o The <defaultValue> element is optional, and if present is used to
specify a default value for a component. If a default value is
specified, the FE must ensure that the component has that value
when the LFB is initialized or reset. If a default value is not
specified for a component, the CE MUST make no assumptions as to
what the value of the component will be upon initialization. The
CE must either read the value or set the value, if it needs to
know what it is.
o The <description> element MAY also appear. If included, it
provides 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.
In addition to the above elements, the <component> element includes
an optional "access" attribute, which can take any of the following
values: "read-only", "read-write", "write-only", "read-reset", and
"trigger-only". The default access mode is "read-write".
Whether optional components are supported, and whether components
defined as read-write can actually be written, can be determined for
a given LFB instance by the CE by reading the property information of
that component. An access control setting of "trigger-only" means
that this component is included only 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>
The first component ("foo") is a read-only 32-bit unsigned integer,
defined by referring to the built-in "uint32" atomic type. The
second component ("bar") is also an integer, but uses the <atomic>
element to provide additional range restrictions. This component has
access mode of read-write allowing it to be both read and written. A
default value of 10 is provided for bar. Although the access for bar
is read-write, some implementations MAY offer only more restrictive
access, and this would be reported in the component properties.
Note that not all components are likely to exist at all times in a particular implementation. While the capabilities will frequently indicate this non-existence, CEs may attempt to reference non- existent or non-permitted components anyway. The ForCES protocol mechanisms should include appropriate error indicators for this case. The mechanism defined above for non-supported components can also apply to attempts 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 specification provides some flexibility for the FE implementation regarding how the LFB class is implemented. For example, the instance may have some limitations that are not inherent from the class definition, but rather the result of some implementation limitations. Some of these limitations are captured by the property information of the LFB components. The model allows for the notion of additional capability information. Such capability-related information is expressed by the capability components of the LFB class. The capability components are always read-only attributes, and they are listed in a separate <capabilities> element in the <LFBClassDef>. The <capabilities> element contains one or more <capability> elements, each defining one capability component. The format of the <capability> element is almost the same as the <component> element. It differs in two aspects: it lacks the access mode attribute (because it is always read-only), and it lacks the <defaultValue> element (because default value is not applicable to read-only attributes). Some examples of capability components follow: o The version of the LFB class with which this LFB instance complies o Supported optional features of the LFB class o Maximum number of configurable outputs for an output group o Metadata pass-through limitations of the LFB o 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 contains the information about the occurrences
for which instances of this LFB class can generate notifications to
the CE. High-level view on the declaration and operation of LFB
events is described in Section 3.2.5.
The <events> element contains 0 or more <event> elements, each of
which declares a single event. The <event> element has an eventID
attribute giving the unique (per LFB class) ID of the event. The
element will include:
o <eventTarget> element indicating which LFB field (component) is
tested to generate the event.
o <condition> element indicating what condition on the field will
generate the event from a list of defined conditions.
o <eventReports> element indicating what values are to be reported
in the notification of the event.
The example below demonstrates the different constructs.
The <events> element has a baseID attribute value, which is normally
<events baseID="number">. The value of 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 contains information identifying a field in
the LFB that is to be monitored for events.
The <eventTarget> element contains one or more <eventField>s each of
which MAY be followed by one or more <eventSubscript> elements. Each
of these two elements represents the textual equivalent 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.
This is the case illustrated in the event named Foochanged.
<eventField> is also used to address complex components such as
arrays or structures.
The first defined event, Foochanged, demonstrates how a scalar LFB
component, foo, could be monitored to trigger an event.
The second event, Goof1changed, demonstrates how a member of the
complex structure goo could 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.
Defined event Goof1changed demonstrates how a second <eventField> is
used to point to member f1 of the structure goo.
If an <eventField> identifies an array, then the following rules
apply:
o <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.
o 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, event
Gah11changed shows how table gah's index 11 is being targeted
for monitoring.
Or
* It is expected that the more common usage is to have the event
being defined across all elements of the array (i.e., a
wildcard for all indices). 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 wild card table index is shown in event
NewBarentry where the <eventSubscript> value is named
_barIndex_
o An <eventField> MAY follow an <eventSubscript> to further refine
the path to the target element. (Note: this is in the same spirit
as the case where <eventField> is used to further refine
<eventField> in the earlier example of a complex structure example
of Goof1changed.) The example event Gah10field1 illustrates how
the column field1 of table gah is monitored for changes.
It should be emphasized that the name in an <eventSubscript> element
in defined event NewbarEntry is not a component name. It is 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.
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. 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
The <eventReports> element of an <event> declares the information to be delivered by the FE along with the notification of the occurrence of the event. The <eventReports> element contains one or more <eventReport> elements. Each <eventReport> element identifies a piece of data from the LFB class to be reported. The notification carries that data as if the collection of <eventReport> elements had been defined in a structure. The syntax is exactly the same as used in the <eventTarget> element, using <eventField> and <eventSubscript> elements, and so the same rules apply. 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 will use the value for the subscript that
identifies that specific element triggering the event. This can be
used to reference the component causing the event, or to reference
related information in parallel tables.
In the example shown, in the case of the event Foochanged, the report
will carry the value of foo. In the case of the defined event
NewbarEntry acting on LFB component bar, which is an array, there are
two items that are reported as indicated by the two <eventReport>
declarations:
o The first <eventReport> details what new entry was added in the
table bar. Recall that _barIndex_ is declared as the event's
<eventTarget> <eventSubcript> and that by virtue of using a name
instead of a numeric value, the <eventSubcript> is implied to be a
wildcard and will carry whatever index of the new entry.
o The second <eventReport> includes the value of LFB component foo
at the time the new entry was created in bar. Reporting foo in
this case is provided to demonstrate the flexibility of event
reporting.
This event reporting structure is designed to allow the LFB designer
to specify information that is likely not known a priori by the CE
and is likely needed by the CE to process the event. While the
structure allows for pointing at large blocks of information (full
arrays or complex structures), this is not recommended. Also, the
variable reference/subscripting in reporting only captures a small
portion of the kinds of related information. Chaining through index
fields stored in a table, for example, is not supported. In general,
the <eventReports> mechanism is an optimization for cases that have
been found to be common, saving the CE from having to query for
information it needs to understand the event. It does not represent
all possible information needs.
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
The high-level view of the declaration and operation of LFB events is
described in Section 3.2.5.
The <eventTarget> provides additional components used in the path to reference the event. The path constitutes the baseID for events, followed by the ID for the specific event, followed by a value for each <eventSubscript> element if it exists in the <eventTarget>. The event path will uniquely identify a specific occurrence of the event in the event notification to the CE. In the example provided above, at the end of Section 4.7.6, a notification with path of 7.7 uniquely identifies the event to be that caused by the change of foo; an event with path 7.9.100 uniquely identifies the event to be that caused by a creation of table bar entry with index/subscript 100. As described in Section 4.8.5, event elements have properties associated with them. These properties include the subscription information indicating whether the CE wishes 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 generated by the FE. Details of the filtering conditions that can be applied are given in that section. The filtering conditions allow the FE to suppress floods of events that could result from oscillation around a condition value. For FEs that do not wish to support filtering, the filter properties can be either read-only or not supported. In addition to identifying the event sources, the CE also uses the event path to activate runtime control of the event via the event properties (defined in Section 4.8.5) utilizing SET-PROP as defined in the ForCES protocol [RFC5810] operation. To activate event generation on the FE, a SET-PROP message referencing the event and registration property of the event is issued to the FE by the CE with any prefix of the path of the event. So, for an event defined on the example table bar, a SET-PROP with a path of 7.9 will subscribe the CE to all occurrences of that event on any entry of the table. This is particularly useful for the <eventCreated/> and <eventDestroyed/> conditions on tables. Events using those conditions will generally be defined with a field/ subscript sequence that identifies an array and ends with an <eventSubscript> element. Thus, the event notification will indicate which array entry has been created or destroyed. A typical subscriber will subscribe for the array, as opposed to a specific entry in an array, so it will use a shorter path. In the example provided, subscribing to 7.8 implies receiving all declared events from table bar. Subscribing to 7.8.100 implies receiving an event when subscript/index 100 table entry 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 for defining a threshold or filtering condition on an event for all elements of an array.4.7.7. <description> Element for LFB Operational Specification
The <description> element of the <LFBClass> provides unstructured text (in XML sense) to explain what the LFB does to a human user.
(page 79 continued on part 4)
