### Install QBinDiff via Pip

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/install.rst

Installs the QBinDiff package directly from the Python Package Index (PyPI). This is the simplest method for users who want to quickly start using QBinDiff.

```bash
pip install qbindiff
```

--------------------------------

### Installation and Documentation Build

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

Instructions for installing QBinDiff via pip and building its documentation locally using make.

```shell
pip install qbindiff
```

```shell
pip install .[doc]
```

```shell
cd doc
```

```shell
make html
```

--------------------------------

### Clone QBinDiff Repository

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/install.rst

Clones the official QBinDiff source code repository from GitHub. This is the first step for manual installation or contributing to the project.

```bash
git clone https://github.com/quarkslab/qbindiff
cd qbindiff
```

--------------------------------

### Build and Install QBinDiff Manually

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/install.rst

Builds and installs QBinDiff from the cloned source code after setting up a virtual environment. This method installs QBinDiff along with its backend loaders.

```bash
pip install .
```

--------------------------------

### Setup Python Virtual Environment

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/install.rst

Creates and activates a Python virtual environment to isolate QBinDiff's dependencies from your system's Python installation. This is highly recommended for managing project dependencies.

```bash
python -m venv venv
. venv/bin/activate
```

--------------------------------

### QBinDiff Command Line Example

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

Demonstrates how to use the qbindiff command-line tool with different input file types, including Quokka and BinExport exports, and shows how to specify output paths.

```commandline
Usage: qbindiff [OPTIONS] <primary file> <secondary file>                                                                                                                                    
                                                                                                                                                                                              
QBinDiff is an experimental binary diffing tool based on machine learning technics, namely Belief propagation.                                                                               
 Examples:                                                                                                                                                                                    
 - For Quokka exports: qbindiff -e1 file1.bin -e2 file2.bin file1.quokka file2.quokka                                                                                                         
 - For BinExport exports, changing the output path: qbindiff -o my_diff.bindiff file1.BinExport file2.BinExport                                                                               
```

--------------------------------

### qbindiff Example with BinExport Loader and Tradeoff

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Illustrates using qbindiff with the BinExport loader, focusing on feature similarity, sparsity ratio, tradeoff between content and topology, and output file specification.

```bash
qbindiff binary-primary.BinExport binary-secondary.BinExport \
     -f wlgk:cosine \
     -f fname:3 \
     -f addr:0.01 \
     -s 0.7 \
     -t 0.5 \
     -ff bindiff -o ./result.BinDiff -vv
```

--------------------------------

### Load BinExport Files into QBinDiff

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Shows how to load exported backend files (specifically BinExport in this example) into QBinDiff for analysis. This is the initial step before configuring the differ object.

```python
import qbindiff
from qbindiff import LoaderType

primary = qbindiff.Program("/path/to/primary.BinExport")
secondary = qbindiff.Program("/path/to/secondary.BinExport")
```

--------------------------------

### Export Binary to Quokka File

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Demonstrates how to export a binary file to the Quokka backend format using the `quokka.Program.from_binary` method. This process requires the IDA plugin to be installed.

```python
import quokka

prog = quokka.Program.from_binary('/path/to/bin',
                                  output_file='/path/to/output.quokka',
                                  database_file='/path/to/db.i64')
```

--------------------------------

### qbindiff Example with Quokka Loader and Custom Features

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Demonstrates a typical qbindiff usage scenario with the Quokka loader, specifying multiple custom features with weights and distances, along with sparsity settings and output configuration.

```bash
qbindiff -l quokka -e1 binary-primary.exe -e2 binary-secondary.exe \
     binary-primary.qk binary-secondary.qk \
     -f wlgk:cosine \
     -f fname:3 \
     -f dat \
     -f cst \
     -f addr:0.01 \
     -d haussmann -s 0.999 -sr \
     -ff bindiff -o ./result.BinDiff -vv
```

--------------------------------

### Generate BinDiff File using qBinDiff CLI

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

Example of using the qBinDiff command-line interface to generate a .BinDiff file from two BinExport files. It specifies the output format and file name.

```shell
qbindiff primary.BinExport secondary.BinExport -ff bindiff -o out.BinDiff
```

--------------------------------

### Quokka Exporter Custom Features and Parameters

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

An example showing how to use the Quokka exporter with custom diffing features and parameters, including specifying features like basic block number and cyclomatic complexity with weights, and setting the maximum iterations.

```shell
$ qbindiff -e1 primary.exe \
           -e2 secondary.exe \
           -f bnb \
           -f cc:3.0 \
           -f cst:5.0 \
           --maxiter 100 \
           primary.exe.Quokka \
           secondary.exe.Quokka
```

