[DynInst_API:] Proposal: Add System Call Events to ProcControlAPI

[Emily Jacobson <jacobson@xxxxxxxxxxx>]

Hi all,

We’re proposing adding system call callbacks to ProcControlAPI. After internal discussion, we're sending out this proposal for wider feedback. What follows is an overview of this feature, as well as the proposed ProcControlAPI interface. For this feature to be exposed in the DyninstAPI interface, it must first be exposed via ProcControlAPI. We expect the DyninstAPI interface will closely mirror this.

Feedback is appreciated.

Overview:

This feature adds the ability to stop a thread at system call entry and exit. The API will provide information about the system call and the address at which the thread is stopped; on system call exit, the API also provides the system call return value. A user would make use of existing API calls to extract any other information they might want.

Proposed Interface:

A new Event child class: EventSyscall.  An EventSyscall is triggered when a thread, which was put in syscall-monitoring mode by Thread::setSyscallMode, enters or exists a system call. The Thread will remain in syscall-monitoring mode after completion of this event (presuming it has not been explicitly disabled by Thread::setSyscallMode). An EventSyscall may be associated with an EventType of pre-syscall (system call entry) or post-syscall (system call exit).

We’re proposing adding a class representation for system calls; we’re currently calling this class MachSyscall. Also, in support of this syscall representation, we’re proposing representing the cross-product of various architecture, OS, and possibly version information in a Platform class. In this context, this allows us to go from a syscall’s mutatee-side ID to its name (and to its arguments, eventually). More generally, it allows us to represent the platform of a mutatee, which even with our current feature set is not necessarily the platform of the mutator (e.g. 32-bit mutatees/64-bit mutators). As this is variable based on the process, it needs to be a process-level piece of information and can’t be baked in at compile time.

This interface could be expanded in the future to support argument types and value information.

class Platform {

public:

Arch arch();

OSType os();

string version();

};

namespace ProcControlAPI {

class MachSyscall {

public:

// Factory methods

// Allows ProcControlAPI to construct a MachSyscall for an event 

static MachSyscall makeFromEvent(ProcControlAPI::EventSyscall);

// Allows users to construct a MachSyscall 

static MachSyscall makeFromID(ProcControlAPI::Process, ID);

// Accessors

// Returns the platform-specific number for this system call

int num() const;

// Returns the name for this system call (e.g., “getpid”)

string name() const;

// Strict equality based on matching Platforms and IDs

bool operator==(const MachSyscall &) const;

private:

Platform plat;

ID id;

};

}

== additional ProcControlAPI::Event class member functions ==

EventSyscall::ptr getEventSyscall();

EventSyscall::const_ptr getEventSyscall const();

    These functions follow the existing model and serve as a form of dynamic_cast.

== additional ProcControlAPI::Thread class member functions ==

void setSyscallMode(bool mode) const;

    This function sets whether a Thread is stopped at each entry or exit from a system call. If called with a mode of true, then the Thread is put in this syscall-monitoring mode. If called with a mode of false, then the Thread is taken out of syscall-monitoring mode.

bool getSyscallMode() const;

    This function returns true if the Thread is in syscall-monitoring mode and false otherwise.

== ProcControlAPI::EventSyscall Member functions ==

Dyninst::Address getAddress() const;

    This function returns the address at which system call event occurred.

Dyninst::MachSyscall getSyscall() const;

This function returns a MachSyscall object that represents the system call occurring at the system call event.

long getReturnValue() const;

This function returns the return value associated with the system call. (This function is specific to Post-Syscall.)

Implementation details:

On Linux, we distinguish between system call entry and exit based on the system call return value. This approach will always correctly label a system call entry. Only in the case where the invoked system call does not exist (0 < syscall number > __NR_syscall_max) will we incorrectly label the system call exit as system call entry.

On Windows, system call events will correspond to calls and returns from kernel calls. Note that Windows will only provide Pre-Syscall and will not support Post-Syscall.

Best,

Emily