Zsolt Haraszti | 7eeb2b3 | 2016-11-06 14:04:55 -0800 | [diff] [blame] | 1 | # |
Zsolt Haraszti | 3eb27a5 | 2017-01-03 21:56:48 -0800 | [diff] [blame^] | 2 | # Copyright 2017 the original author or authors. |
Zsolt Haraszti | 7eeb2b3 | 2016-11-06 14:04:55 -0800 | [diff] [blame] | 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 | """ |
| 20 | from zope.interface import Interface |
| 21 | |
| 22 | |
| 23 | class IAdapterInterface(Interface): |
| 24 | """ |
| 25 | A Voltha adapter |
| 26 | """ |
| 27 | |
| 28 | def start(): |
| 29 | """ |
| 30 | Called once after adapter instance is laoded. Can be used to async |
| 31 | initialization. |
| 32 | :return: (None or Deferred) |
| 33 | """ |
| 34 | |
| 35 | def stop(): |
| 36 | """ |
| 37 | Called once before adapter is unloaded. It can be used to perform |
| 38 | any cleanup after the adapter. |
| 39 | :return: (None or Deferred) |
| 40 | """ |
| 41 | |
| 42 | def adapter_descriptor(): |
| 43 | """ |
| 44 | Return the adapter descriptor object for this adapter. |
| 45 | :return: voltha.Adapter grpc object (see voltha/protos/adapter.proto), |
| 46 | with adapter-specific information and config extensions. |
| 47 | """ |
| 48 | |
| 49 | def device_types(): |
| 50 | """ |
| 51 | Return list of device types supported by the adapter. |
| 52 | :return: voltha.DeviceTypes protobuf object, with optional type |
| 53 | specific extensions. |
| 54 | """ |
| 55 | |
| 56 | def health(): |
| 57 | """ |
| 58 | Return a 3-state health status using the voltha.HealthStatus message. |
| 59 | :return: Deferred or direct return with voltha.HealthStatus message |
| 60 | """ |
| 61 | |
| 62 | def change_master_state(master): |
| 63 | """ |
| 64 | Called to indicate if plugin shall assume or lose master role. The |
| 65 | master role can be used to perform functions that must be performed |
| 66 | from a single point in the cluster. In single-node deployments of |
| 67 | Voltha, the plugins are always in master role. |
| 68 | :param master: (bool) True to indicate the mastership needs to be |
| 69 | assumed; False to indicate that mastership needs to be abandoned. |
| 70 | :return: (Deferred) which is fired by the adapter when mastership is |
| 71 | assumed/dropped, respectively. |
| 72 | """ |
| 73 | |
| 74 | def adopt_device(device): |
| 75 | """ |
| 76 | Make sure the adapter looks after given device. Called when a device |
| 77 | is provisioned top-down and needs to be activated by the adapter. |
| 78 | :param device: A voltha.Device object, with possible device-type |
| 79 | specific extensions. Such extensions shall be described as part of |
| 80 | the device type specification returned by device_types(). |
| 81 | :return: (Deferred) Shall be fired to acknowledge device ownership. |
| 82 | """ |
| 83 | |
| 84 | def abandon_device(device): |
| 85 | """ |
| 86 | Make sur ethe adapter no longer looks after device. This is called |
| 87 | if device ownership is taken over by another Voltha instance. |
| 88 | :param device: A Voltha.Device object. |
| 89 | :return: (Deferred) Shall be fired to acknowledge abandonment. |
| 90 | """ |
| 91 | |
| 92 | def deactivate_device(device): |
| 93 | """ |
| 94 | Called if the device is to be deactivate based on a NBI call. |
Zsolt Haraszti | c5c5d10 | 2016-12-07 21:12:27 -0800 | [diff] [blame] | 95 | :param device: A Voltha.Device object. |
Zsolt Haraszti | 7eeb2b3 | 2016-11-06 14:04:55 -0800 | [diff] [blame] | 96 | :return: (Deferred) Shall be fired to acknowledge deactivation. |
| 97 | """ |
| 98 | |
Zsolt Haraszti | c5c5d10 | 2016-12-07 21:12:27 -0800 | [diff] [blame] | 99 | def update_flows_bulk(device, flows, groups): |
| 100 | """ |
| 101 | Called after any flow table change, but only if the device supports |
| 102 | bulk mode, which is expressed by the 'accepts_bulk_flow_update' |
| 103 | capability attribute of the device type. |
| 104 | :param device: A Voltha.Device object. |
| 105 | :param flows: An openflow_v13.Flows object |
| 106 | :param groups: An openflow_v13.Flows object |
| 107 | :return: (Deferred or None) |
| 108 | """ |
| 109 | |
| 110 | def update_flows_incrementally(device, flow_changes, group_changes): |
| 111 | """ |
| 112 | [This mode is not supported yet.] |
| 113 | :param device: A Voltha.Device object. |
| 114 | :param flow_changes: |
| 115 | :param group_changes: |
| 116 | :return: |
| 117 | """ |
| 118 | |
| 119 | def send_proxied_message(proxy_address, msg): |
| 120 | """ |
| 121 | Forward a msg to a child device of device, addressed by the given |
| 122 | proxy_address=Device.ProxyAddress(). |
| 123 | :param proxy_address: Address info for the parent device |
| 124 | to route the message to the child device. This was given to the |
| 125 | child device by the parent device at the creation of the child |
| 126 | device. |
| 127 | :param msg: (str) The actual message to send. |
| 128 | :return: (Deferred(None) or None) The return of this method should |
| 129 | indicate that the message was successfully *sent*. |
| 130 | """ |
| 131 | |
| 132 | def receive_proxied_message(proxy_address, msg): |
| 133 | """ |
| 134 | Pass an async message (arrived via a proxy) to this device. |
| 135 | :param proxy_address: Address info for the parent device |
| 136 | to route the message to the child device. This was given to the |
| 137 | child device by the parent device at the creation of the child |
| 138 | device. Note this is the proxy_address with which the adapter |
| 139 | had to register prior to receiving proxied messages. |
| 140 | :param msg: (str) The actual message received. |
| 141 | :return: None |
| 142 | """ |
| 143 | |
Zsolt Haraszti | 656ecc6 | 2016-12-28 15:08:23 -0800 | [diff] [blame] | 144 | def receive_packet_out(logical_device_id, egress_port_no, msg): |
| 145 | """ |
| 146 | Pass a packet_out message content to adapter so that it can forward it |
| 147 | out to the device. This is only called on root devices. |
| 148 | :param logical_device_id: |
| 149 | :param egress_port: egress logical port number |
| 150 | :param msg: actual message |
| 151 | :return: None |
| 152 | """ |
| 153 | |
Zsolt Haraszti | 7eeb2b3 | 2016-11-06 14:04:55 -0800 | [diff] [blame] | 154 | # TODO work in progress |
| 155 | # ... |
Zsolt Haraszti | 00d9a84 | 2016-11-23 11:18:23 -0800 | [diff] [blame] | 156 | |
| 157 | |
Zsolt Haraszti | 6686203 | 2016-11-28 14:28:39 -0800 | [diff] [blame] | 158 | class IAdapterAgent(Interface): |
Zsolt Haraszti | 00d9a84 | 2016-11-23 11:18:23 -0800 | [diff] [blame] | 159 | """ |
| 160 | This object is passed in to the __init__ function of each adapter, |
| 161 | and can be used by the adapter implementation to initiate async calls |
| 162 | toward Voltha's CORE via the APIs defined here. |
| 163 | """ |
| 164 | |
Zsolt Haraszti | c5c5d10 | 2016-12-07 21:12:27 -0800 | [diff] [blame] | 165 | def get_device(device_id): |
Zsolt Haraszti | 6686203 | 2016-11-28 14:28:39 -0800 | [diff] [blame] | 166 | # TODO add doc |
| 167 | """""" |
| 168 | |
| 169 | def add_device(device): |
| 170 | # TODO add doc |
| 171 | """""" |
| 172 | |
| 173 | def update_device(device): |
Zsolt Haraszti | 00d9a84 | 2016-11-23 11:18:23 -0800 | [diff] [blame] | 174 | # TODO add doc |
| 175 | """""" |
| 176 | |
| 177 | def add_port(device_id, port): |
| 178 | # TODO add doc |
| 179 | """""" |
| 180 | |
| 181 | def create_logical_device(logical_device): |
| 182 | # TODO add doc |
| 183 | """""" |
| 184 | |
| 185 | def add_logical_port(logical_device_id, port): |
| 186 | # TODO add doc |
| 187 | """""" |
| 188 | |
Zsolt Haraszti | 6686203 | 2016-11-28 14:28:39 -0800 | [diff] [blame] | 189 | def child_device_detected(parent_device_id, |
Zsolt Haraszti | c5c5d10 | 2016-12-07 21:12:27 -0800 | [diff] [blame] | 190 | parent_port_no, |
Zsolt Haraszti | 6686203 | 2016-11-28 14:28:39 -0800 | [diff] [blame] | 191 | child_device_type, |
Zsolt Haraszti | 89a2730 | 2016-12-08 16:53:06 -0800 | [diff] [blame] | 192 | proxy_address, |
| 193 | **kw): |
Zsolt Haraszti | 6686203 | 2016-11-28 14:28:39 -0800 | [diff] [blame] | 194 | # TODO add doc |
| 195 | """""" |
| 196 | |
Zsolt Haraszti | c5c5d10 | 2016-12-07 21:12:27 -0800 | [diff] [blame] | 197 | def send_proxied_message(proxy_address, msg): |
| 198 | """ |
| 199 | Forward a msg to a child device of device, addressed by the given |
| 200 | proxy_address=Device.ProxyAddress(). |
| 201 | :param proxy_address: Address info for the parent device |
| 202 | to route the message to the child device. This was given to the |
| 203 | child device by the parent device at the creation of the child |
| 204 | device. |
| 205 | :param msg: (str) The actual message to send. |
| 206 | :return: (Deferred(None) or None) The return of this method should |
| 207 | indicate that the message was successfully *sent*. |
| 208 | """ |
| 209 | |
| 210 | def receive_proxied_message(proxy_address, msg): |
| 211 | """ |
| 212 | Pass an async message (arrived via a proxy) to this device. |
| 213 | :param proxy_address: Address info for the parent device |
| 214 | to route the message to the child device. This was given to the |
| 215 | child device by the parent device at the creation of the child |
| 216 | device. Note this is the proxy_address with which the adapter |
| 217 | had to register prior to receiving proxied messages. |
| 218 | :param msg: (str) The actual message received. |
| 219 | :return: None |
| 220 | """ |
| 221 | |
| 222 | def register_for_proxied_messages(proxy_address): |
| 223 | """ |
| 224 | A child device adapter can use this to indicate its intent to |
| 225 | receive async messages sent via a parent device. Example: an |
| 226 | ONU adapter can use this to register for OMCI messages received |
| 227 | via the OLT and the OLT adapter. |
| 228 | :param child_device_address: Address info that was given to the |
| 229 | child device by the parent device at the creation of the child |
| 230 | device. Its uniqueness acts as a router information for the |
| 231 | registration. |
| 232 | :return: None |
| 233 | """ |
| 234 | |
| 235 | def unregister_for_proxied_messages(proxy_address): |
| 236 | """ |
| 237 | Cancel a previous registration |
| 238 | :return: |
| 239 | """ |
Zsolt Haraszti | 00d9a84 | 2016-11-23 11:18:23 -0800 | [diff] [blame] | 240 | |
Zsolt Haraszti | 8925d1f | 2016-12-21 00:45:19 -0800 | [diff] [blame] | 241 | def send_packet_in(logical_device_id, logical_port_no, packet): |
| 242 | """ |
| 243 | Forward given packet to the northbound toward an SDN controller. |
| 244 | :param device_id: logical device identifier |
| 245 | :param logical_port_no: logical port_no (as numbered in openflow) |
| 246 | :param packet: the actual packet; can be a serialized string or a scapy |
| 247 | Packet. |
| 248 | :return: None returned on success |
| 249 | """ |
Zsolt Haraszti | 00d9a84 | 2016-11-23 11:18:23 -0800 | [diff] [blame] | 250 | |