1/*
2 * Copyright (C) 2016 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.memtrack@1.0;
18
19/**
20 * The Memory Tracker HAL is designed to return information about
21 * device-specific memory usage.
22 * The primary goal is to be able to track memory that is not
23 * trackable in any other way, for example texture memory that is allocated by
24 * a process, but not mapped in to that process's address space.
25 * A secondary goal is to be able to categorize memory used by a process into
26 * GL, graphics, etc. All memory sizes must be in real memory usage,
27 * accounting for stride, bit depth, rounding up to page size, etc.
28 *
29 * Constructor for the interface should be used to perform memtrack management
30 * setup actions and is called once before any calls to getMemory().
31 */
32interface IMemtrack {
33    /**
34     * getMemory() populates MemtrackRecord vector with the sizes of memory
35     * plus associated flags for that memory.
36     *
37     * This function must be thread-safe, it may get called from multiple
38     * threads at the same time.
39     *
40     * A process collecting memory statistics will call getMemory for each
41     * combination of pid and memory type. For each memory type that it
42     * recognizes, the HAL must fill out an array of memtrack_record
43     * structures breaking down the statistics of that memory type as much as
44     * possible. For example,
45     * getMemory(<pid>, GL) might return:
46     * { { 4096,  ACCOUNTED | PRIVATE | SYSTEM },
47     *   { 40960, UNACCOUNTED | PRIVATE | SYSTEM },
48     *   { 8192,  ACCOUNTED | PRIVATE | DEDICATED },
49     *   { 8192,  UNACCOUNTED | PRIVATE | DEDICATED } }
50     * If the HAL cannot differentiate between SYSTEM and DEDICATED memory, it
51     * could return:
52     * { { 12288,  ACCOUNTED | PRIVATE },
53     *   { 49152,  UNACCOUNTED | PRIVATE } }
54     *
55     * Memory must not overlap between types. For example, a graphics buffer
56     * that has been mapped into the GPU as a surface must show up when
57     * GRAPHICS is requested and not when GL
58     * is requested.
59     *
60     * @param pid process for which memory information is requested
61     * @param type memory type that information is being requested about
62     * @return records vector of MemtrackRecord containing memory information
63     * @return retval SUCCESS on success, TYPE_NOT_FOUND if the type is not
64     * supported.
65     */
66    getMemory(int32_t pid, MemtrackType type)
67            generates (MemtrackStatus retval, vec<MemtrackRecord> records);
68};
69