1 /* 2 * Copyright (c) 2016-2019, Intel Corporation 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are met: 6 * 7 * * Redistributions of source code must retain the above copyright notice, 8 * this list of conditions and the following disclaimer. 9 * * Redistributions in binary form must reproduce the above copyright notice, 10 * this list of conditions and the following disclaimer in the documentation 11 * and/or other materials provided with the distribution. 12 * * Neither the name of Intel Corporation nor the names of its contributors 13 * may be used to endorse or promote products derived from this software 14 * without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 #ifndef PT_IMAGE_SECTION_CACHE_H 30 #define PT_IMAGE_SECTION_CACHE_H 31 32 #include <stdint.h> 33 34 #if defined(FEATURE_THREADS) 35 # include <threads.h> 36 #endif /* defined(FEATURE_THREADS) */ 37 38 struct pt_section; 39 40 41 /* An image section cache entry. */ 42 struct pt_iscache_entry { 43 /* The section object. 44 * 45 * We hold a reference to the section - put it when the section is 46 * removed from the cache. 47 */ 48 struct pt_section *section; 49 50 /* The base address at which @section has been loaded. */ 51 uint64_t laddr; 52 }; 53 54 /* An image section cache least recently used cache entry. */ 55 struct pt_iscache_lru_entry { 56 /* The next entry in a list ordered by recent use. */ 57 struct pt_iscache_lru_entry *next; 58 59 /* The section mapped by the image section cache. */ 60 struct pt_section *section; 61 62 /* The amount of memory used by mapping @section in bytes. */ 63 uint64_t size; 64 }; 65 66 /* A cache of image sections and their load addresses. 67 * 68 * We combine the section with its load address to reduce the amount of 69 * information we need to store in order to read from a cached section by 70 * virtual address. 71 * 72 * Internally, the section object will be shared if it is loaded at different 73 * addresses in the cache. 74 * 75 * The cache does not consider the address-space the section is mapped into. 76 * This is not relevant for reading from the section. 77 */ 78 struct pt_image_section_cache { 79 /* The optional name of the cache; NULL if not named. */ 80 char *name; 81 82 /* An array of @nentries cached sections. */ 83 struct pt_iscache_entry *entries; 84 85 /* A list of mapped sections ordered by time of last access. */ 86 struct pt_iscache_lru_entry *lru; 87 88 /* The memory limit for our LRU cache. */ 89 uint64_t limit; 90 91 /* The current size of our LRU cache. */ 92 uint64_t used; 93 94 #if defined(FEATURE_THREADS) 95 /* A lock protecting this image section cache. */ 96 mtx_t lock; 97 #endif /* defined(FEATURE_THREADS) */ 98 99 /* The capacity of the @entries array. 100 * 101 * Cached sections are identified by a positive integer, the image 102 * section identifier (isid), which is derived from their index into the 103 * @entries array. 104 * 105 * We can't expand the section cache capacity beyond INT_MAX. 106 */ 107 uint16_t capacity; 108 109 /* The current size of the cache in number of entries. 110 * 111 * This is smaller than @capacity if there is still room in the @entries 112 * array; equal to @capacity if the @entries array is full and needs to 113 * be reallocated. 114 */ 115 uint16_t size; 116 }; 117 118 119 /* Initialize an image section cache. */ 120 extern int pt_iscache_init(struct pt_image_section_cache *iscache, 121 const char *name); 122 123 /* Finalize an image section cache. */ 124 extern void pt_iscache_fini(struct pt_image_section_cache *iscache); 125 126 /* Add a section to the cache. 127 * 128 * Adds @section at @laddr to @iscache and returns its isid. If a similar 129 * section is already cached, returns that section's isid, instead. 130 * 131 * We take a full section rather than its filename and range in that file to 132 * avoid the dependency to pt_section.h. Callers are expected to query the 133 * cache before creating the section, so we should only see unnecessary section 134 * creation/destruction on insertion races. 135 * 136 * Returns zero on success, a negative error code otherwise. 137 * Returns -pte_internal if @iscache or @section is NULL. 138 * Returns -pte_internal if @section's filename is NULL. 139 */ 140 extern int pt_iscache_add(struct pt_image_section_cache *iscache, 141 struct pt_section *section, uint64_t laddr); 142 143 /* Find a section in the cache. 144 * 145 * Returns a positive isid if a section matching @filename, @offset, @size 146 * loaded at @laddr is found in @iscache. 147 * Returns zero if no such section is found. 148 * Returns a negative error code otherwise. 149 * Returns -pte_internal if @iscache or @filename is NULL. 150 */ 151 extern int pt_iscache_find(struct pt_image_section_cache *iscache, 152 const char *filename, uint64_t offset, 153 uint64_t size, uint64_t laddr); 154 155 /* Lookup the section identified by its isid. 156 * 157 * Provides a reference to the section in @section and its load address in 158 * @laddr on success. The caller is expected to put the returned section after 159 * use. 160 * 161 * Returns zero on success, a negative error code otherwise. 162 * Returns -pte_internal if @iscache, @section, or @laddr is NULL. 163 * Returns -pte_bad_image if @iscache does not contain @isid. 164 */ 165 extern int pt_iscache_lookup(struct pt_image_section_cache *iscache, 166 struct pt_section **section, uint64_t *laddr, 167 int isid); 168 169 /* Clear an image section cache. */ 170 extern int pt_iscache_clear(struct pt_image_section_cache *iscache); 171 172 /* Notify about the mapping of a cached section. 173 * 174 * Notifies @iscache that @section has been mapped. 175 * 176 * The caller guarantees that @iscache contains @section (by using @section's 177 * iscache pointer) and prevents @iscache from detaching. 178 * 179 * The caller must not lock @section to allow @iscache to map it. This function 180 * must not try to detach from @section. 181 * 182 * Returns zero on success, a negative pt_error_code otherwise. 183 * Returns -pte_internal if @iscache or @section is NULL. 184 * Returns -pte_bad_lock on any locking error. 185 */ 186 extern int pt_iscache_notify_map(struct pt_image_section_cache *iscache, 187 struct pt_section *section); 188 189 /* Notify about a size change of a mapped section. 190 * 191 * Notifies @iscache that @section's size has changed while it was mapped. 192 * 193 * The caller guarantees that @iscache contains @section (by using @section's 194 * iscache pointer) and prevents @iscache from detaching. 195 * 196 * The caller must not lock @section to allow @iscache to map it. This function 197 * must not try to detach from @section. 198 * 199 * Returns zero on success, a negative pt_error_code otherwise. 200 * Returns -pte_internal if @iscache or @section is NULL. 201 * Returns -pte_bad_lock on any locking error. 202 */ 203 extern int pt_iscache_notify_resize(struct pt_image_section_cache *iscache, 204 struct pt_section *section, uint64_t size); 205 206 #endif /* PT_IMAGE_SECTION_CACHE_H */ 207