pub_tool_tooliface.h revision e739ac0589b4fb43561f801c4faba8c1b89f8680
19f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 29f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/*--------------------------------------------------------------------*/ 39f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/*--- The core/tool interface. pub_tool_tooliface.h ---*/ 49f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/*--------------------------------------------------------------------*/ 59f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 69f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* 79f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson This file is part of Valgrind, a dynamic binary instrumentation 89f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson framework. 99f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Copyright (C) 2000-2010 Julian Seward 119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson jseward@acm.org 129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson This program is free software; you can redistribute it and/or 149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson modify it under the terms of the GNU General Public License as 159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson published by the Free Software Foundation; either version 2 of the 169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson License, or (at your option) any later version. 179f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 189f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson This program is distributed in the hope that it will be useful, but 199f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson WITHOUT ANY WARRANTY; without even the implied warranty of 209f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 219f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson General Public License for more details. 229f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 239f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson You should have received a copy of the GNU General Public License 249f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson along with this program; if not, write to the Free Software 259f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 269f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 02111-1307, USA. 279f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 289f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson The GNU General Public License is contained in the file COPYING. 299f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson*/ 309f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 319f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson#ifndef __PUB_TOOL_TOOLIFACE_H 329f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson#define __PUB_TOOL_TOOLIFACE_H 339f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 349f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson#include "pub_tool_errormgr.h" // for Error, Supp 359f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson#include "libvex.h" // for all Vex stuff 369f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 379f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* ------------------------------------------------------------------ */ 389f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* The interface version */ 399f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 409f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Initialise tool. Must do the following: 419f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - initialise the `details' struct, via the VG_(details_*)() functions 429f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - register the basic tool functions, via VG_(basic_tool_funcs)(). 439f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson May do the following: 449f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - initialise the `needs' struct to indicate certain requirements, via 459f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson the VG_(needs_*)() functions 469f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - any other tool-specific initialisation 479f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson*/ 489f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void (*VG_(tl_pre_clo_init)) ( void ); 499f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 509f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Every tool must include this macro somewhere, exactly once. The 519f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson interface version is no longer relevant, but we kept the same name 529f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson to avoid requiring changes to tools. 539f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson*/ 549f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson#define VG_DETERMINE_INTERFACE_VERSION(pre_clo_init) \ 559f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson void (*VG_(tl_pre_clo_init)) ( void ) = pre_clo_init; 569f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 579f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* ------------------------------------------------------------------ */ 589f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Basic tool functions */ 599f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 609f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* The tool_instrument function is passed as a callback to 619f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson LibVEX_Translate. VgCallbackClosure carries additional info 629f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson which the instrumenter might like to know, but which is opaque to 639f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Vex. 649f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson*/ 659f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsontypedef 669f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson struct { 679f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Addr64 nraddr; /* non-redirected guest address */ 689f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Addr64 readdr; /* redirected guest address */ 699f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson ThreadId tid; /* tid requesting translation */ 709f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson } 719f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson VgCallbackClosure; 729f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 739f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(basic_tool_funcs)( 749f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Do any initialisation that can only be done after command line 759f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // processing. 769f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson void (*post_clo_init)(void), 779f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 789f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Instrument a basic block. Must be a true function, ie. the same 799f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // input always results in the same output, because basic blocks 809f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // can be retranslated, unless you're doing something really 819f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // strange. Anyway, the arguments. Mostly they are straightforward 829f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // except for the distinction between redirected and non-redirected 839f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // guest code addresses, which is important to understand. 849f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 859f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // VgCallBackClosure* closure contains extra arguments passed 869f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // from Valgrind to the instrumenter, which Vex doesn't know about. 879f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // You are free to look inside this structure. 889f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 899f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // * closure->tid is the ThreadId of the thread requesting the 909f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // translation. Not sure why this is here; perhaps callgrind 919f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // uses it. 929f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 939f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // * closure->nraddr is the non-redirected guest address of the 949f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // start of the translation. In other words, the translation is 959f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // being constructed because the guest program jumped to 969f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // closure->nraddr but no translation of it was found. 979f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 989f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // * closure->readdr is the redirected guest address, from which 999f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // the translation was really made. 1009f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1019f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // To clarify this, consider what happens when, in Memcheck, the 1029f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // first call to malloc() happens. The guest program will be 1039f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // trying to jump to malloc() in libc; hence ->nraddr will contain 1049f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // that address. However, Memcheck intercepts and replaces 1059f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // malloc, hence ->readdr will be the address of Memcheck's 1069f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // malloc replacement in 1079f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // coregrind/m_replacemalloc/vg_replacemalloc.c. It follows 1089f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // that the first IMark in the translation will be labelled as 1099f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // from ->readdr rather than ->nraddr. 1109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Since most functions are not redirected, the majority of the 1129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // time ->nraddr will be the same as ->readdr. However, you 1139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // cannot assume this: if your tool has metadata associated 1149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // with code addresses it will get into deep trouble if it does 1159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // make this assumption. 1169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1179f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // IRSB* sb_in is the incoming superblock to be instrumented, 1189f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // in flat IR form. 1199f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1209f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // VexGuestLayout* layout contains limited info on the layout of 1219f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // the guest state: where the stack pointer and program counter 1229f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // are, and which fields should be regarded as 'always defined'. 1239f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Memcheck uses this. 1249f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1259f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // VexGuestExtents* vge points to a structure which states the 1269f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // precise byte ranges of original code from which this translation 1279f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // was made (there may be up to three different ranges involved). 1289f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Note again that these are the real addresses from which the code 1299f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // came. And so it should be the case that closure->readdr is the 1309f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // same as vge->base[0]; indeed Cachegrind contains this assertion. 1319f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1329f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Tools which associate shadow data with code addresses 1339f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // (cachegrind, callgrind) need to be particularly clear about 1349f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // whether they are making the association with redirected or 1359f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // non-redirected code addresses. Both approaches are viable 1369f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // but you do need to understand what's going on. See comments 1379f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // below on discard_basic_block_info(). 1389f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1399f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // IRType gWordTy and IRType hWordTy contain the types of native 1409f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // words on the guest (simulated) and host (real) CPUs. They will 1419f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // by either Ity_I32 or Ity_I64. So far we have never built a 1429f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // cross-architecture Valgrind so they should always be the same. 1439f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // 1449f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /* --- Further comments about the IR that your --- */ 1459f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /* --- instrumentation function will receive. --- */ 1469f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /* 1479f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson In the incoming IRSB, the IR for each instruction begins with an 1489f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson IRStmt_IMark, which states the address and length of the 1499f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson instruction from which this IR came. This makes it easy for 1509f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson profiling-style tools to know precisely which guest code 1519f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson addresses are being executed. 1529f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1539f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson However, before the first IRStmt_IMark, there may be other IR 1549f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson statements -- a preamble. In most cases this preamble is empty, 1559f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson but when it isn't, what it contains is some supporting IR that 1569f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson the JIT uses to ensure control flow works correctly. This 1579f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson preamble does not modify any architecturally defined guest state 1589f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson (registers or memory) and so does not contain anything that will 1599f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson be of interest to your tool. 1609f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1619f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson You should therefore 1629f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1639f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson (1) copy any IR preceding the first IMark verbatim to the start 1649f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson of the output IRSB. 1659f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1669f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson (2) not try to instrument it or modify it in any way. 1679f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1689f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson For the record, stuff that may be in the preamble at 1699f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson present is: 1709f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1719f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - A self-modifying-code check has been requested for this block. 1729f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson The preamble will contain instructions to checksum the block, 1739f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson compare against the expected value, and exit the dispatcher 1749f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson requesting a discard (hence forcing a retranslation) if they 1759f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson don't match. 1769f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1779f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - This block is known to be the entry point of a wrapper of some 1789f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson function F. In this case the preamble contains code to write 1799f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson the address of the original F (the fn being wrapped) into a 1809f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 'hidden' guest state register _NRADDR. The wrapper can later 1819f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson read this register using a client request and make a 1829f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson non-redirected call to it using another client-request-like 1839f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson magic macro. 1849f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1859f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - For platforms that use the AIX ABI (including ppc64-linux), it 1869f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson is necessary to have a preamble even for replacement functions 1879f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson (not just for wrappers), because it is necessary to switch the 1889f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson R2 register (constant-pool pointer) to a different value when 1899f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson swizzling the program counter. 1909f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1919f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Hence the preamble pushes both R2 and LR (the return address) 1929f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson on a small 16-entry stack in the guest state and sets R2 to an 1939f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson appropriate value for the wrapper/replacement fn. LR is then 1949f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson set so that the wrapper/replacement fn returns to a magic IR 1959f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson stub which restores R2 and LR and returns. 1969f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 1979f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson It's all hugely ugly and fragile. And it places a stringent 1989f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson requirement on m_debuginfo to find out the correct R2 (toc 1999f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson pointer) value for the wrapper/replacement function. So much 2009f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson so that m_redir will refuse to honour a redirect-to-me request 2019f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson if it cannot find (by asking m_debuginfo) a plausible R2 value 2029f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson for 'me'. 2039f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2049f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Because this mechanism maintains a shadow stack of (R2,LR) 2059f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson pairs in the guest state, it will fail if the 2069f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson wrapper/redirection function, or anything it calls, longjumps 2079f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson out past the wrapper, because then the magic return stub will 2089f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson not be run and so the shadow stack will not be popped. So it 2099f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson will quickly fill up. Fortunately none of this applies to 2109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson {x86,amd64,ppc32}-linux; on those platforms, wrappers can 2119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson longjump and recurse arbitrarily and everything should work 2129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson fine. 2139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Note that copying the preamble verbatim may cause complications 2159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson for your instrumenter if you shadow IR temporaries. See big 2169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson comment in MC_(instrument) in memcheck/mc_translate.c for 2179f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson details. 2189f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 2199f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson IRSB*(*instrument)(VgCallbackClosure* closure, 2209f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson IRSB* sb_in, 2219f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson VexGuestLayout* layout, 2229f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson VexGuestExtents* vge, 2239f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson IRType gWordTy, 2249f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson IRType hWordTy), 2259f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2269f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Finish up, print out any results, etc. `exitcode' is program's exit 2279f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // code. The shadow can be found with VG_(get_exit_status_shadow)(). 2289f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson void (*fini)(Int) 2299f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson); 2309f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2319f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* ------------------------------------------------------------------ */ 2329f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Details */ 2339f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2349f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Default value for avg_translations_sizeB (in bytes), indicating typical 2359f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson code expansion of about 6:1. */ 2369f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson#define VG_DEFAULT_TRANS_SIZEB 172 2379f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2389f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Information used in the startup message. `name' also determines the 2399f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson string used for identifying suppressions in a suppression file as 2409f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson belonging to this tool. `version' can be NULL, in which case (not 2419f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson surprisingly) no version info is printed; this mechanism is designed for 2429f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson tools distributed with Valgrind that share a version number with 2439f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Valgrind. Other tools not distributed as part of Valgrind should 2449f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson probably have their own version number. */ 2459f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(details_name) ( Char* name ); 2469f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(details_version) ( Char* version ); 2479f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(details_description) ( Char* description ); 2489f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(details_copyright_author) ( Char* copyright_author ); 2499f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2509f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Average size of a translation, in bytes, so that the translation 2519f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson storage machinery can allocate memory appropriately. Not critical, 2529f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson setting is optional. */ 2539f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(details_avg_translation_sizeB) ( UInt size ); 2549f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2559f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* String printed if an `tl_assert' assertion fails or VG_(tool_panic) 2569f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson is called. Should probably be an email address. */ 2579f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(details_bug_reports_to) ( Char* bug_reports_to ); 2589f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2599f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* ------------------------------------------------------------------ */ 2609f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Needs */ 2619f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2629f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Should __libc_freeres() be run? Bugs in it can crash the tool. */ 2639f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(needs_libc_freeres) ( void ); 2649f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2659f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Want to have errors detected by Valgrind's core reported? Includes: 2669f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - pthread API errors (many; eg. unlocking a non-locked mutex) 2679f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson [currently disabled] 2689f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - invalid file descriptors to syscalls like read() and write() 2699f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - bad signal numbers passed to sigaction() 2709f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson - attempt to install signal handler for SIGKILL or SIGSTOP */ 2719f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(needs_core_errors) ( void ); 2729f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2739f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Booleans that indicate extra operations are defined; if these are True, 2749f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson the corresponding template functions (given below) must be defined. A 2759f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson lot like being a member of a type class. */ 2769f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2779f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* Want to report errors from tool? This implies use of suppressions, too. */ 2789f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonextern void VG_(needs_tool_errors) ( 2799f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Identify if two errors are equal, or close enough. This function is 2809f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // only called if e1 and e2 will have the same error kind. `res' indicates 2819f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // how close is "close enough". `res' should be passed on as necessary, 2829f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // eg. if the Error's `extra' part contains an ExeContext, `res' should be 2839f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // passed to VG_(eq_ExeContext)() if the ExeContexts are considered. Other 2849f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // than that, probably don't worry about it unless you have lots of very 2859f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // similar errors occurring. 2869f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Bool (*eq_Error)(VgRes res, Error* e1, Error* e2), 2879f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2889f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // We give tools a chance to have a look at errors 2899f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // just before they are printed. That is, before_pp_Error is 2909f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // called just before pp_Error itself. This gives the tool a 2919f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // chance to look at the just-about-to-be-printed error, so as to 2929f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // emit any arbitrary output if wants to, before the error itself 2939f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // is printed. This functionality was added to allow Helgrind to 2949f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // print thread-announcement messages immediately before the 2959f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // errors that refer to them. 2969f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson void (*before_pp_Error)(Error* err), 2979f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 2989f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Print error context. 2999f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson void (*pp_Error)(Error* err), 3009f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 3019f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Should the core indicate which ThreadId each error comes from? 3029f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Bool show_ThreadIDs_for_errors, 3039f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 3049f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Should fill in any details that could be postponed until after the 3059f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // decision whether to ignore the error (ie. details not affecting the 3069f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // result of VG_(tdict).tool_eq_Error()). This saves time when errors 3079f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // are ignored. 3089f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Yuk. 3099f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Return value: must be the size of the `extra' part in bytes -- used by 3109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // the core to make a copy. 3119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson UInt (*update_extra)(Error* err), 3129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 3139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // Return value indicates recognition. If recognised, must set skind using 3149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson // VG_(set_supp_kind)(). 3159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson Bool (*recognised_suppression)(Char* name, Supp* su), 316 317 // Read any extra info for this suppression kind. Most likely for filling 318 // in the `extra' and `string' parts (with VG_(set_supp_{extra, string})()) 319 // of a suppression if necessary. Should return False if a syntax error 320 // occurred, True otherwise. bufpp and nBufp are the same as for 321 // VG_(get_line). 322 Bool (*read_extra_suppression_info)(Int fd, Char** bufpp, SizeT* nBufp, 323 Supp* su), 324 325 // This should just check the kinds match and maybe some stuff in the 326 // `string' and `extra' field if appropriate (using VG_(get_supp_*)() to 327 // get the relevant suppression parts). 328 Bool (*error_matches_suppression)(Error* err, Supp* su), 329 330 // This should return the suppression name, for --gen-suppressions, or NULL 331 // if that error type cannot be suppressed. This is the inverse of 332 // VG_(tdict).tool_recognised_suppression(). 333 Char* (*get_error_name)(Error* err), 334 335 // This should print into buf[0..nBuf-1] any extra info for the 336 // error, for --gen-suppressions, but not including any leading 337 // spaces nor a trailing newline. When called, buf[0 .. nBuf-1] 338 // will be zero filled, and it is expected and checked that the 339 // last element is still zero after the call. In other words the 340 // tool may not overrun the buffer, and this is checked for. If 341 // there is any info printed in the buffer, return True, otherwise 342 // do nothing, and return False. This function is the inverse of 343 // VG_(tdict).tool_read_extra_suppression_info(). 344 Bool (*print_extra_suppression_info)(Error* err, 345 /*OUT*/Char* buf, Int nBuf) 346); 347 348/* Is information kept by the tool about specific instructions or 349 translations? (Eg. for cachegrind there are cost-centres for every 350 instruction, stored in a per-translation fashion.) If so, the info 351 may have to be discarded when translations are unloaded (eg. due to 352 .so unloading, or otherwise at the discretion of m_transtab, eg 353 when the table becomes too full) to avoid stale information being 354 reused for new translations. */ 355extern void VG_(needs_superblock_discards) ( 356 // Discard any information that pertains to specific translations 357 // or instructions within the address range given. There are two 358 // possible approaches. 359 // - If info is being stored at a per-translation level, use orig_addr 360 // to identify which translation is being discarded. Each translation 361 // will be discarded exactly once. 362 // This orig_addr will match the closure->nraddr which was passed to 363 // to instrument() (see extensive comments above) when this 364 // translation was made. Note that orig_addr won't necessarily be 365 // the same as the first address in "extents". 366 // - If info is being stored at a per-instruction level, you can get 367 // the address range(s) being discarded by stepping through "extents". 368 // Note that any single instruction may belong to more than one 369 // translation, and so could be covered by the "extents" of more than 370 // one call to this function. 371 // Doing it the first way (as eg. Cachegrind does) is probably easier. 372 void (*discard_superblock_info)(Addr64 orig_addr, VexGuestExtents extents) 373); 374 375/* Tool defines its own command line options? */ 376extern void VG_(needs_command_line_options) ( 377 // Return True if option was recognised, False if it wasn't (but also see 378 // below). Presumably sets some state to record the option as well. 379 // 380 // Nb: tools can assume that the argv will never disappear. So they can, 381 // for example, store a pointer to a string within an option, rather than 382 // having to make a copy. 383 // 384 // Options (and combinations of options) should be checked in this function 385 // if possible rather than in post_clo_init(), and if they are bad then 386 // VG_(fmsg_bad_option)() should be called. This ensures that the 387 // messaging is consistent with command line option errors from the core. 388 Bool (*process_cmd_line_option)(Char* argv), 389 390 // Print out command line usage for options for normal tool operation. 391 void (*print_usage)(void), 392 393 // Print out command line usage for options for debugging the tool. 394 void (*print_debug_usage)(void) 395); 396 397/* Tool defines its own client requests? */ 398extern void VG_(needs_client_requests) ( 399 // If using client requests, the number of the first request should be equal 400 // to VG_USERREQ_TOOL_BASE('X', 'Y'), where 'X' and 'Y' form a suitable two 401 // character identification for the string. The second and subsequent 402 // requests should follow. 403 // 404 // This function should use the VG_IS_TOOL_USERREQ macro (in 405 // include/valgrind.h) to first check if it's a request for this tool. Then 406 // should handle it if it's recognised (and return True), or return False if 407 // not recognised. arg_block[0] holds the request number, any further args 408 // from the request are in arg_block[1..]. 'ret' is for the return value... 409 // it should probably be filled, if only with 0. 410 Bool (*handle_client_request)(ThreadId tid, UWord* arg_block, UWord* ret) 411); 412 413/* Tool does stuff before and/or after system calls? */ 414// Nb: If either of the pre_ functions malloc() something to return, the 415// corresponding post_ function had better free() it! 416// Also, the args are the 'original args' -- that is, it may be 417// that the syscall pre-wrapper will modify the args before the 418// syscall happens. So these args are the original, un-modified 419// args. Finally, nArgs merely indicates the length of args[..], 420// it does not indicate how many of those values are actually 421// relevant to the syscall. args[0 .. nArgs-1] is guaranteed 422// to be defined and to contain all the args for this syscall, 423// possibly including some trailing zeroes. 424extern void VG_(needs_syscall_wrapper) ( 425 void (* pre_syscall)(ThreadId tid, UInt syscallno, 426 UWord* args, UInt nArgs), 427 void (*post_syscall)(ThreadId tid, UInt syscallno, 428 UWord* args, UInt nArgs, SysRes res) 429); 430 431/* Are tool-state sanity checks performed? */ 432// Can be useful for ensuring a tool's correctness. cheap_sanity_check() 433// is called very frequently; expensive_sanity_check() is called less 434// frequently and can be more involved. 435extern void VG_(needs_sanity_checks) ( 436 Bool(*cheap_sanity_check)(void), 437 Bool(*expensive_sanity_check)(void) 438); 439 440/* Do we need to see variable type and location information? */ 441extern void VG_(needs_var_info) ( void ); 442 443/* Does the tool replace malloc() and friends with its own versions? 444 This has to be combined with the use of a vgpreload_<tool>.so module 445 or it won't work. See massif/Makefile.am for how to build it. */ 446// The 'p' prefix avoids GCC complaints about overshadowing global names. 447extern void VG_(needs_malloc_replacement)( 448 void* (*pmalloc) ( ThreadId tid, SizeT n ), 449 void* (*p__builtin_new) ( ThreadId tid, SizeT n ), 450 void* (*p__builtin_vec_new) ( ThreadId tid, SizeT n ), 451 void* (*pmemalign) ( ThreadId tid, SizeT align, SizeT n ), 452 void* (*pcalloc) ( ThreadId tid, SizeT nmemb, SizeT size1 ), 453 void (*pfree) ( ThreadId tid, void* p ), 454 void (*p__builtin_delete) ( ThreadId tid, void* p ), 455 void (*p__builtin_vec_delete) ( ThreadId tid, void* p ), 456 void* (*prealloc) ( ThreadId tid, void* p, SizeT new_size ), 457 SizeT (*pmalloc_usable_size) ( ThreadId tid, void* p), 458 SizeT client_malloc_redzone_szB 459); 460 461/* Can the tool do XML output? This is a slight misnomer, because the tool 462 * is not requesting the core to do anything, rather saying "I can handle 463 * it". */ 464extern void VG_(needs_xml_output) ( void ); 465 466/* Does the tool want to have one final pass over the IR after tree 467 building but before instruction selection? If so specify the 468 function here. */ 469extern void VG_(needs_final_IR_tidy_pass) ( IRSB*(*final_tidy)(IRSB*) ); 470 471 472/* ------------------------------------------------------------------ */ 473/* Core events to track */ 474 475/* Part of the core from which this call was made. Useful for determining 476 what kind of error message should be emitted. */ 477typedef 478 enum { Vg_CoreStartup=1, Vg_CoreSignal, Vg_CoreSysCall, 479 // This is for platforms where syscall args are passed on the 480 // stack; although pre_mem_read is the callback that will be 481 // called, such an arg should be treated (with respect to 482 // presenting information to the user) as if it was passed in a 483 // register, ie. like pre_reg_read. 484 Vg_CoreSysCallArgInMem, 485 Vg_CoreTranslate, Vg_CoreClientReq 486 } CorePart; 487 488/* Events happening in core to track. To be notified, pass a callback 489 function to the appropriate function. To ignore an event, don't do 490 anything (the default is for events to be ignored). 491 492 Note that most events aren't passed a ThreadId. If the event is one called 493 from generated code (eg. new_mem_stack_*), you can use 494 VG_(get_running_tid)() to find it. Otherwise, it has to be passed in, 495 as in pre_mem_read, and so the event signature will require changing. 496 497 Memory events (Nb: to track heap allocation/freeing, a tool must replace 498 malloc() et al. See above how to do this.) 499 500 These ones occur at startup, upon some signals, and upon some syscalls. 501 502 For new_mem_brk and new_mem_stack_signal, the supplied ThreadId 503 indicates the thread for whom the new memory is being allocated. 504 505 For new_mem_startup and new_mem_mmap, the di_handle argument is a 506 handle which can be used to retrieve debug info associated with the 507 mapping or allocation (because it is of a file that Valgrind has 508 decided to read debug info from). If the value is zero, there is 509 no associated debug info. If the value exceeds zero, it can be 510 supplied as an argument to selected queries in m_debuginfo. 511*/ 512void VG_(track_new_mem_startup) (void(*f)(Addr a, SizeT len, 513 Bool rr, Bool ww, Bool xx, 514 ULong di_handle)); 515void VG_(track_new_mem_stack_signal)(void(*f)(Addr a, SizeT len, ThreadId tid)); 516void VG_(track_new_mem_brk) (void(*f)(Addr a, SizeT len, ThreadId tid)); 517void VG_(track_new_mem_mmap) (void(*f)(Addr a, SizeT len, 518 Bool rr, Bool ww, Bool xx, 519 ULong di_handle)); 520 521void VG_(track_copy_mem_remap) (void(*f)(Addr from, Addr to, SizeT len)); 522void VG_(track_change_mem_mprotect) (void(*f)(Addr a, SizeT len, 523 Bool rr, Bool ww, Bool xx)); 524void VG_(track_die_mem_stack_signal)(void(*f)(Addr a, SizeT len)); 525void VG_(track_die_mem_brk) (void(*f)(Addr a, SizeT len)); 526void VG_(track_die_mem_munmap) (void(*f)(Addr a, SizeT len)); 527 528/* These ones are called when SP changes. A tool could track these itself 529 (except for ban_mem_stack) but it's much easier to use the core's help. 530 531 The specialised ones are called in preference to the general one, if they 532 are defined. These functions are called a lot if they are used, so 533 specialising can optimise things significantly. If any of the 534 specialised cases are defined, the general case must be defined too. 535 536 Nb: all the specialised ones must use the VG_REGPARM(n) attribute. 537 538 For the _new functions, a tool may specify with with-ECU 539 (ExeContext Unique) or without-ECU version for each size, but not 540 both. If the with-ECU version is supplied, then the core will 541 arrange to pass, as the ecu argument, a 32-bit int which uniquely 542 identifies the instruction moving the stack pointer down. This 543 32-bit value is as obtained from VG_(get_ECU_from_ExeContext). 544 VG_(get_ExeContext_from_ECU) can then be used to retrieve the 545 associated depth-1 ExeContext for the location. All this 546 complexity is provided to support origin tracking in Memcheck. 547*/ 548void VG_(track_new_mem_stack_4_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 549void VG_(track_new_mem_stack_8_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 550void VG_(track_new_mem_stack_12_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 551void VG_(track_new_mem_stack_16_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 552void VG_(track_new_mem_stack_32_w_ECU) (VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 553void VG_(track_new_mem_stack_112_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 554void VG_(track_new_mem_stack_128_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 555void VG_(track_new_mem_stack_144_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 556void VG_(track_new_mem_stack_160_w_ECU)(VG_REGPARM(2) void(*f)(Addr new_ESP, UInt ecu)); 557void VG_(track_new_mem_stack_w_ECU) (void(*f)(Addr a, SizeT len, 558 UInt ecu)); 559 560void VG_(track_new_mem_stack_4) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 561void VG_(track_new_mem_stack_8) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 562void VG_(track_new_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 563void VG_(track_new_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 564void VG_(track_new_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr new_ESP)); 565void VG_(track_new_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 566void VG_(track_new_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 567void VG_(track_new_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 568void VG_(track_new_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr new_ESP)); 569void VG_(track_new_mem_stack) (void(*f)(Addr a, SizeT len)); 570 571void VG_(track_die_mem_stack_4) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 572void VG_(track_die_mem_stack_8) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 573void VG_(track_die_mem_stack_12) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 574void VG_(track_die_mem_stack_16) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 575void VG_(track_die_mem_stack_32) (VG_REGPARM(1) void(*f)(Addr die_ESP)); 576void VG_(track_die_mem_stack_112)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 577void VG_(track_die_mem_stack_128)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 578void VG_(track_die_mem_stack_144)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 579void VG_(track_die_mem_stack_160)(VG_REGPARM(1) void(*f)(Addr die_ESP)); 580void VG_(track_die_mem_stack) (void(*f)(Addr a, SizeT len)); 581 582/* Used for redzone at end of thread stacks */ 583void VG_(track_ban_mem_stack) (void(*f)(Addr a, SizeT len)); 584 585/* These ones occur around syscalls, signal handling, etc */ 586void VG_(track_pre_mem_read) (void(*f)(CorePart part, ThreadId tid, 587 Char* s, Addr a, SizeT size)); 588void VG_(track_pre_mem_read_asciiz)(void(*f)(CorePart part, ThreadId tid, 589 Char* s, Addr a)); 590void VG_(track_pre_mem_write) (void(*f)(CorePart part, ThreadId tid, 591 Char* s, Addr a, SizeT size)); 592void VG_(track_post_mem_write) (void(*f)(CorePart part, ThreadId tid, 593 Addr a, SizeT size)); 594 595/* Register events. Use VG_(set_shadow_state_area)() to set the shadow regs 596 for these events. */ 597void VG_(track_pre_reg_read) (void(*f)(CorePart part, ThreadId tid, 598 Char* s, PtrdiffT guest_state_offset, 599 SizeT size)); 600void VG_(track_post_reg_write)(void(*f)(CorePart part, ThreadId tid, 601 PtrdiffT guest_state_offset, 602 SizeT size)); 603 604/* This one is called for malloc() et al if they are replaced by a tool. */ 605void VG_(track_post_reg_write_clientcall_return)( 606 void(*f)(ThreadId tid, PtrdiffT guest_state_offset, SizeT size, Addr f)); 607 608 609/* Scheduler events (not exhaustive) */ 610 611/* Called when 'tid' starts or stops running client code blocks. 612 Gives the total dispatched block count at that event. Note, this 613 is not the same as 'tid' holding the BigLock (the lock that ensures 614 that only one thread runs at a time): a thread can hold the lock 615 for other purposes (making translations, etc) yet not be running 616 client blocks. Obviously though, a thread must hold the lock in 617 order to run client code blocks, so the times bracketed by 618 'start_client_code'..'stop_client_code' are a subset of the times 619 when thread 'tid' holds the cpu lock. 620*/ 621void VG_(track_start_client_code)( 622 void(*f)(ThreadId tid, ULong blocks_dispatched) 623 ); 624void VG_(track_stop_client_code)( 625 void(*f)(ThreadId tid, ULong blocks_dispatched) 626 ); 627 628 629/* Thread events (not exhaustive) 630 631 ll_create: low level thread creation. Called before the new thread 632 has run any instructions (or touched any memory). In fact, called 633 immediately before the new thread has come into existence; the new 634 thread can be assumed to exist when notified by this call. 635 636 ll_exit: low level thread exit. Called after the exiting thread 637 has run its last instruction. 638 639 The _ll_ part makes it clear these events are not to do with 640 pthread_create or pthread_exit/pthread_join (etc), which are a 641 higher level abstraction synthesised by libpthread. What you can 642 be sure of from _ll_create/_ll_exit is the absolute limits of each 643 thread's lifetime, and hence be assured that all memory references 644 made by the thread fall inside the _ll_create/_ll_exit pair. This 645 is important for tools that need a 100% accurate account of which 646 thread is responsible for every memory reference in the process. 647 648 pthread_create/join/exit do not give this property. Calls/returns 649 to/from them happen arbitrarily far away from the relevant 650 low-level thread create/quit event. In general a few hundred 651 instructions; hence a few hundred(ish) memory references could get 652 misclassified each time. 653 654 pre_thread_first_insn: is called when the thread is all set up and 655 ready to go (stack in place, etc) but has not executed its first 656 instruction yet. Gives threading tools a chance to ask questions 657 about the thread (eg, what is its initial client stack pointer) 658 that are not easily answered at pre_thread_ll_create time. 659 660 For a given thread, the call sequence is: 661 ll_create (in the parent's context) 662 first_insn (in the child's context) 663 ll_exit (in the child's context) 664*/ 665void VG_(track_pre_thread_ll_create) (void(*f)(ThreadId tid, ThreadId child)); 666void VG_(track_pre_thread_first_insn)(void(*f)(ThreadId tid)); 667void VG_(track_pre_thread_ll_exit) (void(*f)(ThreadId tid)); 668 669 670/* Signal events (not exhaustive) 671 672 ... pre_send_signal, post_send_signal ... 673 674 Called before a signal is delivered; `alt_stack' indicates if it is 675 delivered on an alternative stack. */ 676void VG_(track_pre_deliver_signal) (void(*f)(ThreadId tid, Int sigNo, 677 Bool alt_stack)); 678/* Called after a signal is delivered. Nb: unfortunately, if the signal 679 handler longjmps, this won't be called. */ 680void VG_(track_post_deliver_signal)(void(*f)(ThreadId tid, Int sigNo)); 681 682#endif // __PUB_TOOL_TOOLIFACE_H 683 684/*--------------------------------------------------------------------*/ 685/*--- end ---*/ 686/*--------------------------------------------------------------------*/ 687