libguestrace

libguestrace — a library which allows programs to monitor the system calls serviced by a kernel running as a Xen guest.

Functions

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 ()

Types and Values

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

Includes

#include <libguestrace/guestrace.h>

Description

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

Functions

GtSyscallFunc ()

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.

Parameters

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 gt_loop_set_cb(); if set, the guestrace event loop will pass it here.

 

GtSysretFunc ()

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.

Parameters

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.

 

gt_loop_new ()

GtLoop *
gt_loop_new (const char *guest_name);

Creates a new GtLoop structure.

Parameters

guest_name

the name of a running guest virtual machine.

 

Returns

a new GtLoop.


gt_loop_get_ostype ()

GtOSType
gt_loop_get_ostype (GtLoop *loop);

Parameters

loop

a GtLoop.

 

Returns

the OS type of GtLoop.


gt_loop_set_cb ()

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 .

Parameters

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 syscall_cb

 

Returns

TRUE on success, FALSE on failure; an invalid kernel_func will cause the callback registration to fail.


gt_loop_set_cbs ()

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.

Parameters

loop

a GtLoop.

 

syscalls

an array of GtCallbackRegistry values, where each contains a function name and corresponding GtSyscallFunc and GtSysretFunc.

 

Returns

an integer which represents the number of callbacks successfully set; an invalid function name in syscalls will cause the corresponding callback registration to fail.


gt_loop_add_watch ()

guint
gt_loop_add_watch (GIOChannel *channel,
                   GIOCondition condition,
                   GIOFunc func,
                   gpointer user_data);

Parameters

channel

a GIOChannel.

 

condition

the condition to watch for.

 

func

the function to call when the condition is satisfied.

 

user_data

user data to pass to func .

 

Returns

the event source ID.


gt_guest_get_register ()

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.

Parameters

state

a pointer to a GtGuestState.

 

name

name of register to get.

 

gt_guest_get_string ()

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.

Parameters

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

 

gt_guest_get_vmi_instance ()

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.

Parameters

state

a pointer to a GtGuestState.

 

gt_guest_get_vmi_event ()

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.

Parameters

state

a pointer to a GtGuestState.

 

gt_loop_run ()

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 .

Parameters

loop

a GtLoop.

 

gt_loop_quit ()

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.

Parameters

loop

a GtLoop.

 

gt_loop_free ()

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.

Parameters

loop

a GtLoop.

 

Types and Values

gt_reg_name_t

typedef registers_t gt_reg_name_t;

The gt_reg_name_t enum contains the valid names of the registers found on the guest.


gt_addr_t

typedef addr_t    gt_addr_t;

A guest virtual memory address.


gt_pid_t

typedef vmi_pid_t gt_pid_t;

The unique identifier for a guest process.


gt_tid_t

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.


gt_reg_t

typedef reg_t     gt_reg_t;

The value of some guest register.


GtCallbackRegistry

typedef struct {
} GtCallbackRegistry;

Full callback definition for use with gt_loop_set_cbs().

Members


enum GtOSType

Enum values which specify the operating system running on the guest.

Members

GT_OS_UNKNOWN

an unknown operating system.

 

GT_OS_WINDOWS

a Windows operating system.

 

GT_OS_LINUX

a Linux operating system.

 

GtGuestState

typedef struct {
} GtGuestState;

The GtGuestState struct is an opaque data type representing the state of the instrumented guest.


GtLoop

typedef struct {
} GtLoop;

The GtLoop struct is an opaque data type representing the main event loop of a guestrace application.