Introduction to HAL

HAL [/hel/] is a comprehensive netlist reverse engineering and manipulation framework. Virtually all available research on netlist analysis operates on a graph-based representation of the netlist under inspection. At its core, HAL provides exactly that: A framework to parse netlists of arbitrary sources, e.g., FPGAs or ASICs, into a graph-based netlist representation and to provide the necessary built-in tools for traversal and analysis of the included gates and nets.

Our vision is that HAL becomes the hardware-reverse-engineering-equivalent of tools like IDA or Ghidra. We want HAL to enable a common baseline for researchers and analysts to improve reproducibility of research results and abstract away recurring basic tasks such as netlist parsing etc.

• High performance thanks to the optimized C++ core
• Flexibility through built-in Python bindings
• Modularity via a C++ plugin system
• Stability is ensured via a rich test suite

HAL is actively developed by the Embedded Security group of the Max Planck Institute for Security and Privacy. Apart from multiple research projects, it is also used in our university lecture Introduction to Hardware Reverse Engineering.

GUI

While the core functionality of HAL resides within the so called HAL Core and is available only via the C++ and Python APIs, the GUI provides an easy interface for users to interact with the netlist. It provides a graphical representation of the netlist enabling the user to navigate through the sea-of-gates or even manipulate it during investigation. Providing a set of widgets, it gives access to all kinds of information about the netlist and its components. Additionally, it provides access to the Python API via an embedded Python editor and a respective shell.

Python Bindings

The Python API provides easy access to the underlying core functionalities from within the GUI and the integrated Python shell. It presents the user with a powerful tooling to easily run small experiments on the netlist for which the C++ Plugin system emerges to be too cumbersome. The Python API is provided via so called Python bindings that basically translate (almost) all C++ API functions into Python.

Plugin System

HAL facilitates customization by providing a sophisticated plugin interface that allows to its extend its functionality using plugins written in C++. Via the plugin system, the developer has full access to HAL's rich C++ API providing access to all components of its internal netlist representation. Furthermore, Python bindings for plugin functionality can easily be deployed to be used within the GUI or from the build-in Python shell. By default, HAL comes with a set of plugins that have been developed at our research group and enrich HAL's capabilities.

Shipped Plugins

• GUI: A feature-rich GUI allowing for visual netlist inspection and interactive analysis
  • Native integration of a Python shell with access to the HAL Python bindings
  • Isolation of specific gates or modules for clutter-free inspection
  • Interactive traversal of netlists
  • Detailed widgets with information on all aspects of the inspected netlist
• Netlist Simulator: A simulator for arbitrary parts of a loaded netlist
• Dataflow Analysis: Our dataflow analysis plugin DANA that recovers high-level registers in an unstructured netlist
• Graph Algorithms: igraph integration for direct access to common algorithms from graph-theory
• Python Shell: A command-line plugin to spawn a Python shell preloaded with the HAL Python bindings
• VHDL & Verilog Parsers: Adds support for parsing VHDL and Verilog files as netlist input formats
• Liberty Parser: Adds support for arbitrary gate libraries in the standard liberty gate library format
• VHDL & Verilog Writers: Adds support for serializing a (modified) netlist to synthesizable VHDL or Verilog files
• Gate Libraries: Adds support for the XILINX Unisim and Simprim gate libraries

Additional Ressources

This wiki provides an overview of HAL and its most important applications. It presents small code snippets written using the Python API to teach the underlying concepts. Additionally, a detailed description of the APIs can be found here:

• C++ API documentation
• Python API documentation.

Note that we also have a set of modern state-of-the-art benchmark circuits for the evaluation of netlist reverse engineering techniques available in a seperate repository.