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 64 enum 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 73 struct 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 */ 120 typedef 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