1 /* 2 * Copyright (C) 2017 The Android Open Source Project 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 package android.hardware.tetheroffload.control@1.0; 18 19 import ITetheringOffloadCallback; 20 21 22 /** 23 * Interface used to control the lifecycle of tethering offload 24 */ 25 interface IOffloadControl { 26 /** 27 * Indicates intent to start offload for tethering in immediate future. 28 * 29 * This API must be called exactly once the first time that Tethering is requested by 30 * the user. 31 * 32 * If this API is called multiple times without first calling stopOffload, then the subsequent 33 * calls must fail without changing the state of the server. 34 * 35 * If for some reason, the hardware is currently unable to support offload, this call must fail. 36 * 37 * @param cb Assuming success, this callback must provide unsolicited updates of offload status. 38 * It is assumed to be valid until stopOffload is called. 39 * 40 * @return success true if initialization is successful, false otherwise 41 * @return errMsg a human readable string if eror has occured. 42 * 43 * Remarks: Initializing offload does not imply that any upstreams or downstreams have yet been, 44 * or even will be, chosen. This API is symmetrical with stopOffload. 45 */ 46 @entry 47 @callflow(next={"*"}) 48 initOffload(ITetheringOffloadCallback cb) generates (bool success, string errMsg); 49 50 /** 51 * Indicate desire to tear down all tethering offload. 52 * 53 * Called after tethering is no longer requested by the user. Any remaining offload must 54 * be subsequently torn down by the management process. Upon success, the callback registered 55 * in initOffload must be released, and offload must be stopped. 56 * 57 * @return success true if offload is stopped, false otherwise 58 * @return errMsg a human readable string if eror has occured. 59 * 60 * Remarks: Statistics must be reset by this API. 61 */ 62 @exit 63 stopOffload() generates (bool success, string errMsg); 64 65 /** 66 * Instruct management process not to forward traffic destined to or from the specified prefixes. 67 * 68 * This API may only be called after initOffload and before stopOffload. 69 * 70 * @param prefixes List containing fully specified prefixes. For e.g. 192.168.1.12/24 71 or 2001:4860:0684:0:0:0:0:0:1002/64 72 * 73 * @return success true if success, false otherwise 74 * @return errMsg a human readable string if eror has occured. 75 * 76 * Remarks: This list overrides any previously specified list 77 */ 78 setLocalPrefixes(vec<string> prefixes) generates (bool success, string errMsg); 79 80 /** 81 * Query offloaded traffic statistics forwarded to an upstream address. 82 * 83 * Return statistics that have transpired since the last query. This would include 84 * statistics from all offloaded downstream tether interfaces that have been forwarded to this 85 * upstream interface. After returning the statistics, the counters are reset to zero. 86 * 87 * Only offloaded statistics must be returned by this API, software stats must not be 88 * returned. 89 * 90 * @param upstream Upstream interface on which traffic exited/entered 91 * 92 * @return rxBytes values depicting the received bytes 93 * @return txBytes values depicting the transmitted bytes 94 */ 95 getForwardedStats(string upstream) generates (uint64_t rxBytes, uint64_t txBytes); 96 97 /** 98 * Instruct hardware to stop forwarding traffic and send a callback after limit bytes have been 99 * transferred in either direction on this upstream interface. 100 * 101 * The limit must be applied to all traffic on the given upstream interface. This 102 * includes hardware forwarded traffic, software forwarded traffic, and AP-originated traffic. 103 * IPv4 and IPv6 traffic both count towards the same limit. IP headers are included in the 104 * byte count limit, but, link-layer headers are not. 105 * 106 * This API may only be called while offload is occurring on this upstream. The hardware 107 * management process is not expected to cache the value and apply the quota once offload is 108 * started. This cache is not expected, because the limit value would likely become stale over 109 * time and would not reflect any new traffic that has occurred. 110 * 111 * This limit must replace any previous limit. It may be interpreted as "tell me when 112 * <limit> bytes have been transferred (in either direction) on <upstream>, starting 113 * now and counting from zero." 114 * 115 * Once the limit is reached, the callback registered in initOffload must be called to indicate 116 * this event and all offload must be stopped. If offload is desired again, the hardware 117 * management process must be completely reprogrammed by calling setUpstreamParameters and 118 * addDownstream again. Note that it is not necessary to call initOffload again to resume offload 119 * if stopOffload was not called by the client. 120 * 121 * @param upstream Upstream interface name that limit must apply to 122 * @param limit Bytes limit that can occur before action must be taken 123 * 124 * @return success true if limit is applied, false otherwise 125 * @return errMsg a human readable string if eror has occured. 126 */ 127 setDataLimit(string upstream, uint64_t limit) generates (bool success, string errMsg); 128 129 /** 130 * Instruct hardware to start forwarding traffic to the specified upstream. 131 * 132 * When iface, v4Addr, and v4Gw are all non-null, the management process may begin forwarding 133 * any currently configured or future configured IPv4 downstreams to this upstream interface. 134 * 135 * If any of the previously three mentioned parameters are null, then any current IPv4 offload 136 * must be stopped. 137 * 138 * When iface and v6Gws are both non-null, and in the case of v6Gws, are not empty, the 139 * management process may begin forwarding any currently configured or future configured IPv6 140 * downstreams to this upstream interface. 141 * 142 * If either of the two above parameters are null, or no V6 Gateways are provided, then IPv6 143 * offload must be stopped. 144 * 145 * This API may only be called after initOffload and before stopOffload. 146 * 147 * @param iface Upstream interface name. Note that only one is needed because IPv4 and IPv6 148 * interfaces cannot be different (only known that this can occur during software 149 * xlat, which cannot be offloaded through hardware anyways). If the iface is 150 * null, offload must be stopped. 151 * @param v4Addr The local IPv4 address assigned to the provided upstream interface, i.e. the 152 * IPv4 address the packets are NATed to. For e.g. 192.168.1.12. 153 * @param v4Gw The IPv4 address of the IPv4 gateway on the upstream interface. 154 * For e.g. 192.168.1.1 155 * @param v6Gws A list of IPv6 addresses (for e.g. 2001:4860:0684:0:0:0:0:0:1002) for possible 156 * IPv6 gateways on the upstream interface. 157 * 158 * @return success true if success, false otherwise 159 * @return errMsg a human readable string if eror has occured. 160 * 161 * Remarks: This overrides any previously configured parameters. 162 */ 163 setUpstreamParameters(string iface, string v4Addr, string v4Gw, vec<string> v6Gws) 164 generates (bool success, string errMsg); 165 166 /** 167 * Configure a downstream interface and prefix in the hardware management process that may be 168 * forwarded. 169 * 170 * The prefix may be an IPv4 or an IPv6 address to signify which family can be offloaded from the 171 * specified tether interface. The list of IPv4 and IPv6 downstreams that are configured may 172 * differ. 173 * 174 * If the given protocol, as determined by the prefix, has an upstream set, 175 * the hardware may begin forwarding traffic between the upstream and any devices on the 176 * downstream interface that have IP addresses within the specified prefix. Traffic from the same 177 * downstream interfaces is unaffected and must be forwarded if and only if it was already 178 * being forwarded. 179 * 180 * If no upstream is currently configured, then these downstream interface and prefixes must be 181 * preserved so that offload may begin in the future when an upstream is set. 182 * 183 * This API does not replace any previously configured downstreams and must be explictly removed 184 * by calling removeDownstream. 185 * 186 * This API may only be called after initOffload and before stopOffload. 187 * 188 * @param iface Tether interface 189 * @param prefix Downstream prefix depicting addresses that may be offloaded. 190 * For e.g. 192.168.1.12/24 or 2001:4860:0684::/64) 191 * 192 * @return success true if success, false otherwise 193 * @return errMsg a human readable string if eror has occured. 194 * 195 * Remarks: The hardware management process may fail this call in a normal situation. This can 196 * happen because the hardware cannot support the current number of prefixes, the 197 * hardware cannot support concurrent offload on multiple interfaces, the hardware 198 * cannot currently support offload on the tether interface for some reason, or any 199 * other dynamic configuration issues which may occur. In this case, 200 * traffic must remain unaffected and must be forwarded if and only if it was already 201 * being forwarded. 202 */ 203 addDownstream(string iface, string prefix) generates (bool success, string errMsg); 204 205 /** 206 * Remove a downstream prefix that may be forwarded from the hardware management process. 207 * 208 * The prefix may be an IPv4 or an IPv6 address. If it was not previously configured using 209 * addDownstream, then this must be a no-op. 210 * 211 * This API may only be called after initOffload and before stopOffload. 212 * 213 * @param iface Tether interface 214 * @param prefix Downstream prefix depicting address that must no longer be offloaded 215 * For e.g. 192.168.1.12/24 or 2001:4860:0684::/64) 216 * 217 * @return success true if success, false otherwise 218 * @return errMsg a human readable string if eror has occured. 219 */ 220 removeDownstream(string iface, string prefix) generates (bool success, string errMsg); 221 }; 222
