Chip Boling | 67b674a | 2019-02-08 11:42:18 -0600 | [diff] [blame] | 1 | # |
| 2 | # Copyright 2018 the original author or authors. |
| 3 | # |
| 4 | # Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | # you may not use this file except in compliance with the License. |
| 6 | # You may obtain a copy of the License at |
| 7 | # |
| 8 | # http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | # |
| 10 | # Unless required by applicable law or agreed to in writing, software |
| 11 | # distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | # See the License for the specific language governing permissions and |
| 14 | # limitations under the License. |
| 15 | # |
| 16 | |
| 17 | """ |
| 18 | Interface definition for Voltha Adapters |
| 19 | """ |
Zack Williams | 84a71e9 | 2019-11-15 09:00:19 -0700 | [diff] [blame] | 20 | from __future__ import absolute_import |
Chip Boling | 67b674a | 2019-02-08 11:42:18 -0600 | [diff] [blame] | 21 | from zope.interface import Interface |
| 22 | |
| 23 | |
| 24 | class IAdapterInterface(Interface): |
| 25 | """ |
| 26 | A Voltha adapter. This interface is used by the Voltha Core to initiate |
| 27 | requests towards a voltha adapter. |
| 28 | """ |
| 29 | |
| 30 | def adapter_descriptor(): |
| 31 | """ |
| 32 | Return the adapter descriptor object for this adapter. |
| 33 | :return: voltha.Adapter grpc object (see voltha/protos/adapter.proto), |
| 34 | with adapter-specific information and config extensions. |
| 35 | """ |
| 36 | |
| 37 | def device_types(): |
| 38 | """ |
| 39 | Return list of device types supported by the adapter. |
| 40 | :return: voltha.DeviceTypes protobuf object, with optional type |
| 41 | specific extensions. |
| 42 | """ |
| 43 | |
| 44 | def health(): |
| 45 | """ |
| 46 | Return a 3-state health status using the voltha.HealthStatus message. |
| 47 | :return: Deferred or direct return with voltha.HealthStatus message |
| 48 | """ |
| 49 | |
| 50 | def adopt_device(device): |
| 51 | """ |
| 52 | Make sure the adapter looks after given device. Called when a device |
| 53 | is provisioned top-down and needs to be activated by the adapter. |
| 54 | :param device: A voltha.Device object, with possible device-type |
| 55 | specific extensions. Such extensions shall be described as part of |
| 56 | the device type specification returned by device_types(). |
| 57 | :return: (Deferred) Shall be fired to acknowledge device ownership. |
| 58 | """ |
| 59 | |
| 60 | def reconcile_device(device): |
| 61 | """ |
| 62 | Make sure the adapter looks after given device. Called when this |
| 63 | device has changed ownership from another Voltha instance to |
| 64 | this one (typically, this occurs when the previous voltha |
| 65 | instance went down). |
| 66 | :param device: A voltha.Device object, with possible device-type |
| 67 | specific extensions. Such extensions shall be described as part of |
| 68 | the device type specification returned by device_types(). |
| 69 | :return: (Deferred) Shall be fired to acknowledge device ownership. |
| 70 | """ |
| 71 | |
| 72 | def abandon_device(device): |
| 73 | """ |
| 74 | Make sur ethe adapter no longer looks after device. This is called |
| 75 | if device ownership is taken over by another Voltha instance. |
| 76 | :param device: A Voltha.Device object. |
| 77 | :return: (Deferred) Shall be fired to acknowledge abandonment. |
| 78 | """ |
| 79 | |
| 80 | def disable_device(device): |
| 81 | """ |
| 82 | This is called when a previously enabled device needs to be disabled |
| 83 | based on a NBI call. |
| 84 | :param device: A Voltha.Device object. |
| 85 | :return: (Deferred) Shall be fired to acknowledge disabling the device. |
| 86 | """ |
| 87 | |
| 88 | def reenable_device(device): |
| 89 | """ |
| 90 | This is called when a previously disabled device needs to be enabled |
| 91 | based on a NBI call. |
| 92 | :param device: A Voltha.Device object. |
| 93 | :return: (Deferred) Shall be fired to acknowledge re-enabling the |
| 94 | device. |
| 95 | """ |
| 96 | |
| 97 | def reboot_device(device): |
| 98 | """ |
| 99 | This is called to reboot a device based on a NBI call. The admin |
| 100 | state of the device will not change after the reboot |
| 101 | :param device: A Voltha.Device object. |
| 102 | :return: (Deferred) Shall be fired to acknowledge the reboot. |
| 103 | """ |
| 104 | |
| 105 | def download_image(device, request): |
| 106 | """ |
| 107 | This is called to request downloading a specified image into |
| 108 | the standby partition of a device based on a NBI call. |
| 109 | This call is expected to be non-blocking. |
| 110 | :param device: A Voltha.Device object. |
| 111 | A Voltha.ImageDownload object. |
| 112 | :return: (Deferred) Shall be fired to acknowledge the download. |
| 113 | """ |
| 114 | |
| 115 | def get_image_download_status(device, request): |
| 116 | """ |
| 117 | This is called to inquire about a requested image download |
| 118 | status based on a NBI call. |
| 119 | The adapter is expected to update the DownloadImage DB object |
| 120 | with the query result |
| 121 | :param device: A Voltha.Device object. |
| 122 | A Voltha.ImageDownload object. |
| 123 | :return: (Deferred) Shall be fired to acknowledge |
| 124 | """ |
| 125 | |
| 126 | def cancel_image_download(device, request): |
| 127 | """ |
| 128 | This is called to cancel a requested image download |
| 129 | based on a NBI call. The admin state of the device will not |
| 130 | change after the download. |
| 131 | :param device: A Voltha.Device object. |
| 132 | A Voltha.ImageDownload object. |
| 133 | :return: (Deferred) Shall be fired to acknowledge |
| 134 | """ |
| 135 | |
| 136 | def activate_image_update(device, request): |
| 137 | """ |
| 138 | This is called to activate a downloaded image from |
| 139 | a standby partition into active partition. |
| 140 | Depending on the device implementation, this call |
| 141 | may or may not cause device reboot. |
| 142 | If no reboot, then a reboot is required to make the |
| 143 | activated image running on device |
| 144 | This call is expected to be non-blocking. |
| 145 | :param device: A Voltha.Device object. |
| 146 | A Voltha.ImageDownload object. |
| 147 | :return: (Deferred) OperationResponse object. |
| 148 | """ |
| 149 | |
| 150 | def revert_image_update(device, request): |
| 151 | """ |
| 152 | This is called to deactivate the specified image at |
| 153 | active partition, and revert to previous image at |
| 154 | standby partition. |
| 155 | Depending on the device implementation, this call |
| 156 | may or may not cause device reboot. |
| 157 | If no reboot, then a reboot is required to make the |
| 158 | previous image running on device |
| 159 | This call is expected to be non-blocking. |
| 160 | :param device: A Voltha.Device object. |
| 161 | A Voltha.ImageDownload object. |
| 162 | :return: (Deferred) OperationResponse object. |
| 163 | """ |
| 164 | |
kesavand | d9ef7fe | 2020-01-29 20:54:13 -0500 | [diff] [blame] | 165 | def enable_port(device_id, port): |
| 166 | """ |
| 167 | This is called to enable the specified port. |
| 168 | |
| 169 | Depending on the implementation, this call may or may |
| 170 | not cause port enable. |
| 171 | This call is expected to be non-blocking. |
| 172 | :param device_id: A voltha.Device.id object. |
| 173 | :param port: A voltha.Port object |
| 174 | """ |
| 175 | |
| 176 | def disable_port(device_id, port): |
| 177 | """ |
| 178 | This is called to disable the specified port. |
| 179 | |
| 180 | Depending on the implementation, this call may or may |
| 181 | not cause port disable. |
| 182 | This call is expected to be non-blocking. |
| 183 | :param device_id: A voltha.Device.id object. |
| 184 | :param port: A voltha.Port object |
| 185 | """ |
| 186 | |
Chip Boling | 67b674a | 2019-02-08 11:42:18 -0600 | [diff] [blame] | 187 | def self_test_device(device): |
| 188 | """ |
| 189 | This is called to Self a device based on a NBI call. |
| 190 | :param device: A Voltha.Device object. |
| 191 | :return: Will return result of self test |
| 192 | """ |
| 193 | |
| 194 | def delete_device(device): |
| 195 | """ |
| 196 | This is called to delete a device from the PON based on a NBI call. |
| 197 | If the device is an OLT then the whole PON will be deleted. |
| 198 | :param device: A Voltha.Device object. |
| 199 | :return: (Deferred) Shall be fired to acknowledge the deletion. |
| 200 | """ |
| 201 | |
| 202 | def get_device_details(device): |
| 203 | """ |
| 204 | This is called to get additional device details based on a NBI call. |
| 205 | :param device: A Voltha.Device object. |
| 206 | :return: (Deferred) Shall be fired to acknowledge the retrieval of |
| 207 | additional details. |
| 208 | """ |
| 209 | |
| 210 | def update_flows_bulk(device, flows, groups): |
| 211 | """ |
| 212 | Called after any flow table change, but only if the device supports |
| 213 | bulk mode, which is expressed by the 'accepts_bulk_flow_update' |
| 214 | capability attribute of the device type. |
| 215 | :param device: A Voltha.Device object. |
| 216 | :param flows: An openflow_v13.Flows object |
| 217 | :param groups: An openflow_v13.Flows object |
| 218 | :return: (Deferred or None) |
| 219 | """ |
| 220 | |
| 221 | def update_flows_incrementally(device, flow_changes, group_changes): |
| 222 | """ |
| 223 | Called after a flow table update, but only if the device supports |
| 224 | non-bulk mode, which is expressed by the 'accepts_add_remove_flow_updates' |
| 225 | capability attribute of the device type. |
| 226 | :param device: A Voltha.Device object. |
| 227 | :param flow_changes: An openflow_v13.FlowChanges object |
| 228 | :param group_changes: An openflow_v13.FlowGroupChanges object |
| 229 | :return: (Deferred or None) |
| 230 | """ |
| 231 | |
| 232 | def update_pm_config(device, pm_configs): |
| 233 | """ |
| 234 | Called every time a request is made to change pm collection behavior |
| 235 | :param device: A Voltha.Device object |
| 236 | :param pm_collection_config: A Pms |
| 237 | """ |
| 238 | |
| 239 | def receive_packet_out(device_id, egress_port_no, msg): |
| 240 | """ |
| 241 | Pass a packet_out message content to adapter so that it can forward |
| 242 | it out to the device. This is only called on root devices. |
| 243 | :param device_id: device ID |
| 244 | :param egress_port: egress logical port number |
| 245 | :param msg: actual message |
| 246 | :return: None |
| 247 | """ |
| 248 | |
| 249 | def suppress_alarm(filter): |
| 250 | """ |
| 251 | Inform an adapter that all incoming alarms should be suppressed |
| 252 | :param filter: A Voltha.AlarmFilter object. |
| 253 | :return: (Deferred) Shall be fired to acknowledge the suppression. |
| 254 | """ |
| 255 | |
| 256 | def unsuppress_alarm(filter): |
| 257 | """ |
| 258 | Inform an adapter that all incoming alarms should resume |
| 259 | :param filter: A Voltha.AlarmFilter object. |
| 260 | :return: (Deferred) Shall be fired to acknowledge the unsuppression. |
| 261 | """ |
| 262 | |
| 263 | def get_ofp_device_info(device): |
| 264 | """ |
| 265 | Retrieve the OLT device info. This includes the ofp_desc and |
| 266 | ofp_switch_features. The existing ofp structures can be used, |
| 267 | or all the attributes get added to the Device definition or a new proto |
| 268 | definition gets created. This API will allow the Core to create a |
| 269 | LogicalDevice associated with this device (OLT only). |
| 270 | :param device: device |
| 271 | :return: Proto Message (TBD) |
| 272 | """ |
| 273 | |
Chip Boling | 67b674a | 2019-02-08 11:42:18 -0600 | [diff] [blame] | 274 | def process_inter_adapter_message(msg): |
| 275 | """ |
| 276 | Called when the adapter receives a message that was sent to it directly |
| 277 | from another adapter. An adapter is automatically registered for these |
| 278 | messages when creating the inter-container kafka proxy. Note that it is |
| 279 | the responsibility of the sending and receiving adapters to properly encode |
| 280 | and decode the message. |
| 281 | :param msg: Proto Message (any) |
| 282 | :return: Proto Message Response |
| 283 | """ |
| 284 | |
| 285 | |
| 286 | class ICoreSouthBoundInterface(Interface): |
| 287 | """ |
| 288 | Represents a Voltha Core. This is used by an adapter to initiate async |
| 289 | calls towards Voltha Core. |
| 290 | """ |
| 291 | |
| 292 | def get_device(device_id): |
| 293 | """ |
| 294 | Retrieve a device using its ID. |
| 295 | :param device_id: a device ID |
| 296 | :return: Device Object or None |
| 297 | """ |
| 298 | |
| 299 | def get_child_device(parent_device_id, **kwargs): |
| 300 | """ |
| 301 | Retrieve a child device object belonging to the specified parent |
| 302 | device based on some match criteria. The first child device that |
| 303 | matches the provided criteria is returned. |
| 304 | :param parent_device_id: parent's device protobuf ID |
| 305 | :param **kwargs: arbitrary list of match criteria where the Value |
| 306 | in each key-value pair must be a protobuf type |
| 307 | :return: Child Device Object or None |
| 308 | """ |
| 309 | |
| 310 | def get_ports(device_id, port_type): |
| 311 | """ |
| 312 | Retrieve all the ports of a given type of a Device. |
| 313 | :param device_id: a device ID |
| 314 | :param port_type: type of port |
| 315 | :return Ports object |
| 316 | """ |
| 317 | |
| 318 | def get_child_devices(parent_device_id): |
| 319 | """ |
| 320 | Get all child devices given a parent device id |
| 321 | :param parent_device_id: The parent device ID |
| 322 | :return: Devices object |
| 323 | """ |
| 324 | |
| 325 | def get_child_device_with_proxy_address(proxy_address): |
| 326 | """ |
| 327 | Get a child device based on its proxy address. Proxy address is |
| 328 | defined as {parent id, channel_id} |
| 329 | :param proxy_address: A Device.ProxyAddress object |
| 330 | :return: Device object or None |
| 331 | """ |
| 332 | |
| 333 | def device_state_update(device_id, |
| 334 | oper_status=None, |
| 335 | connect_status=None): |
| 336 | """ |
| 337 | Update a device state. |
| 338 | :param device_id: The device ID |
| 339 | :param oper_state: Operational state of device |
| 340 | :param conn_state: Connection state of device |
| 341 | :return: None |
| 342 | """ |
| 343 | |
| 344 | def child_device_detected(parent_device_id, |
| 345 | parent_port_no, |
| 346 | child_device_type, |
| 347 | channel_id, |
| 348 | **kw): |
| 349 | """ |
| 350 | A child device has been detected. Core will create the device along |
| 351 | with its unique ID. |
| 352 | :param parent_device_id: The parent device ID |
| 353 | :param parent_port_no: The parent port number |
| 354 | :param device_type: The child device type |
| 355 | :param channel_id: A unique identifier for that child device within |
| 356 | the parent device (e.g. vlan_id) |
| 357 | :param kw: A list of key-value pair where the value is a protobuf |
| 358 | message |
| 359 | :return: None |
| 360 | """ |
| 361 | |
| 362 | def device_update(device): |
| 363 | """ |
| 364 | Event corresponding to a device update. |
| 365 | :param device: Device Object |
| 366 | :return: None |
| 367 | """ |
| 368 | |
| 369 | def child_device_removed(parent_device_id, child_device_id): |
| 370 | """ |
| 371 | Event indicating a child device has been removed from a parent. |
| 372 | :param parent_device_id: Device ID of the parent |
| 373 | :param child_device_id: Device ID of the child |
| 374 | :return: None |
| 375 | """ |
| 376 | |
| 377 | def child_devices_state_update(parent_device_id, |
| 378 | oper_status=None, |
| 379 | connect_status=None, |
| 380 | admin_status=None): |
| 381 | """ |
| 382 | Event indicating the status of all child devices have been changed. |
| 383 | :param parent_device_id: Device ID of the parent |
| 384 | :param oper_status: Operational status |
| 385 | :param connect_status: Connection status |
| 386 | :param admin_status: Admin status |
| 387 | :return: None |
| 388 | """ |
| 389 | |
| 390 | def child_devices_removed(parent_device_id): |
| 391 | """ |
| 392 | Event indicating all child devices have been removed from a parent. |
| 393 | :param parent_device_id: Device ID of the parent device |
| 394 | :return: None |
| 395 | """ |
| 396 | |
| 397 | def device_pm_config_update(device_pm_config, init=False): |
| 398 | """ |
| 399 | Event corresponding to a PM config update of a device. |
| 400 | :param device_pm_config: a PmConfigs object |
| 401 | :param init: True indicates initializing stage |
| 402 | :return: None |
| 403 | """ |
| 404 | |
| 405 | def port_created(device_id, port): |
| 406 | """ |
| 407 | A port has been created and needs to be added to a device. |
| 408 | :param device_id: a device ID |
| 409 | :param port: Port object |
| 410 | :return None |
| 411 | """ |
| 412 | |
| 413 | def port_removed(device_id, port): |
| 414 | """ |
| 415 | A port has been removed and it needs to be removed from a Device. |
| 416 | :param device_id: a device ID |
| 417 | :param port: a Port object |
| 418 | :return None |
| 419 | """ |
| 420 | |
| 421 | def ports_enabled(device_id): |
| 422 | """ |
| 423 | All ports on that device have been re-enabled. The Core will change |
| 424 | the admin state to ENABLED and operational state to ACTIVE for all |
| 425 | ports on that device. |
| 426 | :param device_id: a device ID |
| 427 | :return: None |
| 428 | """ |
| 429 | |
| 430 | def ports_disabled(device_id): |
| 431 | """ |
| 432 | All ports on that device have been disabled. The Core will change the |
| 433 | admin status to DISABLED and operational state to UNKNOWN for all |
| 434 | ports on that device. |
| 435 | :param device_id: a device ID |
| 436 | :return: None |
| 437 | """ |
| 438 | |
| 439 | def ports_oper_status_update(device_id, oper_status): |
| 440 | """ |
| 441 | The operational status of all ports of a Device has been changed. |
| 442 | The Core will update the operational status for all ports on the |
| 443 | device. |
| 444 | :param device_id: a device ID |
| 445 | :param oper_status: operational Status |
| 446 | :return None |
| 447 | """ |
| 448 | |
| 449 | def image_download_update(img_dnld): |
| 450 | """ |
| 451 | Event corresponding to an image download update. |
| 452 | :param img_dnld: a ImageDownload object |
| 453 | :return: None |
| 454 | """ |
| 455 | |
| 456 | def image_download_deleted(img_dnld): |
| 457 | """ |
| 458 | Event corresponding to the deletion of a downloaded image. The |
| 459 | references of this image needs to be removed from the Core. |
| 460 | :param img_dnld: a ImageDownload object |
| 461 | :return: None |
| 462 | """ |
| 463 | |
| 464 | def packet_in(device_id, egress_port_no, packet): |
| 465 | """ |
| 466 | Sends a packet to the SDN controller via voltha Core |
| 467 | :param device_id: The OLT device ID |
| 468 | :param egress_port_no: The port number representing the ONU (cvid) |
| 469 | :param packet: The actual packet |
| 470 | :return: None |
| 471 | """ |