2 * Copyright (c) 2016-2018, Intel Corporation
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
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.
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.
29 #ifndef PT_IMAGE_SECTION_CACHE_H
30 #define PT_IMAGE_SECTION_CACHE_H
34 #if defined(FEATURE_THREADS)
36 #endif /* defined(FEATURE_THREADS) */
41 /* An image section cache entry. */
42 struct pt_iscache_entry {
43 /* The section object.
45 * We hold a reference to the section - put it when the section is
46 * removed from the cache.
48 struct pt_section *section;
50 /* The base address at which @section has been loaded. */
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;
59 /* The section mapped by the image section cache. */
60 struct pt_section *section;
62 /* The amount of memory used by mapping @section in bytes. */
66 /* A cache of image sections and their load addresses.
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
72 * Internally, the section object will be shared if it is loaded at different
73 * addresses in the cache.
75 * The cache does not consider the address-space the section is mapped into.
76 * This is not relevant for reading from the section.
78 struct pt_image_section_cache {
79 /* The optional name of the cache; NULL if not named. */
82 /* An array of @nentries cached sections. */
83 struct pt_iscache_entry *entries;
85 /* A list of mapped sections ordered by time of last access. */
86 struct pt_iscache_lru_entry *lru;
88 /* The memory limit for our LRU cache. */
91 /* The current size of our LRU cache. */
94 #if defined(FEATURE_THREADS)
95 /* A lock protecting this image section cache. */
97 #endif /* defined(FEATURE_THREADS) */
99 /* The capacity of the @entries array.
101 * Cached sections are identified by a positive integer, the image
102 * section identifier (isid), which is derived from their index into the
105 * We can't expand the section cache capacity beyond INT_MAX.
109 /* The current size of the cache in number of entries.
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
119 /* Initialize an image section cache. */
120 extern int pt_iscache_init(struct pt_image_section_cache *iscache,
123 /* Finalize an image section cache. */
124 extern void pt_iscache_fini(struct pt_image_section_cache *iscache);
126 /* Add a section to the cache.
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.
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.
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.
140 extern int pt_iscache_add(struct pt_image_section_cache *iscache,
141 struct pt_section *section, uint64_t laddr);
143 /* Find a section in the cache.
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.
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);
155 /* Lookup the section identified by its isid.
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
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.
165 extern int pt_iscache_lookup(struct pt_image_section_cache *iscache,
166 struct pt_section **section, uint64_t *laddr,
169 /* Clear an image section cache. */
170 extern int pt_iscache_clear(struct pt_image_section_cache *iscache);
172 /* Notify about the mapping of a cached section.
174 * Notifies @iscache that @section has been mapped.
176 * The caller guarantees that @iscache contains @section (by using @section's
177 * iscache pointer) and prevents @iscache from detaching.
179 * The caller must not lock @section to allow @iscache to map it. This function
180 * must not try to detach from @section.
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.
186 extern int pt_iscache_notify_map(struct pt_image_section_cache *iscache,
187 struct pt_section *section);
189 /* Notify about a size change of a mapped section.
191 * Notifies @iscache that @section's size has changed while it was mapped.
193 * The caller guarantees that @iscache contains @section (by using @section's
194 * iscache pointer) and prevents @iscache from detaching.
196 * The caller must not lock @section to allow @iscache to map it. This function
197 * must not try to detach from @section.
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.
203 extern int pt_iscache_notify_resize(struct pt_image_section_cache *iscache,
204 struct pt_section *section, uint64_t size);
206 #endif /* PT_IMAGE_SECTION_CACHE_H */