1/*
2 * Copyright (C) 2013 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
17#ifndef ANDROID_INCLUDE_HARDWARE_MEMTRACK_H
18#define ANDROID_INCLUDE_HARDWARE_MEMTRACK_H
19
20#include <stdint.h>
21#include <sys/cdefs.h>
22#include <sys/types.h>
23
24#include <hardware/hardware.h>
25
26__BEGIN_DECLS
27
28#define MEMTRACK_MODULE_API_VERSION_0_1  HARDWARE_MODULE_API_VERSION(0, 1)
29
30/**
31 * The id of this module
32 */
33#define MEMTRACK_HARDWARE_MODULE_ID "memtrack"
34
35/*
36 * The Memory Tracker HAL is designed to return information about device-specific
37 * memory usage.  The primary goal is to be able to track memory that is not
38 * trackable in any other way, for example texture memory that is allocated by
39 * a process, but not mapped in to that process' address space.
40 * A secondary goal is to be able to categorize memory used by a process into
41 * GL, graphics, etc.  All memory sizes should be in real memory usage,
42 * accounting for stride, bit depth, rounding up to page size, etc.
43 *
44 * A process collecting memory statistics will call getMemory for each
45 * combination of pid and memory type.  For each memory type that it recognizes
46 * the HAL should fill out an array of memtrack_record structures breaking
47 * down the statistics of that memory type as much as possible.  For example,
48 * getMemory(<pid>, MEMTRACK_TYPE_GL) might return:
49 * { { 4096,  ACCOUNTED | PRIVATE | SYSTEM },
50 *   { 40960, UNACCOUNTED | PRIVATE | SYSTEM },
51 *   { 8192,  ACCOUNTED | PRIVATE | DEDICATED },
52 *   { 8192,  UNACCOUNTED | PRIVATE | DEDICATED } }
53 * If the HAL could not differentiate between SYSTEM and DEDICATED memory, it
54 * could return:
55 * { { 12288,  ACCOUNTED | PRIVATE },
56 *   { 49152,  UNACCOUNTED | PRIVATE } }
57 *
58 * Memory should not overlap between types.  For example, a graphics buffer
59 * that has been mapped into the GPU as a surface should show up when
60 * MEMTRACK_TYPE_GRAPHICS is requested, and not when MEMTRACK_TYPE_GL
61 * is requested.
62 */
63
64enum memtrack_type {
65    MEMTRACK_TYPE_OTHER = 0,
66    MEMTRACK_TYPE_GL = 1,
67    MEMTRACK_TYPE_GRAPHICS = 2,
68    MEMTRACK_TYPE_MULTIMEDIA = 3,
69    MEMTRACK_TYPE_CAMERA = 4,
70    MEMTRACK_NUM_TYPES,
71};
72
73struct memtrack_record {
74    size_t size_in_bytes;
75    unsigned int flags;
76};
77
78/**
79 * Flags to differentiate memory that can already be accounted for in
80 * /proc/<pid>/smaps,
81 * (Shared_Clean + Shared_Dirty + Private_Clean + Private_Dirty = Size).
82 * In general, memory mapped in to a userspace process is accounted unless
83 * it was mapped with remap_pfn_range.
84 * Exactly one of these should be set.
85 */
86#define MEMTRACK_FLAG_SMAPS_ACCOUNTED   (1 << 1)
87#define MEMTRACK_FLAG_SMAPS_UNACCOUNTED (1 << 2)
88
89/**
90 * Flags to differentiate memory shared across multiple processes vs. memory
91 * used by a single process.  Only zero or one of these may be set in a record.
92 * If none are set, record is assumed to count shared + private memory.
93 */
94#define MEMTRACK_FLAG_SHARED      (1 << 3)
95#define MEMTRACK_FLAG_SHARED_PSS  (1 << 4) /* shared / num_procesess */
96#define MEMTRACK_FLAG_PRIVATE     (1 << 5)
97
98/**
99 * Flags to differentiate memory taken from the kernel's allocation pool vs.
100 * memory that is dedicated to non-kernel allocations, for example a carveout
101 * or separate video memory.  Only zero or one of these may be set in a record.
102 * If none are set, record is assumed to count system + dedicated memory.
103 */
104#define MEMTRACK_FLAG_SYSTEM     (1 << 6)
105#define MEMTRACK_FLAG_DEDICATED  (1 << 7)
106
107/**
108 * Flags to differentiate memory accessible by the CPU in non-secure mode vs.
109 * memory that is protected.  Only zero or one of these may be set in a record.
110 * If none are set, record is assumed to count secure + nonsecure memory.
111 */
112#define MEMTRACK_FLAG_NONSECURE  (1 << 8)
113#define MEMTRACK_FLAG_SECURE     (1 << 9)
114
115/**
116 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
117 * and the fields of this data structure must begin with hw_module_t
118 * followed by module specific information.
119 */
120typedef struct memtrack_module {
121    struct hw_module_t common;
122
123    /**
124     * (*init)() performs memtrack management setup actions and is called
125     * once before any calls to getMemory().
126     * Returns 0 on success, -errno on error.
127     */
128    int (*init)(const struct memtrack_module *module);
129
130    /**
131     * (*getMemory)() expects an array of record objects and populates up to
132     * *num_record structures with the sizes of memory plus associated flags for
133     * that memory.  It also updates *num_records with the total number of
134     * records it could return if *num_records was large enough when passed in.
135     * Returning records with size 0 is expected, the number of records should
136     * not vary between calls to getMemory for the same memory type, even
137     * for different pids.
138     *
139     * The caller will often call getMemory for a type and pid with
140     * *num_records == 0 to determine how many records to allocate room for,
141     * this case should be a fast-path in the HAL, returning a constant and
142     * not querying any kernel files.  If *num_records passed in is 0,
143     * then records may be NULL.
144     *
145     * This function must be thread-safe, it may get called from multiple
146     * threads at the same time.
147     *
148     * Returns 0 on success, -ENODEV if the type is not supported, -errno
149     * on other errors.
150     */
151    int (*getMemory)(const struct memtrack_module *module,
152                     pid_t pid,
153                     int type,
154                     struct memtrack_record *records,
155                     size_t *num_records);
156} memtrack_module_t;
157
158__END_DECLS
159
160#endif  // ANDROID_INCLUDE_HARDWARE_MEMTRACK_H
161