== LACP Developer Guide
=== LACP Overview
-The LACP(Link Aggregation Control Protocol) feature can be used to
-aggregate multiple links between OpenDaylight controlled network
-switches and their directly connected LACP enabled legacy switches or
-hosts operating in active mode.
-
-LACP passively negotiates automatic bundling of multiple links to form
-a single logical interface.
-The logical interface is currently realised in the OpenDaylight controlled
-switches using Openflow(1.3) group table functionality.
-The realisation of the logical interface can be also be done by informing the
-creation of the LAG(LACP Aggregator) interface to the OpenDaylight controlled
-switches or in any other manner by adding the required pluggable extension to
-the LACP.
+The OpenDaylight LACP (Link Aggregation Control Protocol) project can be used to
+aggregate multiple links between OpenDaylight controlled network switches and
+LACP enabled legacy switches or hosts operating in active LACP mode.
+
+OpenDaylight LACP passively negotiates automatic bundling of multiple links to form
+a single LAG (Link Aggregation Group). LAGs are realised in the OpenDaylight controlled
+switches using OpenFlow 1.3+ group table functionality.
+
=== LACP Architecture
+
* *inventory*
- ** Maintains the list of LACP supporting OpenDaylight controlled switches,
- the list of logical interfaces created and physical links that are part
- of the logical interfaces available in each switch
+ ** Maintains list of OpenDaylight controlled switches and port information
+ ** List of LAGs created and physical ports that are part
+ of the LAG
+ ** Interacts with MD-SAL to update LACP related information
+
+* *inventorylistener*
+ ** This module interacts with MD-SAL for receiving node/node-connector notifications
+
+* *flow*
+ ** Programs the switch to punt LACP PDU (Protocol Data Unit) to controller
+
* *packethandler*
** Receives and transmits LACP PDUs to the LACP enabled endpoint
+ ** Provides infrastructure services for group table programming
+
* *core*
** Performs LACP state machine processing
-=== Realizing logical interface in switches
-==== Group Table programming
-The logical interface representing the aggregated multiple physical links
+==== How LAG programming is implemented
+
+The LAG representing the aggregated multiple physical ports
are realized in the OpenDaylight controlled switches by creating a
group table entry (Group table supported from Openflow 1.3 onwards).
The group table entry has a group type *Select* and action referring to
-the aggregated physical links.
-Any data traffic to be sent out through the logical interface can be sent
-through the *Group entry* available for the logical interface.
+the aggregated physical ports.
+Any data traffic to be sent out through the LAG can be sent
+through the *group entry* available for the LAG.
+
+Suppose there are ports P1-P8 in a node.
+When LACP project is installed, a group table entry for handling broadcast traffic is automatically
+created on all the switches that have registered to the controller.
+
+[options="header"]
+|=================================
+|GroupID |GroupType|EgressPorts
+|<B'castgID>|ALL |P1,P2,...P8
+|=================================
+
+Now, assume P1 & P2 are now part of LAG1. The group table would be programmed as follows:
+
+[options="header"]
+|========================================
+|GroupID |GroupType|EgressPorts
+|<B'castgID>|ALL |P3,P4,...P8
+|<LAG1> |SELECT |P1,P2
+|========================================
+
+When a second LAG, LAG2, is formed with ports P3 and P4,
+
+[options="header"]
+|===============================================
+|GroupID |GroupType|EgressPorts
+|<B'castgID>|ALL |P5,P6,...P8
+|<LAG1> |SELECT |P1,P2
+|<LAG2> |SELECT |P3,P4
+|===============================================
+
+==== How applications can program OpenFlow flows using LACP-created LAG groups
-==== Alternate ways of realizing logical interface
+OpenDaylight controller modules can get the information of LAG by listening/querying the LACP Aggregator datastore.
-An interface for the logical interface creation / modification / deletion
-is provided by the LACP feature. The plugin to realize the logical interface
-has to implement this interface and provide implementation for the following
-interface functions
+When any application receives packets, it can check, if the ingress port is part of a LAG by verifying the
+LAG Aggregator reference (lacp-agg-ref) for the source nodeConnector that OpenFlow plugin provides.
-* LACreateLag(nodeId, aggId, portId)
+When applications want to add flows to egress out of the LAG, they must use the group entry corresponding to the LAG.
-* LADeleteLag(nodeId, aggId)
+From the above example, for a flow to egress out of LAG1,
-* LAUpdateLag(nodeId, aggId, portId, action)
+*add-flow eth_type=<xxxx>,ip_dst=<x.x.x.x>,actions=output:<LAG1>*
-==== Realizing logical interface using other pluggable extension
-Any new extension that wants to realize the logical interface in the
-switch must implement the above mentioned interface functions.
-These implemented functions must have a way of informing the
-logical interface related operation to the switch.
-It also has to provide a mapping so as to handle the data
-traffic transmitted through the logical interface using the hardware
-support available for that logical interface in the switch.
+Similarly, when applications want traffic to be broadcasted, they should use the group table entries *<B'castgID>,<LAG1>,<LAG2>* in output action.
+For all applications, the group table information is accessible from LACP Aggregator datastore.