You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
218 lines
11 KiB
218 lines
11 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.13"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>Pin: Trace version APIs</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">Pin
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.13 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<div class="header">
|
|
<div class="summary">
|
|
<a href="#func-members">Functions</a> </div>
|
|
<div class="headertitle">
|
|
<div class="title">Trace version APIs</div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
|
|
Functions</h2></td></tr>
|
|
<tr class="memitem:ga92b15fcd9cc969a2139e900ced67d9c6"><td class="memItemLeft" align="right" valign="top">VOID </td><td class="memItemRight" valign="bottom"><a class="el" href="group__TRACE__VERSION__API.html#ga92b15fcd9cc969a2139e900ced67d9c6">LEVEL_PINCLIENT::BBL_SetTargetVersion</a> (BBL bbl, ADDRINT version)</td></tr>
|
|
<tr class="separator:ga92b15fcd9cc969a2139e900ced67d9c6"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga64f041866d7afab9c0760362859d060b"><td class="memItemLeft" align="right" valign="top">ADDRINT </td><td class="memItemRight" valign="bottom"><a class="el" href="group__TRACE__VERSION__API.html#ga64f041866d7afab9c0760362859d060b">LEVEL_PINCLIENT::TRACE_Version</a> (<a class="el" href="group__TRACE__BASIC__API.html#gaf9f3009a146688d5230a16f8d3e575be">TRACE</a> trace)</td></tr>
|
|
<tr class="separator:ga64f041866d7afab9c0760362859d060b"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:gad981e85ff0ffbdfea7f64a9506791126"><td class="memItemLeft" align="right" valign="top">VOID </td><td class="memItemRight" valign="bottom"><a class="el" href="group__TRACE__VERSION__API.html#gad981e85ff0ffbdfea7f64a9506791126">LEVEL_PINCLIENT::INS_InsertVersionCase</a> (INS ins, REG reg, INT32 case_value, ADDRINT version,...)</td></tr>
|
|
<tr class="separator:gad981e85ff0ffbdfea7f64a9506791126"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table>
|
|
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
|
|
<p>APIs to implement multiple types of instrumentation on traces and switch between them. Trace versioning allows the same code to be instrumented multiple times. For example, a trace can have both heavyweight and lightweight instrumentation and Pin can switch between the two while the application is running. See tests in the tools/InstrumentationOrderAndVersion directory for examples that use the versioning API's.</p>
|
|
<p>Versions are user-defined integer values. By default, all traces have a version value of 0. Tool writers insert instrumentation that switch the application between different versions values. A trace with version value N only transfers control to successor traces with version value N.</p>
|
|
<p>There are 2 ways to switch between versions. By calling BBL_SetTargetVersion on a BBL, all successor BBL's (taken and not taken path) will have the new version. BBL_SetTargetVersion can only be called once for a BBL, but it can be applied to every BBL in a trace, allowing all the exits to have different versions.</p>
|
|
<p>In addition to BBL_SetTargetVersion, it is possible to insert a dynamic test to jump to a different version based on the value of a Pin virtual register with INS_InsertVersionCase</p>
|
|
<p>Instrumentation functions can query which version is being used with TRACE_Version.</p>
|
|
<p>There are some situations where Pin will reset the version value to 0, even if executing a non 0 trace. This may occur after a system call, exception or other unusual control flow. Versioning is intended to enable lightweight instrumentation. We suggest you structure the tool so a non-zero version value is used for lightweight instrumentation and 0 is for heavyweight, but always safe to use instrumentation. </p>
|
|
<h2 class="groupheader">Function Documentation</h2>
|
|
<a id="ga92b15fcd9cc969a2139e900ced67d9c6"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga92b15fcd9cc969a2139e900ced67d9c6">◆ </a></span>BBL_SetTargetVersion()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">VOID LEVEL_PINCLIENT::BBL_SetTargetVersion </td>
|
|
<td>(</td>
|
|
<td class="paramtype">BBL </td>
|
|
<td class="paramname"><em>bbl</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">ADDRINT </td>
|
|
<td class="paramname"><em>version</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>Set the versioning for traces that can be reached from this basic block. Overrides the versioning from previous basic blocks. It is an error to set the versioning for the same basic block more than once.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">bbl</td><td>BBL to mark for versioning </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">version</td><td>make BBL have this version</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: All<br />
|
|
<b>CPU:</b> All<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="gad981e85ff0ffbdfea7f64a9506791126"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#gad981e85ff0ffbdfea7f64a9506791126">◆ </a></span>INS_InsertVersionCase()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">VOID LEVEL_PINCLIENT::INS_InsertVersionCase </td>
|
|
<td>(</td>
|
|
<td class="paramtype">INS </td>
|
|
<td class="paramname"><em>ins</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">REG </td>
|
|
<td class="paramname"><em>reg</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">INT32 </td>
|
|
<td class="paramname"><em>case_value</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">ADDRINT </td>
|
|
<td class="paramname"><em>version</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype"> </td>
|
|
<td class="paramname"><em>...</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>Insert a dynamic test to switch between versions before <em>ins</em>. If the value in <em>reg</em> matches <em>case_value</em>, then continue execution at <em>ins</em> with version <em>version</em>. Switching to a new version will cause execution to continue at a new trace starting with <em>ins</em>. This API can be called multiple times for the same instruction, creating a switch/case construct to select the version.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">ins</td><td>Insert case test before this instruction </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">reg</td><td>Virtual register used to select case. </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">case_value</td><td>Go to new version if reg contains case_value </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">version</td><td>New version to use </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>List of additional arguments (see <a class="el" href="group__INST__ARGS.html#ga089c27ca15e9ff139dd3a3f8a6f8451d">IARG_TYPE</a>), terminated with IARG_END. Currently, only IARG_CALL_ORDER is supported. For more information, see <a class="el" href="group__INST__ARGS.html#ga3d1d5f6805cb16d00bce441290ca2212">CALL_ORDER</a>.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: All<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga64f041866d7afab9c0760362859d060b"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga64f041866d7afab9c0760362859d060b">◆ </a></span>TRACE_Version()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">ADDRINT LEVEL_PINCLIENT::TRACE_Version </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__TRACE__BASIC__API.html#gaf9f3009a146688d5230a16f8d3e575be">TRACE</a> </td>
|
|
<td class="paramname"><em>trace</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>Returns the version for this trace. See <a class="el" href="group__TRACE__VERSION__API.html#ga92b15fcd9cc969a2139e900ced67d9c6">BBL_SetTargetVersion</a></p>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: All<br />
|
|
<b>CPU:</b> All<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
</div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.13
|
|
</small></address>
|
|
</body>
|
|
</html>
|