/* * Copyright (C) 2017 The Android Open Source Project * * 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. */ package android.hardware.tetheroffload.control@1.0; import ITetheringOffloadCallback; /** * Interface used to control the lifecycle of tethering offload */ interface IOffloadControl { /** * Indicates intent to start offload for tethering in immediate future. * * This API must be called exactly once the first time that Tethering is requested by * the user. * * If this API is called multiple times without first calling stopOffload, then the subsequent * calls must fail without changing the state of the server. * * If for some reason, the hardware is currently unable to support offload, this call must fail. * * @param cb Assuming success, this callback must provide unsolicited updates of offload status. * It is assumed to be valid until stopOffload is called. * * @return success true if initialization is successful, false otherwise * @return errMsg a human readable string if eror has occured. * * Remarks: Initializing offload does not imply that any upstreams or downstreams have yet been, * or even will be, chosen. This API is symmetrical with stopOffload. */ @entry @callflow(next={"*"}) initOffload(ITetheringOffloadCallback cb) generates (bool success, string errMsg); /** * Indicate desire to tear down all tethering offload. * * Called after tethering is no longer requested by the user. Any remaining offload must * be subsequently torn down by the management process. Upon success, the callback registered * in initOffload must be released, and offload must be stopped. * * @return success true if offload is stopped, false otherwise * @return errMsg a human readable string if eror has occured. * * Remarks: Statistics must be reset by this API. */ @exit stopOffload() generates (bool success, string errMsg); /** * Instruct management process not to forward traffic destined to or from the specified prefixes. * * This API may only be called after initOffload and before stopOffload. * * @param prefixes List containing fully specified prefixes. For e.g. 192.168.1.12/24 or 2001:4860:0684:0:0:0:0:0:1002/64 * * @return success true if success, false otherwise * @return errMsg a human readable string if eror has occured. * * Remarks: This list overrides any previously specified list */ setLocalPrefixes(vec prefixes) generates (bool success, string errMsg); /** * Query offloaded traffic statistics forwarded to an upstream address. * * Return statistics that have transpired since the last query. This would include * statistics from all offloaded downstream tether interfaces that have been forwarded to this * upstream interface. After returning the statistics, the counters are reset to zero. * * Only offloaded statistics must be returned by this API, software stats must not be * returned. * * @param upstream Upstream interface on which traffic exited/entered * * @return rxBytes values depicting the received bytes * @return txBytes values depicting the transmitted bytes */ getForwardedStats(string upstream) generates (uint64_t rxBytes, uint64_t txBytes); /** * Instruct hardware to stop forwarding traffic and send a callback after limit bytes have been * transferred in either direction on this upstream interface. * * The limit must be applied to all traffic on the given upstream interface. This * includes hardware forwarded traffic, software forwarded traffic, and AP-originated traffic. * IPv4 and IPv6 traffic both count towards the same limit. IP headers are included in the * byte count limit, but, link-layer headers are not. * * This API may only be called while offload is occurring on this upstream. The hardware * management process is not expected to cache the value and apply the quota once offload is * started. This cache is not expected, because the limit value would likely become stale over * time and would not reflect any new traffic that has occurred. * * This limit must replace any previous limit. It may be interpreted as "tell me when * bytes have been transferred (in either direction) on , starting * now and counting from zero." * * Once the limit is reached, the callback registered in initOffload must be called to indicate * this event and all offload must be stopped. If offload is desired again, the hardware * management process must be completely reprogrammed by calling setUpstreamParameters and * addDownstream again. Note that it is not necessary to call initOffload again to resume offload * if stopOffload was not called by the client. * * @param upstream Upstream interface name that limit must apply to * @param limit Bytes limit that can occur before action must be taken * * @return success true if limit is applied, false otherwise * @return errMsg a human readable string if eror has occured. */ setDataLimit(string upstream, uint64_t limit) generates (bool success, string errMsg); /** * Instruct hardware to start forwarding traffic to the specified upstream. * * When iface, v4Addr, and v4Gw are all non-null, the management process may begin forwarding * any currently configured or future configured IPv4 downstreams to this upstream interface. * * If any of the previously three mentioned parameters are null, then any current IPv4 offload * must be stopped. * * When iface and v6Gws are both non-null, and in the case of v6Gws, are not empty, the * management process may begin forwarding any currently configured or future configured IPv6 * downstreams to this upstream interface. * * If either of the two above parameters are null, or no V6 Gateways are provided, then IPv6 * offload must be stopped. * * This API may only be called after initOffload and before stopOffload. * * @param iface Upstream interface name. Note that only one is needed because IPv4 and IPv6 * interfaces cannot be different (only known that this can occur during software * xlat, which cannot be offloaded through hardware anyways). If the iface is * null, offload must be stopped. * @param v4Addr The local IPv4 address assigned to the provided upstream interface, i.e. the * IPv4 address the packets are NATed to. For e.g. 192.168.1.12. * @param v4Gw The IPv4 address of the IPv4 gateway on the upstream interface. * For e.g. 192.168.1.1 * @param v6Gws A list of IPv6 addresses (for e.g. 2001:4860:0684:0:0:0:0:0:1002) for possible * IPv6 gateways on the upstream interface. * * @return success true if success, false otherwise * @return errMsg a human readable string if eror has occured. * * Remarks: This overrides any previously configured parameters. */ setUpstreamParameters(string iface, string v4Addr, string v4Gw, vec v6Gws) generates (bool success, string errMsg); /** * Configure a downstream interface and prefix in the hardware management process that may be * forwarded. * * The prefix may be an IPv4 or an IPv6 address to signify which family can be offloaded from the * specified tether interface. The list of IPv4 and IPv6 downstreams that are configured may * differ. * * If the given protocol, as determined by the prefix, has an upstream set, * the hardware may begin forwarding traffic between the upstream and any devices on the * downstream interface that have IP addresses within the specified prefix. Traffic from the same * downstream interfaces is unaffected and must be forwarded if and only if it was already * being forwarded. * * If no upstream is currently configured, then these downstream interface and prefixes must be * preserved so that offload may begin in the future when an upstream is set. * * This API does not replace any previously configured downstreams and must be explictly removed * by calling removeDownstream. * * This API may only be called after initOffload and before stopOffload. * * @param iface Tether interface * @param prefix Downstream prefix depicting addresses that may be offloaded. * For e.g. 192.168.1.12/24 or 2001:4860:0684::/64) * * @return success true if success, false otherwise * @return errMsg a human readable string if eror has occured. * * Remarks: The hardware management process may fail this call in a normal situation. This can * happen because the hardware cannot support the current number of prefixes, the * hardware cannot support concurrent offload on multiple interfaces, the hardware * cannot currently support offload on the tether interface for some reason, or any * other dynamic configuration issues which may occur. In this case, * traffic must remain unaffected and must be forwarded if and only if it was already * being forwarded. */ addDownstream(string iface, string prefix) generates (bool success, string errMsg); /** * Remove a downstream prefix that may be forwarded from the hardware management process. * * The prefix may be an IPv4 or an IPv6 address. If it was not previously configured using * addDownstream, then this must be a no-op. * * This API may only be called after initOffload and before stopOffload. * * @param iface Tether interface * @param prefix Downstream prefix depicting address that must no longer be offloaded * For e.g. 192.168.1.12/24 or 2001:4860:0684::/64) * * @return success true if success, false otherwise * @return errMsg a human readable string if eror has occured. */ removeDownstream(string iface, string prefix) generates (bool success, string errMsg); };