1 /* 2 * Copyright (c) 2013-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_H 30 #define PT_IMAGE_H 31 32 #include "pt_mapped_section.h" 33 34 #include "intel-pt.h" 35 36 #include <stdint.h> 37 38 39 /* A list of sections. */ 40 struct pt_section_list { 41 /* The next list element. */ 42 struct pt_section_list *next; 43 44 /* The mapped section. */ 45 struct pt_mapped_section section; 46 47 /* The image section identifier. */ 48 int isid; 49 }; 50 51 /* A traced image consisting of a collection of sections. */ 52 struct pt_image { 53 /* The optional image name. */ 54 char *name; 55 56 /* The list of sections. */ 57 struct pt_section_list *sections; 58 59 /* An optional read memory callback. */ 60 struct { 61 /* The callback function. */ 62 read_memory_callback_t *callback; 63 64 /* The callback context. */ 65 void *context; 66 } readmem; 67 }; 68 69 /* Initialize an image with an optional @name. */ 70 extern void pt_image_init(struct pt_image *image, const char *name); 71 72 /* Finalize an image. 73 * 74 * This removes all sections and frees the name. 75 */ 76 extern void pt_image_fini(struct pt_image *image); 77 78 /* Add a section to an image. 79 * 80 * Add @section identified by @isid to @image at @vaddr in @asid. If @section 81 * overlaps with existing sections, the existing sections are shrunk, split, or 82 * removed to accomodate @section. Absence of a section identifier is indicated 83 * by an @isid of zero. 84 * 85 * Returns zero on success. 86 * Returns -pte_internal if @image, @section, or @asid is NULL. 87 */ 88 extern int pt_image_add(struct pt_image *image, struct pt_section *section, 89 const struct pt_asid *asid, uint64_t vaddr, int isid); 90 91 /* Remove a section from an image. 92 * 93 * Returns zero on success. 94 * Returns -pte_internal if @image, @section, or @asid is NULL. 95 * Returns -pte_bad_image if @image does not contain @section at @vaddr. 96 */ 97 extern int pt_image_remove(struct pt_image *image, struct pt_section *section, 98 const struct pt_asid *asid, uint64_t vaddr); 99 100 /* Read memory from an image. 101 * 102 * Reads at most @size bytes from @image at @addr in @asid into @buffer. 103 * 104 * Returns the number of bytes read on success, a negative error code otherwise. 105 * Returns -pte_internal if @image, @isid, @buffer, or @asid is NULL. 106 * Returns -pte_nomap if the section does not contain @addr. 107 */ 108 extern int pt_image_read(struct pt_image *image, int *isid, uint8_t *buffer, 109 uint16_t size, const struct pt_asid *asid, 110 uint64_t addr); 111 112 /* Find an image section. 113 * 114 * Find the section containing @vaddr in @asid and provide it in @msec. On 115 * success, takes a reference of @msec->section that the caller needs to put 116 * after use. 117 * 118 * Returns the section's identifier on success, a negative error code otherwise. 119 * Returns -pte_internal if @image, @msec, or @asid is NULL. 120 * Returns -pte_nomap if there is no such section in @image. 121 */ 122 extern int pt_image_find(struct pt_image *image, struct pt_mapped_section *msec, 123 const struct pt_asid *asid, uint64_t vaddr); 124 125 /* Validate an image section. 126 * 127 * Validate that a lookup of @vaddr in @msec->asid in @image would result in 128 * @msec identified by @isid. 129 * 130 * Validation may fail sporadically. 131 * 132 * Returns zero on success, a negative error code otherwise. 133 * Returns -pte_invalid if @image or @msec is NULL. 134 * Returns -pte_nomap if validation failed. 135 */ 136 extern int pt_image_validate(const struct pt_image *image, 137 const struct pt_mapped_section *msec, 138 uint64_t vaddr, int isid); 139 140 #endif /* PT_IMAGE_H */ 141