--------------------------------

### Specify Architecture for qBinDiff CLI

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

Example of using the qBinDiff command-line interface to specify exact architecture and mode for disassembly, particularly useful for ARM/Thumb mode. It relies on Capstone naming conventions.

```shell
qbindiff primary.BinExport secondary.BinExport -a1 CS_ARCH_ARM:CS_MODE_THUMB -a2 CS_ARCH_ARM:CS_MODE_THUMB
```

--------------------------------

### Load Program with Custom Backend

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Demonstrates how to create a QBinDiff `Program` instance using a custom backend implementation. This allows QBinDiff to work with binaries processed by user-defined loaders.

```python
import qbindiff
import MyCustomProgramBackend # Assuming this is your custom backend implementation

my_custom_backend_obj = MyCustomProgramBackend('my-program.exe')
program = qbindiff.Program.from_backend(my_custom_backend_obj)
```

--------------------------------

### Initialize QBinDiff Differ with Parameters

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Illustrates the creation of a QBinDiff differ object, configuring various parameters such as distance metric, epsilon, tradeoff, and sparsity settings for the comparison process.

```python
import qbindiff

differ = qbindiff.QBinDiff(
    primary,
    secondary,
    distance="canberra",
    epsilon=0.5,
    tradeoff=0.75,
    normalize=False,
    sparsity_ratio=0.999,
    sparse_row=True,
)
```

--------------------------------

### qbindiff Usage and Options

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Provides a comprehensive overview of the qbindiff command-line tool, detailing its primary arguments and a wide array of options for configuring the binary diffing process. It covers loader selection, feature management, normalization, distance metrics, sparsity control, and output formatting.

```APIDOC
qbindiff [OPTIONS] <primary file> <secondary file>

Command-line tool for binary diffing.

Parameters:
  <primary file>      Path to the primary binary file.
  <secondary file>    Path to the secondary binary file.

Options:
  -l, --loader        The backend loader to use. Possible values: binexport, quokka. Default: binexport.
                      'binexport' is flexible (IDA, Ghidra, BinaryNinja) but may yield worse results.
                      'quokka' produces better results but is only compatible with IDA.
  -f, --features      Specify a feature to populate the similarity matrix. Multiple features can be specified.
                      Syntax:
                        <name>
                        <name>:<weight>
                        <name>:<distance>
                        <name>:<weight>:<distance>
                      Default weight is 1.0, default distance is 'canberra'.
  -fopt, --feature-option
                      Set an option for a previously enabled feature. Consult feature descriptions for accepted options.
  -n, --normalize     Normalize the Call Graph by removing edges/nodes that might worsen diffing results. WARNING: can potentially lead to worse matching.
  -d, --distance      Set the default distance metric for features. Possible values: canberra, correlation, cosine, euclidean, haussmann. Default: canberra.
  -s, --sparsity-ratio
                      Set the density of the similarity matrix. Values closer to 1.0 increase performance but decrease accuracy.
                      Example: 0.999 means 99.9% of the matrix will be zeros. Default: 0.75.
  -sr, --sparse-row   Enable sparse row processing: the sparsity ratio affects each row individually, ensuring no rows are completely erased.
  -t, --tradeoff      Tradeoff between function content (near 1.0) and call-graph topology information (near 0.0). Default: 0.75.
  -e, --epsilon       Relaxation parameter for belief propagation convergence. Default: 0.50.
  -i, --maxiter       Maximum number of iterations for the belief propagation algorithm. Default: 1000.
  -e1, --executable1  Path to the primary raw executable. Required if using the quokka loader.
  -e2, --executable2  Path to the secondary raw executable. Required if using the quokka loader.
  -o, --output        Path to the output file where the diffing result is stored.
  -ff, --file-format  Format of the output file. Currently supported: bindiff. Default: bindiff.
  --enable-cortexm    Enable the usage of the cortex-m extension when disassembling (relevant for binexport loader).
  -v, --verbose       Increase verbosity. Can be supplied up to 3 times.

Warning:
  Lower sparsity (higher density) improves accuracy but slows down the algorithm. Tuning is required per use case. Reducing sparsity beyond a certain threshold may not yield better results.

Related:
  {ref}`usage/custom_backend`
  {ref}`features`
  {ref}`normalization`
  {ref}`haussmann`
  {ref}`belief-propagation`
  {ref}`bindiff`
```

--------------------------------

### QBinDiff API Modules Overview

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/qbindiff.rst

This section provides an overview of the different modules available within the QBinDiff API. Each module corresponds to a specific aspect of binary analysis and comparison, allowing users to leverage QBinDiff's functionalities programmatically.

