Colin Cross | aa77350 | 2013-09-05 17:45:07 -0700 | [diff] [blame] | 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 |