1PT_IMAGE_ADD_FILE(3) PT_IMAGE_ADD_FILE(3)
2
6 pt_image_add_file, pt_image_add_cached, pt_image_copy - add file sec‐
7 tions to a traced memory image descriptor
8
10 #include <intel-pt.h>
11 int pt_image_add_file(struct pt_image *image, const char *filename,
12 uint64_t offset, uint64_t size,
13 const struct pt_asid *asid, uint64_t vaddr);
14 int pt_image_add_cached(struct pt_image *image,
15 struct pt_image_section_cache *iscache,
16 int isid, const struct pt_asid *asid);
17 int pt_image_copy(struct pt_image *image,
18 const struct pt_image *src);
19 Link with -lipt.
21
23 pt_image_add_file() adds a new section to a pt_image object. The image
24 argument points to the pt_image object to which the new section is
25 added. The filename argument gives the absolute or relative path to
26 the file on disk that contains the section. The offset and size argu‐
27 ments define the section within the file. The size argument is silent‐
28 ly truncated to end the section with the end of the underlying file.
29 The vaddr argument gives the virtual address at which the section is
30 being loaded.
31 pt_image_add_cached() adds a new section from an image section cache.
33 See pt_iscache_add_file(3). The iscache argument points to the pt_im‐
34 age_section_cache object containing the section. The isid argument
35 gives the image section identifier for the desired section in that
36 cache.
37 The asid argument gives an optional address space identifier. If it is
39 not NULL, it points to a pt_asid structure, which is declared as:
40 /** An Intel PT address space identifier.
42 *
43 * This identifies a particular address space when adding file
44 * sections or when reading memory.
45 */
46 struct pt_asid {
47 /** The size of this object - set to sizeof(struct pt_asid).
48 */
49 size_t size;
50 /** The CR3 value. */
52 uint64_t cr3;
53 /** The VMCS Base address. */
55 uint64_t vmcs;
56 };
57 The asid argument can be used to prepare a collection of process,
59 guest, and hypervisor images to an Intel(R) Processor Trace (Intel PT)
60 instruction flow decoder. The decoder will select the current image
61 based on CR3 and VMCS information in the Intel PT trace.
62 If only the CR3 or only the VMCS field should be considered by the de‐
64 coder, supply pt_asid_no_cr3 and pt_asid_no_vmcs to the other field re‐
65 spectively.
66 If the asid argument is NULL, the file section will be added for all
68 processes, guests, and hypervisor images.
69 If the new section overlaps with an existing section, the existing sec‐
71 tion is truncated or split to make room for the new section.
72 pt_image_copy() adds file sections from the pt_image pointed to by the
74 src argument to the pt_image pointed to by the dst argument.
75
77 pt_image_add_file() and pt_image_add_cached() return zero on success or
78 a negative pt_error_code enumeration constant in case of an error.
79 pt_image_copy() returns the number of ignored sections on success or a
81 negative pt_error_code enumeration constant in case of an error.
82
84 pte_invalid
85 The image or filename argument is NULL or the offset argument is
86 too big such that the section would start past the end of the
87 file (pt_image_add_file()). The image or iscache argument is
88 NULL (pt_image_add_cached()). The src or dst argument is NULL
89 (pt_image_copy()).
90 pte_bad_image
92 The iscache does not contain isid (pt_image_add_cached()).
93
95 pt_image_alloc(3), pt_image_free(3), pt_image_remove_by_filename(3),
96 pt_image_remove_by_asid(3), pt_image_set_callback(3), pt_insn_set_im‐
97 age(3), pt_insn_get_image(3), pt_iscache_alloc(3), pt_is‐
98 cache_add_file(3)
99 PT_IMAGE_ADD_FILE(3)