```APIDOC
QBinDiff API Modules:

- differ: Core functionalities for comparing binary files.
- distances: Modules related to calculating similarity or distance metrics between binary components.
- visitor: Implements the visitor pattern for traversing and processing binary structures.
- features: Handles the extraction and management of features from binary code.
- extractor: Components responsible for extracting relevant information from binaries.
- loader: APIs for loading and parsing various binary file formats.
- backend: Underlying backend implementations and interfaces.
- mapping: Functionality for mapping elements between different binary representations.
- matcher: Algorithms and tools for matching corresponding code or data structures.
- passes: Defines analysis passes that can be applied to binaries.
- metrics: Utilities for computing and analyzing performance or quality metrics.
- types: Definitions and handling of data types within the binary analysis context.
```

--------------------------------

### qbindiff.QBinDiff API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/differ.rst

Documentation for the main QBinDiff class, orchestrating the entire binary diffing process from loading binaries to generating reports.

```APIDOC
qbindiff.QBinDiff:
  Description: The main class for performing binary diffing operations.
  Members:
    - __init__(self, path1, path2, **kwargs)
      Initializes QBinDiff with paths to two binary files.
      Parameters:
        - path1: Path to the first binary file.
        - path2: Path to the second binary file.
        - kwargs: Configuration options for loading, parsing, and diffing.
    - load_binaries(self)
      Loads and parses the specified binary files.
    - diff_graphs(self)
      Performs the graph comparison using the Differ component.
    - save_diff(self, output_path)
      Saves the diff results to a specified file path.
    - report(self, report_type)
      Generates a report of the diff results in a specified format.
```

--------------------------------

### Compute and Export QBinDiff Matching Results

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Explains how to compute the binary matching using the configured QBinDiff differ, export the results to a BinDiff file, and iterate through the computed matches to access details like addresses, similarity, and confidence.

```python
import qbindiff

# Assuming 'differ' is already initialized and features registered
result = differ.compute_matching()

# Export the result to the BinDiff file format
differ.export_to_bindiff('./result.BinDiff')

# Iterate over all the matches
for match in result:
    print(match.primary.addr, match.secondary.addr, match.similarity, match.confidence)
```

--------------------------------

### InstructionBackendQuokka API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/quokka.rst

API reference for the InstructionBackendQuokka class, detailing its members and inherited functionalities.

```APIDOC
.. autoclass:: qbindiff.loader.backend.quokka.InstructionBackendQuokka
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### qbindiff.Program API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the Program class, representing a loaded binary program. It includes members related to program-level information and analysis.

```APIDOC
Program:
  Represents a loaded binary program.
  Includes members for program-level information and analysis.
```

--------------------------------

### Qbindiff Visitor Classes API Documentation

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/visitor.rst

Documentation for the core Visitor classes in qbindiff. This includes the abstract base class 'Visitor' and concrete implementations 'NoVisitor' and 'ProgramVisitor'. These classes are fundamental for implementing the visitor pattern, allowing for the traversal and manipulation of program structures without modifying the structures themselves.

```APIDOC
.. autoclass:: qbindiff.visitor.Visitor
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:

.. autoclass:: qbindiff.visitor.NoVisitor
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:

.. autoclass:: qbindiff.visitor.ProgramVisitor
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### MeanInsNB Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the MeanInsNB feature class, likely representing the average number of instructions. All members are documented.

```APIDOC
.. autoclass:: qbindiff.features.MeanInsNB
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### QBinDiff CLI Options

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

A detailed reference of all available command-line options for the qbindiff tool, categorized by function (output, primary file, secondary file, global).

```APIDOC
QBinDiff Command Line Interface:

Main Usage:
  qbindiff [OPTIONS] <primary file> <secondary file>

Output Parameters:
  --output, -o FILE      Output file path. [default: qbindiff_results.csv]
  --format, -ff FORMAT   Output file format. (bindiff|csv) [default: csv]

Primary File Options:
  --primary-loader, -l1 LOADER  Enforce loader type. (binexport|quokka|ida)
  --primary-executable, -e1 PATH  Path to the raw executable (required for quokka exports).
  --primary-arch, -a1 TEXT      Enforce disassembling architecture. Format is like 'CS_ARCH_X86:CS_MODE_64'.

Secondary File Options:
  --secondary-loader, -l2 LOADER  Enforce loader type. (binexport|quokka|ida)
  --secondary-executable, -e2 PATH  Path to the raw executable (required for quokka exports).
  --secondary-arch, -a2 TEXT      Enforce disassembling architecture. Format is like 'CS_ARCH_X86:CS_MODE_64'.

