contrib/processor-trace/libipt/internal/include/pt_image_section_cache.h

   1 /*
   2  * Copyright (c) 2016-2018, 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 */