pt_image_add_file - Man Page

#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_add_cached(struct pt_image *image,

                        struct pt_image_section_cache *iscache,

                        int isid, const struct pt_asid *asid);

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.

pt_image_add_cached() adds a new section from an image section cache. See pt_iscache_add_file(3). The iscache argument points to the pt_image_section_cache object containing the section. The isid argument gives the image section identifier for the desired section in that cache.

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.

If the new section overlaps with an existing section, the existing section is truncated or split to make room for the new section.

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.

pt_image_add_file() and pt_image_add_cached() return 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 image or iscache argument is NULL (pt_image_add_cached()). The src or dst argument is NULL (pt_image_copy()).

pte_bad_image

The iscache does not contain isid (pt_image_add_cached()).

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), pt_iscache_alloc(3), pt_iscache_add_file(3)

pt_blk_next(3), pt_image_alloc(3), pt_image_remove_by_filename(3), pt_image_set_callback(3), pt_insn_get_image(3), pt_insn_next(3), pt_iscache_add_file(3), pt_iscache_alloc(3).

The man pages pt_image_add_cached(3) and pt_image_copy(3) are aliases of pt_image_add_file(3).