Global Options:
  --verbose, -v LEVEL      Activate debugging messages. (-v|-vv|-vvv)
  --quiet, -q              Do not display progress bars and final statistics.
  --help, -h               Show this message and exit.
  --version                Show the version and exit.
```

--------------------------------

### QBinDiff Custom Backend Abstract Classes

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Defines the abstract base classes that must be implemented to create a custom backend loader for QBinDiff. This includes interfaces for operands, instructions, basic blocks, functions, and the program itself.

```APIDOC
Custom Backend Loader Interfaces for QBinDiff:

Implementations are required for classes found in `src/qbindiff/loader/backend/abstract.py`.

1. AbstractOperandBackend:
   - `__str__(self) -> str`: String representation of the operand.
   - `@property immutable_value(self) -> int | None`: Returns the operand's value if it's immutable, otherwise None.
   - `@property type(self) -> int`: The type of the operand (e.g., register, immediate, memory).
   - `is_immutable(self) -> bool`: Checks if the operand's value is immutable.

2. AbstractInstructionBackend:
   - `@property addr(self) -> Addr`: The memory address of the instruction.
   - `@property mnemonic(self) -> str`: The mnemonic of the instruction (e.g., 'MOV', 'ADD').
   - `@property references(self) -> dict[ReferenceType, list[ReferenceTarget]]`: Dictionary of references made by the instruction.
   - `@property operands(self) -> Iterator[AbstractOperandBackend]`: Iterator over the instruction's operands.
   - `@property groups(self) -> list[int]`: List of group identifiers for the instruction.
   - `@property id(self) -> int`: Unique identifier for the instruction.
   - `@property comment(self) -> str`: Any associated comment for the instruction.
   - `@property bytes(self) -> bytes`: The raw bytes of the instruction.

3. AbstractBasicBlockBackend:
   - `@property addr(self) -> Addr`: The starting address of the basic block.
   - `@property instructions(self) -> Iterator[AbstractInstructionBackend]`: Iterator over the instructions within the basic block.

4. AbstractFunctionBackend:
   - `@property basic_blocks(self) -> Iterator[AbstractBasicBlockBackend]`: Iterator over the basic blocks in the function.
   - `@property addr(self) -> Addr`: The entry address of the function.
   - `@property graph(self) -> networkx.DiGraph`: Control flow graph of the function.
   - `@property parents(self) -> set[Addr]`: Set of addresses of parent functions (callers).
   - `@property children(self) -> set[Addr]`: Set of addresses of child functions (callees).
   - `@property type(self) -> FunctionType`: The type of the function (e.g., normal, library).
   - `@property name(self) -> str`: The name of the function.

5. AbstractProgramBackend:
   - `@property functions(self) -> Iterator[AbstractFunctionBackend]`: Iterator over all functions in the program.
   - `@property name(self) -> str`: The name of the program/binary.
   - `@property structures(self) -> list[Structure]`: List of structures defined in the program.
   - `@property callgraph(self) -> networkx.DiGraph`: The call graph of the entire program.
   - `@property fun_names(self) -> dict[str, Addr]`: Mapping from function names to their addresses.

Refer to the docstrings in `src/qbindiff/loader/backend/abstract.py` for detailed explanations.
```

--------------------------------

### qbindiff.loader.Instruction API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the Instruction class, representing a single machine instruction. It details the operation, operands, and address of the instruction.

```APIDOC
Instruction:
  Represents a single machine instruction.
  Details the operation, operands, and address of the instruction.
```

--------------------------------

### qbindiff.loader.BasicBlock API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the BasicBlock class, representing a basic block in a disassembled function. It contains a sequence of instructions.

```APIDOC
BasicBlock:
  Represents a basic block in a disassembled function.
  Contains a sequence of instructions.
```

--------------------------------

### ProgramBackendQuokka API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/quokka.rst

API reference for the ProgramBackendQuokka class, detailing its members and inherited functionalities.

```APIDOC
.. autoclass:: qbindiff.loader.backend.quokka.ProgramBackendQuokka
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### BasicBlockBackendQuokka API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/quokka.rst

API reference for the BasicBlockBackendQuokka class, detailing its members and inherited functionalities.

```APIDOC
.. autoclass:: qbindiff.loader.backend.quokka.BasicBlockBackendQuokka
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### Quokka Exporter Basic Usage

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

Demonstrates the basic command-line invocation for the Quokka exporter, requiring paths to primary and secondary executables along with their corresponding Quokka files.

```shell
$ qbindiff -e1 primary.exe -e2 secondary.exe primary.exe.Quokka secondary.exe.Quokka
```

--------------------------------

### Python Library Usage for Binary Diffing

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

Demonstrates how to use qBinDiff as a Python library. It shows loading BinExport files, registering feature extractors like MnemonicTyped, processing the programs, and computing the matching results.

```python
from qbindiff import QBinDiff, Program
from qbindiff.features import MnemonicTyped
from pathlib import Path

