| # |
| # Copyright 2018 the original author or authors. |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| # |
| |
| """ |
| Interface definition for Voltha Adapters |
| """ |
| from zope.interface import Interface |
| |
| |
| class IAdapterInterface(Interface): |
| """ |
| A Voltha adapter. This interface is used by the Voltha Core to initiate |
| requests towards a voltha adapter. |
| """ |
| |
| def adapter_descriptor(): |
| """ |
| Return the adapter descriptor object for this adapter. |
| :return: voltha.Adapter grpc object (see voltha/protos/adapter.proto), |
| with adapter-specific information and config extensions. |
| """ |
| |
| def device_types(): |
| """ |
| Return list of device types supported by the adapter. |
| :return: voltha.DeviceTypes protobuf object, with optional type |
| specific extensions. |
| """ |
| |
| def health(): |
| """ |
| Return a 3-state health status using the voltha.HealthStatus message. |
| :return: Deferred or direct return with voltha.HealthStatus message |
| """ |
| |
| def adopt_device(device): |
| """ |
| Make sure the adapter looks after given device. Called when a device |
| is provisioned top-down and needs to be activated by the adapter. |
| :param device: A voltha.Device object, with possible device-type |
| specific extensions. Such extensions shall be described as part of |
| the device type specification returned by device_types(). |
| :return: (Deferred) Shall be fired to acknowledge device ownership. |
| """ |
| |
| def reconcile_device(device): |
| """ |
| Make sure the adapter looks after given device. Called when this |
| device has changed ownership from another Voltha instance to |
| this one (typically, this occurs when the previous voltha |
| instance went down). |
| :param device: A voltha.Device object, with possible device-type |
| specific extensions. Such extensions shall be described as part of |
| the device type specification returned by device_types(). |
| :return: (Deferred) Shall be fired to acknowledge device ownership. |
| """ |
| |
| def abandon_device(device): |
| """ |
| Make sur ethe adapter no longer looks after device. This is called |
| if device ownership is taken over by another Voltha instance. |
| :param device: A Voltha.Device object. |
| :return: (Deferred) Shall be fired to acknowledge abandonment. |
| """ |
| |
| def disable_device(device): |
| """ |
| This is called when a previously enabled device needs to be disabled |
| based on a NBI call. |
| :param device: A Voltha.Device object. |
| :return: (Deferred) Shall be fired to acknowledge disabling the device. |
| """ |
| |
| def reenable_device(device): |
| """ |
| This is called when a previously disabled device needs to be enabled |
| based on a NBI call. |
| :param device: A Voltha.Device object. |
| :return: (Deferred) Shall be fired to acknowledge re-enabling the |
| device. |
| """ |
| |
| def reboot_device(device): |
| """ |
| This is called to reboot a device based on a NBI call. The admin |
| state of the device will not change after the reboot |
| :param device: A Voltha.Device object. |
| :return: (Deferred) Shall be fired to acknowledge the reboot. |
| """ |
| |
| def download_image(device, request): |
| """ |
| This is called to request downloading a specified image into |
| the standby partition of a device based on a NBI call. |
| This call is expected to be non-blocking. |
| :param device: A Voltha.Device object. |
| A Voltha.ImageDownload object. |
| :return: (Deferred) Shall be fired to acknowledge the download. |
| """ |
| |
| def get_image_download_status(device, request): |
| """ |
| This is called to inquire about a requested image download |
| status based on a NBI call. |
| The adapter is expected to update the DownloadImage DB object |
| with the query result |
| :param device: A Voltha.Device object. |
| A Voltha.ImageDownload object. |
| :return: (Deferred) Shall be fired to acknowledge |
| """ |
| |
| def cancel_image_download(device, request): |
| """ |
| This is called to cancel a requested image download |
| based on a NBI call. The admin state of the device will not |
| change after the download. |
| :param device: A Voltha.Device object. |
| A Voltha.ImageDownload object. |
| :return: (Deferred) Shall be fired to acknowledge |
| """ |
| |
| def activate_image_update(device, request): |
| """ |
| This is called to activate a downloaded image from |
| a standby partition into active partition. |
| Depending on the device implementation, this call |
| may or may not cause device reboot. |
| If no reboot, then a reboot is required to make the |
| activated image running on device |
| This call is expected to be non-blocking. |
| :param device: A Voltha.Device object. |
| A Voltha.ImageDownload object. |
| :return: (Deferred) OperationResponse object. |
| """ |
| |
| def revert_image_update(device, request): |
| """ |
| This is called to deactivate the specified image at |
| active partition, and revert to previous image at |
| standby partition. |
| Depending on the device implementation, this call |
| may or may not cause device reboot. |
| If no reboot, then a reboot is required to make the |
| previous image running on device |
| This call is expected to be non-blocking. |
| :param device: A Voltha.Device object. |
| A Voltha.ImageDownload object. |
| :return: (Deferred) OperationResponse object. |
| """ |
| |
| def self_test_device(device): |
| """ |
| This is called to Self a device based on a NBI call. |
| :param device: A Voltha.Device object. |
| :return: Will return result of self test |
| """ |
| |
| def delete_device(device): |
| """ |
| This is called to delete a device from the PON based on a NBI call. |
| If the device is an OLT then the whole PON will be deleted. |
| :param device: A Voltha.Device object. |
| :return: (Deferred) Shall be fired to acknowledge the deletion. |
| """ |
| |
| def get_device_details(device): |
| """ |
| This is called to get additional device details based on a NBI call. |
| :param device: A Voltha.Device object. |
| :return: (Deferred) Shall be fired to acknowledge the retrieval of |
| additional details. |
| """ |
| |
| def update_flows_bulk(device, flows, groups): |
| """ |
| Called after any flow table change, but only if the device supports |
| bulk mode, which is expressed by the 'accepts_bulk_flow_update' |
| capability attribute of the device type. |
| :param device: A Voltha.Device object. |
| :param flows: An openflow_v13.Flows object |
| :param groups: An openflow_v13.Flows object |
| :return: (Deferred or None) |
| """ |
| |
| def update_flows_incrementally(device, flow_changes, group_changes): |
| """ |
| Called after a flow table update, but only if the device supports |
| non-bulk mode, which is expressed by the 'accepts_add_remove_flow_updates' |
| capability attribute of the device type. |
| :param device: A Voltha.Device object. |
| :param flow_changes: An openflow_v13.FlowChanges object |
| :param group_changes: An openflow_v13.FlowGroupChanges object |
| :return: (Deferred or None) |
| """ |
| |
| def update_pm_config(device, pm_configs): |
| """ |
| Called every time a request is made to change pm collection behavior |
| :param device: A Voltha.Device object |
| :param pm_collection_config: A Pms |
| """ |
| |
| def receive_packet_out(device_id, egress_port_no, msg): |
| """ |
| Pass a packet_out message content to adapter so that it can forward |
| it out to the device. This is only called on root devices. |
| :param device_id: device ID |
| :param egress_port: egress logical port number |
| :param msg: actual message |
| :return: None |
| """ |
| |
| def suppress_alarm(filter): |
| """ |
| Inform an adapter that all incoming alarms should be suppressed |
| :param filter: A Voltha.AlarmFilter object. |
| :return: (Deferred) Shall be fired to acknowledge the suppression. |
| """ |
| |
| def unsuppress_alarm(filter): |
| """ |
| Inform an adapter that all incoming alarms should resume |
| :param filter: A Voltha.AlarmFilter object. |
| :return: (Deferred) Shall be fired to acknowledge the unsuppression. |
| """ |
| |
| def get_ofp_device_info(device): |
| """ |
| Retrieve the OLT device info. This includes the ofp_desc and |
| ofp_switch_features. The existing ofp structures can be used, |
| or all the attributes get added to the Device definition or a new proto |
| definition gets created. This API will allow the Core to create a |
| LogicalDevice associated with this device (OLT only). |
| :param device: device |
| :return: Proto Message (TBD) |
| """ |
| |
| def get_ofp_port_info(device, port_no): |
| """ |
| Retrieve the port info. This includes the ofp_port. The existing ofp |
| structure can be used, or all the attributes get added to the Port |
| definitions or a new proto definition gets created. This API will allow |
| the Core to create a LogicalPort associated with this device. |
| :param device: device |
| :param port_no: port number |
| :return: Proto Message (TBD) |
| """ |
| |
| # def start(): |
| # """ |
| # Called once after adapter instance is laoded. Can be used to async |
| # initialization. |
| # :return: (None or Deferred) |
| # """ |
| # |
| # def stop(): |
| # """ |
| # Called once before adapter is unloaded. It can be used to perform |
| # any cleanup after the adapter. |
| # :return: (None or Deferred) |
| # """ |
| # |
| # def receive_inter_adapter_message(msg): |
| # """ |
| # Called when the adapter recieves a message that was sent to it directly |
| # from another adapter. An adapter may register for these messages by calling |
| # the register_for_inter_adapter_messages() method in the adapter agent. |
| # Note that it is the responsibility of the sending and receiving |
| # adapters to properly encode and decode the message. |
| # :param msg: The message contents. |
| # :return: None |
| # """ |
| # |
| # def send_proxied_message(proxy_address, msg): |
| # """ |
| # Forward a msg to a child device of device, addressed by the given |
| # proxy_address=Device.ProxyAddress(). |
| # :param proxy_address: Address info for the parent device |
| # to route the message to the child device. This was given to the |
| # child device by the parent device at the creation of the child |
| # device. |
| # :param msg: (str) The actual message to send. |
| # :return: (Deferred(None) or None) The return of this method should |
| # indicate that the message was successfully *sent*. |
| # """ |
| # |
| # def receive_proxied_message(proxy_address, msg): |
| # """ |
| # Pass an async message (arrived via a proxy) to this device. |
| # :param proxy_address: Address info for the parent device |
| # to route the message to the child device. This was given to the |
| # child device by the parent device at the creation of the child |
| # device. Note this is the proxy_address with which the adapter |
| # had to register prior to receiving proxied messages. |
| # :param msg: (str) The actual message received. |
| # :return: None |
| # """ |
| # |
| # def receive_packet_out(logical_device_id, egress_port_no, msg): |
| # """ |
| # Pass a packet_out message content to adapter so that it can forward it |
| # out to the device. This is only called on root devices. |
| # :param logical_device_id: |
| # :param egress_port: egress logical port number |
| # :param msg: actual message |
| # :return: None |
| # """ |
| # |
| # def change_master_state(master): |
| # """ |
| # Called to indicate if plugin shall assume or lose master role. The |
| # master role can be used to perform functions that must be performed |
| # from a single point in the cluster. In single-node deployments of |
| # Voltha, the plugins are always in master role. |
| # :param master: (bool) True to indicate the mastership needs to be |
| # assumed; False to indicate that mastership needs to be abandoned. |
| # :return: (Deferred) which is fired by the adapter when mastership is |
| # assumed/dropped, respectively. |
| # """ |
| |
| |
| # class IAdapterAgent(Interface): |
| # """ |
| # This object is passed in to the __init__ function of each adapter, |
| # and can be used by the adapter implementation to initiate async calls |
| # toward Voltha's CORE via the APIs defined here. |
| # """ |
| # |
| # def get_device(device_id): |
| # # TODO add doc |
| # """""" |
| # |
| # def add_device(device): |
| # # TODO add doc |
| # """""" |
| # |
| # def update_device(device): |
| # # TODO add doc |
| # """""" |
| # |
| # def add_port(device_id, port): |
| # # TODO add doc |
| # """""" |
| # |
| # def create_logical_device(logical_device): |
| # # TODO add doc |
| # """""" |
| # |
| # def add_logical_port(logical_device_id, port): |
| # # TODO add doc |
| # """""" |
| # |
| # def child_device_detected(parent_device_id, |
| # parent_port_no, |
| # child_device_type, |
| # proxy_address, |
| # admin_state, |
| # **kw): |
| # # TODO add doc |
| # """""" |
| # |
| # def send_proxied_message(proxy_address, msg): |
| # """ |
| # Forward a msg to a child device of device, addressed by the given |
| # proxy_address=Device.ProxyAddress(). |
| # :param proxy_address: Address info for the parent device |
| # to route the message to the child device. This was given to the |
| # child device by the parent device at the creation of the child |
| # device. |
| # :param msg: (str) The actual message to send. |
| # :return: (Deferred(None) or None) The return of this method should |
| # indicate that the message was successfully *sent*. |
| # """ |
| # |
| # def receive_proxied_message(proxy_address, msg): |
| # """ |
| # Pass an async message (arrived via a proxy) to this device. |
| # :param proxy_address: Address info for the parent device |
| # to route the message to the child device. This was given to the |
| # child device by the parent device at the creation of the child |
| # device. Note this is the proxy_address with which the adapter |
| # had to register prior to receiving proxied messages. |
| # :param msg: (str) The actual message received. |
| # :return: None |
| # """ |
| # |
| # def register_for_proxied_messages(proxy_address): |
| # """ |
| # A child device adapter can use this to indicate its intent to |
| # receive async messages sent via a parent device. Example: an |
| # ONU adapter can use this to register for OMCI messages received |
| # via the OLT and the OLT adapter. |
| # :param child_device_address: Address info that was given to the |
| # child device by the parent device at the creation of the child |
| # device. Its uniqueness acts as a router information for the |
| # registration. |
| # :return: None |
| # """ |
| # |
| # def unregister_for_proxied_messages(proxy_address): |
| # """ |
| # Cancel a previous registration |
| # :return: |
| # """ |
| # |
| # def send_packet_in(logical_device_id, logical_port_no, packet): |
| # """ |
| # Forward given packet to the northbound toward an SDN controller. |
| # :param device_id: logical device identifier |
| # :param logical_port_no: logical port_no (as numbered in openflow) |
| # :param packet: the actual packet; can be a serialized string or a scapy |
| # Packet. |
| # :return: None returned on success |
| # """ |
| # |
| # def submit_kpis(kpi_event_msg): |
| # """ |
| # Submit KPI metrics on behalf of the OLT and its adapter. This can |
| # include hardware related metrics, usage and utilization metrics, as |
| # well as optional adapter specific metrics. |
| # :param kpi_event_msg: A protobuf message of KpiEvent type. |
| # :return: None |
| # """ |
| # |
| # def submit_alarm(device_id, alarm_event_msg): |
| # """ |
| # Submit an alarm on behalf of the OLT and its adapter. |
| # :param alarm_event_msg: A protobuf message of AlarmEvent type. |
| # :return: None |
| # """ |
| # |
| # def register_for_onu_detect_state(proxy_address): |
| # """ |
| # |
| # :return: None |
| # """ |
| # |
| # def unregister_for_onu_detect_state(proxy_address): |
| # """ |
| # |
| # :return: None |
| # """ |
| # |
| # def forward_onu_detect_state(proxy_address, state): |
| # """ |
| # Forward onu detect state to ONU adapter |
| # :param proxy_address: ONU device address |
| # :param state: ONU detect state (bool) |
| # :return: None |
| # """ |
| |
| class ICoreSouthBoundInterface(Interface): |
| """ |
| Represents a Voltha Core. This is used by an adapter to initiate async |
| calls towards Voltha Core. |
| """ |
| |
| def get_device(device_id): |
| """ |
| Retrieve a device using its ID. |
| :param device_id: a device ID |
| :return: Device Object or None |
| """ |
| |
| def get_child_device(parent_device_id, **kwargs): |
| """ |
| Retrieve a child device object belonging to the specified parent |
| device based on some match criteria. The first child device that |
| matches the provided criteria is returned. |
| :param parent_device_id: parent's device protobuf ID |
| :param **kwargs: arbitrary list of match criteria where the Value |
| in each key-value pair must be a protobuf type |
| :return: Child Device Object or None |
| """ |
| |
| def get_ports(device_id, port_type): |
| """ |
| Retrieve all the ports of a given type of a Device. |
| :param device_id: a device ID |
| :param port_type: type of port |
| :return Ports object |
| """ |
| |
| def get_child_devices(parent_device_id): |
| """ |
| Get all child devices given a parent device id |
| :param parent_device_id: The parent device ID |
| :return: Devices object |
| """ |
| |
| def get_child_device_with_proxy_address(proxy_address): |
| """ |
| Get a child device based on its proxy address. Proxy address is |
| defined as {parent id, channel_id} |
| :param proxy_address: A Device.ProxyAddress object |
| :return: Device object or None |
| """ |
| |
| def device_state_update(device_id, |
| oper_status=None, |
| connect_status=None): |
| """ |
| Update a device state. |
| :param device_id: The device ID |
| :param oper_state: Operational state of device |
| :param conn_state: Connection state of device |
| :return: None |
| """ |
| |
| |
| def child_device_detected(parent_device_id, |
| parent_port_no, |
| child_device_type, |
| channel_id, |
| **kw): |
| """ |
| A child device has been detected. Core will create the device along |
| with its unique ID. |
| :param parent_device_id: The parent device ID |
| :param parent_port_no: The parent port number |
| :param device_type: The child device type |
| :param channel_id: A unique identifier for that child device within |
| the parent device (e.g. vlan_id) |
| :param kw: A list of key-value pair where the value is a protobuf |
| message |
| :return: None |
| """ |
| |
| def device_update(device): |
| """ |
| Event corresponding to a device update. |
| :param device: Device Object |
| :return: None |
| """ |
| |
| def child_device_removed(parent_device_id, child_device_id): |
| """ |
| Event indicating a child device has been removed from a parent. |
| :param parent_device_id: Device ID of the parent |
| :param child_device_id: Device ID of the child |
| :return: None |
| """ |
| |
| def child_devices_state_update(parent_device_id, |
| oper_status=None, |
| connect_status=None, |
| admin_status=None): |
| """ |
| Event indicating the status of all child devices have been changed. |
| :param parent_device_id: Device ID of the parent |
| :param oper_status: Operational status |
| :param connect_status: Connection status |
| :param admin_status: Admin status |
| :return: None |
| """ |
| |
| def child_devices_removed(parent_device_id): |
| """ |
| Event indicating all child devices have been removed from a parent. |
| :param parent_device_id: Device ID of the parent device |
| :return: None |
| """ |
| |
| def device_pm_config_update(device_pm_config, init=False): |
| """ |
| Event corresponding to a PM config update of a device. |
| :param device_pm_config: a PmConfigs object |
| :param init: True indicates initializing stage |
| :return: None |
| """ |
| |
| def port_created(device_id, port): |
| """ |
| A port has been created and needs to be added to a device. |
| :param device_id: a device ID |
| :param port: Port object |
| :return None |
| """ |
| |
| def port_removed(device_id, port): |
| """ |
| A port has been removed and it needs to be removed from a Device. |
| :param device_id: a device ID |
| :param port: a Port object |
| :return None |
| """ |
| |
| def ports_enabled(device_id): |
| """ |
| All ports on that device have been re-enabled. The Core will change |
| the admin state to ENABLED and operational state to ACTIVE for all |
| ports on that device. |
| :param device_id: a device ID |
| :return: None |
| """ |
| |
| def ports_disabled(device_id): |
| """ |
| All ports on that device have been disabled. The Core will change the |
| admin status to DISABLED and operational state to UNKNOWN for all |
| ports on that device. |
| :param device_id: a device ID |
| :return: None |
| """ |
| |
| def ports_oper_status_update(device_id, oper_status): |
| """ |
| The operational status of all ports of a Device has been changed. |
| The Core will update the operational status for all ports on the |
| device. |
| :param device_id: a device ID |
| :param oper_status: operational Status |
| :return None |
| """ |
| |
| def image_download_update(img_dnld): |
| """ |
| Event corresponding to an image download update. |
| :param img_dnld: a ImageDownload object |
| :return: None |
| """ |
| |
| def image_download_deleted(img_dnld): |
| """ |
| Event corresponding to the deletion of a downloaded image. The |
| references of this image needs to be removed from the Core. |
| :param img_dnld: a ImageDownload object |
| :return: None |
| """ |
| |
| def packet_in(device_id, egress_port_no, packet): |
| """ |
| Sends a packet to the SDN controller via voltha Core |
| :param device_id: The OLT device ID |
| :param egress_port_no: The port number representing the ONU (cvid) |
| :param packet: The actual packet |
| :return: None |
| """ |
| |
| # def add_device(device): |
| # # TODO add doc |
| # """""" |
| |
| # def update_device(device): |
| # # TODO add doc |
| # """""" |
| |
| # def add_port(device_id, port): |
| # # TODO add doc |
| # """""" |
| |
| # def create_logical_device(logical_device): |
| # # TODO add doc |
| # """""" |
| # |
| # def add_logical_port(logical_device_id, port): |
| # # TODO add doc |
| # """""" |
| |
| # def child_device_detected(parent_device_id, |
| # parent_port_no, |
| # child_device_type, |
| # proxy_address, |
| # admin_state, |
| # **kw): |
| # # TODO add doc |
| # """""" |
| |
| # def send_proxied_message(proxy_address, msg): |
| # """ |
| # Forward a msg to a child device of device, addressed by the given |
| # proxy_address=Device.ProxyAddress(). |
| # :param proxy_address: Address info for the parent device |
| # to route the message to the child device. This was given to the |
| # child device by the parent device at the creation of the child |
| # device. |
| # :param msg: (str) The actual message to send. |
| # :return: (Deferred(None) or None) The return of this method should |
| # indicate that the message was successfully *sent*. |
| # """ |
| # |
| # def receive_proxied_message(proxy_address, msg): |
| # """ |
| # Pass an async message (arrived via a proxy) to this device. |
| # :param proxy_address: Address info for the parent device |
| # to route the message to the child device. This was given to the |
| # child device by the parent device at the creation of the child |
| # device. Note this is the proxy_address with which the adapter |
| # had to register prior to receiving proxied messages. |
| # :param msg: (str) The actual message received. |
| # :return: None |
| # """ |
| # |
| # def register_for_proxied_messages(proxy_address): |
| # """ |
| # A child device adapter can use this to indicate its intent to |
| # receive async messages sent via a parent device. Example: an |
| # ONU adapter can use this to register for OMCI messages received |
| # via the OLT and the OLT adapter. |
| # :param child_device_address: Address info that was given to the |
| # child device by the parent device at the creation of the child |
| # device. Its uniqueness acts as a router information for the |
| # registration. |
| # :return: None |
| # """ |
| # |
| # def unregister_for_proxied_messages(proxy_address): |
| # """ |
| # Cancel a previous registration |
| # :return: |
| # """ |
| # |
| # def submit_kpis(kpi_event_msg): |
| # """ |
| # Submit KPI metrics on behalf of the OLT and its adapter. This can |
| # include hardware related metrics, usage and utilization metrics, as |
| # well as optional adapter specific metrics. |
| # :param kpi_event_msg: A protobuf message of KpiEvent type. |
| # :return: None |
| # """ |
| # |
| # def submit_alarm(device_id, alarm_event_msg): |
| # """ |
| # Submit an alarm on behalf of the OLT and its adapter. |
| # :param alarm_event_msg: A protobuf message of AlarmEvent type. |
| # :return: None |
| # """ |
| |
| # def register_for_onu_detect_state(proxy_address): |
| # """ |
| # |
| # :return: None |
| # """ |
| # |
| # def unregister_for_onu_detect_state(proxy_address): |
| # """ |
| # |
| # :return: None |
| # """ |
| # |
| # def forward_onu_detect_state(proxy_address, state): |
| # """ |
| # Forward onu detect state to ONU adapter |
| # :param proxy_address: ONU device address |
| # :param state: ONU detect state (bool) |
| # :return: None |
| # """ |
| # |
| # def send_packet_in(logical_device_id, logical_port_no, packet): |
| # """ |
| # Forward given packet to the northbound toward an SDN controller. |
| # :param device_id: logical device identifier |
| # :param logical_port_no: logical port_no (as numbered in openflow) |
| # :param packet: the actual packet; can be a serialized string or a |
| # scapy Packet. |
| # :return: None returned on success |
| # """ |