Deploying to gh-pages from @ 3af7fb3 🚀

_modules/qbindiff/differ.html

@@ -137,6 +137,7 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="kn">from</span> <span class="nn">qbindiff.features.extractor</span> <span class="kn">import</span> <span class="n">FeatureExtractor</span>
 <span class="kn">from</span> <span class="nn">qbindiff.passes</span> <span class="kn">import</span> <span class="n">FeaturePass</span><span class="p">,</span> <span class="n">ZeroPass</span>
 <span class="kn">from</span> <span class="nn">qbindiff.utils</span> <span class="kn">import</span> <span class="n">is_debug</span><span class="p">,</span> <span class="n">wrapper_iter</span>
+<span class="kn">from</span> <span class="nn">qbindiff.exceptions</span> <span class="kn">import</span> <span class="o">*</span>
 <span class="kn">from</span> <span class="nn">qbindiff.types</span> <span class="kn">import</span> <span class="n">RawMapping</span><span class="p">,</span> <span class="n">Positive</span><span class="p">,</span> <span class="n">Ratio</span><span class="p">,</span> <span class="n">Graph</span><span class="p">,</span> <span class="n">AdjacencyMatrix</span><span class="p">,</span> <span class="n">Distance</span>
 <span class="kn">from</span> <span class="nn">qbindiff.mapping.bindiff</span> <span class="kn">import</span> <span class="n">export_to_bindiff</span>
 
@@ -177,11 +178,11 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="sd">        :param primary: primary graph</span>
 <span class="sd">        :param secondary: secondary graph</span>
 <span class="sd">        :param sparsity_ratio: the sparsity ratio enforced to the similarity matrix</span>
-<span class="sd">            of type py:class:`qbindiff.types.Ratio`</span>
+<span class="sd">            of type :py:class:`qbindiff.types.Ratio`</span>
 <span class="sd">        :param tradeoff: tradeoff ratio bewteen node similarity (tradeoff=1.0)</span>
-<span class="sd">            and edge similarity (tradeoff=0.0) of type py:class:`qbindiff.types.Ratio`</span>
+<span class="sd">            and edge similarity (tradeoff=0.0) of type :py:class:`qbindiff.types.Ratio`</span>
 <span class="sd">        :param epsilon: perturbation parameter to enforce convergence and speed up computation,</span>
-<span class="sd">            of type py:class:`qbindiff.types.Positive`. The greatest the fastest, but least accurate</span>
+<span class="sd">            of type :py:class:`qbindiff.types.Positive`. The greatest the fastest, but least accurate</span>
 <span class="sd">        :param maxiter: maximum number of message passing iterations</span>
 <span class="sd">        :param sparse_row: Whether to build the sparse similarity matrix considering its</span>
 <span class="sd">            entirety or processing it row per row</span>
@@ -494,7 +495,7 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Initialize the similarity matrix</span>
 
-<span class="sd">        :param sim_matrix: The similarity matrix of type py:class:`qbindiff.types.SimMatrix`</span>
+<span class="sd">        :param sim_matrix: The similarity matrix of type :py:class:`qbindiff.types.SimMatrix`</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="n">sim_matrix</span><span class="p">[:]</span> <span class="o">=</span> <span class="mi">1</span>
@@ -567,7 +568,7 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Initialize the similarity matrix</span>
 
-<span class="sd">        :param sim_matrix: The similarity matrix of type py:class:`qbindiff.types.SimMatrix`</span>
+<span class="sd">        :param sim_matrix: The similarity matrix of type :py:class:`qbindiff.types.SimMatrix`</span>
 <span class="sd">        :return: None</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 
@@ -592,12 +593,12 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        QBinDiff class that provides a high-level interface to trigger a diff between two binaries.</span>
 
-<span class="sd">        :param primary: The primary binary of type py:class:`qbindiff.loader.Program`</span>
-<span class="sd">        :param secondary: The secondary binary of type py:class:`qbindiff.loader.Program`</span>
+<span class="sd">        :param primary: The primary binary of type :py:class:`qbindiff.loader.Program`</span>
+<span class="sd">        :param secondary: The secondary binary of type :py:class:`qbindiff.loader.Program`</span>
 <span class="sd">        :param distance: the distance function used when comparing the feature vector</span>
 <span class="sd">            extracted from the graphs.</span>
 <span class="sd">        :param normalize: Normalize the two programs Call Graphs with a series of heuristics. Look at</span>
-<span class="sd">            :py:method:`normalize` for more information.</span>
+<span class="sd">            :py:meth:`normalize` for more information.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="k">if</span> <span class="n">normalize</span><span class="p">:</span>  <span class="c1"># Optional normalization step</span>
@@ -651,13 +652,30 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="sd">        Register a feature extractor class. This will include the corresponding feature in the similarity matrix</span>
 <span class="sd">        computation</span>
 
