blob: ae8d0700db88f9bba2cf7db02b7b601288799860 [file] [log] [blame]
/* **********************************************************
* Copyright (c) 2010-2021 Google, Inc. All rights reserved.
* Copyright (c) 2002-2010 VMware, Inc. All rights reserved.
* **********************************************************/
/*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* * Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* * Neither the name of VMware, Inc. nor the names of its contributors may be
* used to endorse or promote products derived from this software without
* specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL VMWARE, INC. OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
* DAMAGE.
*/
#ifndef _DR_IR_INSTRLIST_H_
#define _DR_IR_INSTRLIST_H_ 1
/****************************************************************************
* INSTRLIST ROUTINES
*/
/**
* @file dr_ir_instrlist.h
* @brief Functions to create and manipulate lists of instructions.
*/
DR_API
/** Returns an initialized instrlist_t allocated on the thread-local heap. */
instrlist_t *
instrlist_create(void *drcontext);
DR_API
/** Initializes \p ilist. */
void
instrlist_init(instrlist_t *ilist);
DR_API
/** Deallocates the thread-local heap storage for \p ilist. */
void
instrlist_destroy(void *drcontext, instrlist_t *ilist);
DR_API
/** Frees the instructions in \p ilist. */
void
instrlist_clear(void *drcontext, instrlist_t *ilist);
DR_API
/** Destroys the instructions in \p ilist and destroys the instrlist_t object itself. */
void
instrlist_clear_and_destroy(void *drcontext, instrlist_t *ilist);
DR_API
/**
* All future instructions inserted into \p ilist that do not have raw bits
* will have instr_set_translation() called with \p pc as the target.
* This is a convenience routine to make it easy to have the same
* code generate non-translation and translation instructions, and it does
* not try to enforce that all instructions have translations (e.g.,
* some could be inserted via instr_set_next()).
*/
void
instrlist_set_translation_target(instrlist_t *ilist, app_pc pc);
DR_API
/** Returns the translation target, or NULL if none is set. */
app_pc
instrlist_get_translation_target(instrlist_t *ilist);
/* not exported: for PR 267260 */
void
instrlist_set_our_mangling(instrlist_t *ilist, bool ours);
DR_API
/**
* All future instructions inserted into \p ilist will be predicated
* with \p pred. This is a convenience routine to make it easy to have
* emitted code from internal DR components predicated.
*
* \note only has an effect on ARM
*
* \note clients may not emit instrumentation that writes to flags, nor
* may clients insert cti's. Internal DR components such as
* \p dr_insert_clean_call() handle auto predication gracefully and are
* thus safe for use with auto predication.
*/
void
instrlist_set_auto_predicate(instrlist_t *ilist, dr_pred_type_t pred);
DR_API
/** Returns the predicate for \p ilist. */
dr_pred_type_t
instrlist_get_auto_predicate(instrlist_t *ilist);
DR_API
/** Returns the first instr_t in \p ilist. */
instr_t *
instrlist_first(instrlist_t *ilist);
DR_API
/**
* Returns the first application (non-meta) instruction in the instruction list
* \p ilist.
*
* \note All preceding meta instructions will be skipped.
*
* \note We recommend using this routine during the phase of application
* code analysis, as any non-app instructions present are guaranteed to be ok
* to skip.
* However, caution should be exercised if using this routine after any
* instrumentation insertion has already happened, as instrumentation might
* affect register usage or other factors being analyzed.
*/
instr_t *
instrlist_first_app(instrlist_t *ilist);
DR_API
/**
* Returns the first instruction in the instruction list \p ilist for which
* instr_is_label() returns false.
*/
instr_t *
instrlist_first_nonlabel(instrlist_t *ilist);
DR_API
/** Returns the last instr_t in \p ilist. */
instr_t *
instrlist_last(instrlist_t *ilist);
DR_API
/**
* Returns the last application (non-meta) instruction in the instruction list
* \p ilist.
*
* \note All preceding meta instructions will be skipped.
*
* \note We recommend using this routine during the phase of application
* code analysis, as any non-app instructions present are guaranteed to be ok
* to skip.
* However, caution should be exercised if using this routine after any
* instrumentation insertion has already happened, as instrumentation might
* affect register usage or other factors being analyzed.
*/
instr_t *
instrlist_last_app(instrlist_t *ilist);
DR_API
/** Cuts off subsequent instructions starting from \p instr from \p ilist. */
void
instrlist_cut(instrlist_t *ilist, instr_t *instr);
DR_API
/** Adds \p instr to the end of \p ilist. */
void
instrlist_append(instrlist_t *ilist, instr_t *instr);
DR_API
/** Adds \p instr to the front of \p ilist. */
void
instrlist_prepend(instrlist_t *ilist, instr_t *instr);
DR_API
/**
* Allocates a new instrlist_t and for each instr_t in \p old allocates
* a new instr_t using instr_clone to produce a complete copy of \p old.
* Each operand that is opnd_is_instr() has its target updated
* to point to the corresponding instr_t in the new instrlist_t
* (this routine assumes that all such targets are contained within \p old,
* and may fault otherwise).
*/
instrlist_t *
instrlist_clone(void *drcontext, instrlist_t *old);
DR_API
/** Inserts \p instr into \p ilist prior to \p where. */
void
instrlist_preinsert(instrlist_t *ilist, instr_t *where, instr_t *instr);
DR_API
/** Inserts \p instr into \p ilist after \p where. */
void
instrlist_postinsert(instrlist_t *ilist, instr_t *where, instr_t *instr);
DR_API
/** Replaces \p oldinst with \p newinst in \p ilist (does not destroy \p oldinst). */
instr_t *
instrlist_replace(instrlist_t *ilist, instr_t *oldinst, instr_t *newinst);
DR_API
/** Removes (does not destroy) \p instr from \p ilist. */
void
instrlist_remove(instrlist_t *ilist, instr_t *instr);
DR_API
/**
* Specifies the fall-through target of a basic block if its last
* instruction is a conditional branch instruction.
* It can only be called in basic block building event callbacks
* when the \p for_trace parameter is false,
* and has NO EFFECT in other cases.
*/
bool
instrlist_set_fall_through_target(instrlist_t *bb, app_pc tgt);
DR_API
/**
* Specifies the return target of a basic block if its last
* instruction is a call instruction.
* It can only be called in basic block building event callbacks
* when the \p for_trace parameter is false,
* and has NO EFFECT in other cases.
*/
bool
instrlist_set_return_target(instrlist_t *bb, app_pc tgt);
#endif /* _DR_IR_INSTRLIST_H_ */