docs/developer-guide/didm-developer-guide.rst

   1 .. _didm-developer-guide:
   2 DIDM Developer Guide
   3 ====================
   4
   5 Overview
   6 --------
   7
   8 The Device Identification and Driver Management (DIDM) project addresses
   9 the need to provide device-specific functionality. Device-specific
  10 functionality is code that performs a feature, and the code is
  11 knowledgeable of the capability and limitations of the device. For
  12 example, configuring VLANs and adjusting FlowMods are features, and
  13 there may be different implementations for different device types.
  14 Device-specific functionality is implemented as Device Drivers. Device
  15 Drivers need to be associated with the devices they can be used with. To
  16 determine this association requires the ability to identify the device
  17 type.
  18
  19 DIDM Architecture
  20 -----------------
  21
  22 The DIDM project creates the infrastructure to support the following
  23 functions:
  24
  25 -  **Discovery** - Determination that a device exists in the controller
  26    management domain and connectivity to the device can be established.
  27    For devices that support the OpenFlow protocol, the existing
  28    discovery mechanism in OpenDaylight suffices. Devices that do not
  29    support OpenFlow will be discovered through manual means such as the
  30    operator entering device information via GUI or REST API.
  31
  32 -  **Identification** – Determination of the device type.
  33
  34 -  **Driver Registration** – Registration of Device Drivers as routed
  35    RPCs.
  36
  37 -  **Synchronization** – Collection of device information, device
  38    configuration, and link (connection) information.
  39
  40 -  **Data Models for Common Features** – Data models will be defined to
  41    perform common features such as VLAN configuration. For example,
  42    applications can configure a VLAN by writing the VLAN data to the
  43    data store as specified by the common data model.
  44
  45 -  **RPCs for Common Features** – Configuring VLANs and adjusting
  46    FlowMods are example of features. RPCs will be defined that specify
  47    the APIs for these features. Drivers implement features for specific
  48    devices and support the APIs defined by the RPCs. There may be
  49    different Driver implementations for different device types.
  50
  51 Key APIs and Interfaces
  52 -----------------------
  53
  54 .. _didm-flow-objective-api:
  55
  56 FlowObjective API
  57 ~~~~~~~~~~~~~~~~~
  58
  59 Following are the list of the APIs to create the flow objectives to
  60 install the flow rule in OpenFlow switch in pipeline agnostic way.
  61 Currently these APIs are getting consumed by Atrium project.
  62
  63 Install the Forwarding Objective:
  64
  65 ``http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:forward``
  66
  67 Install the Filter Objective
  68
  69 ``http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:filter``
  70
  71 Install the Next Objective:
  72
  73 ``http://<CONTROLLER-IP>:8181/restconf/operations/atrium-flow-objective:next``
  74
  75 Flow mod driver API
  76 ~~~~~~~~~~~~~~~~~~~
  77
  78 This release includes a flow mod driver for the HP 3800. This
  79 driver adjusts the flows and push the same to the device. This API takes
  80 the flow to be adjusted as input and displays the adjusted flow as
  81 output in the REST output container. Here is the REST API to adjust and
  82 push flows to HP 3800 device:
  83
  84 ::
  85
  86     http://<CONTROLLER-IP:8181>/restconf/operations/openflow-feature:adjust-flow
  87
  88 Here is an example of an ARP flow and how it gets adjusted and pushed to
  89 device HP3800:
  90
  91 **adjust-flow input.**
  92
  93 ::
  94
  95     <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  96     <input xmlns="urn:opendaylight:params:xml:ns:yang:didm:drivers:openflow" xmlns:opendaylight-inventory="urn:opendaylight:inventory">
  97       <node>/opendaylight-inventory:nodes/opendaylight-inventory:node[opendaylight-inventory:id='openflow:673249119553088']</node>
  98         <flow>
  99           <match>
 100             <ethernet-match>
 101                 <ethernet-type>
 102                     <type>2054</type>
 103                 </ethernet-type>
 104             </ethernet-match>
 105           </match>
 106           <flags>SEND_FLOW_REM</flags>
 107           <priority>0</priority>
 108           <flow-name>ARP_FLOW</flow-name>
 109           <instructions>
 110             <instruction>
 111                 <order>0</order>
 112                 <apply-actions>
 113                     <action>
 114                         <order>0</order>
 115                         <output-action>
 116                             <output-node-connector>CONTROLLER</output-node-connector>
 117                             <max-length>65535</max-length>
 118                         </output-action>
 119                     </action>
 120                     <action>
 121                         <order>1</order>
 122                         <output-action>
 123                             <output-node-connector>NORMAL</output-node-connector>
 124                             <max-length>65535</max-length>
 125                         </output-action>
 126                     </action>
 127                 </apply-actions>
 128             </instruction>
 129           </instructions>
 130           <idle-timeout>180</idle-timeout>
 131           <hard-timeout>1800</hard-timeout>
 132           <cookie>10</cookie>
 133         </flow>
 134     </input>
 135
 136 In the output, you can see that the table ID has been identified for the
 137 given flow and two flow mods are created as a result of adjustment. The
 138 first one is to catch ARP packets in Hardware table 100 with an action
 139 to goto table 200. The second flow mod is in table 200 with actions:
 140 output normal and output controller.
 141
 142 **adjust-flow output.**
 143
 144 ::
 145
 146     {
 147       "output": {
 148         "flow": [
 149           {
 150             "idle-timeout": 180,
 151             "instructions": {
 152               "instruction": [
 153                 {
 154                   "order": 0,
 155                   "apply-actions": {
 156                     "action": [
 157                       {
 158                         "order": 1,
 159                         "output-action": {
 160                           "output-node-connector": "NORMAL",
 161                           "max-length": 65535
 162                         }
 163                       },
 164                       {
 165                         "order": 0,
 166                         "output-action": {
 167                           "output-node-connector": "CONTROLLER",
 168                           "max-length": 65535
 169                         }
 170                       }
 171                     ]
 172                   }
 173                 }
 174               ]
 175             },
 176             "strict": false,
 177             "table_id": 200,
 178             "flags": "SEND_FLOW_REM",
 179             "cookie": 10,
 180             "hard-timeout": 1800,
 181             "match": {
 182               "ethernet-match": {
 183                 "ethernet-type": {
 184                   "type": 2054
 185                 }
 186               }
 187             },
 188             "flow-name": "ARP_FLOW",
 189             "priority": 0
 190           },
 191           {
 192             "idle-timeout": 180,
 193             "instructions": {
 194               "instruction": [
 195                 {
 196                   "order": 0,
 197                   "go-to-table": {
 198                     "table_id": 200
 199                   }
 200                 }
 201               ]
 202             },
 203             "strict": false,
 204             "table_id": 100,
 205             "flags": "SEND_FLOW_REM",
 206             "cookie": 10,
 207             "hard-timeout": 1800,
 208             "match": {},
 209             "flow-name": "ARP_FLOW",
 210             "priority": 0
 211           }
 212         ]
 213       }
 214     }
 215
 216 API Reference Documentation
 217 ---------------------------
 218
 219 Go to
 220 http://${controller-ip}:8181/apidoc/explorer/index.html,
 221 and look under DIDM section to see all the available REST calls and
 222 tables
 223