Top | ![]() |
![]() |
![]() |
![]() |
libguestracelibguestrace — a library which allows programs to monitor the system calls serviced by a kernel running as a Xen guest. |
void * | (*GtSyscallFunc) () |
void | (*GtSysretFunc) () |
GtLoop * | gt_loop_new () |
GtOSType | gt_loop_get_ostype () |
gboolean | gt_loop_set_cb () |
int | gt_loop_set_cbs () |
guint | gt_loop_add_watch () |
gt_reg_t | gt_guest_get_register () |
char * | gt_guest_get_string () |
vmi_instance_t | gt_guest_get_vmi_instance () |
vmi_event_t * | gt_guest_get_vmi_event () |
void | gt_loop_run () |
void | gt_loop_quit () |
void | gt_loop_free () |
typedef | gt_reg_name_t |
typedef | gt_addr_t |
typedef | gt_pid_t |
typedef | gt_tid_t |
typedef | gt_reg_t |
GtCallbackRegistry | |
enum | GtOSType |
GtGuestState | |
GtLoop |
A program using libguestrace registers callbacks which the guestrace event loop invokes when a system call occurs in the monitored guest operating system.
Example 1. Program which uses libguestrace to print open()
s and read()
s which occur on a Linux guest (error handling and other details omitted)
1 2 3 4 5 6 |
GLoop *loop = gt_loop_new("xen-guest-name"); gt_loop_set_cb(loop, "sys_open", open_cb, sysret_cb, NULL); gt_loop_set_cb(loop, "sys_read", read_cb, sysret_cb, NULL); gt_loop_run(loop); |
Example 2. Example open_cb()
1 2 3 4 5 6 7 8 9 |
void *open_cb(GtGuestState *state, gt_pid_t pid, gt_tid_t tid, void *user_data) { reg_t addr = gt_guest_get_register(state, RDI); char *path = gt_guest_get_string(state, addr); int flags = gt_guest_get_register(state, RSI); int mode = gt_guest_get_register(state, RDX); printf("%u called open(\"%s\", %i, %d)\n", pid, path, flags, mode); return NULL; } |
void * (*GtSyscallFunc) (GtGuestState *state
,gt_pid_t pid
,gt_tid_t tid
,void *user_data
);
Specifies one of the two types of functions passed to gt_loop_set_cb()
.
The guestrace event loop invokes this callback each time a program running
on the guest invokes the corresponding system call. Implementations can
optionally return a pointer which the guestrace event loop will later pass
to the corresponding GtSysretFunc after the system call returns.
vmi |
the libvmi instance which abstracts the guest. |
|
event |
the event which abstracts the system call which caused the guestrace event loop to invoke this function. |
|
pid |
the ID of the process running when the event occurred. |
|
tid |
the unique ID of the thread running within the current process. |
|
user_data |
optional data which might have been passed to the
corresponding |
void (*GtSysretFunc) (GtGuestState *state
,gt_pid_t pid
,gt_tid_t tid
,void *user_data
);
Specifies one of the two types of functions passed to gt_loop_set_cb()
.
The guestrace event loop invokes this callback each time a system call on
the guest returns control to a program. It is the responsibility of each
GtSysretFunc implementation to free user_data
if the corresponding
GtSyscallFunc returned a pointer to a dynamically-allocated object.
vmi |
the libvmi instance which abstracts the guest. |
|
event |
the event which abstracts the system return which caused the guestrace event loop to invoke this function. |
|
pid |
the ID of the process running when the event occurred. |
|
tid |
the unique ID of the thread running within the current process. |
|
user_data |
the return value from GtSyscallFunc which the guestrace event loop passes to GtSysretFunc. |
gboolean gt_loop_set_cb (GtLoop *loop
,const char *kernel_func
,GtSyscallFunc syscall_cb
,GtSysretFunc sysret_cb
,void *user_data
);
Sets the callback functions associated with kernel_func
. Each time
processing a system call in the guest kernel calls kernel_func
,
The loop will invoke syscall_cb
with the parameters associated with the
call. When kernel_func
returns, the loop will invoke sysret_cb
.
loop |
a GtLoop. |
|
kernel_func |
the name of a function in the traced kernel which implements a system call. |
|
syscall_cb |
a GtSyscallFunc which will handle the named system call. |
|
sysret_cb |
a GtSysretFunc which will handle returns from the named system call. |
|
user_data |
optional data which the guestrace event loop will pass to each call of |
int gt_loop_set_cbs (GtLoop *loop
,const GtCallbackRegistry callbacks[]
);
A convenience function which repeatedly invoke gt_loop_set_cb for each
callback defined in syscalls
. The syscalls
array must be terminated with
an GtCallbackRegistry with each field set to NULL.
loop |
a GtLoop. |
|
syscalls |
an array of GtCallbackRegistry values, where each contains a function name and corresponding GtSyscallFunc and GtSysretFunc. |
guint gt_loop_add_watch (GIOChannel *channel
,GIOCondition condition
,GIOFunc func
,gpointer user_data
);
gt_reg_t gt_guest_get_register (GtGuestState *state
,gt_reg_name_t name
);
Returns the value of the named register from the guest state.
char * gt_guest_get_string (GtGuestState *state
,gt_addr_t vaddr
,gt_pid_t pid
);
Returns the NULL-terminated string which starts at vaddr
or NULL on error.
The returned string must be freed by the caller.
state |
a pointer to a GtGuestState. |
|
vaddr |
a virtual address from the guest's address space. |
|
pid |
PID of the virtual address space (0 for kernel). |
vmi_instance_t
gt_guest_get_vmi_instance (GtGuestState *state
);
Returns the vmi_instance_t associated with state
. Refer to the libvmi
documentation for a description of vmi_instance_t.
vmi_event_t *
gt_guest_get_vmi_event (GtGuestState *state
);
Returns the vmi_event_t associated with state
. Refer to the libvmi
documentation for a description of vmi_event_t.
void
gt_loop_run (GtLoop *loop
);
Uses libvmi to complete the preparations necessary to trace a guest's system
calls. Runs loop
until gt_loop_quit()
is called on loop
.
void
gt_loop_quit (GtLoop *loop
);
Stops loop
from running. Any calls to gt_loop_run()
for the loop will return.
This removes any modifications to the guest's memory and allows the guest
to run without instrumentation.
void
gt_loop_free (GtLoop *loop
);
Free loop
and its associated memory. If the loop is currently running, then
gt_loop_quit()
must first terminate the loop and remove the guest
instrumentation.
typedef registers_t gt_reg_name_t;
The gt_reg_name_t
enum contains the valid names
of the registers found on the guest.
typedef addr_t gt_tid_t;
An identifier which serves to correlate between calls and returns at thread granularity. Generally the value of the stack pointer upon invoking a system call.
typedef struct { } GtCallbackRegistry;
Full callback definition for use with gt_loop_set_cbs()
.
typedef struct { } GtGuestState;
The GtGuestState
struct is an opaque data type representing the state of
the instrumented guest.