== BGP Developer Guide
=== Overview
-Provide an overview of the feature, what it logical functionality it
-provides and why you might use it as a developer. To be clear the target
-audience for this guide is a developer who will be _using_ the feature
-to build something separate, but _not_ somebody who will be developing
-code for this feature itself.
-
-NOTE: More so than with user guides, the guide may cover more than one
-feature. If that is the case, be sure to list all of the features this
-covers.
+This section provides an overview of *feature odl-bgpcep-bgp-all* . This
+feature will install everything needed for BGP (Border Gateway Protocol)
+from establishing the connection, storing the data in RIBs (Route Information
+Base) and displaying data in network-topology overview.
=== BGP Architecture
-Provide information about feature components and how they work together.
-Also include information about how the feature integrates with
-OpenDaylight. An architecture diagram could help. This may be the same
-as the diagram used in the user guide, but it should likely be less
-abstract and provide more information that would be applicable to a
-developer.
+
+Each feature represents a module in the BGPCEP codebase. The following diagram
+illustrates how the features are related.
+
+image::bgpcep/bgp-dependency-tree.png[height="450px", width="550px",title="BGP Dependency Tree"]
=== Key APIs and Interfaces
-Document the key things a user would want to use. For some features,
-there will only be one logical grouping of APIs. For others there may be
-more than one grouping.
-Assuming the API is MD-SAL- and YANG-based, the APIs will be available
-both via RESTCONF and via Java APIs. Giving a few examples using each is
-likely a good idea.
+==== BGP concepts
+
+This module contains the base BGP concepts contained in
+http://tools.ietf.org/html/rfc4271[RFC4271],
+http://tools.ietf.org/html/rfc4760[RFC4760],
+http://tools.ietf.org/html/rfc4456[RFC4456],
+http://tools.ietf.org/html/rfc1997[RFC1997] and
+http://tools.ietf.org/html/rfc4360[RFC4360].
+
+All the concepts are described in one yang model :
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/concepts/src/main/yang/bgp-types.yang;hb=refs/heads/stable/lithium[bgp-types.yang]
+.
+
+Outside generated classes, there is just one class
+_https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/concepts/src/main/java/org/opendaylight/bgp/concepts/NextHopUtil.java;hb=refs/heads/stable/lithium[NextHopUtil]_
+that contains methods for serializing and parsing NextHop.
+
+==== BGP parser
+
+Base BGP parser includes messages and attributes from
+http://tools.ietf.org/html/rfc4271[RFC4271],
+http://tools.ietf.org/html/rfc4760[RFC4760],
+http://tools.ietf.org/html/rfc1997[RFC1997] and
+http://tools.ietf.org/html/rfc4360[RFC4360].
+
+_API_ module defines BGP messages in YANG.
+
+_IMPL_ module contains actual parsers and serializers for BGP messages
+and
+_https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/parser-impl/src/main/java/org/opendaylight/protocol/bgp/parser/impl/BGPActivator.java;hb=refs/heads/stable/lithium[Activator]_
+class
+
+_SPI_ module contains helper classes needed for registering parsers into
+activators
+
+===== Registration
+
+As mentioned before, all parsers and serializers need to be registered
+into the _Extension provider_. This _Extension provider_ is configured in
+initial configuration of the parser-spi module (_31-bgp.xml_).
+
+[source,xml]
+----
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">prefix:bgp-extensions-impl</type>
+ <name>global-bgp-extensions</name>
+ <extension>
+ <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
+ <name>base-bgp-parser</name>
+ </extension>
+ <extension>
+ <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">bgpspi:extension</type>
+ <name>bgp-linkstate</name>
+ </extension>
+ </module>
+----
+
+* _base-bgp-parser_ - will register parsers and serializers
+implemented in the bgp-parser-impl module
+
+* _bgp-linkstate_ - will register parsers and serializers
+implemented in the bgp-linkstate module
+
+The bgp-linkstate module is a good example of a BGP parser extension.
+
+The configuration of bgp-parser-spi specifies one implementation of
+_Extension provider_ that will take care of registering mentioned parser
+extensions:
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/parser-spi/src/main/java/org/opendaylight/protocol/bgp/parser/spi/pojo/SimpleBGPExtensionProviderContext.java;hb=refs/heads/stable/lithium[SimpleBGPExtensionProviderContext].
+All registries are implemented in package
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=tree;f=bgp/parser-spi/src/main/java/org/opendaylight/protocol/bgp/parser/spi;hb=refs/heads/stable/lithium[bgp-parser-spi].
+
+===== Serializing
+
+The serializing of BGP elements is mostly done in the same way as in PCEP, the only
+exception is the serialization of path attributes, that is described
+here. Path attributes are different from any other BGP element, as
+path attributes don't implement one common interface, but this
+interface contains getters for individual path attributes (this
+structure is because update message can contain exactly one instance of
+each path attribute). This means, that a given _PathAttributes_ object,
+you can only get to the specific type of the path attribute through
+checking its presence. Therefore method _serialize()_ in
+_AttributeRegistry_, won't look up the registered class, instead it will
+go through the registrations and offer this object to the each
+registered parser. This way the object will be passed also to
+serializers unknown to module bgp-parser, for example to
+LinkstateAttributeParser. RFC4271 recommends ordering path attributes,
+hence the serializers are ordered in a list as they are registered in
+the _Activator_. In other words, this is the only case, where
+registration ordering matters.
+
+image::bgpcep/PathAttributesSerialization.png[height="450px", width="550px",title="PathAttributesSerialization"]
+
+_serialize()_ method in each Path Attribute parser contains check for
+presence of its attribute in the PathAttributes object, which simply
+returns, if the attribute is not there:
+
+[source,java]
+----
+ if (pathAttributes.getAtomicAggregate() == null) {
+ return;
+ }
+ //continue with serialization of Atomic Aggregate
+----
+
+=== BGP RIB
+
+The BGP RIB module can be divided into two semantic parts:
+* BGP listener and speaker session handling
+* RIB handling.
+
+==== Session handling
+
+_31-bgp.xml_ defines only bgp-dispatcher and the parser it should be
+using (global-bgp-extensions).
+
+[source,xml]
+----
+ <module>
+ <type>prefix:bgp-dispatcher-impl</type>
+ <name>global-bgp-dispatcher</name>
+ <bgp-extensions>
+ <type>bgpspi:extensions</type>
+ <name>global-bgp-extensions</name>
+ </bgp-extensions>
+ <boss-group>
+ <type>netty:netty-threadgroup</type>
+ <name>global-boss-group</name>
+ </boss-group>
+ <worker-group>
+ <type>netty:netty-threadgroup</type>
+ <name>global-worker-group</name>
+ </worker-group>
+ </module>
+----
+
+For user configuration of BGP, check User Guide.
+
+==== Synchronization
+
+Synchronization is a phase, where upon connection, a BGP speaker sends all
+available data about topology to its new client. After the whole
+topology has been advertized, the synchronization is over. For the
+listener, the synchronization is over when the RIB receives End-of-RIB
+(EOR) messages. There is a special EOR message for each AFI (Address Family
+Identifier).
+
+* IPv4 EOR is an empty Update message
+* Ipv6 EOR is an Update message with empty MP_UNREACH attribute where
+AFI and SAFI (Subsequent Address Family Identifier) are set to Ipv6.
+OpenDaylight also supports EOR for IPv4 in this format
+* Linkstate EOR is an Update message with empty MP_UNREACH attribute
+where AFI and SAFI are set to Linkstate
+
+For BGP connections, where both peers support graceful restart, the EORs
+are sent by the BGP speaker and are redirected to RIB, where the specific
+AFI/SAFI table is set to _true_. Without graceful restart, the
+messages are generated by OpenDaylight itself and sent after second keepalive for
+each AFI/SAFI. This is done in
+_https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/BGPSynchronization.java;hb=refs/heads/stable/lithium[BGPSynchronization]_
+
+*Peers*
+
+_https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/BGPPeer.java;hb=refs/heads/stable/lithium[BGPPeer]_
+has various meanings. If you configure BGP listener, _BGPPeer_
+represents the BGP listener itself. If you are configuring BGP speaker,
+you need to provide a list of peers, that are allowed to connect to this
+speaker. Unknown peer represents, in this case, a peer that is allowed
+to be refused. _BGPPeer_ represents in this case peer, that is supposed
+to connect to your speaker. _BGPPeer_ is stored in _https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/StrictBGPPeerRegistry.java;hb=refs/heads/stable/lithium[BGPPeerRegistry]_.
+This registry controls the number of sessions. Our strict implementation
+limits sessions to one per peer.
+
+_https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/ApplicationPeer.java;hb=refs/heads/stable/lithium[ApplicationPeer]_
+is a special case of peer, that has it's own RIB. This RIB is populated
+from RESTCONF. The RIB is synchronized with default BGP RIB. Incoming
+routes to the default RIB are treated in the same way as they were from a
+BGP peer (speaker or listener) in the network.
+
+==== RIB handling
+
+RIB (Route Information Base) is defined as a concept in
+http://tools.ietf.org/html/rfc4271#section-3.2[RFC4271]. RFC does not
+define how it should be implemented. In our implementation,
+the routes are stored in MD-SALs data-store. There are four supported
+routes - _Ipv4Routes_, _Ipv6Routes_, _LinkstateRoutes_ and
+_FlowspecRoutes_.
+
+Each route type needs to provide a
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-spi/src/main/java/org/opendaylight/protocol/bgp/rib/spi/RIBSupport.java;hb=refs/heads/stable/lithium[RIBSupport.java]
+implementation. _RIBSupport_ tells RIB how to parse binding-aware data
+(BGP Update message) to binding-independent (datastore format).
+
+Following picture describes the data flow from BGP message that is sent
+to _BGPPeer_ to datastore and various types of RIB.
+
+image::bgpcep/RIB.png[height="450px", width="550px",title="RIB"]
+
+*https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/AdjRibInWriter.java;hb=refs/heads/stable/lithium[AdjRibInWriter]*
+- represents the first step in putting data to datastore. This writer is
+notified whenever a peer receives an Update message. The message is
+transformed into binding-independent format and pushed into datastore to
+_adj-rib-in_. This RIB is associated with a peer.
+
+*https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/EffectiveRibInWriter.java;hb=refs/heads/stable/lithium[EffectiveRibInWriter]*
+- this writer is notified whenever _adj-rib-in_ is updated. It applies
+all configured import policies to the routes and stores them in
+_effective-rib-in_. This RIB is also associated with a peer.
+
+*https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/LocRibWriter.java;hb=refs/heads/stable/lithium[LocRibWriter]*
+- this writer is notified whenever *any* _effective-rib-in_ is updated
+(in any peer). Performs best path selection filtering and stores the
+routes in _loc-rib_. It also determines which routes need to be
+advertised and fills in _adj-rib-out_ that is per peer as well.
+
+*https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/rib-impl/src/main/java/org/opendaylight/protocol/bgp/rib/impl/AdjRibOutListener.java;h=a14fd54a29ea613b381a36248f67491d968963b8;hb=refs/heads/stable/lithium[AdjRibOutListener]*
+- listens for changes in _adj-rib-out_, transforms the routes into
+BGPUpdate messages and sends them to its associated peer.
+
+=== BGP inet
+
+This module contains only one YANG model
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/inet/src/main/yang/bgp-inet.yang;hb=refs/heads/stable/lithium[bgp-inet.yang]
+that summarizes the ipv4 and ipv6 extensions to RIB routes and BGP
+messages.
+
+=== BGP flowspec
+
+BGP flowspec is a module that implements
+http://tools.ietf.org/html/rfc5575[RFC5575]. The RFC defines an
+extension to BGP in form of a new subsequent address family, NLRI and
+extended communities. All of those are defined in the
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/flowspec/src/main/yang/bgp-flowspec.yang;hb=refs/heads/stable/lithium[bgp-flowspec.yang]
+model. In addition to generated sources, the module contains parsers for
+newly defined elements and RIBSupport for flowspec-routes. The route key of
+flowspec routes is a string representing human-readable flowspec
+request.
+
+=== BGP linkstate
+
+BGP linkstate is a module that implements
+http://tools.ietf.org/html/draft-ietf-idr-ls-distribution-04[draft-ietf-idr-ls-distribution]
+version 04. The draft defines an extension to BGP in form of a new
+address family, subsequent address family, NLRI and path attribute. All
+of those are defined in the
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/linkstate/src/main/yang/bgp-linkstate.yang;hb=refs/heads/stable/lithium[bgp-linkstate.yang]
+model. In addition to generated sources, the module contains
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/linkstate/src/main/java/org/opendaylight/protocol/bgp/linkstate/attribute/LinkstateAttributeParser.java;hb=refs/heads/stable/lithium[LinkstateAttributeParser],
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=bgp/linkstate/src/main/java/org/opendaylight/protocol/bgp/linkstate/nlri/LinkstateNlriParser.java;hb=refs/heads/stable/lithium[LinkstateNlriParser],
+activators for both, parser and RIB, and RIBSupport handler for
+linkstate address family. As each route needs a key, in case of
+linkstate, the route key is defined as a binary string, containing all
+the nlri serialized to byte format.
-==== API Group 1
-Provide a description of what the API does and some examples of how to
-use it.
+=== BGP topology provider
-==== API Group 2
-Provide a description of what the API does and some examples of how to
-use it.
+BGP data besides RIB, is stored in network-topology view. The
+format of how the data is displayed there conforms to
+https://tools.ietf.org/html/draft-clemm-netmod-yang-network-topo-01[draft-clemm-netmod-yang-network-topo].
=== API Reference Documentation
-Provide links to JavaDoc, REST API documentation, etc.
+Javadocs are generated while creating mvn:site
+and they are located in target/ directory in each module.
== PCEP Developer Guide
=== Overview
-Provide an overview of the feature, what it logical functionality it
-provides and why you might use it as a developer. To be clear the target
-audience for this guide is a developer who will be _using_ the feature
-to build something separate, but _not_ somebody who will be developing
-code for this feature itself.
-
-NOTE: More so than with user guides, the guide may cover more than one
-feature. If that is the case, be sure to list all of the features this
-covers.
+This section provides an overview of *feature odl-bgpcep-pcep-all* . This
+feature will install everything needed for PCEP (Path Computation Element
+Protocol) including establishing the connection, storing information about LSPs
+(Label Switched Paths) and displaying data in network-topology overview.
=== PCEP Architecture
-Provide information about feature components and how they work together.
-Also include information about how the feature integrates with
-OpenDaylight. An architecture diagram could help. This may be the same
-as the diagram used in the user guide, but it should likely be less
-abstract and provide more information that would be applicable to a
-developer.
+Each feature represents a module in the BGPCEP codebase. The following diagram
+illustrates how the features are related.
+
+image::bgpcep/pcep-dependency-tree.png[height="450px",width="550px",title="PCEP Dependency Tree"]
=== Key APIs and Interfaces
-Document the key things a user would want to use. For some features,
-there will only be one logical grouping of APIs. For others there may be
-more than one grouping.
-Assuming the API is MD-SAL- and YANG-based, the APIs will be available
-both via RESTCONF and via Java APIs. Giving a few examples using each is
-likely a good idea.
+==== PCEP
+
+===== Session handling
+
+_32-pcep.xml_ defines only pcep-dispatcher the parser should be
+using (global-pcep-extensions), factory for creating session proposals
+(you can create different proposals for different PCCs (Path Computation Clients)).
+
+[source,xml]
+----
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">prefix:pcep-dispatcher-impl</type>
+ <name>global-pcep-dispatcher</name>
+ <pcep-extensions>
+ <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extensions</type>
+ <name>global-pcep-extensions</name>
+ </pcep-extensions>
+ <pcep-session-proposal-factory>
+ <type xmlns:pcep="urn:opendaylight:params:xml:ns:yang:controller:pcep">pcep:pcep-session-proposal-factory</type>
+ <name>stateful07-proposal</name>
+ </pcep-session-proposal-factory>
+ <boss-group>
+ <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
+ <name>global-boss-group</name>
+ </boss-group>
+ <worker-group>
+ <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
+ <name>global-worker-group</name>
+ </worker-group>
+ </module>
+----
+
+For user configuration of PCEP, check User Guide.
+
+===== Parser
+
+The base PCEP parser includes messages and attributes from
+http://tools.ietf.org/html/rfc5441[RFC5441],
+http://tools.ietf.org/html/rfc5541[RFC5541],
+http://tools.ietf.org/html/rfc5455[RFC5455],
+http://tools.ietf.org/html/rfc5557[RFC5557] and
+http://tools.ietf.org/html/rfc5521[RFC5521].
+
+===== Registration
+
+All parsers and serializers need to be registered
+into _Extension provider_. This _Extension provider_ is configured in
+initial configuration of the parser-spi module (_32-pcep.xml_).
+
+[source,xml]
+----
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">prefix:pcep-extensions-impl</type>
+ <name>global-pcep-extensions</name>
+ <extension>
+ <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extension</type>
+ <name>pcep-parser-base</name>
+ </extension>
+ <extension>
+ <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extension</type>
+ <name>pcep-parser-ietf-stateful07</name>
+ </extension>
+ <extension>
+ <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">pcepspi:extension</type>
+ <name>pcep-parser-ietf-initiated00</name>
+ </extension>
+ </module>
+----
+
+* _pcep-parser-base_ - will register parsers and serializers
+implemented in pcep-impl module
+
+* _pcep-parser-ietf-stateful07_ - will register parsers and
+serializers implemented in stateful07 module
+
+Stateful07 module is a good example of a PCEP parser extension.
+
+Configuration of PCEP parsers specifies one implementation of _Extension
+provider_ that will take care of registering mentioned parser
+extensions:
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/spi/src/main/java/org/opendaylight/protocol/pcep/spi/pojo/SimplePCEPExtensionProviderContext.java;hb=refs/for/stable/lithium[SimplePCEPExtensionProviderContext].
+All registries are implemented in package
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=tree;f=pcep/spi/src/main/java/org/opendaylight/protocol/pcep/spi/pojo;hb=refs/for/stable/lithium[pcep-spi].
+
+===== Parsing
+
+Parsing of PCEP elements is mostly done equally to BGP,
+the only exception is message parsing, that is described here.
+
+In BGP messages, parsing of first-level elements (path-attributes)
+can be validated in a simple way, as the attributes should be ordered
+chronologically. PCEP, on the other hand, has a strict object order
+policy, that is described in RBNF (Routing Backus-Naur Form) in each RFC.
+Therefore the algorithm for parsing here is to parse all objects in order
+as they appear in the message. The result of parsing is a list of _PCEPObjects_,
+that is put through validation. _validate()_ methods are present in each
+message parser. Depending on the complexity of the message, it can
+contain either a simple condition (checking the presence of a mandatory
+object) or a full state machine.
+
+In addition to that, PCEP requires sending error message for each
+documented parsing error. This is handled by creating an empty list of
+messages _errors_ which is then passed as argument throughout whole
+parsing process. If some parser encounters _PCEPDocumentedException_,
+it has the duty to create appropriate PCEP error message and add it to
+this list. In the end, when the parsing is finished, this list is
+examined and all messages are sent to peer.
+
+Better understanding provides this sequence diagram:
+
+image::bgpcep/pcep-parsing.png[height="450px",width="550px",title="Parsing"]
+
+==== PCEP IETF stateful
+
+This section summarizes module pcep-ietf-stateful07. The term
+_stateful_ refers to
+http://tools.ietf.org/html/draft-ietf-pce-stateful-pce[draft-ietf-pce-stateful-pce]
+and
+http://tools.ietf.org/html/draft-ietf-pce-pce-initiated-lsp[draft-ietf-pce-pce-initiated-lsp]
+in versions draft-ietf-pce-stateful-pce-07 with draft-ietf-pce-pce-initiated-lsp-00.
+
+We will upgrade our implementation, when the stateful draft gets
+promoted to RFC.
+
+The stateful module is implemented as extensions to pcep-base-parser.
+The stateful draft declared new elements as well as additional fields or
+TLVs (type,length,value) to known objects. All new elements are defined in yang models, that
+contain augmentations to elements defined in
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/api/src/main/yang/pcep-types.yang;hb=refs/for/stable/lithium[pcep-types.yang].
+In the case of extending known elements, the _Parser_ class merely extends
+the base class and overrides necessary methods as shown in following
+diagram:
+
+image::bgpcep/validation.png[height="450px",width="550px",title="Extending existing parsers"]
+
+All parsers (including those for newly defined PCEP elements) have to be
+registered via the _Activator_ class. This class is present in both modules.
+
+In addition to parsers, the stateful module also introduces additional session
+proposal. This proposal includes new fields defined in stateful drafts
+for Open object.
+
+==== PCEP segment routing (SR)
+
+PCEP Segment Routing is an extension of base PCEP and
+pcep-ietf-stateful-07 extension. The pcep-segment-routing module
+implements
+http://tools.ietf.org/html/draft-ietf-pce-segment-routing-01[draft-ietf-pce-segment-routing-01].
+
+The extension brings new SR-ERO (Explicit Route Object) and SR-RRO (Reported Route Object)
+subobject composed of SID (Segment Identifier) and/or NAI (Node or Adjacency Identifier).
+The segment Routing path is carried in the ERO and RRO object, as a list of
+SR-ERO/SR-RRO subobjects in an order specified by the user. The draft defines new TLV -
+SR-PCE-CAPABILITY TLV, carried in PCEP Open object, used to negotiate Segment
+Routing ability.
+
+The yang models of subobject, SR-PCE-CAPABILITY TLV and appropriate
+augmentations are defined in
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/segment-routing/src/main/yang/odl-pcep-segment-routing.yang;hb=refs/for/stable/lithium[odl-pcep-segment-routing.yang]. +
+The pcep-segment-routing module includes parsers/serializers for new
+subobject
+(https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/segment-routing/src/main/java/org/opendaylight/protocol/pcep/segment/routing/SrEroSubobjectParser.java;hb=refs/for/stable/lithium[SrEroSubobjectParser])
+and TLV
+(https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/segment-routing/src/main/java/org/opendaylight/protocol/pcep/segment/routing/SrPceCapabilityTlvParser.java;hb=refs/for/stable/lithium[SrPceCapabilityTlvParser]).
+
+The pcep-segment-routing module implements
+http://tools.ietf.org/html/draft-ietf-pce-lsp-setup-type-01[draft-ietf-pce-lsp-setup-type-01],
+too. The draft defines new TLV - Path Setup Type TLV, which value
+indicate path setup signaling technique. The TLV may be included in
+RP(Request Parameters)/SRP(Stateful PCE Request Parameters) object.
+For the default RSVP-TE (Resource Reservation Protocol), the TLV is omitted.
+For Segment Routing, PST = 1 is defined.
+
+The Path Setup Type TLV is modeled with yang in module
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/api/src/main/yang/pcep-types.yang;hb=refs/for/stable/lithium[pcep-types.yang].
+A parser/serializer is implemented in
+https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;a=blob;f=pcep/impl/src/main/java/org/opendaylight/protocol/pcep/impl/tlv/PathSetupTypeTlvParser.java;hb=refs/for/stable/lithium[PathSetupTypeTlvParser]
+and it is overriden in segment-routing module to provide the aditional
+PST.
+
+==== PCEP Topology
+
+PCEP data is displayed only through one URL that is accessible from the base network-topology URL:
+
+_http://localhost:8181/restconf/operational/network-topology:network-topology/topology/pcep-topology_
+
+Each PCC will be displayed as a node:
+
+[source,xml]
+----
+<node>
+ <path-computation-client>
+ <ip-address>42.42.42.42</ip-address>
+ <state-sync>synchronized</state-sync>
+ <stateful-tlv>
+ <stateful>
+ <initiation>true</initiation>
+ <lsp-update-capability>true</lsp-update-capability>
+ </stateful>
+ </stateful-tlv>
+ </path-computation-client>
+ <node-id>pcc://42.42.42.42</node-id>
+</node>
+</source>
+----
+
+If some tunnels are configured on the network, they would be displayed on the same page, within a node that initiated the tunnel:
-==== API Group 1
-Provide a description of what the API does and some examples of how to
-use it.
+[source,xml]
+----
+<node>
+ <path-computation-client>
+ <state-sync>synchronized</state-sync>
+ <stateful-tlv>
+ <stateful>
+ <initiation>true</initiation>
+ <lsp-update-capability>true</lsp-update-capability>
+ </stateful>
+ </stateful-tlv>
+ <reported-lsp>
+ <name>foo</name>
+ <lsp>
+ <operational>down</operational>
+ <sync>false</sync>
+ <ignore>false</ignore>
+ <plsp-id>1</plsp-id>
+ <create>false</create>
+ <administrative>true</administrative>
+ <remove>false</remove>
+ <delegate>true</delegate>
+ <processing-rule>false</processing-rule>
+ <tlvs>
+ <lsp-identifiers>
+ <ipv4>
+ <ipv4-tunnel-sender-address>43.43.43.43</ipv4-tunnel-sender-address>
+ <ipv4-tunnel-endpoint-address>0.0.0.0</ipv4-tunnel-endpoint-address>
+ <ipv4-extended-tunnel-id>0.0.0.0</ipv4-extended-tunnel-id>
+ </ipv4>
+ <tunnel-id>0</tunnel-id>
+ <lsp-id>0</lsp-id>
+ </lsp-identifiers>
+ <symbolic-path-name>
+ <path-name>Zm9v</path-name>
+ </symbolic-path-name>
+ </tlvs>
+ </lsp>
+ </reported-lsp>
+ <ip-address>43.43.43.43</ip-address>
+ </path-computation-client>
+ <node-id>pcc://43.43.43.43</node-id>
+</node>
+----
-==== API Group 2
-Provide a description of what the API does and some examples of how to
-use it.
+Note that, the _<path-name>_ tag displays tunnel name in Base64 encoding.
=== API Reference Documentation
-Provide links to JavaDoc, REST API documentation, etc.
+Javadocs are generated while creating mvn:site
+and they are located in target/ directory in each module.
Code Review / docs.git / commitdiff