p1 = Program("primary.BinExport")
p2 = Program("secondary.BinExport")

differ = QBinDiff(p1, p2)
differ.register_feature_extractor(MnemonicTyped, 1.0)
# Add other features if you want to

differ.process()

mapping = differ.compute_matching()
output = {(match.primary.addr, match.secondary.addr) for match in mapping}
```

--------------------------------

### AbstractInstructionBackend API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/abstract.rst

Defines the abstract interface for instruction backends, specifying methods and properties for representing and accessing instruction-level information.

```APIDOC
AbstractInstructionBackend:
  Description: Abstract base class for instruction backends.
  Inherits:
    - AbstractInstructionBackend
  Properties:
    - address: The address of the instruction.
    - mnemonic: The mnemonic of the instruction.
    - operands: A list of operands for the instruction.
    - size: The size of the instruction in bytes.
    - comment: An optional comment associated with the instruction.
  Methods:
    - get_operands(self) -> List[AbstractOperandBackend]: Retrieves all operands for the instruction.
  Example:
    # This is a conceptual representation. Actual usage depends on concrete implementations.
    # instruction = ConcreteInstructionBackend(...)
    # print(f"Instruction at {instruction.address}: {instruction.mnemonic}")
    # operands = instruction.get_operands()
  Related:
    - AbstractBasicBlockBackend
    - AbstractOperandBackend
```

--------------------------------

### InstNB Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the InstNB feature class, likely counting instructions. It includes all members and inherited properties.

```APIDOC
.. autoclass:: qbindiff.features.InstNB
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### MaxInsNB Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the MaxInsNB feature class, likely representing the maximum number of instructions. It includes all members and inherited attributes.

```APIDOC
.. autoclass:: qbindiff.features.MaxInsNB
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### InstructionBackendBinExport API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/binexport.rst

Documents the InstructionBackendBinExport class, used for representing individual instructions extracted by BinExport. It includes all public members and inherits from base classes.

```APIDOC
InstructionBackendBinExport:
  __init__(...) 
    Initializes the instruction backend with BinExport data.

  (Inherited members from base classes are documented here)

  (Specific methods and attributes for instruction representation)

  Parameters:
    - (Details about parameters for initialization and methods)
  Returns:
    - (Details about return values for methods)
```

--------------------------------

### qbindiff.loader.Data API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the Data class, representing a data element within the binary. It includes information about the data's address, size, and type.

```APIDOC
Data:
  Represents a data element within the binary.
  Includes information about the data's address, size, and type.
```

--------------------------------

### qbindiff MnemonicSimple Feature (Python)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/features.rst

TODO write description for MnemonicSimple feature.

```python
qbindiff.features.MnemonicSimple
```

--------------------------------

### qbindiff BeliefMWM Matcher API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/matcher.rst

API documentation for the BeliefMWM (Belief Message Passing) matching algorithm within qbindiff. This class implements a specific belief propagation approach for matching. All public members are documented.

```APIDOC
qbindiff.matcher.belief_propagation.BeliefMWM
  Documentation for the BeliefMWM matching algorithm.
  Implements belief propagation for matching.
  Includes all public members, inheritance details, and undocumented members.
  Purpose: Perform matching using the BeliefMWM algorithm.
```

--------------------------------

### qbindiff Matcher Class API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/matcher.rst

Documentation for the base Matcher class in qbindiff. This class likely serves as an abstract base or a common interface for various matching strategies. It is documented with all its public members.

```APIDOC
qbindiff.matcher.Matcher
  Documentation for the base Matcher class.
  Includes all public members (methods and attributes).
  Purpose: Provides a common interface for matching algorithms.
```

--------------------------------

### ProgramBackendBinExport API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/binexport.rst

Documents the ProgramBackendBinExport class, responsible for representing program-level data from BinExport. It inherits from base classes and includes all public members.

```APIDOC
ProgramBackendBinExport:
  __init__(...) 
    Initializes the program backend with BinExport data.

  (Inherited members from base classes are documented here)

  (Specific methods and attributes for program representation)

  Parameters:
    - (Details about parameters for initialization and methods)
  Returns:
    - (Details about return values for methods)
