Android Hardware Abstraction Layer
memtrack.h
Go to the documentation of this file.
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 
71 };
72 
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  */
120 typedef struct memtrack_module {
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);
157 
158 __END_DECLS
159 
160 #endif // ANDROID_INCLUDE_HARDWARE_MEMTRACK_H