% PT_IMAGE_ADD_FILE(3)
pt_image_add_file, pt_image_copy - add file sections to a traced memory image descriptor
| #include <intel-pt.h> | | int pt_image_add_file(struct pt_image *image, const char *filename, | uint64_t offset, uint64_t size, | const struct pt_asid *asid, uint64_t vaddr); | int pt_image_copy(struct pt_image *image, | const struct pt_image *src);
Link with -lipt.
pt_image_add_file() adds a new section to a pt_image object. The image argument points to the pt_image object to which the new section is added. The filename argument gives the absolute or relative path to the file on disk that contains the section. The offset and size arguments define the section within the file. The size argument is silently truncated to end the section with the end of the underlying file. The vaddr argument gives the virtual address at which the section is being loaded.
The asid argument gives an optional address space identifier. If it is not NULL, it points to a pt_asid structure, which is declared as:
/** An Intel PT address space identifier. * * This identifies a particular address space when adding file * sections or when reading memory. */ struct pt_asid { /** The size of this object - set to sizeof(struct pt_asid). */ size_t size; /** The CR3 value. */ uint64_t cr3; /** The VMCS Base address. */ uint64_t vmcs; };
The asid argument can be used to prepare a collection of process, guest, and hypervisor images to an Intel(R) Processor Trace (Intel PT) instruction flow decoder. The decoder will select the current image based on CR3 and VMCS information in the Intel PT trace.
If only the CR3 or only the VMCS field should be considered by the decoder, supply pt_asid_no_cr3 and pt_asid_no_vmcs to the other field respectively.
If the asid argument is NULL, the file section will be added for all processes, guests, and hypervisor images.
pt_image_copy() adds file sections from the pt_image pointed to by the src argument to the pt_image pointed to by the dst argument. Sections in src that would overlap with sections in dst are ignored.
pt_image_add_file() returns zero on success or a negative pt_error_code enumeration constant in case of an error.
pt_image_copy() returns the number of ignored sections on success or a negative pt_error_code enumeration constant in case of an error.
pte_invalid : The image or filename argument is NULL or the offset argument is too big such that the section would start past the end of the file (pt_image_add_file()). The src or dst argument is NULL (pt_image_copy()).
pte_bad_image : The image section would overlap with some other section already contained in image.
pt_image_alloc(3), pt_image_free(3), pt_image_remove_by_filename(3), pt_image_remove_by_asid(3), pt_image_set_callback(3), pt_insn_set_image(3), pt_insn_get_image(3)