```

--------------------------------

### qbindiff Features API Documentation

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

API documentation for qbindiff features, detailing classes like LSH, StronglyConnectedComponents, BytesHash, CyclomaticComplexity, MDIndex, SmallPrimeNumbers, and ReadWriteAccess. This section aggregates class definitions and their associated members as specified by Sphinx autoclass directives.

```APIDOC
LSH:
    .. autoclass:: qbindiff.features.wlgk.LSH
        :members:
        :show-inheritance:
        :inherited-members:
        :undoc-members:
        :exclude-members:

StronglyConnectedComponents:
    .. autoclass:: qbindiff.features.StronglyConnectedComponents
        :members:
        :show-inheritance:
        :inherited-members:
        :undoc-members:
        :exclude-members:

BytesHash:
    .. autoclass:: qbindiff.features.BytesHash
        :members:
        :show-inheritance:
        :inherited-members:
        :undoc-members:
        :exclude-members:

CyclomaticComplexity:
    .. autoclass:: qbindiff.features.CyclomaticComplexity
        :members:
        :show-inheritance:
        :inherited-members:
        :undoc-members:
        :exclude-members:

MDIndex:
    .. autoclass:: qbindiff.features.MDIndex
        :members:
        :show-inheritance:
        :inherited-members:
        :undoc-members:
        :exclude-members:

SmallPrimeNumbers:
    .. autoclass:: qbindiff.features.SmallPrimeNumbers
        :members:
        :show-inheritance:
        :inherited-members:
        :undoc-members:
        :exclude-members:

ReadWriteAccess:
    .. autoclass:: qbindiff.features.ReadWriteAccess
        :members:
        :show-inheritance:
        :inherited-members:
        :undoc-members:
        :exclude-members:
```

--------------------------------

### Qbindiff Command-Line Options

Source: https://github.com/quarkslab/qbindiff/blob/main/README.md

Details the various command-line arguments available for Qbindiff, covering diffing parameters and post-processing passes. These options control the binary analysis, feature selection, distance metrics, and matching strategies.

```APIDOC
Qbindiff Command-Line Options:

Diffing Parameters:
  --feature -f <feature>[:<weight>[:<distance>]]
    Features to use for binary analysis. Can be specified multiple times. Features may be weighted and compared with a specific distance.
    Example: -f bnb, -f cc:3.0, -f cst:5.0

  --list-features
    List all available features.

  --normalize -n
    Normalize the Call Graph (can potentially lead to a partial matching).

  --distance -d <distance>
    Available distances: (canberra|euclidean|cosine|haussmann) [default: haussmann].

  --tradeoff -t <FLOAT>
    Tradeoff between function content (near 1.0) and call-graph information (near 0.0). [default: 0.8].

  --sparsity-ratio -s <FLOAT>
    Ratio of least probable matches to ignore. Between 0.0 (nothing ignored) to 1.0 (only perfect matches considered). [default: 0.6].

  --sparse-row -sr
    Whether to build the sparse similarity matrix considering its entirety or processing it row per row.

  --epsilon -e <FLOAT>
    Relaxation parameter to enforce convergence. [default: 0.9].

  --maxiter -i <INTEGER>
    Maximum number of iterations for belief propagation. [default: 1000].

Passes Parameters:
  --pass-feature-hash
    Anchor matches when functions have the same feature hash.

  --pass-user-defined <TEXT>
    Anchor matches using user-defined matches. Format is like 'primary-addr1:secondary-addr2,...'.

  --pass-flirt-hash
    Anchor matches using FLIRT/FunctionID like signatures.
```

--------------------------------

### PcodeMnemonicSimple Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the PcodeMnemonicSimple feature class, likely representing simple p-code mnemonics. It includes all members.

```APIDOC
.. autoclass:: qbindiff.features.PcodeMnemonicSimple
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### Mapping Class API Documentation (Python)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/mapping.rst

Documentation for the qbindiff.mapping.Mapping class. This entry details all public members, including methods and attributes, and indicates inherited members. It serves as a reference for using the Mapping functionality within the Qbindiff project.

```APIDOC
Class: qbindiff.mapping.Mapping

Description: Represents a mapping between elements in two different binaries.

Directives:
  :members: Document all public methods and attributes.
  :show-inheritance: Show inherited members.
  :inherited-members: Include members inherited from base classes.
  :undoc-members: Include members that do not have docstrings.
  :exclude-members: Exclude specific members from documentation.

This documentation block represents the structure and intent of documenting the Mapping class and its members as per the provided source directives. Specific method signatures, parameters, return values, and examples are not detailed in the input text but would typically be found here.
```

--------------------------------

### qbindiff.loader.Structure API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the Structure class, representing a data structure in the binary. It defines the layout and members of the structure.

```APIDOC
Structure:
  Represents a data structure in the binary.
  Defines the layout and members of the structure.
```

--------------------------------

### FunctionBackendQuokka API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/quokka.rst

