GUI
The HAL 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.
The left, right and bottom border of the HAL GUI provide buttons with the names of the widgets being written on. Click on one of these buttons to toggle their visibility. Click and drag the buttons to one of the borders to change their positions inside the HAL GUI. Each widget can be detached to form a separate windows instead of being incorporated in the docking system. To achieve this click the button in the top right corner of each widget. The detached windows offers a button in the same position to reattach it back into the docking system.
The GUI uses three key concepts to guarantee easy interaction with the netlist. Described below are the concepts of selections, views and user interactions. Selections and views are mainly used in the Graph View. User interactions are tracked internally to allow the user to revert certain actions by clicking the undo button on the upper left. Besides these abstract descriptions check the Graph View article here to see how these concepts are integrated in the workflow of the HAL GUI.
A selection is a subset of gates, nets, and modules that are visible within the Graph View. Selections are the basis for further operations like assignments to modules or groupings.
See here for more information on selections.
One of the key aspects of the GUI is the concept of views. A single view visualizes a subset of the netlist's gates, nets and modules. The GUI can hold multiple views with each view showing a different subset of the netlist's components. For example, one view can show the complete netlist with all components present while another view only shows a couple of gates. It's possible to create these views, switch between them and modify them. Views are an important part of the Graph View. For optimal use of views check the Graph View article here.
Most interactions with the GUI are tracked internally. This allows the user to revert these actions by clicking the undo button on the upper left. These interactions include, among other things, grouping assignments, selecting elements in the Graph View and creating new modules. The user can record user interactions with macros by selecting Macros > Start Recording in the menu bar. After selecting Macro > Stop recording in the menubar, the recorded macro will be saved as an .xml file. Macros can be played by selecting Macros > Play Recording in the menu bar. In case that HAL crashes, the user interactions are dumped into a file in the HAL directory (build/bin). This file is useful in combination with the netlist for the developers to reproduce the crash.
The GUI is comprised of multiple widgets each with a specific purpose for helping the hardware reverse engineering process. Each paragraph below describes one of the available widgets. To see in-depth descriptions follow the linked wiki pages.
The Graph View displays the netlist's components as a graph and offers several ways to interact with them. It allows to create modules as well as to fold and unfold them. Groupings can be viewed and edited. The navigation feature offers an easy way to follow a path through the graph on an element by element basis. Additionally the Cone View can reveal elements step by step that are connected to a starting point of interest to explore the graph and slowly reveal the structure of the netlist and its components.
See here for more detailed descriptions on the features offered by the Graph View.
The Views Widget provides an overview of all existing views. From within the widget, new views can be created and old ones can be (re)opened in the Graph View, duplicated, have their name changed, searched, and deleted.
See here for more detailed descriptions on the features offered by the Views Widget.
The Module Widget illustrates the netlist's module hierarchy as a tree. The widget features helpful actions including, but not limited to, adding a child module or changing the module's displayed color.
See here for more detailed descriptions on the features offered by the Module Widget.
The Groupings Widget provides a table of all existing groupings. From within the widget, new groupings can be created, selected in the Graph View, have their name or color changed and deleted.
See here for more detailed descriptions on the features offered by the Groupings Widget.
The Selection Details Widget presents details on each of the gates, nets and modules within the current selection. Its main features are a hierarchical list of elements that are currently selected in the GUI and a details section delivering additional information on a single element of that selection.
See here for more detailed descriptions on the features offered by the Selection Details Widget.
The Python Editor Widget provides a light weight code editor for developing Python scripts. From within the widget, multiple scripts can be opened, edited, run and saved. The editor behaves like a standard text editor with functions like undo, copy and past but also supports some quality of life features such as auto indent, simple syntax highlighting, a code minimap as well as auto completion to some extent.
See here for more detailed descriptions on the features offered by the Selection Python Editor Widget.
The Python Console Widget provides an interactive console in which python code can be executed. The python console is connected to the hal python environment so that the Python Core API and Python GUI API are accessible. Code completion and code suggestion via Tab are also supported to some extent.
See here for more detailed descriptions on the features offered by the Python Console Widget.
The Log Widget provides a live view of the HAL log. The information is split up into different channels depending on their category like core, python or gui. The information can be filtered by selecting either a specific channel or the all category in the drop-down list at the top left corner of the widget. The widget does not show channels in which nothing has been logged yet, so new channels may appear while using HAL.
See here for more detailed descriptions on the features offered by the Log Widget.
The Python GUI API enables access to the HAL GUI through the Python Console and through python scripts executed in the Python Editor. The Python GUI API allows interacting with the current selection of the Graph View. The python code can retrieve gates, nets and modules of the current selection as well as select and deselect items.
See here for more detailed descriptions on the features offered by the Python GUI API.