<!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/html; charset=utf-8" />
<title>Working with functions and control flow graphs — gcc-python-plugin 0.9 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.9',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="gcc-python-plugin 0.9 documentation" href="index.html" />
<link rel="next" title="gcc.Tree and its subclasses" href="tree.html" />
<link rel="prev" title="Working with C code" href="working-with-c.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="tree.html" title="gcc.Tree and its subclasses"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="working-with-c.html" title="Working with C code"
accesskey="P">previous</a> |</li>
<li><a href="index.html">gcc-python-plugin 0.9 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="working-with-functions-and-control-flow-graphs">
<h1>Working with functions and control flow graphs<a class="headerlink" href="#working-with-functions-and-control-flow-graphs" title="Permalink to this headline">¶</a></h1>
<p>Many of the plugin events are called for each function within the source code
being compiled. Each time, the plugin passes a <a class="reference internal" href="#gcc.Function" title="gcc.Function"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Function</span></tt></a>
instance as a parameter to your callback, so that you can work on it.</p>
<p>You can get at the control flow graph of a <a class="reference internal" href="#gcc.Function" title="gcc.Function"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Function</span></tt></a> via its
<tt class="docutils literal"><span class="pre">cfg</span></tt> attribute. This is an instance of <a class="reference internal" href="#gcc.Cfg" title="gcc.Cfg"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Cfg</span></tt></a>.</p>
<dl class="class">
<dt id="gcc.Function">
<em class="property">class </em><tt class="descclassname">gcc.</tt><tt class="descname">Function</tt><a class="headerlink" href="#gcc.Function" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper around one of GCC’s <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">function</span> <span class="pre">*</span></tt></p>
<dl class="attribute">
<dt id="gcc.Function.cfg">
<tt class="descname">cfg</tt><a class="headerlink" href="#gcc.Function.cfg" title="Permalink to this definition">¶</a></dt>
<dd><p>An instance of <a class="reference internal" href="#gcc.Cfg" title="gcc.Cfg"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Cfg</span></tt></a> for this function (or None during early
passes)</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Function.decl">
<tt class="descname">decl</tt><a class="headerlink" href="#gcc.Function.decl" title="Permalink to this definition">¶</a></dt>
<dd><p>The declaration of this function, as a <a class="reference internal" href="tree.html#gcc.FunctionDecl" title="gcc.FunctionDecl"><tt class="xref py py-class docutils literal"><span class="pre">gcc.FunctionDecl</span></tt></a></p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Function.local_decls">
<tt class="descname">local_decls</tt><a class="headerlink" href="#gcc.Function.local_decls" title="Permalink to this definition">¶</a></dt>
<dd><p>List of <a class="reference internal" href="tree.html#gcc.VarDecl" title="gcc.VarDecl"><tt class="xref py py-class docutils literal"><span class="pre">gcc.VarDecl</span></tt></a> for the function’s local variables. It
does not contain arguments; for those see the <cite>arguments</cite> property of
the function’s <cite>decl</cite>.</p>
<p>Note that for locals with initializers, <cite>initial</cite> only seems to get set
on those <cite>local_decls</cite> that are static variables. For other locals, it
appears that you have to go into the gimple representation to locate
assignments.</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Function.start">
<tt class="descname">start</tt><a class="headerlink" href="#gcc.Function.start" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="basics.html#gcc.Location" title="gcc.Location"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Location</span></tt></a> of the beginning of the function</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Function.end">
<tt class="descname">end</tt><a class="headerlink" href="#gcc.Function.end" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="basics.html#gcc.Location" title="gcc.Location"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Location</span></tt></a> of the end of the function</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Function.funcdef_no">
<tt class="descname">funcdef_no</tt><a class="headerlink" href="#gcc.Function.funcdef_no" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer: a sequence number for profiling, debugging, etc.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="gcc.Cfg">
<em class="property">class </em><tt class="descclassname">gcc.</tt><tt class="descname">Cfg</tt><a class="headerlink" href="#gcc.Cfg" title="Permalink to this definition">¶</a></dt>
<dd><p>A <tt class="docutils literal"><span class="pre">gcc.Cfg</span></tt> is a wrapper around GCC’s <cite>struct control_flow_graph</cite>.</p>
<dl class="attribute">
<dt id="gcc.Cfg.basic_blocks">
<tt class="descname">basic_blocks</tt><a class="headerlink" href="#gcc.Cfg.basic_blocks" title="Permalink to this definition">¶</a></dt>
<dd><p>List of <a class="reference internal" href="#gcc.BasicBlock" title="gcc.BasicBlock"><tt class="xref py py-class docutils literal"><span class="pre">gcc.BasicBlock</span></tt></a>, giving all of the basic blocks within
this CFG</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Cfg.entry">
<tt class="descname">entry</tt><a class="headerlink" href="#gcc.Cfg.entry" title="Permalink to this definition">¶</a></dt>
<dd><p>Instance of <a class="reference internal" href="#gcc.BasicBlock" title="gcc.BasicBlock"><tt class="xref py py-class docutils literal"><span class="pre">gcc.BasicBlock</span></tt></a>: the entrypoint for this CFG</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Cfg.exit">
<tt class="descname">exit</tt><a class="headerlink" href="#gcc.Cfg.exit" title="Permalink to this definition">¶</a></dt>
<dd><p>Instance of <a class="reference internal" href="#gcc.BasicBlock" title="gcc.BasicBlock"><tt class="xref py py-class docutils literal"><span class="pre">gcc.BasicBlock</span></tt></a>: the final one within this CFG</p>
</dd></dl>
<dl class="method">
<dt id="gcc.Cfg.get_block_for_label">
<tt class="descname">get_block_for_label</tt><big>(</big><em>labeldecl</em><big>)</big><a class="headerlink" href="#gcc.Cfg.get_block_for_label" title="Permalink to this definition">¶</a></dt>
<dd><p>Given a <tt class="xref py py-class docutils literal"><span class="pre">gcc.LabelDecl</span></tt>, get the corresponding
<a class="reference internal" href="#gcc.BasicBlock" title="gcc.BasicBlock"><tt class="xref py py-class docutils literal"><span class="pre">gcc.BasicBlock</span></tt></a></p>
</dd></dl>
<p>You can use <tt class="docutils literal"><span class="pre">gccutils.cfg_to_dot</span></tt> to render a gcc.Cfg as a graphviz
diagram. It will render the diagram, showing each basic block, with
source code on the left-hand side, interleaved with the “gimple”
representation on the right-hand side. Each block is labelled with its
index, and edges are labelled with appropriate flags.</p>
<p>For example, given this sample C code:</p>
<blockquote>
<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span>
<span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
<span class="n">printf</span><span class="p">(</span><span class="s">"argc: %i</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">argc</span><span class="p">);</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">argc</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="n">printf</span><span class="p">(</span><span class="s">"argv[%i]: %s</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">argv</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
<span class="p">}</span>
<span class="n">helper_function</span><span class="p">();</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div></blockquote>
<p>then the following Python code:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">dot</span> <span class="o">=</span> <span class="n">gccutils</span><span class="o">.</span><span class="n">cfg_to_dot</span><span class="p">(</span><span class="n">fun</span><span class="o">.</span><span class="n">cfg</span><span class="p">)</span>
<span class="n">gccutils</span><span class="o">.</span><span class="n">invoke_dot</span><span class="p">(</span><span class="n">dot</span><span class="p">)</span>
</pre></div>
</div>
<p>will render a CFG bitmap like this:</p>
<blockquote>
<div><div class="figure">
<a class="reference internal image-reference" href="_images/sample-gimple-cfg.png"><img alt="image of a control flow graph" src="_images/sample-gimple-cfg.png" style="width: 850.5px; height: 538.5px;" /></a>
</div>
</div></blockquote>
</dd></dl>
<dl class="class">
<dt id="gcc.BasicBlock">
<em class="property">class </em><tt class="descclassname">gcc.</tt><tt class="descname">BasicBlock</tt><a class="headerlink" href="#gcc.BasicBlock" title="Permalink to this definition">¶</a></dt>
<dd><p>A <tt class="docutils literal"><span class="pre">gcc.BasicBlock</span></tt> is a wrapper around GCC’s <cite>basic_block</cite> type.</p>
<dl class="attribute">
<dt id="gcc.BasicBlock.index">
<tt class="descname">index</tt><a class="headerlink" href="#gcc.BasicBlock.index" title="Permalink to this definition">¶</a></dt>
<dd><p>The index of the block (an int), as seen in the cfg_to_dot rendering.</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.BasicBlock.preds">
<tt class="descname">preds</tt><a class="headerlink" href="#gcc.BasicBlock.preds" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of predecessor <a class="reference internal" href="#gcc.Edge" title="gcc.Edge"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Edge</span></tt></a> instances leading into this
block</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.BasicBlock.succs">
<tt class="descname">succs</tt><a class="headerlink" href="#gcc.BasicBlock.succs" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of successor <a class="reference internal" href="#gcc.Edge" title="gcc.Edge"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Edge</span></tt></a> instances leading out of this
block</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.BasicBlock.phi_nodes">
<tt class="descname">phi_nodes</tt><a class="headerlink" href="#gcc.BasicBlock.phi_nodes" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of <a class="reference internal" href="gimple.html#gcc.GimplePhi" title="gcc.GimplePhi"><tt class="xref py py-class docutils literal"><span class="pre">gcc.GimplePhi</span></tt></a> phoney functions at the top of this
block, if appropriate for this pass, or None</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.BasicBlock.gimple">
<tt class="descname">gimple</tt><a class="headerlink" href="#gcc.BasicBlock.gimple" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of <a class="reference internal" href="gimple.html#gcc.Gimple" title="gcc.Gimple"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Gimple</span></tt></a> instructions, if appropriate for this
pass, or None</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.BasicBlock.rtl">
<tt class="descname">rtl</tt><a class="headerlink" href="#gcc.BasicBlock.rtl" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of <a class="reference internal" href="rtl.html#gcc.Rtl" title="gcc.Rtl"><tt class="xref py py-class docutils literal"><span class="pre">gcc.Rtl</span></tt></a> expressions, if appropriate for this
pass, or None</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="gcc.Edge">
<em class="property">class </em><tt class="descclassname">gcc.</tt><tt class="descname">Edge</tt><a class="headerlink" href="#gcc.Edge" title="Permalink to this definition">¶</a></dt>
<dd><p>A wrapper around GCC’s <cite>edge</cite> type.</p>
<dl class="attribute">
<dt id="gcc.Edge.src">
<tt class="descname">src</tt><a class="headerlink" href="#gcc.Edge.src" title="Permalink to this definition">¶</a></dt>
<dd><p>The source <a class="reference internal" href="#gcc.BasicBlock" title="gcc.BasicBlock"><tt class="xref py py-class docutils literal"><span class="pre">gcc.BasicBlock</span></tt></a> of this edge</p>
</dd></dl>
<dl class="attribute">
<dt id="gcc.Edge.dest">
<tt class="descname">dest</tt><a class="headerlink" href="#gcc.Edge.dest" title="Permalink to this definition">¶</a></dt>
<dd><p>The destination <a class="reference internal" href="#gcc.BasicBlock" title="gcc.BasicBlock"><tt class="xref py py-class docutils literal"><span class="pre">gcc.BasicBlock</span></tt></a> of this edge</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="working-with-c.html"
title="previous chapter">Working with C code</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="tree.html"
title="next chapter">gcc.Tree and its subclasses</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/cfg.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="tree.html" title="gcc.Tree and its subclasses"
>next</a> |</li>
<li class="right" >
<a href="working-with-c.html" title="Working with C code"
>previous</a> |</li>
<li><a href="index.html">gcc-python-plugin 0.9 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2011, David Malcolm.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
