Skip to content

Commit

Permalink
Add dyninstAPI_RT/dyninstAPI_RT.h
Browse files Browse the repository at this point in the history
  • Loading branch information
@hainest
hainest committed Apr 3, 2024
1 parent 8bc986e commit ec6d41d
Show file tree
Hide file tree
Showing 2 changed files with 281 additions and 44 deletions.
263 changes: 263 additions & 0 deletions docs/dyninstAPI_RT/developer/dyninstAPI_RT.h.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,266 @@
dyninstAPI_RT.h
###############

Standard instrumentation functions that are provided by the run-time instrumentation layer.


.. code:: c
/*
* Define the size of the per process data area.
*
* This should be a power of two to reduce paging and caching shifts.
* Note that larger sizes may result in requiring longjumps within
* mini-trampolines to reach within this area.
*/
#if !defined(target_smallmem)
# define SYN_INST_BUF_SIZE (1024*1024*4)
#else
# define SYN_INST_BUF_SIZE (1024*1024*1)
#endif
#define DYNINST_BREAKPOINT_SIGNUM (SIGRTMIN+4)
#if !defined(DYNINST_SINGLETHREADED)
# define DYNINST_SINGLETHREADED -128
#endif
#define DYNINST_TRACEPIPE_ERRVAL -1
#define DYNINST_PRINTF_ERRVAL -2
#define DYNINST_NOT_IN_HASHTABLE ((unsigned)-1)
#define TRAP_HEADER_SIG 0x759191D6
#define DT_DYNINST 0x6D191957
#define RTprintf if (DYNINSTdebugPrintRT) printf
#define TARGET_CACHE_WIDTH 128
#define TARGET_CACHE_WAYS 2
#define THREAD_AWAITING_DELETION -2
#define ERROR_STRING_LENGTH 256
#define MAX_MEMORY_MAPPER_ELEMENTS 1024
.. c:type::unsigned char RT_Boolean
If we must make up a boolean type, we should make it unique.

.. c:var:: static const RT_Boolean RT_TRUE=1
.. c:var:: static const RT_Boolean RT_FALSE=0
.. c:var:: extern char gLoadLibraryErrorString[]
.. c:var:: extern void *gBRKptr
.. c:struct:: DYNINST_bootstrapStruct
.. c:member:: int event
Takes on one of these values:

| 0 --> nothing
| 1 --> end of DYNINSTinit (normal)
| 2 --> end of DYNINSTinit (forked process)
| 3 --> start of DYNINSTexec (before exec)
.. c:member:: int pid
.. c:member:: int ppid
parent of forked process

.. c:enum:: DYNINST_synch_event_t
.. c:enumerator:: DSE_undefined
.. c:enumerator:: DSE_forkEntry
.. c:enumerator:: DSE_forkExit
.. c:enumerator:: DSE_execEntry
.. c:enumerator:: DSE_execExit
.. c:enumerator:: DSE_exitEntry
.. c:enumerator:: DSE_loadLibrary
.. c:enumerator:: DSE_lwpExit
.. c:enumerator:: DSE_snippetBreakpoint
.. c:enumerator:: DSE_stopThread
.. c:enumerator:: DSE_userMessage
.. c:enumerator:: DSE_dynFuncCall
.. c:var:: extern int DYNINSTdebugPrintRT
control run-time lib debug/trace prints

