1PT_IMAGE_SET_CALLBACK(3)                              PT_IMAGE_SET_CALLBACK(3)
2
3
4

NAME

6       pt_image_set_callback - set a traced memory image read memory callback
7

SYNOPSIS

9       #include <intel-pt.h>
10       typedef int (read_memory_callback_t)(uint8_t *buffer, size_t size,
11                                            const struct pt_asid *asid,
12                                            uint64_t ip, void *context);
13       int pt_image_set_callback(struct pt_image *image,
14                                 read_memory_callback_t *callback,
15                                 void *context);
16
17       Link with -lipt.
18

DESCRIPTION

20       pt_image_set_callback() sets the function pointed to by callback as the
21       read-memory callback function in the pt_image object pointed to by  im‐
22       age.   Any  previous  read-memory  callback  function is replaced.  The
23       read-memory callback function can be removed by passing NULL  as  call‐
24       back argument.
25
26       When  the  Intel(R) Processor Trace (Intel PT) instruction flow decoder
27       that is using image tries to read memory from a location  that  is  not
28       contained in any of the file sections in image, it calls the read-memo‐
29       ry callback function with the following arguments:
30
31       buffer A pre-allocated memory buffer to  hold  the  to-be-read  memory.
32              The callback function shall provide the read memory in that buf‐
33              fer.
34
35       size   The size of the memory buffer pointed to by the buffer argument.
36
37       asid   The address-space identifier specifying the process,  guest,  or
38              hypervisor, in which context the ip argument is to be interpret‐
39              ed.  See pt_image_add_file(3).
40
41       ip     The virtual address from which size bytes  of  memory  shall  be
42              read.
43
44       context
45              The context argument passed to pt_image_set_callback().
46
47       The  callback function shall return the number of bytes read on success
48       (no more than size) or a negative pt_error_code enumeration constant in
49       case of an error.
50

RETURN VALUE

52       pt_image_set_callback()  returns  zero  on success or a negative pt_er‐
53       ror_code enumeration constant in case of an error.
54

ERRORS

56       pte_invalid
57              If the image argument is NULL.
58

SEE ALSO

60       pt_image_alloc(3),   pt_image_free(3),   pt_image_add_file(3),   pt_im‐
61       age_add_cached(3),   pt_image_copy(3),  pt_image_remove_by_filename(3),
62       pt_image_remove_by_asid(3),    pt_insn_set_image(3),    pt_insn_get_im‐
63       age**(3)
64
65
66
67                                                      PT_IMAGE_SET_CALLBACK(3)
Impressum