<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Fprobe - Function entry/exit probe — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Lockless Ring Buffer Design" href="ring-buffer-design.html" />
<link rel="prev" title="Eprobe - Event-based Probe Tracing" href="eprobetrace.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Tracing</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="index.html#introduction-to-tracing">Introduction to Tracing</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html#core-tracing-frameworks">Core Tracing Frameworks</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="ftrace.html">ftrace - Function Tracer</a></li>
<li class="toctree-l3"><a class="reference internal" href="ftrace-design.html">Function Tracer Design</a></li>
<li class="toctree-l3"><a class="reference internal" href="ftrace-uses.html">Using ftrace to hook to functions</a></li>
<li class="toctree-l3"><a class="reference internal" href="kprobes.html">Kernel Probes (Kprobes)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kprobetrace.html">Kprobe-based Event Tracing</a></li>
<li class="toctree-l3"><a class="reference internal" href="fprobetrace.html">Fprobe-based Event Tracing</a></li>
<li class="toctree-l3"><a class="reference internal" href="eprobetrace.html">Eprobe - Event-based Probe Tracing</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Fprobe - Function entry/exit probe</a></li>
<li class="toctree-l3"><a class="reference internal" href="ring-buffer-design.html">Lockless Ring Buffer Design</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="index.html#event-tracing-and-analysis">Event Tracing and Analysis</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#hardware-and-performance-tracing">Hardware and Performance Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#user-space-tracing">User-Space Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#additional-resources">Additional Resources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/trace/fprobe.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="fprobe-function-entry-exit-probe">
<h1>Fprobe - Function entry/exit probe<a class="headerlink" href="#fprobe-function-entry-exit-probe" title="Link to this heading">¶</a></h1>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<p>Fprobe is a function entry/exit probe based on the function-graph tracing
feature in ftrace.
Instead of tracing all functions, if you want to attach callbacks on specific
function entry and exit, similar to the kprobes and kretprobes, you can
use fprobe. Compared with kprobes and kretprobes, fprobe gives faster
instrumentation for multiple functions with single handler. This document
describes how to use fprobe.</p>
</section>
<section id="the-usage-of-fprobe">
<h2>The usage of fprobe<a class="headerlink" href="#the-usage-of-fprobe" title="Link to this heading">¶</a></h2>
<p>The fprobe is a wrapper of ftrace (+ kretprobe-like return callback) to
attach callbacks to multiple function entry and exit. User needs to set up
the <cite><a class="reference internal" href="#c.fprobe" title="fprobe"><code class="xref c c-struct docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span></code></a></cite> and pass it to <cite><a class="reference internal" href="#c.register_fprobe" title="register_fprobe"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe()</span></code></a></cite>.</p>
<p>Typically, <cite>fprobe</cite> data structure is initialized with the <cite>entry_handler</cite>
and/or <cite>exit_handler</cite> as below.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">fprobe</span><span class="w"> </span><span class="n">fp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="p">.</span><span class="n">entry_handler</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">my_entry_callback</span><span class="p">,</span>
<span class="w"> </span><span class="p">.</span><span class="n">exit_handler</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">my_exit_callback</span><span class="p">,</span>
<span class="p">};</span>
</pre></div>
</div>
<p>To enable the fprobe, call one of <a class="reference internal" href="#c.register_fprobe" title="register_fprobe"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe()</span></code></a>, <a class="reference internal" href="#c.register_fprobe_ips" title="register_fprobe_ips"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe_ips()</span></code></a>, and
<a class="reference internal" href="#c.register_fprobe_syms" title="register_fprobe_syms"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe_syms()</span></code></a>. These functions register the fprobe with different types
of parameters.</p>
<p>The <a class="reference internal" href="#c.register_fprobe" title="register_fprobe"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe()</span></code></a> enables a fprobe by function-name filters.
E.g. this enables @fp on “func*()” function except “<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">func2()</span></code>”.:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>register_fprobe(&fp, "func*", "func2");
</pre></div>
</div>
<p>The <a class="reference internal" href="#c.register_fprobe_ips" title="register_fprobe_ips"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe_ips()</span></code></a> enables a fprobe by ftrace-location addresses.
E.g.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="n">ips</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">0</span><span class="n">x</span><span class="p">....</span><span class="w"> </span><span class="p">};</span>
<span class="n">register_fprobe_ips</span><span class="p">(</span><span class="o">&</span><span class="n">fp</span><span class="p">,</span><span class="w"> </span><span class="n">ips</span><span class="p">,</span><span class="w"> </span><span class="n">ARRAY_SIZE</span><span class="p">(</span><span class="n">ips</span><span class="p">));</span>
</pre></div>
</div>
<p>And the <a class="reference internal" href="#c.register_fprobe_syms" title="register_fprobe_syms"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe_syms()</span></code></a> enables a fprobe by symbol names.
E.g.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">char</span><span class="w"> </span><span class="n">syms</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s">"func1"</span><span class="p">,</span><span class="w"> </span><span class="s">"func2"</span><span class="p">,</span><span class="w"> </span><span class="s">"func3"</span><span class="p">};</span>
<span class="n">register_fprobe_syms</span><span class="p">(</span><span class="o">&</span><span class="n">fp</span><span class="p">,</span><span class="w"> </span><span class="n">syms</span><span class="p">,</span><span class="w"> </span><span class="n">ARRAY_SIZE</span><span class="p">(</span><span class="n">syms</span><span class="p">));</span>
</pre></div>
</div>
<p>To disable (remove from functions) this fprobe, call:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>unregister_fprobe(&fp);
</pre></div>
</div>
<p>You can temporally (soft) disable the fprobe by:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>disable_fprobe(&fp);
</pre></div>
</div>
<p>and resume by:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>enable_fprobe(&fp);
</pre></div>
</div>
<p>The above is defined by including the header:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#include <linux/fprobe.h>
</pre></div>
</div>
<p>Same as ftrace, the registered callbacks will start being called some time
after the <a class="reference internal" href="#c.register_fprobe" title="register_fprobe"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_fprobe()</span></code></a> is called and before it returns. See
<code class="file docutils literal notranslate"><span class="pre">Documentation/trace/ftrace.rst</span></code>.</p>
<p>Also, the <a class="reference internal" href="#c.unregister_fprobe" title="unregister_fprobe"><code class="xref c c-func docutils literal notranslate"><span class="pre">unregister_fprobe()</span></code></a> will guarantee that both enter and exit
handlers are no longer being called by functions after <a class="reference internal" href="#c.unregister_fprobe" title="unregister_fprobe"><code class="xref c c-func docutils literal notranslate"><span class="pre">unregister_fprobe()</span></code></a>
returns as same as <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">unregister_ftrace_function()</span></code>.</p>
</section>
<section id="the-fprobe-entry-exit-handler">
<h2>The fprobe entry/exit handler<a class="headerlink" href="#the-fprobe-entry-exit-handler" title="Link to this heading">¶</a></h2>
<p>The prototype of the entry/exit callback function are as follows:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf">entry_callback</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">fprobe</span><span class="w"> </span><span class="o">*</span><span class="n">fp</span><span class="p">,</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="n">entry_ip</span><span class="p">,</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="n">ret_ip</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">ftrace_regs</span><span class="w"> </span><span class="o">*</span><span class="n">fregs</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">entry_data</span><span class="p">);</span>
<span class="kt">void</span><span class="w"> </span><span class="nf">exit_callback</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">fprobe</span><span class="w"> </span><span class="o">*</span><span class="n">fp</span><span class="p">,</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="n">entry_ip</span><span class="p">,</span><span class="w"> </span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="n">ret_ip</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">ftrace_regs</span><span class="w"> </span><span class="o">*</span><span class="n">fregs</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">entry_data</span><span class="p">);</span>
</pre></div>
</div>
<p>Note that the @entry_ip is saved at function entry and passed to exit
handler.
If the entry callback function returns !0, the corresponding exit callback
will be cancelled.</p>
<dl class="simple">
<dt>@fp</dt><dd><p>This is the address of <cite>fprobe</cite> data structure related to this handler.
You can embed the <cite>fprobe</cite> to your data structure and get it by
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">container_of()</span></code> macro from @fp. The @fp must not be NULL.</p>
</dd>
<dt>@entry_ip</dt><dd><p>This is the ftrace address of the traced function (both entry and exit).
Note that this may not be the actual entry address of the function but
the address where the ftrace is instrumented.</p>
</dd>
<dt>@ret_ip</dt><dd><p>This is the return address that the traced function will return to,
somewhere in the caller. This can be used at both entry and exit.</p>
</dd>
<dt>@fregs</dt><dd><p>This is the <cite>ftrace_regs</cite> data structure at the entry and exit. This
includes the function parameters, or the return values. So user can
access thos values via appropriate <cite>ftrace_regs_*</cite> APIs.</p>
</dd>
<dt>@entry_data</dt><dd><p>This is a local storage to share the data between entry and exit handlers.
This storage is NULL by default. If the user specify <cite>exit_handler</cite> field
and <cite>entry_data_size</cite> field when registering the fprobe, the storage is
allocated and passed to both <cite>entry_handler</cite> and <cite>exit_handler</cite>.</p>
</dd>
</dl>
</section>
<section id="entry-data-size-and-exit-handlers-on-the-same-function">
<h2>Entry data size and exit handlers on the same function<a class="headerlink" href="#entry-data-size-and-exit-handlers-on-the-same-function" title="Link to this heading">¶</a></h2>
<p>Since the entry data is passed via per-task stack and it has limited size,
the entry data size per probe is limited to <cite>15 * sizeof(long)</cite>. You also need
to take care that the different fprobes are probing on the same function, this
limit becomes smaller. The entry data size is aligned to <cite>sizeof(long)</cite> and
each fprobe which has exit handler uses a <cite>sizeof(long)</cite> space on the stack,
you should keep the number of fprobes on the same function as small as
possible.</p>
</section>
<section id="share-the-callbacks-with-kprobes">
<h2>Share the callbacks with kprobes<a class="headerlink" href="#share-the-callbacks-with-kprobes" title="Link to this heading">¶</a></h2>
<p>Since the recursion safeness of the fprobe (and ftrace) is a bit different
from the kprobes, this may cause an issue if user wants to run the same
code from the fprobe and the kprobes.</p>
<p>Kprobes has per-cpu ‘current_kprobe’ variable which protects the kprobe
handler from recursion in all cases. On the other hand, fprobe uses
only <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">ftrace_test_recursion_trylock()</span></code>. This allows interrupt context to
call another (or same) fprobe while the fprobe user handler is running.</p>
<p>This is not a matter if the common callback code has its own recursion
detection, or it can handle the recursion in the different contexts
(normal/interrupt/NMI.)
But if it relies on the ‘current_kprobe’ recursion lock, it has to check
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">kprobe_running()</span></code> and use kprobe_busy_*() APIs.</p>
<p>Fprobe has FPROBE_FL_KPROBE_SHARED flag to do this. If your common callback
code will be shared with kprobes, please set FPROBE_FL_KPROBE_SHARED
<em>before</em> registering the fprobe, like:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">fprobe</span><span class="p">.</span><span class="n">flags</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">FPROBE_FL_KPROBE_SHARED</span><span class="p">;</span>
<span class="n">register_fprobe</span><span class="p">(</span><span class="o">&</span><span class="n">fprobe</span><span class="p">,</span><span class="w"> </span><span class="s">"func*"</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">);</span>
</pre></div>
</div>
<p>This will protect your common callback from the nested call.</p>
</section>
<section id="the-missed-counter">
<h2>The missed counter<a class="headerlink" href="#the-missed-counter" title="Link to this heading">¶</a></h2>
<p>The <cite>fprobe</cite> data structure has <cite>fprobe::nmissed</cite> counter field as same as
kprobes.
This counter counts up when;</p>
<blockquote>
<div><ul class="simple">
<li><p>fprobe fails to take ftrace_recursion lock. This usually means that a function
which is traced by other ftrace users is called from the entry_handler.</p></li>
<li><p>fprobe fails to setup the function exit because of failing to allocate the
data buffer from the per-task shadow stack.</p></li>
</ul>
</div></blockquote>
<p>The <cite>fprobe::nmissed</cite> field counts up in both cases. Therefore, the former
skips both of entry and exit callback and the latter skips the exit
callback, but in both case the counter will increase by 1.</p>
<p>Note that if you set the FTRACE_OPS_FL_RECURSION and/or FTRACE_OPS_FL_RCU to
<cite>fprobe::ops::flags</cite> (ftrace_ops::flags) when registering the fprobe, this
counter may not work correctly, because ftrace skips the fprobe function which
increase the counter.</p>
</section>
<section id="functions-and-structures">
<h2>Functions and structures<a class="headerlink" href="#functions-and-structures" title="Link to this heading">¶</a></h2>
<dl class="c struct">
<dt class="sig sig-object c" id="c.fprobe_hlist_node">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">fprobe_hlist_node</span></span></span><a class="headerlink" href="#c.fprobe_hlist_node" title="Link to this definition">¶</a><br /></dt>
<dd><p>address based hash list node for fprobe.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct fprobe_hlist_node {
struct rhlist_head hlist;
unsigned long addr;
struct fprobe *fp;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">hlist</span></code></dt><dd><p>The hlist node for address search hash table.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">addr</span></code></dt><dd><p>One of the probing address of <strong>fp</strong>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fp</span></code></dt><dd><p>The fprobe which owns this.</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.fprobe_hlist">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">fprobe_hlist</span></span></span><a class="headerlink" href="#c.fprobe_hlist" title="Link to this definition">¶</a><br /></dt>
<dd><p>hash list nodes for fprobe.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct fprobe_hlist {
struct hlist_node hlist;
struct rcu_head rcu;
struct fprobe *fp;
int size;
struct fprobe_hlist_node array[] ;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">hlist</span></code></dt><dd><p>The hlist node for existence checking hash table.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">rcu</span></code></dt><dd><p>rcu_head for RCU deferred release.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fp</span></code></dt><dd><p>The fprobe which owns this fprobe_hlist.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">size</span></code></dt><dd><p>The size of <strong>array</strong>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">array</span></code></dt><dd><p>The fprobe_hlist_node for each address to probe.</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.fprobe">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">fprobe</span></span></span><a class="headerlink" href="#c.fprobe" title="Link to this definition">¶</a><br /></dt>
<dd><p>ftrace based probe.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct fprobe {
unsigned long nmissed;
unsigned int flags;
size_t entry_data_size;
fprobe_entry_cb entry_handler;
fprobe_exit_cb exit_handler;
struct fprobe_hlist *hlist_array;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">nmissed</span></code></dt><dd><p>The counter for missing events.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">flags</span></code></dt><dd><p>The status flag.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">entry_data_size</span></code></dt><dd><p>The private data storage size.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">entry_handler</span></code></dt><dd><p>The callback function for function entry.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">exit_handler</span></code></dt><dd><p>The callback function for function exit.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">hlist_array</span></code></dt><dd><p>The fprobe_hlist for fprobe search from IP hash table.</p>
</dd>
</dl>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.disable_fprobe">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">disable_fprobe</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.fprobe" title="fprobe"><span class="n"><span class="pre">fprobe</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.disable_fprobe" title="Link to this definition">¶</a><br /></dt>
<dd><p>Disable fprobe</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span> <span class="pre">*fp</span></code></dt><dd><p>The fprobe to be disabled.</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>This will soft-disable <strong>fp</strong>. Note that this doesn’t remove the ftrace
hooks from the function entry.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.enable_fprobe">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">enable_fprobe</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.fprobe" title="fprobe"><span class="n"><span class="pre">fprobe</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.enable_fprobe" title="Link to this definition">¶</a><br /></dt>
<dd><p>Enable fprobe</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span> <span class="pre">*fp</span></code></dt><dd><p>The fprobe to be enabled.</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>This will soft-enable <strong>fp</strong>.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.register_fprobe">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">register_fprobe</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.fprobe" title="fprobe"><span class="n"><span class="pre">fprobe</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">filter</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">notfilter</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.register_fprobe" title="Link to this definition">¶</a><br /></dt>
<dd><p>Register fprobe to ftrace by pattern.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span> <span class="pre">*fp</span></code></dt><dd><p>A fprobe data structure to be registered.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*filter</span></code></dt><dd><p>A wildcard pattern of probed symbols.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*notfilter</span></code></dt><dd><p>A wildcard pattern of NOT probed symbols.</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Register <strong>fp</strong> to ftrace for enabling the probe on the symbols matched to <strong>filter</strong>.
If <strong>notfilter</strong> is not NULL, the symbols matched the <strong>notfilter</strong> are not probed.</p>
<p>Return 0 if <strong>fp</strong> is registered successfully, -errno if not.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.register_fprobe_ips">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">register_fprobe_ips</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.fprobe" title="fprobe"><span class="n"><span class="pre">fprobe</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span>, <span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">addrs</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">num</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.register_fprobe_ips" title="Link to this definition">¶</a><br /></dt>
<dd><p>Register fprobe to ftrace by address.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span> <span class="pre">*fp</span></code></dt><dd><p>A fprobe data structure to be registered.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">*addrs</span></code></dt><dd><p>An array of target function address.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">num</span></code></dt><dd><p>The number of entries of <strong>addrs</strong>.</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Register <strong>fp</strong> to ftrace for enabling the probe on the address given by <strong>addrs</strong>.
The <strong>addrs</strong> must be the addresses of ftrace location address, which may be
the symbol address + arch-dependent offset.
If you unsure what this mean, please use other registration functions.</p>
<p>Return 0 if <strong>fp</strong> is registered successfully, -errno if not.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.register_fprobe_syms">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">register_fprobe_syms</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.fprobe" title="fprobe"><span class="n"><span class="pre">fprobe</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">syms</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">num</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.register_fprobe_syms" title="Link to this definition">¶</a><br /></dt>
<dd><p>Register fprobe to ftrace by symbols.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span> <span class="pre">*fp</span></code></dt><dd><p>A fprobe data structure to be registered.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">**syms</span></code></dt><dd><p>An array of target symbols.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">num</span></code></dt><dd><p>The number of entries of <strong>syms</strong>.</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Register <strong>fp</strong> to the symbols given by <strong>syms</strong> array. This will be useful if
you are sure the symbols exist in the kernel.</p>
<p>Return 0 if <strong>fp</strong> is registered successfully, -errno if not.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.unregister_fprobe_async">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">unregister_fprobe_async</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.fprobe" title="fprobe"><span class="n"><span class="pre">fprobe</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.unregister_fprobe_async" title="Link to this definition">¶</a><br /></dt>
<dd><p>Unregister fprobe without RCU GP wait</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span> <span class="pre">*fp</span></code></dt><dd><p>A fprobe data structure to be unregistered.</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Unregister fprobe (and remove ftrace hooks from the function entries).
This function will NOT wait until the fprobe is no longer used.</p>
<p>Return 0 if <strong>fp</strong> is unregistered successfully, -errno if not.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.unregister_fprobe">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">unregister_fprobe</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.fprobe" title="fprobe"><span class="n"><span class="pre">fprobe</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.unregister_fprobe" title="Link to this definition">¶</a><br /></dt>
<dd><p>Unregister fprobe with RCU GP wait</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">fprobe</span> <span class="pre">*fp</span></code></dt><dd><p>A fprobe data structure to be unregistered.</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Unregister fprobe (and remove ftrace hooks from the function entries).
This function will block until the fprobe is no longer used.</p>
<p>Return 0 if <strong>fp</strong> is unregistered successfully, -errno if not.</p>
</div>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/trace/fprobe.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>