.. c:enum:: rtBPatch_asyncEventType
.. c:enumerator:: rtBPatch_nullEvent
.. c:enumerator:: rtBPatch_newConnectionEvent
.. c:enumerator:: rtBPatch_internalShutDownEvent
.. c:enumerator:: rtBPatch_threadCreateEvent
.. c:enumerator:: rtBPatch_threadDestroyEvent
.. c:enumerator:: rtBPatch_dynamicCallEvent
.. c:enumerator:: rtBPatch_userEvent
.. c:function:: const char *asyncEventType2str(rtBPatch_asyncEventType)
.. c:struct:: rtBPatch_asyncEventRecord
.. c:member:: unsigned int pid
.. c:member:: rtBPatch_asyncEventType type
.. c:member:: unsigned int event_fd
.. c:member:: unsigned int size
.. c:struct:: BPatch_dynamicCallRecord
.. c:member:: void *call_site_addr
.. c:member:: void *call_target
.. c:struct:: BPatch_newThreadEventRecord
.. c:member:: int ppid
Parent process's pid
.. c:member:: dyntid_t tid
Thread library ID for thread
.. c:member:: int lwp
OS id for thread
.. c:member:: int index
The dyninst index for this thread
.. c:member:: void *stack_addr
The top of this thread's stack
.. c:member:: void *start_pc
The pc of this threads initial function
......
.. rubric::
Only defined for x86_64. Cannot use MUTATEE_32 here b/c libdyninstAPI.so compiles this.
.. c:struct:: BPatch_dynamicCallRecord32
These are the 32 bit structures for use with 32 bit mutatees on AMD64
.. c:member:: unsigned int call_site_addr
.. c:member:: unsigned int call_target
.. c:struct:: BPatch_newThreadEventRecord32
.. c:member:: int ppid
Parent process's pid
.. c:member:: unsigned int tid
Thread library ID for thread
.. c:member:: int lwp
OS id for thread
.. c:member:: int index
The dyninst index for this thread
.. c:member:: unsigned int stack_addr
The top of this thread's stack
.. c:member:: unsigned int start_pc
The pc of this threads initial function
......
. c:struct:: BPatch_deleteThreadEventRecord
.. c:member:: int index
Index of the dead thread
.. c:var:: extern int DYNINST_break_point_event
.. c:struct:: trapMapping_t
.. c:member:: void *source
.. c:member:: void *target
.. c:struct:: trap_mapping_header
.. c:member:: uint32_t signature
.. c:member:: uint32_t num_entries
.. c:member:: int32_t pos
.. c:member:: uint32_t padding
.. c:member:: uint64_t low_entry
.. c:member:: uint64_t high_entry
.. c:member:: trapMapping_t traps[]
Don't change this to a pointer, despite any compiler warnings
.. c:struct:: MemoryMapperCopyElement
.. c:member:: long start
.. c:member:: long size
.. c:struct:: MemoryMapperElement
.. c:member:: unsigned long lo
.. c:member:: unsigned long hi
.. c:member:: long shift
.. c:member:: MemoryMapperCopyElement *copyList
.. c:struct:: MemoryMapper
.. c:member:: int guard1
.. c:member:: int guard2
.. c:member:: int size
.. c:member:: int padding
.. c:member:: MemoryMapperElement elements[MAX_MEMORY_MAPPER_ELEMENTS]
......
.. rubric::
32/64 bit versions for the mutator
.. c:struct:: MemoryMapperElement32
.. c:member:: uint32_t lo
.. c:member:: uint32_t hi
.. c:member:: uint32_t shift
.. c:member:: void *copyList
.. c:struct:: MemoryMapperElement64
.. c:member:: uint64_t lo
.. c:member:: uint64_t hi
.. c:member:: uint64_t shift
.. c:member:: void *copyList
.. c:struct:: MemoryMapper32
.. c:member:: int guard1
.. c:member:: int guard2
.. c:member:: int size
.. c:member:: int padding
.. c:member:: MemoryMapperElement32 elements[MAX_MEMORY_MAPPER_ELEMENTS]
.. c:struct:: MemoryMapper64
.. c:member:: int guard1
.. c:member:: int guard2
.. c:member:: int size
.. c:member:: int padding
.. c:member:: MemoryMapperElement64 elements[MAX_MEMORY_MAPPER_ELEMENTS]
.. c:var:: extern struct MemoryMapper RTmemoryMapper
62 changes: 18 additions & 44 deletions dyninstAPI_RT/h/dyninstAPI_RT.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,23 +28,9 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/

/*
* $Id: dyninstAPI_RT.h,v 1.45 2008/04/15 16:43:43 roundy Exp $
* This file contains the standard instrumentation functions that are provided
* by the run-time instrumentation layer.
*/

#ifndef _DYNINSTAPI_RT_H
#define _DYNINSTAPI_RT_H

/*
* Define the size of the per process data area.
*
* This should be a power of two to reduce paging and caching shifts.
* Note that larger sizes may result in requiring longjumps within
* mini-trampolines to reach within this area.
*/