API reference for the FunctionBackendQuokka class, detailing its members and inherited functionalities.

```APIDOC
.. autoclass:: qbindiff.loader.backend.quokka.FunctionBackendQuokka
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### qbindiff.Function API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the Function class, representing a function within a binary program. It provides access to function-specific details and its constituent basic blocks.

```APIDOC
Function:
  Represents a function within a binary program.
  Provides access to function-specific details and its constituent basic blocks.
```

--------------------------------

### OperandBackendQuokka API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/quokka.rst

API reference for the OperandBackendQuokka class, detailing its members and inherited functionalities.

```APIDOC
.. autoclass:: qbindiff.loader.backend.quokka.OperandBackendQuokka
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### MnemonicSimple Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the MnemonicSimple feature class, likely representing simple mnemonics. All members and inherited properties are documented.

```APIDOC
.. autoclass:: qbindiff.features.MnemonicSimple
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### Register Features for QBinDiff Analysis

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/basicex.rst

Details the process of registering feature extractors with QBinDiff. It involves iterating through a list of features, weights, and optional distance metrics/parameters to configure the comparison algorithm.

```python
import qbindiff

FEATURES_KEYS = {x.key: x for x in qbindiff.features.FEATURES}
ENABLED_FEATURES = (
    ("wlgk", 1.0, "cosine", {"max_passes": 1}),
    ("fname", 3.0),
    ("dat", 1.0),
    ("cst", 1.0),
    ("addr", 0.01),
)

for data in ENABLED_FEATURES:
    feature, weight = data[0], data[1]
    distance, params = None, {}
    if len(data) > 2:
        distance = data[2]
        if len(data) > 3:
            params = data[3]
    if feature not in FEATURES_KEYS:
        print(f"Feature '{feature}' not recognized - ignored.")
        continue
    differ.register_feature_extractor(FEATURES_KEYS[feature], float(weight), distance=distance, **params)
```

--------------------------------

### LibName Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the LibName feature class, likely representing library names. All members and inherited attributes are documented.

```APIDOC
.. autoclass:: qbindiff.features.LibName
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### FuncName Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the FuncName feature class, related to function names. It lists all members and inherited attributes.

```APIDOC
.. autoclass:: qbindiff.features.FuncName
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### AbstractProgramBackend API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/abstract.rst

Defines the abstract interface for program backends, specifying methods and properties required to represent and access program-level information.

```APIDOC
AbstractProgramBackend:
  Description: Abstract base class for program backends.
  Inherits: 
    - AbstractProgramBackend
  Methods:
    - __init__(self, ...): Initializes the program backend.
    - get_functions(self) -> List[AbstractFunctionBackend]: Retrieves all functions within the program.
    - get_function_by_address(self, address: int) -> Optional[AbstractFunctionBackend]: Retrieves a function by its starting address.
    - get_entry_point(self) -> Optional[AbstractFunctionBackend]: Retrieves the program's entry point function.
    - get_functions_count(self) -> int: Returns the total number of functions.
    - get_basic_blocks_count(self) -> int: Returns the total number of basic blocks.
    - get_instructions_count(self) -> int: Returns the total number of instructions.
  Example:
    # This is a conceptual representation. Actual usage depends on concrete implementations.
    # program_backend = ConcreteProgramBackend(...)
    # functions = program_backend.get_functions()
    # entry_point = program_backend.get_entry_point()
  Related:
    - AbstractFunctionBackend
    - AbstractBasicBlockBackend
```

--------------------------------

### qbindiff BeliefQAP Matcher API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/matcher.rst

API documentation for the BeliefQAP (Belief Quadratic Assignment Problem) matching algorithm in qbindiff. This class represents another belief propagation-based matching strategy. All public members are documented.

```APIDOC
qbindiff.matcher.belief_propagation.BeliefQAP
  Documentation for the BeliefQAP matching algorithm.
  Implements belief propagation for the Quadratic Assignment Problem.
  Includes all public members, inheritance details, and undocumented members.
  Purpose: Perform matching using the BeliefQAP algorithm.
```

--------------------------------

### qbindiff.types Module API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/types.rst

Documentation for the qbindiff.types module, listing its members. This section details the types and data structures exposed by the module.

```apidoc
Module: qbindiff.types

Description: Provides core type definitions and enumerations for the qbindiff library.

Members:
  - Excludes 'Distance' from direct module members as it's an enum.
  - Lists other exported members from the module (specific members not detailed in source text).

Usage:
  Import types from the qbindiff library to access these definitions.
  Example:
  from qbindiff.types import SomeType, AnotherType

Related Modules:
  - qbindiff.types.Distance (specific enumeration)
