1/*
2 * Copyright (C) 2020 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
17package android.hardware.tetheroffload.control@1.1;
18
19import @1.0::IOffloadControl;
20
21/**
22 * Interface used to control the lifecycle of tethering offload. Note that callbacks of 1.1 HAL
23 * can be registered with the existing callback registration methods from 1.0 HAL.
24 */
25interface IOffloadControl extends @1.0::IOffloadControl {
26    /**
27     * Instruct hardware to send callbacks after certain number of bytes have been transferred in
28     * either direction on this upstream interface.
29     *
30     * The specified quota bytes must be applied to all traffic on the given upstream interface.
31     * This includes hardware forwarded traffic, software forwarded traffic, and AP-originated
32     * traffic. IPv4 and IPv6 traffic both count towards the same quota. IP headers are included
33     * in the byte count quota, but, link-layer headers are not.
34     *
35     * This API may only be called while offload is occurring on this upstream. The hardware
36     * management process MUST NOT store the values when offload is not started and applies once
37     * offload is started. This is because the quota values would likely become stale over
38     * time and would not reflect any new traffic that has occurred.
39     *
40     * This API replaces {@link @1.0::IOffloadControl::setDataLimit}, the framework will always
41     * call setDataWarningAndLimit on 1.1 implementations, and setDataLimit on 1.0 implementations.
42     * Thus, no interaction between the two APIs need to be addressed.
43     *
44     * The specified quota bytes MUST replace any previous quotas set by
45     * {@code setDataWarningAndLimit} specified on the same interface. It may be interpreted as
46     * "tell me when either <warningBytes> or <limitBytes> bytes have been transferred
47     * (in either direction), and stop offload when <limitBytes> bytes have been transferred,
48     * starting now and counting from zero on <upstream>."
49     *
50     * Once the {@code warningBytes} is reached, the callback registered in initOffload must be
51     * called with {@code OFFLOAD_WARNING_REACHED} to indicate this event. Once the event fires
52     * for this upstream, no further {@code OFFLOAD_WARNING_REACHED} event will be fired for this
53     * upstream unless this method is called again with the same interface. Note that there is
54     * no need to call initOffload again to resume offload if stopOffload was not called by the
55     * client.
56     *
57     * Similarly, Once the {@code limitBytes} is reached, the callback registered in initOffload
58     * must be called with {@code OFFLOAD_STOPPED_LIMIT_REACHED} to indicate this event. Once
59     * the event fires for this upstream, no further {@code OFFLOAD_STOPPED_LIMIT_REACHED}
60     * event will be fired for this upstream unless this method is called again with the same
61     * interface. However, unlike {@code warningBytes}, when {@code limitBytes} is reached,
62     * all offload must be stopped. If offload is desired again, the hardware management
63     * process must be completely reprogrammed by calling setUpstreamParameters and
64     * addDownstream again.
65     *
66     * Note that when one of the quota bytes is reached, the other one is still considered valid
67     * unless this method is called again with the same interface.
68     *
69     * @param upstream Upstream interface name that quota must apply to.
70     * @param warningBytes The quota of warning, defined as the number of bytes, starting from
71     *                     zero and counting from now.
72     * @param limitBytes The quota of limit, defined as the number of bytes, starting from zero
73     *                   and counting from now.
74     *
75     * @return success true if quota is applied, false otherwise
76     * @return errMsg a human readable string if error has occurred.
77     */
78    setDataWarningAndLimit(string upstream, uint64_t warningBytes, uint64_t limitBytes)
79        generates (bool success, string errMsg);
80};
81