ext/drutil/drutil.h

/* **********************************************************
 * Copyright (c) 2010-2014 Google, Inc.   All rights reserved.
 * **********************************************************/

/* drutil: DynamoRIO Instrumentation Utilities
 * Derived from Dr. Memory: the memory debugger
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License, and no later version.

 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Library General Public License for more details.

 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

/* DynamoRIO Instrumentation Utilities Extension */

#ifndef _DRUTIL_H_
#define _DRUTIL_H_ 1

/**
 * @file drutil.h
 * @brief Header for DynamoRIO Instrumentation Utilities Extension
 */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \addtogroup drutil Instrumentation Utilities
 */
/*@{*/ /* begin doxygen group */

/***************************************************************************
 * INIT
 */

DR_EXPORT
/**
 * Initializes the drutil extension.  Must be called prior to any of the
 * other routines.  Can be called multiple times (by separate components,
 * normally) but each call must be paired with a corresponding call to
 * drutil_exit().
 *
 * \return whether successful.
 */
bool
drutil_init(void);

DR_EXPORT
/**
 * Cleans up the drutil extension.
 */
void
drutil_exit(void);


/***************************************************************************
 * MEMORY TRACING
 */

DR_EXPORT
/**
 * Inserts instructions prior to \p where in \p bb that determine and
 * store the memory address referred to by \p memref into the register
 * \p dst.  May clobber the register \p scratch.  Supports far memory
 * references. For far memory references via DS and ES, we assume that
 * the segment base is 0.
 *
 * All registers used in \p memref must hold their original
 * application values in order for the proper address to be computed
 * into \p dst.  The \p dst register may overlap with the registers
 * used in \p memref, but \p scratch must be different from those used
 * in \p memref (as well as from \p dst).
 *
 * To obtain each memory address referenced in a single-instruction
 * string loop, use drutil_expand_rep_string() to transform such loops
 * into regular loops containing (non-loop) string instructions.
 *
 * \return whether successful.
 */
bool
drutil_insert_get_mem_addr(void *drcontext, instrlist_t *bb, instr_t *where,
                           opnd_t memref, reg_id_t dst, reg_id_t scratch);

DR_EXPORT
/**
 * Returns the size of the memory reference \p memref in bytes.
 * To handle OP_enter, requires the containing instruction \p inst
 * to be passed in.
 * For single-instruction string loops, returns the size referenced
 * by each iteration.
 */
uint
drutil_opnd_mem_size_in_bytes(opnd_t memref, instr_t *inst);

DR_EXPORT
/**
 * Expands single-instruction string loops (those using the \p rep or
 * \p repne prefixes) into regular loops to simplify memory usage
 * analysis.  This is accomplished by arranging for each
 * single-instruction string loop to occupy a basic block by itself
 * (by truncating the prior block before the loop, and truncating
 * instructions after the loop) and then exanding it into a
 * multi-instruction loop.
 *
 * WARNING: The added multi-instruction loop contains several
 * control-transfer instructions and is not straight-line code, which
 * can complicate subsequent analysis routines.
 *
 * WARNING: The added instructions have translations that are in the
 * middle of the original string loop instruction.  This is to prevent
 * passes that match exact addresses from having multiple hits and
 * doing something like inserting 6 clean calls.
 *
 * WARNING: The added instructions include a jecxz instruction which
 * will not be transformed into a 32-bit-reach instruction: thus,
 * excessive added instrumentation may result in a reachability problem.
 *
 * The client must use the \p drmgr Extension to order its
 * instrumentation in order to use this function.  This function must
 * be called from the application-to-application ("app2app") stage
 * (see drmgr_register_bb_app2app_event()).
 *
 * This transformation is deterministic, so the caller can return
 * DR_EMIT_DEFAULT from its event.
 *
 * \return whether successful.
 */
bool
drutil_expand_rep_string(void *drcontext, instrlist_t *bb);

DR_EXPORT
/**
 * Identical to drutil_expand_rep_string() but returns additional information.
 *
 * @param[in]  drcontext   The opaque context
 * @param[in]  bb          Instruction list passed to the app2app event
 * @param[out] expanded    Whether any expansion occurred
 * @param[out] stringop    The string instruction in the expanded loop
 *
 * \return whether successful.
 */
bool
drutil_expand_rep_string_ex(void *drcontext, instrlist_t *bb, OUT bool *expanded,
                            OUT instr_t **stringop);


/*@}*/ /* end doxygen group */

#ifdef __cplusplus
}
#endif

#endif /* _DRUTIL_H_ */