-<span class="sd">        :param extractor_class: A feature extractor of type py:class:`qbindiff.features.extractor`</span>
+<span class="sd">        :param extractor_class: A feature extractor of type :py:class:`qbindiff.features.extractor`</span>
 <span class="sd">        :param weight: Weight associated to the corresponding feature. Default is 1.</span>
 <span class="sd">        :param distance: Distance used only for this feature. It does not make sense to use it with bnb feature,</span>
 <span class="sd">            but it can be useful for the WeisfeilerLehman feature.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 
         <span class="n">extractor</span> <span class="o">=</span> <span class="n">extractor_class</span><span class="p">(</span><span class="n">weight</span><span class="p">,</span> <span class="o">**</span><span class="n">extra_args</span><span class="p">)</span>
+
+        <span class="c1"># Check that the capabilities required by the feature are supported by the Programs</span>
+        <span class="n">supported_cap</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">primary</span><span class="o">.</span><span class="n">capabilities</span> <span class="o">&amp;</span> <span class="n">extractor</span><span class="o">.</span><span class="n">required_capabilities</span>
+        <span class="k">if</span> <span class="n">supported_cap</span> <span class="o">!=</span> <span class="n">extractor</span><span class="o">.</span><span class="n">required_capabilities</span><span class="p">:</span>
+            <span class="n">missing</span> <span class="o">=</span> <span class="n">supported_cap</span> <span class="o">^</span> <span class="n">extractor</span><span class="o">.</span><span class="n">required_capabilities</span>
+            <span class="k">raise</span> <span class="n">UnsupportedFeatureException</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;The capability </span><span class="si">{</span><span class="n">missing</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, required by the feature&quot;</span>
+                <span class="sa">f</span><span class="s2">&quot; </span><span class="si">{</span><span class="n">extractor</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s2"> is not supported by the primary backend&quot;</span>
+            <span class="p">)</span>
+        <span class="n">supported_cap</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">secondary</span><span class="o">.</span><span class="n">capabilities</span> <span class="o">&amp;</span> <span class="n">extractor</span><span class="o">.</span><span class="n">required_capabilities</span>
+        <span class="k">if</span> <span class="n">supported_cap</span> <span class="o">!=</span> <span class="n">extractor</span><span class="o">.</span><span class="n">required_capabilities</span><span class="p">:</span>
+            <span class="n">missing</span> <span class="o">=</span> <span class="n">supported_cap</span> <span class="o">^</span> <span class="n">extractor</span><span class="o">.</span><span class="n">required_capabilities</span>
+            <span class="k">raise</span> <span class="n">UnsupportedFeatureException</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;The capability </span><span class="si">{</span><span class="n">missing</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s2">, required by the feature&quot;</span>
+                <span class="sa">f</span><span class="s2">&quot; </span><span class="si">{</span><span class="n">extractor</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s2"> is not supported by the secondary backend&quot;</span>
+            <span class="p">)</span>
+
         <span class="bp">self</span><span class="o">.</span><span class="n">_feature_pass</span><span class="o">.</span><span class="n">register_extractor</span><span class="p">(</span><span class="n">extractor</span><span class="p">,</span> <span class="n">distance</span><span class="o">=</span><span class="n">distance</span><span class="p">)</span></div>
 
 
@@ -712,9 +730,9 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="sd">        similarity to 1. This anchoring phase is necessary to obtain a good match.</span>
 
 <span class="sd">        :param sim_matrix: The similarity matrix of between the primary and secondary, of</span>
-<span class="sd">            type py:class:`qbindiff.types:SimMatrix`</span>
-<span class="sd">        :param primary: The primary binary of type py:class:`qbindiff.loader.Program`</span>
-<span class="sd">        :param secondary: The secondary binary of type py:class:`qbindiff.loader.Program`</span>
+<span class="sd">            type :py:class:`qbindiff.types:SimMatrix`</span>
+<span class="sd">        :param primary: The primary binary of type :py:class:`qbindiff.loader.Program`</span>
+<span class="sd">        :param secondary: The secondary binary of type :py:class:`qbindiff.loader.Program`</span>
 <span class="sd">        :param primary_mapping: Mapping between the primary function addresses and their corresponding index</span>
 <span class="sd">        :param secondary_mapping: Mapping between the secondary function addresses and their corresponding index</span>
 <span class="sd">        &quot;&quot;&quot;</span>
@@ -740,7 +758,7 @@ <h1>Source code for qbindiff.differ</h1><div class="highlight"><pre>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Normalize the input Program. In some cases, this can create an exception, caused by a thunk function.</span>
 
-<span class="sd">        :param program: the program of type py:class:`qbindiff.loader.Program` to normalize.</span>
+<span class="sd">        :param program: the program of type :py:class:`qbindiff.loader.Program` to normalize.</span>
 <span class="sd">        :returns: the normalized program</span>
 <span class="sd">        &quot;&quot;&quot;</span>
 

_modules/qbindiff/features/extractor.html

@@ -118,6 +118,7 @@ <h1>Source code for qbindiff.features.extractor</h1><div class="highlight"><pre>
 
 <span class="kn">from</span> <span class="nn">qbindiff.features.manager</span> <span class="kn">import</span> <span class="n">FeatureKeyManager</span>
 <span class="kn">from</span> <span class="nn">qbindiff.loader</span> <span class="kn">import</span> <span class="n">Program</span><span class="p">,</span> <span class="n">Function</span><span class="p">,</span> <span class="n">BasicBlock</span><span class="p">,</span> <span class="n">Instruction</span><span class="p">,</span> <span class="n">Operand</span>
+<span class="kn">from</span> <span class="nn">qbindiff.loader.types</span> <span class="kn">import</span> <span class="n">ProgramCapability</span>
 <span class="kn">from</span> <span class="nn">qbindiff.types</span> <span class="kn">import</span> <span class="n">Positive</span><span class="p">,</span> <span class="n">SparseVector</span><span class="p">,</span> <span class="n">FeatureValue</span>
 
 
@@ -265,6 +266,7 @@ <h1>Source code for qbindiff.features.extractor</h1><div class="highlight"><pre>
 
     <span class="n">key</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>  <span class="c1">#: feature name (short)</span>
     <span class="n">help_msg</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>  <span class="c1">#: CLI help message</span>
+    <span class="n">required_capabilities</span> <span class="o">=</span> <span class="n">ProgramCapability</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>  <span class="c1">#: By default there are no required capabilities</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">weight</span><span class="p">:</span> <span class="n">Positive</span> <span class="o">=</span> <span class="mf">1.0</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>

_modules/qbindiff/features/graph.html

@@ -127,7 +127,7 @@ <h1>Source code for qbindiff.features.graph</h1><div class="highlight"><pre>
     <span class="n">FeatureCollector</span><span class="p">,</span>
 <span class="p">)</span>
 <span class="kn">from</span> <span class="nn">qbindiff.loader</span> <span class="kn">import</span> <span class="n">Program</span><span class="p">,</span> <span class="n">Function</span><span class="p">,</span> <span class="n">Instruction</span><span class="p">,</span> <span class="n">Operand</span>
-<span class="kn">from</span> <span class="nn">qbindiff.loader.types</span> <span class="kn">import</span> <span class="n">OperandType</span>
+<span class="kn">from</span> <span class="nn">qbindiff.loader.types</span> <span class="kn">import</span> <span class="n">OperandType</span><span class="p">,</span> <span class="n">InstructionGroup</span><span class="p">,</span> <span class="n">ProgramCapability</span>
 
 <span class="k">if</span> <span class="n">TYPE_CHECKING</span><span class="p">:</span>
     <span class="kn">from</span> <span class="nn">qbindiff.loader</span> <span class="kn">import</span> <span class="n">Operand</span>
@@ -289,16 +289,18 @@ <h1>Source code for qbindiff.features.graph</h1><div class="highlight"><pre>
 <span class="k">class</span> <span class="nc">JumpNb</span><span class="p">(</span><span class="n">InstructionFeatureExtractor</span><span class="p">):</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Number of jumps in the function.</span>
+<span class="sd">    Requires INSTR_GROUP capability</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;jnb&quot;</span>
+    <span class="n">required_capabilities</span> <span class="o">=</span> <span class="n">ProgramCapability</span><span class="o">.</span><span class="n">INSTR_GROUP</span>
 
 <div class="viewcode-block" id="JumpNb.visit_instruction">
 <a class="viewcode-back" href="../../../qbindiff/doc/source/api/features.html#qbindiff.features.JumpNb.visit_instruction">[docs]</a>
     <span class="k">def</span> <span class="nf">visit_instruction</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span> <span class="n">program</span><span class="p">:</span> <span class="n">Program</span><span class="p">,</span> <span class="n">instruction</span><span class="p">:</span> <span class="n">Instruction</span><span class="p">,</span> <span class="n">collector</span><span class="p">:</span> <span class="n">FeatureCollector</span>
     <span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="k">if</span> <span class="n">instruction</span><span class="o">.</span><span class="n">mnemonic</span> <span class="o">==</span> <span class="s2">&quot;jmp&quot;</span><span class="p">:</span>
+        <span class="k">if</span> <span class="n">InstructionGroup</span><span class="o">.</span><span class="n">GRP_JUMP</span> <span class="ow">in</span> <span class="n">instruction</span><span class="o">.</span><span class="n">groups</span><span class="p">:</span>
             <span class="n">collector</span><span class="o">.</span><span class="n">add_dict_feature</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="p">,</span> <span class="p">{</span><span class="s2">&quot;value&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span></div>
 </div>