PT_IMAGE_ADD_FILE(3)

📦 version 2.1.2, in fedora 43, fedora 44

🎀 PT_IMAGE_ADD_FILE 🎀

okay bestie, so this one is pt_image_add_file(3) — section 3 of the manual, the library-functions zone — and it's literally the trio of functions that let you feed file sections into a traced memory image descriptor. pt_image_add_file, pt_image_add_cached, pt_image_copy. three icons, one page. let's go 💅

✨ NAME ✨

pt_image_add_file, pt_image_add_cached, pt_image_copy — add file sections to a traced memory image descriptor

no cap, that's the whole vibe: you're telling a memory image "hey, this chunk of memory actually lives in this file on disk, k?"

🦋 SYNOPSIS 🦋

#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.

not me reminding you to actually link the library 🙈 -lipt or it's giving undefined reference, periodt.

💖 DESCRIPTION 💖

the main character: pt_image_add_file()

so pt_image_add_file() adds a new section to a pt_image object. slay.

  • 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 (yes, quietly. no drama. it just does it 💀)
  • the vaddr argument gives the virtual address at which the section is being loaded

the cached one: pt_image_add_cached()

pt_image_add_cached() adds a new section from an image section cache. see pt_iscache_add_file(3) for the whole lore 👑

  • 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, aka the address space identifier 🫶

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;
};

ngl this struct is doing the most, but it's iconic for a reason. 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. main character decoder energy fr fr 🔥

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. like, pick your fighter, but only one 💅

if the asid argument is NULL, the file section will be added for all processes, guests, and hypervisor images. all of them. every single one. no filter ✨

if the new section overlaps with an existing section, the existing section is truncated or split to make room for the new section. it's not mean about it, it just makes space. lowkey generous.

the copy: pt_image_copy()

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. that's it, that's the whole thing, it's a glow-up transplant 💜

🌈 RETURN VALUE 🌈

  • 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
yeah so for pt_image_copy() success is not just "0", it hands you a count. read it. respect it. 🙈

🌸 ERRORS 🌸

  • 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()). it's giving "bestie that section is not in this cache" 🥲

👑 SEE ALSO 👑

iykyk, go read them all, they're all bangers ⭐

and that's the page!! 🧚 this was PT_IMAGE_ADD_FILE(3) — yes, the whole thing is filed under that one name even though three functions live here, that's just how section 3 does it — and that's your sign-off from the manual, section 3, pt_image_add_file era. stay hydrated, link -lipt, and go add some file sections bestie 💖🌸✨

📦 where this page comes from