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.
305 lines
19 KiB
305 lines
19 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: Stop, examine and resume application threads API</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">Stop, examine and resume application threads API</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:ga548ed1631804b58caa91ab40970bea87"><td class="memItemLeft" align="right" valign="top">BOOL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__STOPPED__THREAD__API.html#ga548ed1631804b58caa91ab40970bea87">LEVEL_PINCLIENT::PIN_StopApplicationThreads</a> (<a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid)</td></tr>
|
|
<tr class="separator:ga548ed1631804b58caa91ab40970bea87"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:gab83ac31abfc4074429c4b5cde43dbca1"><td class="memItemLeft" align="right" valign="top">BOOL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__STOPPED__THREAD__API.html#gab83ac31abfc4074429c4b5cde43dbca1">LEVEL_PINCLIENT::PIN_IsThreadStoppedInDebugger</a> (<a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid)</td></tr>
|
|
<tr class="separator:gab83ac31abfc4074429c4b5cde43dbca1"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga3b14a74ff766a0ddf12f591d53e08d2b"><td class="memItemLeft" align="right" valign="top">VOID </td><td class="memItemRight" valign="bottom"><a class="el" href="group__STOPPED__THREAD__API.html#ga3b14a74ff766a0ddf12f591d53e08d2b">LEVEL_PINCLIENT::PIN_ResumeApplicationThreads</a> (<a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid)</td></tr>
|
|
<tr class="separator:ga3b14a74ff766a0ddf12f591d53e08d2b"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga728fc728138b1049d1785f46cd8cd310"><td class="memItemLeft" align="right" valign="top">UINT32 </td><td class="memItemRight" valign="bottom"><a class="el" href="group__STOPPED__THREAD__API.html#ga728fc728138b1049d1785f46cd8cd310">LEVEL_PINCLIENT::PIN_GetStoppedThreadCount</a> ()</td></tr>
|
|
<tr class="separator:ga728fc728138b1049d1785f46cd8cd310"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga117be31fa21b8be7e73d0ef8376e2d11"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__STOPPED__THREAD__API.html#ga117be31fa21b8be7e73d0ef8376e2d11">LEVEL_PINCLIENT::PIN_GetStoppedThreadId</a> (UINT32 i)</td></tr>
|
|
<tr class="separator:ga117be31fa21b8be7e73d0ef8376e2d11"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga50dac280d3e41bea9b48974231f43dab"><td class="memItemLeft" align="right" valign="top">const <a class="el" href="group__CONTEXT__API.html#ga73f8f88949aaecf53a6d23f56399c676">CONTEXT</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__STOPPED__THREAD__API.html#ga50dac280d3e41bea9b48974231f43dab">LEVEL_PINCLIENT::PIN_GetStoppedThreadContext</a> (<a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid)</td></tr>
|
|
<tr class="separator:ga50dac280d3e41bea9b48974231f43dab"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga7154fed50af7d888d5bfd04bd70b7396"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__CONTEXT__API.html#ga73f8f88949aaecf53a6d23f56399c676">CONTEXT</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__STOPPED__THREAD__API.html#ga7154fed50af7d888d5bfd04bd70b7396">LEVEL_PINCLIENT::PIN_GetStoppedThreadWriteableContext</a> (<a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid)</td></tr>
|
|
<tr class="separator:ga7154fed50af7d888d5bfd04bd70b7396"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table>
|
|
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
|
|
<p>This API allows the user to stop all application threads, examine and modify their state and then resume them. It is available in analysis routines and internal threads. </p>
|
|
<h2 class="groupheader">Function Documentation</h2>
|
|
<a id="ga50dac280d3e41bea9b48974231f43dab"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga50dac280d3e41bea9b48974231f43dab">◆ </a></span>PIN_GetStoppedThreadContext()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">const <a class="el" href="group__CONTEXT__API.html#ga73f8f88949aaecf53a6d23f56399c676">CONTEXT</a>* LEVEL_PINCLIENT::PIN_GetStoppedThreadContext </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> </td>
|
|
<td class="paramname"><em>tid</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>This function returns the CONTEXT (register state) of a stopped application thread. The caller can inspect the stopped thread's register state via <a class="el" href="group__CONTEXT__API.html#gac1358a6179f0a63300fdf34ecf8b741d">PIN_GetContextReg()</a> and related API's.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">tid</td><td>Pin ID of a stopped thread.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>The CONTEXT for thread <em>tid</em> or NULL if that thread is not stopped.</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: Linux, Windows<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga728fc728138b1049d1785f46cd8cd310"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga728fc728138b1049d1785f46cd8cd310">◆ </a></span>PIN_GetStoppedThreadCount()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">UINT32 LEVEL_PINCLIENT::PIN_GetStoppedThreadCount </td>
|
|
<td>(</td>
|
|
<td class="paramname"></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>This function can be called in two scenarios. First, it may be called after stopping threads with <a class="el" href="group__STOPPED__THREAD__API.html#ga548ed1631804b58caa91ab40970bea87">PIN_StopApplicationThreads()</a>, in which case it tells the number of application threads that were stopped with that API.</p>
|
|
<p>Alternatively, this function may be called from a call-back that is registered via <a class="el" href="group__APPDEBUG__API.html#ga57d86fbcd855d998c28e27a8dfa56643">PIN_AddDebugInterpreter()</a>. In this case, it tells the number of application threads that are stopped in the debugger.</p>
|
|
<dl class="section return"><dt>Returns</dt><dd>The number of stopped application threads. Returns zero if threads are not currently stopped.</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: Linux, Windows<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga117be31fa21b8be7e73d0ef8376e2d11"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga117be31fa21b8be7e73d0ef8376e2d11">◆ </a></span>PIN_GetStoppedThreadId()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> LEVEL_PINCLIENT::PIN_GetStoppedThreadId </td>
|
|
<td>(</td>
|
|
<td class="paramtype">UINT32 </td>
|
|
<td class="paramname"><em>i</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>This function returns the Pin thread ID of a stopped application thread.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">i</td><td>An index in the range [0, n-1], where <em>n</em> is the value returned by <a class="el" href="group__STOPPED__THREAD__API.html#ga728fc728138b1049d1785f46cd8cd310">PIN_GetStoppedThreadCount()</a>.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>The ID of the indexed thread, which is currently stopped. Returns INVALID_THREADID if <em>i</em> is out of range.</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: Linux, Windows<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga7154fed50af7d888d5bfd04bd70b7396"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga7154fed50af7d888d5bfd04bd70b7396">◆ </a></span>PIN_GetStoppedThreadWriteableContext()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__CONTEXT__API.html#ga73f8f88949aaecf53a6d23f56399c676">CONTEXT</a>* LEVEL_PINCLIENT::PIN_GetStoppedThreadWriteableContext </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> </td>
|
|
<td class="paramname"><em>tid</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>This function is similar to <a class="el" href="group__STOPPED__THREAD__API.html#ga50dac280d3e41bea9b48974231f43dab">PIN_GetStoppedThreadContext()</a>, but it returns a CONTEXT that may be modified. The caller may modify the stopped thread's register state via <a class="el" href="group__CONTEXT__API.html#ga2369ec2d95122f62cb3673a5a3507023">PIN_SetContextReg()</a> and related API's. The stopped thread uses the new register state when it resumes.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">tid</td><td>Pin ID of a stopped thread.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>The CONTEXT for thread <em>tid</em> or NULL if that thread is not stopped.</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: Linux, Windows<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="gab83ac31abfc4074429c4b5cde43dbca1"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#gab83ac31abfc4074429c4b5cde43dbca1">◆ </a></span>PIN_IsThreadStoppedInDebugger()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">BOOL LEVEL_PINCLIENT::PIN_IsThreadStoppedInDebugger </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> </td>
|
|
<td class="paramname"><em>tid</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>This function returns true if the thread with denoted by 'tid' given by its arguments was stopped in the debugger. Note: If there is no thread with ID 'tid', this function returns false.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">tid</td><td>The Pin thread ID to check</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>TRUE if the specified thread was stopped in the debugger. FALSE indicates that the thread is either running, or doesn't exist</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: Linux, Windows<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga3b14a74ff766a0ddf12f591d53e08d2b"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga3b14a74ff766a0ddf12f591d53e08d2b">◆ </a></span>PIN_ResumeApplicationThreads()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">VOID LEVEL_PINCLIENT::PIN_ResumeApplicationThreads </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> </td>
|
|
<td class="paramname"><em>tid</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>This function may be called after a successful call to <a class="el" href="group__STOPPED__THREAD__API.html#ga548ed1631804b58caa91ab40970bea87">PIN_StopApplicationThreads()</a> in order to resume execution of the stopped application threads. If a thread's CONTEXT was changed while it was stopped, it resumes with the new CONTEXT.</p>
|
|
<p>When used in application thread, it is highly recommended to call it in the same analysis function that called <a class="el" href="group__STOPPED__THREAD__API.html#ga548ed1631804b58caa91ab40970bea87">PIN_StopApplicationThreads()</a>. Deferring the call could result in a deadlock when the thread later tries to acquire a lock held by other application thread it suspended.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">tid</td><td>The Pin thread ID of the calling thread. Should be called in the same thread as corresponding <a class="el" href="group__STOPPED__THREAD__API.html#ga548ed1631804b58caa91ab40970bea87">PIN_StopApplicationThreads()</a></td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section note"><dt>Note</dt><dd>The vm lock is obtained during the call of this API.</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: Linux, Windows & macOS*<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga548ed1631804b58caa91ab40970bea87"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga548ed1631804b58caa91ab40970bea87">◆ </a></span>PIN_StopApplicationThreads()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">BOOL LEVEL_PINCLIENT::PIN_StopApplicationThreads </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__PIN__THREAD__API.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> </td>
|
|
<td class="paramname"><em>tid</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>This function may be called by either an application thread or by a Pin internal thread to stop all other application threads at a "safe point". Threads that are stopped at a safe point are always stopped in between traces, so the caller is guaranteed that they are not stopped in the middle of any analysis functions or call-back functions. Once stopped, the calling thread can examine and modify the registers of the stopped threads.</p>
|
|
<p>If this function is called by an internal thread, it stops all application threads. If it is called by an application thread, it stops all other application threads. When called by an application thread, this function may be called from an analysis function, but not from a call-back function.</p>
|
|
<p>Since this function blocks until other application threads finish their current trace, the caller must not hold any locks that the other threads might try to acquire. Doing so could result in a deadlock.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">tid</td><td>The Pin thread ID of the calling thread.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>TRUE if the target threads are successfully stopped. FALSE indicates that some other thread is trying to stop the calling thread. In such a case, the caller should return from its analysis function to avoid a deadlock.</dd></dl>
|
|
<dl class="section note"><dt>Note</dt><dd>The vm lock is obtained during the call of this API.</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br />
|
|
<b>O/S</b>: Linux, Windows & macOS*<br />
|
|
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<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>
|