1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
/*
* 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<string> 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
* <limit> bytes have been transferred (in either direction) on <upstream>, 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<string> 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);
};
|