#if !defined(target_smallmem)
#define SYN_INST_BUF_SIZE (1024*1024*4)
#else
Expand All @@ -58,7 +44,6 @@
#include "dyninstRTExport.h"
#include "common/h/compiler_diagnostics.h"

/* If we must make up a boolean type, we should make it unique */
typedef unsigned char RT_Boolean;
static const RT_Boolean RT_TRUE=1;
static const RT_Boolean RT_FALSE=0;
Expand All @@ -67,20 +52,15 @@ DLLEXPORT extern char gLoadLibraryErrorString[];
extern void *gBRKptr;

struct DYNINST_bootstrapStruct {
int event; /* "event" values:
0 --> nothing
1 --> end of DYNINSTinit (normal)
2 --> end of DYNINSTinit (forked process)
3 --> start of DYNINSTexec (before exec)
*/
int event;
int pid;
int ppid; /* parent of forked process */
int ppid;
};

typedef enum {DSE_undefined, DSE_forkEntry, DSE_forkExit, DSE_execEntry, DSE_execExit, DSE_exitEntry, DSE_loadLibrary, DSE_lwpExit, DSE_snippetBreakpoint, DSE_stopThread,
DSE_userMessage, DSE_dynFuncCall } DYNINST_synch_event_t;

extern int DYNINSTdebugPrintRT; /* control run-time lib debug/trace prints */
extern int DYNINSTdebugPrintRT;
#if !defined(RTprintf)
#define RTprintf if (DYNINSTdebugPrintRT) printf
#endif
Expand Down Expand Up @@ -116,39 +96,35 @@ typedef struct {
} BPatch_dynamicCallRecord;

typedef struct {
int ppid; /*Parent process's pid*/
dyntid_t tid; /*Thread library ID for thread*/
int lwp; /*OS id for thread*/
int index; /*The dyninst index for this thread*/
void *stack_addr; /*The top of this thread's stack*/
void *start_pc; /*The pc of this threads initial function*/
int ppid;
dyntid_t tid;
int lwp;
int index;
void *stack_addr;
void *start_pc;
} BPatch_newThreadEventRecord;

#if defined(arch_x86_64) /* cannot use MUTATEE_32 here b/c libdyninstAPI.so compiles this */
/*these are the 32 bit structures for use with 32 bit mutatees on AMD64*/
#if defined(arch_x86_64)
typedef struct {
unsigned int call_site_addr;
unsigned int call_target;
} BPatch_dynamicCallRecord32;

typedef struct {
int ppid; /*Parent process's pid*/
unsigned int tid; /*Thread library ID for thread*/
int lwp; /*OS id for thread*/
int index; /*The dyninst index for this thread*/
unsigned int stack_addr; /*The top of this thread's stack*/
unsigned int start_pc; /*The pc of this threads initial function*/
int ppid;
unsigned int tid;
int lwp;
int index;
unsigned int stack_addr;
unsigned int start_pc;
} BPatch_newThreadEventRecord32;
#endif


typedef struct {
int index; /*Index of the dead thread*/
int index;
} BPatch_deleteThreadEventRecord;

/* Let's define some constants for, well, everything.... */
/* These should be different to avoid unexpected collisions */

#if !defined(DYNINST_SINGLETHREADED)
#define DYNINST_SINGLETHREADED -128
#endif
Expand Down Expand Up @@ -178,7 +154,7 @@ struct trap_mapping_header {
uint32_t padding;
uint64_t low_entry;
uint64_t high_entry;
trapMapping_t traps[]; //Don't change this to a pointer, despite any compiler warnings
trapMapping_t traps[];
};

DYNINST_DIAGNOSTIC_END_SUPPRESS_FLEX_ARRAY
Expand All @@ -205,8 +181,6 @@ struct MemoryMapper {
MemoryMapperElement elements[MAX_MEMORY_MAPPER_ELEMENTS];
};

/* 32/64 bit versions for the mutator */

typedef struct {
uint32_t lo;
uint32_t hi;
Expand Down

0 comments on commit ec6d41d

Please sign in to comment.