Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 5812

Forwarding and Control Element Separation (ForCES) Forwarding Element Model

Pages: 134
Proposed Standard
Errata
Updated by:  7408
Part 3 of 5 – Pages 41 to 79
First   Prev   Next

Top   ToC   RFC5812 - Page 41   prevText

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
Top   ToC   RFC5812 - Page 42
   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,
Top   ToC   RFC5812 - Page 43
   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:
Top   ToC   RFC5812 - Page 44
       <?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:
Top   ToC   RFC5812 - Page 45
   <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:
Top   ToC   RFC5812 - Page 46
   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:
Top   ToC   RFC5812 - Page 47
          <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.
Top   ToC   RFC5812 - Page 48
   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.
Top   ToC   RFC5812 - Page 49

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>
Top   ToC   RFC5812 - Page 50

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
Top   ToC   RFC5812 - Page 51
   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>
Top   ToC   RFC5812 - Page 52
   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.
Top   ToC   RFC5812 - Page 53
      <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.
Top   ToC   RFC5812 - Page 54
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.
Top   ToC   RFC5812 - Page 55
   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.
Top   ToC   RFC5812 - Page 56
   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
Top   ToC   RFC5812 - Page 57
   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
Top   ToC   RFC5812 - Page 58
   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.
Top   ToC   RFC5812 - Page 59
   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.
Top   ToC   RFC5812 - Page 60
   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.
Top   ToC   RFC5812 - Page 61
   <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.
Top   ToC   RFC5812 - Page 62
   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.
Top   ToC   RFC5812 - Page 63
   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
Top   ToC   RFC5812 - Page 64
   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.
Top   ToC   RFC5812 - Page 65

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:
Top   ToC   RFC5812 - Page 66
   <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.
Top   ToC   RFC5812 - Page 67

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.
Top   ToC   RFC5812 - Page 68
   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.
Top   ToC   RFC5812 - Page 69
   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.
Top   ToC   RFC5812 - Page 70
   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
Top   ToC   RFC5812 - Page 71
   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
Top   ToC   RFC5812 - Page 72
   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>
Top   ToC   RFC5812 - Page 73
    <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>
Top   ToC   RFC5812 - Page 74
    <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.
Top   ToC   RFC5812 - Page 75
      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.
Top   ToC   RFC5812 - Page 76
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
Top   ToC   RFC5812 - Page 77
   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.
Top   ToC   RFC5812 - Page 78
   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.
Top   ToC   RFC5812 - Page 79
   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)

Next Section