2  * Copyright (c) 2013-2019, Intel Corporation
39 #include "intel-pt.h"
44 /* A section of contiguous memory loaded from a file. */
57 	/* A pointer to OS-specific file status for detecting changes.
60 	 * left in the section until the section is destroyed.  This field
61 	 * is owned by the OS-specific mmap-based section implementation.
65 	/* A pointer to implementation-specific mapping information - NULL if
66 	 * the section is currently not mapped.
76 	 * section is unmapped.
78 	 * We read this field without locking and only lock the section in order
81 	 * We rely on guaranteed atomic operations as specified in section 8.1.1
87 	/* A pointer to the iscache attached to this section.
91 	 * section at any time.
94 	 * to the section, which it needs to drop again after detaching.
98 	/* A pointer to the unmap function - NULL if the section is currently
106 	/* A pointer to the read function - NULL if the section is currently
115 	/* A pointer to the memsize function - NULL if the section is currently
121 	int (*memsize)(const struct pt_section *section, uint64_t *size);
124 	/* A lock protecting this section.
126 	 * Most operations do not require the section to be locked.  All
134 	 * the iscache is mapping or unmapping this section.
136 	 * The attach lock must not be taken while holding the section lock; the
142 	/* The number of current users.  The last user destroys the section. */
148 	/* The number of current mappers.  The last unmaps the section. */
152 /* Create a section.
154  * The returned section describes the contents of @file starting at @offset
157  * If @file is shorter than the requested @size, the section is silently
160  * If @offset lies beyond the end of @file, no section is created.
162  * The returned section is not mapped and starts with a user count of one and
166  * Returns -pte_internal if @psection is NULL.
167  * Returns -pte_nomem when running out of memory.
168  * Returns -pte_bad_file if @filename cannot be opened.
169  * Returns -pte_invalid if @offset lies beyond @file.
170  * Returns -pte_invalid if @filename is too long.
175 /* Lock a section.
177  * Locks @section.  The section must not be locked.
179  * Returns a new section on success, NULL otherwise.
180  * Returns -pte_bad_lock on any locking error.
182 extern int pt_section_lock(struct pt_section *section);
184 /* Unlock a section.
186  * Unlocks @section.  The section must be locked.
188  * Returns a new section on success, NULL otherwise.
189  * Returns -pte_bad_lock on any locking error.
191 extern int pt_section_unlock(struct pt_section *section);
195  * Increments the user count of @section.
198  * Returns -pte_internal if @section is NULL.
199  * Returns -pte_overflow if the user count would overflow.
200  * Returns -pte_bad_lock on any locking error.
202 extern int pt_section_get(struct pt_section *section);
206  * Decrements the user count of @section.  Destroys the section if the
210  * Returns -pte_internal if @section is NULL.
211  * Returns -pte_internal if the user count is already zero.
212  * Returns -pte_bad_lock on any locking error.
214 extern int pt_section_put(struct pt_section *section);
216 /* Attaches the image section cache user.
218  * Similar to pt_section_get() but sets @section->iscache to @iscache.
221  * Returns -pte_internal if @section or @iscache is NULL.
222  * Returns -pte_internal if a different cache is already attached.
223  * Returns -pte_overflow if the attach count would overflow.
224  * Returns -pte_bad_lock on any locking error.
226 extern int pt_section_attach(struct pt_section *section,
229 /* Detaches the image section cache user.
231  * Similar to pt_section_put() but clears @section->iscache.
234  * Returns -pte_internal if @section or @iscache is NULL.
235  * Returns -pte_internal if the attach count is already zero.
236  * Returns -pte_internal if @section->iscache is not equal to @iscache.
237  * Returns -pte_bad_lock on any locking error.
239 extern int pt_section_detach(struct pt_section *section,
242 /* Return the filename of @section. */
243 extern const char *pt_section_filename(const struct pt_section *section);
245 /* Return the offset of the section in bytes. */
246 extern uint64_t pt_section_offset(const struct pt_section *section);
248 /* Return the size of the section in bytes. */
249 extern uint64_t pt_section_size(const struct pt_section *section);
251 /* Return the amount of memory currently used by the section in bytes.
253  * We only consider the amount of memory required for mapping @section; we
254  * ignore the size of the section object itself and the size of the status
257  * If @section is currently not mapped, the size is zero.
260  * Returns -pte_internal if @size of @section is NULL.
262 extern int pt_section_memsize(struct pt_section *section, uint64_t *size);
267  * Returns -pte_internal if @section is NULL.
268  * Returns -pte_nomem if the block cache can't be allocated.
269  * Returns -pte_bad_lock on any locking error.
271 extern int pt_section_alloc_bcache(struct pt_section *section);
275  * The caller must ensure that @section is mapped.
277 static inline int pt_section_request_bcache(struct pt_section *section)  in pt_section_request_bcache()  argument
279 	if (!section)  in pt_section_request_bcache()
280 		return -pte_internal;  in pt_section_request_bcache()
282 	if (section->bcache)  in pt_section_request_bcache()
285 	return pt_section_alloc_bcache(section);  in pt_section_request_bcache()
288 /* Return @section's block cache, if available.
290  * The caller must ensure that @section is mapped.
292  * The cache is not use-counted.  It is only valid as long as the caller keeps
293  * @section mapped.
296 pt_section_bcache(const struct pt_section *section)  in pt_section_bcache()  argument
298 	if (!section)  in pt_section_bcache()
301 	return section->bcache;  in pt_section_bcache()
304 /* Create the OS-specific file status.
309  * The status object will be free()'ed when its section is.
311  * This function is implemented in the OS-specific section implementation.
314  * Returns -pte_internal if @pstatus, @psize, or @filename is NULL.
315  * Returns -pte_bad_image if @filename can't be opened.
316  * Returns -pte_nomem if the status object can't be allocated.
321 /* Perform on-map maintenance work.
323  * Notifies an attached image section cache about the mapping of @section.
325  * This function is called by the OS-specific pt_section_map() implementation
326  * after @section has been successfully mapped and @section has been unlocked.
329  * Returns -pte_internal if @section is NULL.
330  * Returns -pte_bad_lock on any locking error.
332 extern int pt_section_on_map_lock(struct pt_section *section);
334 static inline int pt_section_on_map(struct pt_section *section)  in pt_section_on_map()  argument
336 	if (section && !section->iscache)  in pt_section_on_map()
339 	return pt_section_on_map_lock(section);  in pt_section_on_map()
342 /* Map a section.
344  * Maps @section into memory.  Mappings are use-counted.  The number of
348  * This function is implemented in the OS-specific section implementation.
351  * Returns -pte_internal if @section is NULL.
352  * Returns -pte_bad_image if @section changed or can't be opened.
353  * Returns -pte_bad_lock on any locking error.
354  * Returns -pte_nomem if @section can't be mapped into memory.
355  * Returns -pte_overflow if the map count would overflow.
357 extern int pt_section_map(struct pt_section *section);
359 /* Share a section mapping.
361  * Increases the map count for @section without notifying an attached image
362  * section cache.
364  * This function should only be used by the attached image section cache to
365  * resolve a deadlock scenario when mapping a section it intends to cache.
368  * Returns -pte_internal if @section is NULL.
369  * Returns -pte_internal if @section->mcount is zero.
370  * Returns -pte_bad_lock on any locking error.
372 extern int pt_section_map_share(struct pt_section *section);
374 /* Unmap a section.
376  * Unmaps @section from memory.
379  * Returns -pte_internal if @section is NULL.
380  * Returns -pte_bad_lock on any locking error.
381  * Returns -pte_internal if @section has not been mapped.
383 extern int pt_section_unmap(struct pt_section *section);
385 /* Read memory from a section.
387  * Reads at most @size bytes from @section at @offset into @buffer.  @section
391  * Returns -pte_internal if @section or @buffer are NULL.
392  * Returns -pte_nomap if @offset is beyond the end of the section.
394 extern int pt_section_read(const struct pt_section *section, uint8_t *buffer,