blob: d1ac455b879717384e11e4e6c6fd9830e7e65ca6 [file] [log] [blame]
khenaidoob9203542018-09-17 22:56:37 -04001#
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"""
18Interface definition for Voltha Adapters
19"""
20from zope.interface import Interface
21
22
23class IAdapterInterface(Interface):
24 """
25 A Voltha adapter. This interface is used by the Voltha Core to initiate
26 requests towards a voltha adapter.
27 """
28
29 def adapter_descriptor():
30 """
31 Return the adapter descriptor object for this adapter.
32 :return: voltha.Adapter grpc object (see voltha/protos/adapter.proto),
33 with adapter-specific information and config extensions.
34 """
35
36 def device_types():
37 """
38 Return list of device types supported by the adapter.
39 :return: voltha.DeviceTypes protobuf object, with optional type
40 specific extensions.
41 """
42
43 def health():
44 """
45 Return a 3-state health status using the voltha.HealthStatus message.
46 :return: Deferred or direct return with voltha.HealthStatus message
47 """
48
49 def adopt_device(device):
50 """
51 Make sure the adapter looks after given device. Called when a device
52 is provisioned top-down and needs to be activated by the adapter.
53 :param device: A voltha.Device object, with possible device-type
54 specific extensions. Such extensions shall be described as part of
55 the device type specification returned by device_types().
56 :return: (Deferred) Shall be fired to acknowledge device ownership.
57 """
58
59 def reconcile_device(device):
60 """
61 Make sure the adapter looks after given device. Called when this
62 device has changed ownership from another Voltha instance to
63 this one (typically, this occurs when the previous voltha
64 instance went down).
65 :param device: A voltha.Device object, with possible device-type
66 specific extensions. Such extensions shall be described as part of
67 the device type specification returned by device_types().
68 :return: (Deferred) Shall be fired to acknowledge device ownership.
69 """
70
71 def abandon_device(device):
72 """
73 Make sur ethe adapter no longer looks after device. This is called
74 if device ownership is taken over by another Voltha instance.
75 :param device: A Voltha.Device object.
76 :return: (Deferred) Shall be fired to acknowledge abandonment.
77 """
78
79 def disable_device(device):
80 """
81 This is called when a previously enabled device needs to be disabled
82 based on a NBI call.
83 :param device: A Voltha.Device object.
84 :return: (Deferred) Shall be fired to acknowledge disabling the device.
85 """
86
87 def reenable_device(device):
88 """
89 This is called when a previously disabled device needs to be enabled
90 based on a NBI call.
91 :param device: A Voltha.Device object.
92 :return: (Deferred) Shall be fired to acknowledge re-enabling the
93 device.
94 """
95
96 def reboot_device(device):
97 """
98 This is called to reboot a device based on a NBI call. The admin
99 state of the device will not change after the reboot
100 :param device: A Voltha.Device object.
101 :return: (Deferred) Shall be fired to acknowledge the reboot.
102 """
103
104 def download_image(device, request):
105 """
106 This is called to request downloading a specified image into
107 the standby partition of a device based on a NBI call.
108 This call is expected to be non-blocking.
109 :param device: A Voltha.Device object.
110 A Voltha.ImageDownload object.
111 :return: (Deferred) Shall be fired to acknowledge the download.
112 """
113
114 def get_image_download_status(device, request):
115 """
116 This is called to inquire about a requested image download
117 status based on a NBI call.
118 The adapter is expected to update the DownloadImage DB object
119 with the query result
120 :param device: A Voltha.Device object.
121 A Voltha.ImageDownload object.
122 :return: (Deferred) Shall be fired to acknowledge
123 """
124
125 def cancel_image_download(device, request):
126 """
127 This is called to cancel a requested image download
128 based on a NBI call. The admin state of the device will not
129 change after the download.
130 :param device: A Voltha.Device object.
131 A Voltha.ImageDownload object.
132 :return: (Deferred) Shall be fired to acknowledge
133 """
134
135 def activate_image_update(device, request):
136 """
137 This is called to activate a downloaded image from
138 a standby partition into active partition.
139 Depending on the device implementation, this call
140 may or may not cause device reboot.
141 If no reboot, then a reboot is required to make the
142 activated image running on device
143 This call is expected to be non-blocking.
144 :param device: A Voltha.Device object.
145 A Voltha.ImageDownload object.
146 :return: (Deferred) OperationResponse object.
147 """
148
149 def revert_image_update(device, request):
150 """
151 This is called to deactivate the specified image at
152 active partition, and revert to previous image at
153 standby partition.
154 Depending on the device implementation, this call
155 may or may not cause device reboot.
156 If no reboot, then a reboot is required to make the
157 previous image running on device
158 This call is expected to be non-blocking.
159 :param device: A Voltha.Device object.
160 A Voltha.ImageDownload object.
161 :return: (Deferred) OperationResponse object.
162 """
163
164 def self_test_device(device):
165 """
166 This is called to Self a device based on a NBI call.
167 :param device: A Voltha.Device object.
168 :return: Will return result of self test
169 """
170
171 def delete_device(device):
172 """
173 This is called to delete a device from the PON based on a NBI call.
174 If the device is an OLT then the whole PON will be deleted.
175 :param device: A Voltha.Device object.
176 :return: (Deferred) Shall be fired to acknowledge the deletion.
177 """
178
179 def get_device_details(device):
180 """
181 This is called to get additional device details based on a NBI call.
182 :param device: A Voltha.Device object.
183 :return: (Deferred) Shall be fired to acknowledge the retrieval of
184 additional details.
185 """
186
187 def update_flows_bulk(device, flows, groups):
188 """
189 Called after any flow table change, but only if the device supports
190 bulk mode, which is expressed by the 'accepts_bulk_flow_update'
191 capability attribute of the device type.
192 :param device: A Voltha.Device object.
193 :param flows: An openflow_v13.Flows object
194 :param groups: An openflow_v13.Flows object
195 :return: (Deferred or None)
196 """
197
198 def update_flows_incrementally(device, flow_changes, group_changes):
199 """
200 Called after a flow table update, but only if the device supports
201 non-bulk mode, which is expressed by the 'accepts_add_remove_flow_updates'
202 capability attribute of the device type.
203 :param device: A Voltha.Device object.
204 :param flow_changes: An openflow_v13.FlowChanges object
205 :param group_changes: An openflow_v13.FlowGroupChanges object
206 :return: (Deferred or None)
207 """
208
209 def update_pm_config(device, pm_configs):
210 """
211 Called every time a request is made to change pm collection behavior
212 :param device: A Voltha.Device object
213 :param pm_collection_config: A Pms
214 """
215
216 def receive_packet_out(device_id, egress_port_no, msg):
217 """
218 Pass a packet_out message content to adapter so that it can forward
219 it out to the device. This is only called on root devices.
220 :param device_id: device ID
221 :param egress_port: egress logical port number
222 :param msg: actual message
223 :return: None
224 """
225
226 def suppress_alarm(filter):
227 """
228 Inform an adapter that all incoming alarms should be suppressed
229 :param filter: A Voltha.AlarmFilter object.
230 :return: (Deferred) Shall be fired to acknowledge the suppression.
231 """
232
233 def unsuppress_alarm(filter):
234 """
235 Inform an adapter that all incoming alarms should resume
236 :param filter: A Voltha.AlarmFilter object.
237 :return: (Deferred) Shall be fired to acknowledge the unsuppression.
238 """
239
240 def get_ofp_device_info(device):
241 """
242 Retrieve the OLT device info. This includes the ofp_desc and
243 ofp_switch_features. The existing ofp structures can be used,
244 or all the attributes get added to the Device definition or a new proto
245 definition gets created. This API will allow the Core to create a
246 LogicalDevice associated with this device (OLT only).
247 :param device: device
248 :return: Proto Message (TBD)
249 """
250
251 def get_ofp_port_info(device, port_no):
252 """
253 Retrieve the port info. This includes the ofp_port. The existing ofp
254 structure can be used, or all the attributes get added to the Port
255 definitions or a new proto definition gets created. This API will allow
256 the Core to create a LogicalPort associated with this device.
257 :param device: device
258 :param port_no: port number
259 :return: Proto Message (TBD)
260 """
261
262 # def start():
263 # """
264 # Called once after adapter instance is laoded. Can be used to async
265 # initialization.
266 # :return: (None or Deferred)
267 # """
268 #
269 # def stop():
270 # """
271 # Called once before adapter is unloaded. It can be used to perform
272 # any cleanup after the adapter.
273 # :return: (None or Deferred)
274 # """
275 #
276 # def receive_inter_adapter_message(msg):
277 # """
278 # Called when the adapter recieves a message that was sent to it directly
279 # from another adapter. An adapter may register for these messages by calling
280 # the register_for_inter_adapter_messages() method in the adapter agent.
281 # Note that it is the responsibility of the sending and receiving
282 # adapters to properly encode and decode the message.
283 # :param msg: The message contents.
284 # :return: None
285 # """
286 #
287 # def send_proxied_message(proxy_address, msg):
288 # """
289 # Forward a msg to a child device of device, addressed by the given
290 # proxy_address=Device.ProxyAddress().
291 # :param proxy_address: Address info for the parent device
292 # to route the message to the child device. This was given to the
293 # child device by the parent device at the creation of the child
294 # device.
295 # :param msg: (str) The actual message to send.
296 # :return: (Deferred(None) or None) The return of this method should
297 # indicate that the message was successfully *sent*.
298 # """
299 #
300 # def receive_proxied_message(proxy_address, msg):
301 # """
302 # Pass an async message (arrived via a proxy) to this device.
303 # :param proxy_address: Address info for the parent device
304 # to route the message to the child device. This was given to the
305 # child device by the parent device at the creation of the child
306 # device. Note this is the proxy_address with which the adapter
307 # had to register prior to receiving proxied messages.
308 # :param msg: (str) The actual message received.
309 # :return: None
310 # """
311 #
312 # def receive_packet_out(logical_device_id, egress_port_no, msg):
313 # """
314 # Pass a packet_out message content to adapter so that it can forward it
315 # out to the device. This is only called on root devices.
316 # :param logical_device_id:
317 # :param egress_port: egress logical port number
318 # :param msg: actual message
319 # :return: None
320 # """
321 #
322 # def change_master_state(master):
323 # """
324 # Called to indicate if plugin shall assume or lose master role. The
325 # master role can be used to perform functions that must be performed
326 # from a single point in the cluster. In single-node deployments of
327 # Voltha, the plugins are always in master role.
328 # :param master: (bool) True to indicate the mastership needs to be
329 # assumed; False to indicate that mastership needs to be abandoned.
330 # :return: (Deferred) which is fired by the adapter when mastership is
331 # assumed/dropped, respectively.
332 # """
333
334
335# class IAdapterAgent(Interface):
336# """
337# This object is passed in to the __init__ function of each adapter,
338# and can be used by the adapter implementation to initiate async calls
339# toward Voltha's CORE via the APIs defined here.
340# """
341#
342# def get_device(device_id):
343# # TODO add doc
344# """"""
345#
346# def add_device(device):
347# # TODO add doc
348# """"""
349#
350# def update_device(device):
351# # TODO add doc
352# """"""
353#
354# def add_port(device_id, port):
355# # TODO add doc
356# """"""
357#
358# def create_logical_device(logical_device):
359# # TODO add doc
360# """"""
361#
362# def add_logical_port(logical_device_id, port):
363# # TODO add doc
364# """"""
365#
366# def child_device_detected(parent_device_id,
367# parent_port_no,
368# child_device_type,
369# proxy_address,
370# admin_state,
371# **kw):
372# # TODO add doc
373# """"""
374#
375# def send_proxied_message(proxy_address, msg):
376# """
377# Forward a msg to a child device of device, addressed by the given
378# proxy_address=Device.ProxyAddress().
379# :param proxy_address: Address info for the parent device
380# to route the message to the child device. This was given to the
381# child device by the parent device at the creation of the child
382# device.
383# :param msg: (str) The actual message to send.
384# :return: (Deferred(None) or None) The return of this method should
385# indicate that the message was successfully *sent*.
386# """
387#
388# def receive_proxied_message(proxy_address, msg):
389# """
390# Pass an async message (arrived via a proxy) to this device.
391# :param proxy_address: Address info for the parent device
392# to route the message to the child device. This was given to the
393# child device by the parent device at the creation of the child
394# device. Note this is the proxy_address with which the adapter
395# had to register prior to receiving proxied messages.
396# :param msg: (str) The actual message received.
397# :return: None
398# """
399#
400# def register_for_proxied_messages(proxy_address):
401# """
402# A child device adapter can use this to indicate its intent to
403# receive async messages sent via a parent device. Example: an
404# ONU adapter can use this to register for OMCI messages received
405# via the OLT and the OLT adapter.
406# :param child_device_address: Address info that was given to the
407# child device by the parent device at the creation of the child
408# device. Its uniqueness acts as a router information for the
409# registration.
410# :return: None
411# """
412#
413# def unregister_for_proxied_messages(proxy_address):
414# """
415# Cancel a previous registration
416# :return:
417# """
418#
419# def send_packet_in(logical_device_id, logical_port_no, packet):
420# """
421# Forward given packet to the northbound toward an SDN controller.
422# :param device_id: logical device identifier
423# :param logical_port_no: logical port_no (as numbered in openflow)
424# :param packet: the actual packet; can be a serialized string or a scapy
425# Packet.
426# :return: None returned on success
427# """
428#
429# def submit_kpis(kpi_event_msg):
430# """
431# Submit KPI metrics on behalf of the OLT and its adapter. This can
432# include hardware related metrics, usage and utilization metrics, as
433# well as optional adapter specific metrics.
434# :param kpi_event_msg: A protobuf message of KpiEvent type.
435# :return: None
436# """
437#
438# def submit_alarm(device_id, alarm_event_msg):
439# """
440# Submit an alarm on behalf of the OLT and its adapter.
441# :param alarm_event_msg: A protobuf message of AlarmEvent type.
442# :return: None
443# """
444#
445# def register_for_onu_detect_state(proxy_address):
446# """
447#
448# :return: None
449# """
450#
451# def unregister_for_onu_detect_state(proxy_address):
452# """
453#
454# :return: None
455# """
456#
457# def forward_onu_detect_state(proxy_address, state):
458# """
459# Forward onu detect state to ONU adapter
460# :param proxy_address: ONU device address
461# :param state: ONU detect state (bool)
462# :return: None
463# """
464
465class ICoreSouthBoundInterface(Interface):
466 """
467 Represents a Voltha Core. This is used by an adapter to initiate async
468 calls towards Voltha Core.
469 """
470
471 def get_device(device_id):
472 """
473 Retrieve a device using its ID.
474 :param device_id: a device ID
475 :return: Device Object or None
476 """
477
478 def get_child_device(parent_device_id, **kwargs):
479 """
480 Retrieve a child device object belonging to the specified parent
481 device based on some match criteria. The first child device that
482 matches the provided criteria is returned.
483 :param parent_device_id: parent's device protobuf ID
484 :param **kwargs: arbitrary list of match criteria where the Value
485 in each key-value pair must be a protobuf type
486 :return: Child Device Object or None
487 """
488
489 def get_ports(device_id, port_type):
490 """
491 Retrieve all the ports of a given type of a Device.
492 :param device_id: a device ID
493 :param port_type: type of port
494 :return Ports object
495 """
496
497 def get_child_devices(parent_device_id):
498 """
499 Get all child devices given a parent device id
500 :param parent_device_id: The parent device ID
501 :return: Devices object
502 """
503
504 def get_child_device_with_proxy_address(proxy_address):
505 """
506 Get a child device based on its proxy address. Proxy address is
507 defined as {parent id, channel_id}
508 :param proxy_address: A Device.ProxyAddress object
509 :return: Device object or None
510 """
511
512 def device_state_update(device_id,
513 oper_status=None,
514 connect_status=None):
515 """
516 Update a device state.
517 :param device_id: The device ID
518 :param oper_state: Operational state of device
519 :param conn_state: Connection state of device
520 :return: None
521 """
522
523
524 def child_device_detected(parent_device_id,
525 parent_port_no,
526 child_device_type,
527 channel_id,
528 **kw):
529 """
530 A child device has been detected. Core will create the device along
531 with its unique ID.
532 :param parent_device_id: The parent device ID
533 :param parent_port_no: The parent port number
534 :param device_type: The child device type
535 :param channel_id: A unique identifier for that child device within
536 the parent device (e.g. vlan_id)
537 :param kw: A list of key-value pair where the value is a protobuf
538 message
539 :return: None
540 """
541
542 def device_update(device):
543 """
544 Event corresponding to a device update.
545 :param device: Device Object
546 :return: None
547 """
548
549 def child_device_removed(parent_device_id, child_device_id):
550 """
551 Event indicating a child device has been removed from a parent.
552 :param parent_device_id: Device ID of the parent
553 :param child_device_id: Device ID of the child
554 :return: None
555 """
556
557 def child_devices_state_update(parent_device_id,
558 oper_status=None,
559 connect_status=None,
560 admin_status=None):
561 """
562 Event indicating the status of all child devices have been changed.
563 :param parent_device_id: Device ID of the parent
564 :param oper_status: Operational status
565 :param connect_status: Connection status
566 :param admin_status: Admin status
567 :return: None
568 """
569
570 def child_devices_removed(parent_device_id):
571 """
572 Event indicating all child devices have been removed from a parent.
573 :param parent_device_id: Device ID of the parent device
574 :return: None
575 """
576
577 def device_pm_config_update(device_pm_config, init=False):
578 """
579 Event corresponding to a PM config update of a device.
580 :param device_pm_config: a PmConfigs object
581 :param init: True indicates initializing stage
582 :return: None
583 """
584
585 def port_created(device_id, port):
586 """
587 A port has been created and needs to be added to a device.
588 :param device_id: a device ID
589 :param port: Port object
590 :return None
591 """
592
593 def port_removed(device_id, port):
594 """
595 A port has been removed and it needs to be removed from a Device.
596 :param device_id: a device ID
597 :param port: a Port object
598 :return None
599 """
600
601 def ports_enabled(device_id):
602 """
603 All ports on that device have been re-enabled. The Core will change
604 the admin state to ENABLED and operational state to ACTIVE for all
605 ports on that device.
606 :param device_id: a device ID
607 :return: None
608 """
609
610 def ports_disabled(device_id):
611 """
612 All ports on that device have been disabled. The Core will change the
613 admin status to DISABLED and operational state to UNKNOWN for all
614 ports on that device.
615 :param device_id: a device ID
616 :return: None
617 """
618
619 def ports_oper_status_update(device_id, oper_status):
620 """
621 The operational status of all ports of a Device has been changed.
622 The Core will update the operational status for all ports on the
623 device.
624 :param device_id: a device ID
625 :param oper_status: operational Status
626 :return None
627 """
628
629 def image_download_update(img_dnld):
630 """
631 Event corresponding to an image download update.
632 :param img_dnld: a ImageDownload object
633 :return: None
634 """
635
636 def image_download_deleted(img_dnld):
637 """
638 Event corresponding to the deletion of a downloaded image. The
639 references of this image needs to be removed from the Core.
640 :param img_dnld: a ImageDownload object
641 :return: None
642 """
643
644 def packet_in(device_id, egress_port_no, packet):
645 """
646 Sends a packet to the SDN controller via voltha Core
647 :param device_id: The OLT device ID
648 :param egress_port_no: The port number representing the ONU (cvid)
649 :param packet: The actual packet
650 :return: None
651 """
652
653 # def add_device(device):
654 # # TODO add doc
655 # """"""
656
657 # def update_device(device):
658 # # TODO add doc
659 # """"""
660
661 # def add_port(device_id, port):
662 # # TODO add doc
663 # """"""
664
665 # def create_logical_device(logical_device):
666 # # TODO add doc
667 # """"""
668 #
669 # def add_logical_port(logical_device_id, port):
670 # # TODO add doc
671 # """"""
672
673 # def child_device_detected(parent_device_id,
674 # parent_port_no,
675 # child_device_type,
676 # proxy_address,
677 # admin_state,
678 # **kw):
679 # # TODO add doc
680 # """"""
681
682 # def send_proxied_message(proxy_address, msg):
683 # """
684 # Forward a msg to a child device of device, addressed by the given
685 # proxy_address=Device.ProxyAddress().
686 # :param proxy_address: Address info for the parent device
687 # to route the message to the child device. This was given to the
688 # child device by the parent device at the creation of the child
689 # device.
690 # :param msg: (str) The actual message to send.
691 # :return: (Deferred(None) or None) The return of this method should
692 # indicate that the message was successfully *sent*.
693 # """
694 #
695 # def receive_proxied_message(proxy_address, msg):
696 # """
697 # Pass an async message (arrived via a proxy) to this device.
698 # :param proxy_address: Address info for the parent device
699 # to route the message to the child device. This was given to the
700 # child device by the parent device at the creation of the child
701 # device. Note this is the proxy_address with which the adapter
702 # had to register prior to receiving proxied messages.
703 # :param msg: (str) The actual message received.
704 # :return: None
705 # """
706 #
707 # def register_for_proxied_messages(proxy_address):
708 # """
709 # A child device adapter can use this to indicate its intent to
710 # receive async messages sent via a parent device. Example: an
711 # ONU adapter can use this to register for OMCI messages received
712 # via the OLT and the OLT adapter.
713 # :param child_device_address: Address info that was given to the
714 # child device by the parent device at the creation of the child
715 # device. Its uniqueness acts as a router information for the
716 # registration.
717 # :return: None
718 # """
719 #
720 # def unregister_for_proxied_messages(proxy_address):
721 # """
722 # Cancel a previous registration
723 # :return:
724 # """
725 #
726 # def submit_kpis(kpi_event_msg):
727 # """
728 # Submit KPI metrics on behalf of the OLT and its adapter. This can
729 # include hardware related metrics, usage and utilization metrics, as
730 # well as optional adapter specific metrics.
731 # :param kpi_event_msg: A protobuf message of KpiEvent type.
732 # :return: None
733 # """
734 #
735 # def submit_alarm(device_id, alarm_event_msg):
736 # """
737 # Submit an alarm on behalf of the OLT and its adapter.
738 # :param alarm_event_msg: A protobuf message of AlarmEvent type.
739 # :return: None
740 # """
741
742 # def register_for_onu_detect_state(proxy_address):
743 # """
744 #
745 # :return: None
746 # """
747 #
748 # def unregister_for_onu_detect_state(proxy_address):
749 # """
750 #
751 # :return: None
752 # """
753 #
754 # def forward_onu_detect_state(proxy_address, state):
755 # """
756 # Forward onu detect state to ONU adapter
757 # :param proxy_address: ONU device address
758 # :param state: ONU detect state (bool)
759 # :return: None
760 # """
761 #
762 # def send_packet_in(logical_device_id, logical_port_no, packet):
763 # """
764 # Forward given packet to the northbound toward an SDN controller.
765 # :param device_id: logical device identifier
766 # :param logical_port_no: logical port_no (as numbered in openflow)
767 # :param packet: the actual packet; can be a serialized string or a
768 # scapy Packet.
769 # :return: None returned on success
Zack Williams998f4422018-09-19 10:38:57 -0700770 # """