blob: d2f4cfbcd199f51f8e8c6f45a78845ab707d8a8f [file] [log] [blame]
# Tool interface functions
# The format for an interface function definition is:
# return_type, func_name, type arg, type arg
# If the function has no arguments, specify no arguments (rather than void)
#
# Comments starting with "##" are turned into C comments in the output
#
# Lines starting with : set the prefix
## These are the parameterised functions in the core. The default definitions
## are overridden by LD_PRELOADed tool version. At the very least, a tool
## must define the fundamental template functions. Depending on what needs
## are set, extra template functions will be used too. Functions are
## grouped under the needs that govern their use.
:tool
## ------------------------------------------------------------------
## Fundamental template functions
## Do initialisation that can only be done after command line processing.
void, post_clo_init
## Instrument a basic block. Must be a true function, ie. the same input
## always results in the same output, because basic blocks can be
## retranslated. Unless you're doing something really strange...
## 'orig_addr' is the address of the first instruction in the block.
UCodeBlock*, instrument, UCodeBlock* cb, Addr orig_addr
## Finish up, print out any results, etc. `exitcode' is program's exit
## code. The shadow (if the `shadow_regs' need is set) can be found with
## VG_(get_exit_status_shadow)().
void, fini, Int exitcode
## ------------------------------------------------------------------
## VG_(needs).core_errors
## (none needed)
## ------------------------------------------------------------------
## VG_(needs).skin_errors
## Identify if two errors are equal, or equal enough. `res' indicates how
## close is "close enough". `res' should be passed on as necessary, eg. if
## the Error's `extra' part contains an ExeContext, `res' should be
## passed to VG_(eq_ExeContext)() if the ExeContexts are considered. Other
## than that, probably don't worry about it unless you have lots of very
## similar errors occurring.
Bool, eq_SkinError, VgRes res, Error* e1, Error* e2
## Print error context.
void, pp_SkinError, Error* err
## Should fill in any details that could be postponed until after the
## decision whether to ignore the error (ie. details not affecting the
## result of SK_(eq_SkinError)()). This saves time when errors are ignored.
## Yuk.
## Return value: must be the size of the `extra' part in bytes -- used by
## the core to make a copy.
UInt, update_extra, Error* err
## Return value indicates recognition. If recognised, must set skind using
## VG_(set_supp_kind)().
Bool, recognised_suppression, Char* name, Supp* su
## Read any extra info for this suppression kind. Most likely for filling
## in the `extra' and `string' parts (with VG_(set_supp_{extra, string})())
## of a suppression if necessary. Should return False if a syntax error
## occurred, True otherwise.
Bool, read_extra_suppression_info, Int fd, Char* buf, Int nBuf, Supp* su
## This should just check the kinds match and maybe some stuff in the
## `string' and `extra' field if appropriate (using VG_(get_supp_*)() to
## get the relevant suppression parts).
Bool, error_matches_suppression, Error* err, Supp* su
## This should return the suppression name, for --gen-suppressions, or NULL
## if that error type cannot be suppressed. This is the inverse of
## SK_(recognised_suppression)().
Char*, get_error_name, Error* err
## This should print any extra info for the error, for --gen-suppressions,
## including the newline. This is the inverse of
## SK_(read_extra_suppression_info)().
void, print_extra_suppression_info, Error* err
## ------------------------------------------------------------------
## VG_(needs).basic_block_discards
## Should discard any information that pertains to specific basic blocks
## or instructions within the address range given.
void, discard_basic_block_info, Addr a, UInt size
## ------------------------------------------------------------------
## VG_(needs).shadow_regs
## No functions must be defined, but the post_reg[s]_write_* events should
## be tracked.
## ------------------------------------------------------------------
## VG_(needs).command_line_options
## Return True if option was recognised. Presumably sets some state to
## record the option as well.
Bool, process_cmd_line_option, Char* argv
## Print out command line usage for options for normal tool operation.
void, print_usage
## Print out command line usage for options for debugging the tool.
void, print_debug_usage
## ------------------------------------------------------------------
## VG_(needs).client_requests
## If using client requests, the number of the first request should be equal
## to VG_USERREQ_SKIN_BASE('X', 'Y'), where 'X' and 'Y' form a suitable two
## character identification for the string. The second and subsequent
## requests should follow.
## This function should use the VG_IS_SKIN_USERREQ macro (in
## include/valgrind.h) to first check if it's a request for this tool. Then
## should handle it if it's recognised (and return True), or return False if
## not recognised. arg_block[0] holds the request number, any further args
## from the request are in arg_block[1..]. 'ret' is for the return value...
## it should probably be filled, if only with 0.
Bool, handle_client_request, ThreadId tid, UInt* arg_block, UInt* ret
## ------------------------------------------------------------------
## VG_(needs).extends_UCode
## 'X' prefix indicates eXtended UCode.
Int, get_Xreg_usage, UInstr* u, Tag tag, Int* regs, Bool* isWrites
void, emit_XUInstr, UInstr* u, RRegSet regs_live_before
Bool, sane_XUInstr, Bool beforeRA, Bool beforeLiveness, UInstr* u
Char *, name_XUOpcode, Opcode opc
void, pp_XUInstr, UInstr* u
## ------------------------------------------------------------------
## VG_(needs).syscall_wrapper
## If either of the pre_ functions malloc() something to return, the
## corresponding post_ function had better free() it!
void *, pre_syscall, ThreadId tid, UInt syscallno, Bool is_blocking
void, post_syscall, ThreadId tid, UInt syscallno, void* pre_result, Int res, Bool is_blocking
## ---------------------------------------------------------------------
## VG_(needs).sanity_checks
## Can be useful for ensuring a tool's correctness. SK_(cheap_sanity_check)
## is called very frequently; SK_(expensive_sanity_check) is called less
## frequently and can be more involved.
Bool, cheap_sanity_check
Bool, expensive_sanity_check
## ================================================================================
## Event tracking functions
:track
## Events happening in core to track. To be notified, pass a callback
## function to the appropriate function. To ignore an event, don't do
## anything (default is for events to be ignored).
## Note that most events aren't passed a ThreadId. To find out the ThreadId
## of the affected thread, use VG_(get_current_or_recent_tid)(). For the
## ones passed a ThreadId, use that instead, since
## VG_(get_current_or_recent_tid)() might not give the right ThreadId in
## that case.
## Memory events (Nb: to track heap allocation/freeing, a tool must replace
## malloc() et al. See above how to do this.)
## These ones occur at startup, upon some signals, and upon some syscalls
void, new_mem_startup, Addr a, UInt len, Bool rr, Bool ww, Bool xx
void, new_mem_stack_signal, Addr a, UInt len
void, new_mem_brk, Addr a, UInt len
void, new_mem_mmap, Addr a, UInt len, Bool rr, Bool ww, Bool xx
void, copy_mem_remap, Addr from, Addr to, UInt len
void, change_mem_mprotect, Addr a, UInt len, Bool rr, Bool ww, Bool xx
void, die_mem_stack_signal, Addr a, UInt len
void, die_mem_brk, Addr a, UInt len
void, die_mem_munmap, Addr a, UInt len
## These ones are called when %esp changes. A tool could track these itself
## (except for ban_mem_stack) but it's much easier to use the core's help.
## The specialised ones are called in preference to the general one, if they
## are defined. These functions are called a lot if they are used, so
## specialising can optimise things significantly. If any of the
## specialised cases are defined, the general case must be defined too.
## Nb: they must all use the REGPARM(n) attribute.
void, new_mem_stack_4, Addr new_ESP
void, new_mem_stack_8, Addr new_ESP
void, new_mem_stack_12, Addr new_ESP
void, new_mem_stack_16, Addr new_ESP
void, new_mem_stack_32, Addr new_ESP
void, new_mem_stack, Addr a, UInt len
void, die_mem_stack_4, Addr die_ESP
void, die_mem_stack_8, Addr die_ESP
void, die_mem_stack_12, Addr die_ESP
void, die_mem_stack_16, Addr die_ESP
void, die_mem_stack_32, Addr die_ESP
void, die_mem_stack, Addr a, UInt len
## Used for redzone at end of thread stacks
void, ban_mem_stack, Addr a, UInt len
## These ones occur around syscalls, signal handling, etc
void, pre_mem_read, CorePart part, ThreadId tid, Char* s, Addr a, UInt size
void, pre_mem_read_asciiz, CorePart part, ThreadId tid, Char* s, Addr a
void, pre_mem_write, CorePart part, ThreadId tid, Char* s, Addr a, UInt size
## Not implemented yet -- have to add in lots of places, which is a
## pain. Won't bother unless/until there's a need.
## void (*post_mem_read) ( ThreadState* tst, Char* s, Addr a, UInt size );
void, post_mem_write, Addr a, UInt size
## Register events -- if `shadow_regs' need is set, all should probably be
## used. Use VG_(set_thread_shadow_archreg)() to set the shadow of the
## changed register.
## Use VG_(set_shadow_archreg)() to set the eight general purpose regs,
## and use VG_(set_shadow_eflags)() to set eflags.
void, post_regs_write_init, void
## Use VG_(set_thread_shadow_archreg)() to set the shadow regs for these
## events.
void, post_reg_write_syscall_return, ThreadId tid, UInt reg
void, post_reg_write_deliver_signal, ThreadId tid, UInt reg
void, post_reg_write_pthread_return, ThreadId tid, UInt reg
void, post_reg_write_clientreq_return, ThreadId tid, UInt reg
## This one is called for malloc() et al if they are replaced by a tool.
void, post_reg_write_clientcall_return, ThreadId tid, UInt reg, Addr f
## Scheduler events (not exhaustive)
void, thread_run, ThreadId tid
## Thread events (not exhaustive)
## Called during thread create, before the new thread has run any
## instructions (or touched any memory).
void, post_thread_create, ThreadId tid, ThreadId child
void, post_thread_join, ThreadId joiner, ThreadId joinee
## Mutex events (not exhaustive)
## "void *mutex" is really a pthread_mutex *
## Called before a thread can block while waiting for a mutex (called
## regardless of whether the thread will block or not).
void, pre_mutex_lock, ThreadId tid, void* mutex
## Called once the thread actually holds the mutex (always paired with
## pre_mutex_lock).
void, post_mutex_lock, ThreadId tid, void* mutex
## Called after a thread has released a mutex (no need for a corresponding
## pre_mutex_unlock, because unlocking can't block).
void, post_mutex_unlock, ThreadId tid, void* mutex
## Signal events (not exhaustive)
## ... pre_send_signal, post_send_signal ...
## Called before a signal is delivered; `alt_stack' indicates if it is
## delivered on an alternative stack.
void, pre_deliver_signal, ThreadId tid, Int sigNo, Bool alt_stack
## Called after a signal is delivered. Nb: unfortunately, if the signal
## handler longjmps, this won't be called.
void, post_deliver_signal, ThreadId tid, Int sigNo
## Others... condition variable...
## ...
## Shadow memory management
void, init_shadow_page, Addr p
## ================================================================================
## malloc and friends
:malloc
void*, malloc, Int n
void*, __builtin_new, Int n
void*, __builtin_vec_new, Int n
void*, memalign, Int align, Int n
void*, calloc, Int nmemb, Int n
void, free, void* p
void, __builtin_delete, void* p
void, __builtin_vec_delete, void* p
void*, realloc, void* p, Int size