```

--------------------------------

### OperandBackendBinExport API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/binexport.rst

Documents the OperandBackendBinExport class, responsible for representing operands within instructions from BinExport data. It includes all public members and inherits from base classes.

```APIDOC
OperandBackendBinExport:
  __init__(...) 
    Initializes the operand backend with BinExport data.

  (Inherited members from base classes are documented here)

  (Specific methods and attributes for operand representation)

  Parameters:
    - (Details about parameters for initialization and methods)
  Returns:
    - (Details about return values for methods)
```

--------------------------------

### StrRef Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the StrRef feature class, which pertains to string references within the binary. It exposes all members of the class and its inheritance hierarchy.

```APIDOC
.. autoclass:: qbindiff.features.StrRef
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### BasicBlockBackendBinExport API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/binexport.rst

Documents the BasicBlockBackendBinExport class, which handles basic block representations from BinExport data. It includes all public members and inherits from base classes.

```APIDOC
BasicBlockBackendBinExport:
  __init__(...) 
    Initializes the basic block backend with BinExport data.

  (Inherited members from base classes are documented here)

  (Specific methods and attributes for basic block representation)

  Parameters:
    - (Details about parameters for initialization and methods)
  Returns:
    - (Details about return values for methods)
```

--------------------------------

### FunctionBackendBinExport API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/binexport.rst

Documents the FunctionBackendBinExport class, designed to represent function-level information extracted via BinExport. It includes all public members and inherits from base classes.

```APIDOC
FunctionBackendBinExport:
  __init__(...) 
    Initializes the function backend with BinExport data.

  (Inherited members from base classes are documented here)

  (Specific methods and attributes for function representation)

  Parameters:
    - (Details about parameters for initialization and methods)
  Returns:
    - (Details about return values for methods)
```

--------------------------------

### qbindiff StrRef Feature (Python)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/features.rst

TODO write description for StrRef feature.

```python
qbindiff.features.StrRef
```

--------------------------------

### Constant Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the Constant feature class, likely representing constant values found in the binary. All members are included, along with inherited ones.

```APIDOC
.. autoclass:: qbindiff.features.Constant
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### GraphNbComponents Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the GraphNbComponents feature class, likely counting the number of connected components in a graph. It includes all members.

```APIDOC
.. autoclass:: qbindiff.features.GraphNbComponents
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```

--------------------------------

### qbindiff DatName Feature (Python)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/features.rst

TODO write description for DatName feature.

```python
qbindiff.features.DatName
```

--------------------------------

### AbstractBasicBlockBackend API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/backends/abstract.rst

Defines the abstract interface for basic block backends, specifying methods and properties for representing and accessing basic block-level information.

```APIDOC
AbstractBasicBlockBackend:
  Description: Abstract base class for basic block backends.
  Inherits:
    - AbstractBasicBlockBackend
  Properties:
    - address: The starting address of the basic block.
    - size: The size of the basic block in bytes.
    - instructions: A list of instructions belonging to the basic block.
    - successors: A list of addresses of successor basic blocks.
    - predecessors: A list of addresses of predecessor basic blocks.
  Methods:
    - get_instructions(self) -> List[AbstractInstructionBackend]: Retrieves all instructions within the basic block.
    - get_instructions_count(self) -> int: Returns the total number of instructions in the basic block.
  Example:
    # This is a conceptual representation. Actual usage depends on concrete implementations.
    # basic_block = ConcreteBasicBlockBackend(...)
    # print(f"Basic block at {basic_block.address}")
    # instructions = basic_block.get_instructions()
  Related:
    - AbstractFunctionBackend
    - AbstractInstructionBackend
```

--------------------------------

### qbindiff.loader.StructureMember API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the StructureMember class, representing a single member within a data structure. It specifies the member's offset, size, and type.

```APIDOC
StructureMember:
  Represents a single member within a data structure.
  Specifies the member's offset, size, and type.
```

--------------------------------

### qbindiff.loader.Operand API

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/loader.rst

Documentation for the Operand class, representing an operand of an instruction. It can be a register, immediate value, or memory reference.

```APIDOC
Operand:
  Represents an operand of an instruction.
  Can be a register, immediate value, or memory reference.
```

--------------------------------

### BBlockNb Feature Documentation (APIDOC)

Source: https://github.com/quarkslab/qbindiff/blob/main/doc/source/api/features.rst

Documents the BBlockNb feature class, likely counting basic blocks. It includes all public members and inherited attributes.

```APIDOC
.. autoclass:: qbindiff.features.BBlockNb
    :members:
    :show-inheritance:
    :inherited-members:
    :undoc-members:
    :exclude-members:
```