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.dumpstate@1.1;
18
19import @1.0::IDumpstateDevice;
20
21interface IDumpstateDevice extends @1.0::IDumpstateDevice {
22    /**
23     * Extension of dumpstateBoard which also accepts a mode parameter to limit dumped data.
24     *
25     * For an example of when this is relevant, consider a bug report being generated with
26     * DumpstateMode::CONNECTIVITY - there is no reason to include camera or USB logs in this type
27     * of report.
28     *
29     * The 1.0 version of #dumpstateBoard(handle) should just delegate to this new method and pass
30     * DumpstateMode::DEFAULT and a timeout of 30,000ms (30 seconds).
31     *
32     * This method may still be called by the dumpstate routine even if getVerboseLoggingEnabled
33     * returns false. In this case, it may include essential information but must not include
34     * information that identifies the user.
35     *
36     * @param h A native handle with one or two valid file descriptors. The first FD is for text
37     *     output, the second (if present) is for binary output.
38     * @param mode A mode value to restrict dumped content.
39     * @param timeoutMillis An approximate "budget" for how much time this call has been allotted.
40     *     If execution runs longer than this, the IDumpstateDevice service may be killed and only
41     *     partial information will be included in the report.
42     * @return status A DumpstateStatus value indicating the final result.
43     */
44    dumpstateBoard_1_1(handle h, DumpstateMode mode, uint64_t timeoutMillis)
45        generates (DumpstateStatus status);
46
47    /**
48     * Turns verbose device vendor logging on or off.
49     *
50     * The setting should be persistent across reboots. Underlying implementations may need to start
51     * vendor logging daemons, set system properties, or change logging masks, for example. Given
52     * that many vendor logs contain significant amounts of private information and may come with
53     * memory/storage/battery impacts, calling this method on a user build should only be done after
54     * user consent has been obtained, e.g. from a toggle in developer settings.
55     *
56     * Even if verbose logging has been disabled, dumpstateBoard may still be called by the
57     * dumpstate routine, and essential information that does not identify the user may be included.
58     *
59     * @param enable Whether to enable or disable verbose vendor logging.
60     */
61    setVerboseLoggingEnabled(bool enable);
62
63    /**
64     * Queries the current state of verbose device logging. Primarily for UI and informative
65     * purposes.
66     *
67     * Even if verbose logging has been disabled, dumpstateBoard may still be called by the
68     * dumpstate routine, and essential information that does not identify the user may be included.
69     *
70     * @return enabled Whether or not verbose vendor logging is currently enabled.
71     */
72    getVerboseLoggingEnabled() generates (bool enabled);
73};
74