Bienvenue dans la documentation de Degate !¶
Note
Vous trouverez ici toute la documentation disponible pour utiliser Degate. Toutefois, cette documentation est toujours en construction. Ainsi, si une information manque, vous pouvez le signaler ici.
Degate est un logiciel multiplateforme pour la rétro-ingénierie semi-automatique de puce de silicium. Ce projet est un fork du projet initial, l’objectif final étant de le remplacer. Pour en savoir plus, veuillez visiter notre page wiki et, si vous voulez discuter, visitez notre Gitter. Le responsable actuel du projet est Dorian Bachelot.
Introduction¶
You will find below a list of topics that will present basic functionalities of Degate.
Create a new project¶
Note
The old Degate was using a size based project system, with a static project size defined during project creation. This meant inability to change the size after the project creation, even when you add a larger image than previously planned (so, with the old Degate, you had to recreate the project “from scratch”). The new Degate uses a different system, you no longer have to worry about the project size during creation, you just need to provide at least one layer with a valid image.
Images alignment¶
A Degate project needs only layer images to start. They will be the core of the project and the core of the process to recover the netlist (or a part of it). However there is some condition that you need to take care before creating the project (you can reimport layer images after the project creation, so no worries):
- The layer images need to be aligned (they must be able to overlap correctly).
- The layer images need to have the same overall quality (this is not mandatory, but if they are not of the same quality, you will have pain to align them).
Avertissement
Very important: Degate has (for the moment) no built-in tools to align layer images, you have to do this downstream.
To align these layer images, you have to consider that Degate cannot shift them, they will be open directly and placed in 0,0 (upper left corner). So, if these layer images are not aligned from the upper left corner, there will be an offset between the layers.
Project creation dialog¶
You can access the project creation dialog from the « Project » tabs of the top menu, and by pressing the « New » button of this submenu. You will arrive on this window:
With this dialog, you will be able to set the project name, the project directory path and the project layers. The project directory path is the directory where the project directory will be created. You will need at least one valid layer with an image set. To add a layer, you need to click on the « + » button. After that, a new layer will appear where you can set the state (if disabled, you will not see it inside the workspace, this can be changed anytime), the description, the type and the image.
The type of a layer can be of these 4 types:
- Undefined: undefined layer (useful if you want to start the analysis later).
- Metal: interconnection layer (M1, M2 M…).
- Logic: the layer where you will define gates.
- Transistor: transistor layer.
To learn more about these types, please see the Layman’s Guide to IC Reverse Engineering here.
To set the background image, you need to click on the red button, it will open a new dialog to select an image to import. After that done, you just need to click on « Ok » to validate and wait during the image(s) importation.
After clicking « Ok » you will get a loading dialog:
Well done ! Your project is now created and loaded.
Matching¶
To start a « matching phase » you firstly need to select an area (by holding the right click) to define the area used to match templates, vias or wires. This is optional, if you don’t select an area, the whole project size will be used. Also, please note that the « matching phase » will use the current selected/active layer.
You can access the different « matching phase » types in the « Matching » top bar submenu.
Template matching¶
Template matching will automatically detect gate template inside an area. After selecting the area, select « Template matching » in the « Matching » top bar submenu. You will then fall on this dialog:
You need to select the desired gate(s) template to match (you need at least one). Then, you will fall on this dialog:
To start the template matching phase, you can adjust different options, which are:
| Option name | Meaning |
|---|---|
| Threshold to start hill climbing | The threshold to start looking for a gate template. If the value is low, it will take more time to complete. |
| Threshold for detection | The threshold to confirm the detection of a gate template. If the value is low, it will take more time to complete. This value should be greater than the one above. |
| Scale image down by factor | The scaled version of the image to use during the detection. The more the image will be scaled down, the more the time to complete will be low. |
| Max step size for search after scaling | If the value is low (1 pixel minimum), it will take more time to complete, but will be more accurate. This value depends on the scaled version of the image (if the image is very scaled, it’s better to use a value near 1). |
| Match template orientation(s) | Orientation(s) to search for a gate template. For example, if you select only the normal orientation, if there is the same gate template but flipped, it will not match. |
| Match template type | Detect for gate template along grid columns or rows. If no grid is available, it will not use any grid. |
After running the template matching, you will obtain a dialog with the results of the detection phase, like that:
Via matching¶
Via matching in Degate will take all already placed vias as reference (need at least 1), and will use them to match new one(s) with the same layout. After selecting (or not) the matching area, you can access via matching by selecting « Via matching » in the « Matching » top bar submenu. You will then fall on this dialog:
To start the via matching phase, you can adjust different options, which are:
| Option name | Meaning |
|---|---|
| Threshold for detection | The threshold to detect a via, a higher value will only keep the most matching vias. If the value is low, it will take more time to complete. |
| Via diameter | The via diameter to match (default is the project default via diameter value). |
| Max vias to match | Max number of vias to match, it can be useful when you are not sure of your parameters values. |
Wire matching¶
Avertissement
Wire matching is a « broken » feature of Degate, it’s not working well. However, you can try to use it keeping in mind that this functionality get some limitations.
We will not document this part of Degate due to the warning above, and because it will be completely rewritten shortly.
Modules¶
Modules are a way to organize your logic model into separate groups and export them (in Verilog language). You always have a top level module, if you want to export your project in Verilog, export the top level module (the one with the project name).
A module can be a child of another one, and every module is the main module child. You can move gates into modules, inside the module dialog or in the workspace with the « Logic » top bar submenu. All gates are, by default, in the project module (top level one).
In this dialog you can find 3 panels, one is the module one, where you can create or remove modules, set a type or export in Verilog. The second one, will show all gates of the selected module. You can move them into another module or jump to them into the workspace. The last panel will show all module ports.
Avertissement
You can only export a module in Verilog.
Module port¶
A module port is an object connected with other objects (at least one) that are not part of this module.
Rule violations¶
The rule violations dialog defines will list all violations of the current project regarding the logic model. It will help you to keep track of open ports, unconnected input ports or other potential logic errors.
With this dialog you can also mark a violation as accepted, it will remove it from the violations tab if you consider it’s not a real problem/error.
By selecting a violation or accepted violation, you can accept/reject it or go to the concerned object. You also have access to a filter, you just have to write a string of characters and press « ENTER » to filter every violation/accepted violation containing the string. The refresh button will enforce a full refresh of all violations and accepted violations (it will recalculate every violation of the logic model).
Possible violations are:
| Violation | Description |
|---|---|
| open_port | A port is unconnected. |
| net.outputs_connected | An output port is connected with other out ports. |
| net.not_feeded | An input port is not fed. |
Shortcuts¶
Shortcuts usable in Degate are:
| Shortcut | Action |
|---|---|
| LEFT click | Object selection |
| RIGHT click | Context menu |
| Hold LEFT click | Move |
| Hold RIGHT click | Area selection OR wire tool |
| CTRL + LEFT click | Multiple object selection |
| CTRL + hold RIGHT click | Selection of all objects in the area |
| DEL | Delete selected objects |
Degate main window¶
In this page, we will dig into the Degate main window. The Degate main window is composed of a top menu, a toolbar, a workspace and a notification bar.
- 1 (blue): top menu.
- 2 (red): toolbar.
- 3 (green): workspace.
- 4 (yellow): notification bar.
Top menu¶
The top menu is where you will every possible action in the software. It is split in 11 submenu:
- The project submenu: create and load a project.
- The edit submenu: edit preferences.
- The view submenu: hide/show elements and configure the grid.
- The layer submenu: edit layers.
- The gate submenu: create and edit gate and gate template.
- The annotation submenu: edit and create annotations.
- The emarker submenu: edit emarkers.
- The via submenu: edit vias.
- The logic submenu: remove, interconnect and isolate objects.
- The matching submenu: template, via and wire matching.
- The help submenu: list of shortcuts, documentation link and about dialog.
Project submenu¶
The project submenu offers the possibility to open, create and close a project. You can also edit project settings and create a subproject.
View submenu¶
The view submenu offers the possibility to hide or show objects (like gates, gates names, wires…), to enable/disable/configure the grid and to access the fullscreen mode.
Layer submenu¶
The layer submenu allows you to launch the layer edit dialog and to directly change the current layer background (it’s a shortcut to the same functionality in the layer edit dialog).
Gate submenu¶
The gate submenu will help you to create a gate or gate template from selection, to edit a selected gate, to list gates templates, to list gates instances and a way to automatically name gates along rows or columns.
Annotation submenu¶
The annotation submenu will help you to create, edit and get a list of annotations.
Logic submenu¶
The logic submenu will help you to remove selected objects, to interconnect or isolate them, to move objects into a module or to inspect a selected object.
Matching submenu¶
The matching submenu will allow you to start template matching, via matching or wire matching dialogs.
Help submenu¶
To finish, the help menu will give you access to a shortcut list dialog, to a documentation redirection, to an update checker and to the about dialog (with a changelog, license…).
Toolbar¶
The toolbar gives you access to actions and tools selection.
- 1: Move to the upper layer (if possible).
- 2: Move to the lower layer (if possible).
- 3: Zoom in.
- 4: Zoom out.
- 5: Select the area selection tool (to create gates, annotation…). It’s the blue rectangle created using the mouse right click.
- 6: Select the wire creation tool.
- 7: Open the gate library (list of all gates templates).
- 8: Open the rule violation dialog (list of electric errors/warnings).
- 9: Open the module dialog (to sort and export the extracted netlist).
Workspace area¶
The workspace area is where you will work on the chip layers images, draw gates, draw wires, create annotations… It’s where all the magic takes place.
Notification bar¶
The notification bar will show messages on its left side and information, with the current layer position (and type) and the current coordinates, on the right side.
General¶
You will find here general documentation about workspace elements.
Logic model¶
The logic model represents the electrical logic of the project, where the majority of your work will be on. It’s directly linked to the reconstruction of the netlist, which will pass by creating a list of used gates (with a behaviour defined, in Verilog for example), finding gate instances and interconnecting all electrical objects to then be able to retrieve the full netlist and be able to export it.
Annotation¶
An annotation is a block with a text line that can be used to annotate/highlight a region of interest.
Subproject¶
A subproject is a clickable annotation, with a double click you can close and save the current project and open the concerned subproject.
Create subproject¶
To create a subproject, you need to select an area with the right click, go to the « Project » submenu of the top bar, and click on « Create a subproject from selection ».
Then, it will ask you to create a new project, as presented in a previous page (even if it’s a subproject).
EMarker¶
An EMarker is a general connectable electrical object, it representation of an electrically connectable marker object. It can represent any non-available electrical object in Degate (it’s barely a placeholder).
You can set these properties for a EMarker : a name, a description, if the EMarker is a module port and a fill color. To set an EMarker diameter, see the project settings dialog (from the « Project » submenu of the top bar).
Gate¶
There are two separate concepts involving gates : gate instances and gate templates.
Gate templates¶
A gate template represents a gate type (like an inverter, a flip-flop…) that can be analysed, had a specific behaviour (coded in VHDL for example) and be reused and instantiated somewhere else. A gate instance (what appears in the workspace) is always derived from a gate template.
You can access a list of gate templates with the gate library dialog available in the toolbar or in the « Gate » submenu of the top bar.
Gate instances¶
A gate instance is a representation of a physical implementation of a gate template. To create a gate instance, you always need to have the corresponding gate template already created.
Gate edit¶
You can edit a gate instance (or a gate template from the gate library) by double clicking on it or by using the « Edit selected » from the « Gate » submenu of the top bar. In it, you will find three tabs : entity, behaviour and layout.
Entity tab¶
The entity tab will let you edit basic information about the gate template like colors, name, description, ports…
Behaviour tab¶
The behaviour tab will let you set the logic behind a gate, his behaviour. You can set it with free text, in VHDL or in Verilog. You will then be able to compile and test it with gtkwave (for Verilog only).
Also, when the behaviour is set, you can export it when it’s inside a module, and if the module is the project top level module, it will export the whole netlist.
Avertissement
You can only export a module in Verilog so, if you want to be able to export the whole netlist, use Verilog to set gate instances behaviour.
Layout tab¶
The layout tab will show you images of a gate instance for the gate template that’s being edited on one metal layer (if set), one logic layer (mandatory, so always set) and one transistor layer (if set).
Via¶
A via is an electrical connectable object that will represent an electrical connection between two adjacent layers.
To create a via, you can right click to open the context menu, and select « Create new via ». To connect two vias, you need to electrically interconnect them (by switching layers and CTRL + Right click to select them).
You can also connect a via to other objects (like ports or wires…).
You can follow a connected via to go to the interconnected layer, by right clicking and selecting the « Follow via » option in the context menu.
Wire¶
You can create a wire, that is a connectable electrical object, with the wire tool and by right clicking and moving the mouse.
By default, each new wire first point will be the end of the previous one. To reset the wire tool, right click to open the context menu and click on « Reset wire tool ».
You should limit the number of wires to keep the workspace clean, for example, if a wire connects two gate ports, just interconnect them and avoid creating an intermediate wire.