pt_image_set_callback man page

pt_image_set_callback — set a traced memory image read memory callback

Synopsis

#include <intel-pt.h>

typedef int (read_memory_callback_t)(uint8_t *buffer, size_t size,

                                     const struct pt_asid *asid,

                                     uint64_t ip, void *context);

int pt_image_set_callback(struct pt_image *image,

                          read_memory_callback_t *callback,

                          void *context);

Link with -lipt.

Description

pt_image_set_callback() sets the function pointed to by callback as the read-memory callback function in the pt_image object pointed to by image. Any previous read-memory callback function is replaced. The read-memory callback function can be removed by passing NULL as callback argument.

When the Intel(R) Processor Trace (Intel PT) instruction flow decoder that is using image tries to read memory from a location that is not contained in any of the file sections in image, it calls the read-memory callback function with the following arguments:

buffer

A pre-allocated memory buffer to hold the to-be-read memory. The callback function shall provide the read memory in that buffer.

size

The size of the memory buffer pointed to by the buffer argument.

asid

The address-space identifier specifying the process, guest, or hypervisor, in which context the ip argument is to be interpreted. See pt_image_add_file(3).

ip

The virtual address from which size bytes of memory shall be read.

context

The context argument passed to pt_image_set_callback().

The callback function shall return the number of bytes read on success (no more than size) or a negative pt_error_code enumeration constant in case of an error.

Return Value

pt_image_set_callback() returns zero on success or a negative pt_error_code enumeration constant in case of an error.

Errors

pte_invalid

If the image argument is NULL.

See Also

pt_image_alloc(3), pt_image_free(3), pt_image_add_file(3), pt_image_add_cached(3), pt_image_copy(3), pt_image_remove_by_filename(3), pt_image_remove_by_asid(3), pt_insn_set_image(3), pt_insn_get_image**(3)

Referenced By

pt_image_add_file(3), pt_image_alloc(3).