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
38struct pt_section;
39
40
41/* An image section cache entry. */
42struct 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. */
55struct 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 */
78struct 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. */
120extern int pt_iscache_init(struct pt_image_section_cache *iscache,
121			   const char *name);
122
123/* Finalize an image section cache. */
124extern 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 */
140extern 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 */
151extern 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 */
165extern 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. */
170extern 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 */
186extern 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 */
203extern 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