Merge branch 'master' into feature/pin_group_order

CHANGELOG.md

@@ -3,8 +3,7 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 * **WARNING:** this release breaks compatibility with Ubuntu 20.04 LTS
-* **WARNING:** this release breaks the API of the `graph_algorithm` plugin
-* **WARNING:** this release breaks the API of the `dataflow_analysis` plugin
+* **WARNING:** this release breaks the API of the `graph_algorithm`, `dataflow`, and `xilinx_toolbox` plugins
 * GUI
   * refactored module widget
     * added option to show gate content for each module
@@ -42,6 +41,9 @@ All notable changes to this project will be documented in this file.
     * extended maximum line with the CSV parser can handle
     * changed warning messages for waveform parsing and made them more specific
     * changed policy toward 'dangling' wires, they are no longer ignored but considered as global inputs or outputs
+  * changed `xilinx_toolbox` plugin
+    * added `split_shift_registers` function to split `SRL16E` gates into multiple flip-flops
+    * changed Python bindings for better usability
 * core
   * pin (groups)
     * added optional flag to determine whether a pin group has an inherent order (defaults to `false`)

plugins/gate_libraries/definitions/XILINX_UNISIM.hgl

@@ -375865,14 +375865,14 @@
                 {
                     "name": "Q",
                     "direction": "output",
-                    "type": "data",
+                    "type": "state",
                     "ascending": false,
                     "start_index": 0,
                     "pins": [
                         {
                             "name": "Q",
                             "direction": "output",
-                            "type": "data"
+                            "type": "state"
                         }
                     ]
                 }
@@ -485878,28 +485878,28 @@
                 {
                     "name": "Q",
                     "direction": "output",
-                    "type": "data",
+                    "type": "state",
                     "ascending": false,
                     "start_index": 0,
                     "pins": [
                         {
                             "name": "Q",
                             "direction": "output",
-                            "type": "data"
+                            "type": "state"
                         }
                     ]
                 },
                 {
                     "name": "Q31",
                     "direction": "output",
-                    "type": "data",
+                    "type": "state",
                     "ascending": false,
                     "start_index": 0,
                     "pins": [
                         {
                             "name": "Q31",
                             "direction": "output",
-                            "type": "data"
+                            "type": "state"
                         }
                     ]
                 }
@@ -495782,28 +495782,28 @@
                 {
                     "name": "Q",
                     "direction": "output",
-                    "type": "data",
+                    "type": "state",
                     "ascending": false,
                     "start_index": 0,
                     "pins": [
                         {
                             "name": "Q",
                             "direction": "output",
-                            "type": "data"
+                            "type": "state"
                         }
                     ]
                 },
                 {
                     "name": "Q15",
                     "direction": "output",
-                    "type": "data",
+                    "type": "state",
                     "ascending": false,
                     "start_index": 0,
                     "pins": [
                         {
                             "name": "Q15",
                             "direction": "output",
-                            "type": "data"
+                            "type": "state"
                         }
                     ]
                 }
@@ -766832,14 +766832,14 @@
                 {
                     "name": "Q",
                     "direction": "output",
-                    "type": "data",
+                    "type": "state",
                     "ascending": false,
                     "start_index": 0,
                     "pins": [
                         {
                             "name": "Q",
                             "direction": "output",
-                            "type": "data"
+                            "type": "state"
                         }
                     ]
                 }

plugins/verilog_writer/src/verilog_writer.cpp

@@ -473,14 +473,14 @@ namespace hal
 
     std::string VerilogWriter::get_unique_alias(std::unordered_map<std::string, u32>& name_occurrences, const std::string& name) const
     {
+        name_occurrences[name]++;
+
         // if the name only appears once, we don't have to suffix it
         if (name_occurrences[name] < 2)
         {
             return name;
         }
 
-        name_occurrences[name]++;
-
         // otherwise, add a unique string to the name
         return name + "__[" + std::to_string(name_occurrences[name]) + "]__";
     }
@@ -504,4 +504,4 @@ namespace hal
 
         return s;
     }
-}    // namespace hal
+}    // namespace hal

plugins/xilinx_toolbox/CMakeLists.txt

@@ -1,5 +1,7 @@
 option(PL_XILINX_TOOLBOX "PL_XILINX_TOOLBOX" OFF)
+
 if(PL_XILINX_TOOLBOX OR BUILD_ALL_PLUGINS)
+
     file(GLOB_RECURSE XILINX_TOOLBOX_INC ${CMAKE_CURRENT_SOURCE_DIR}/include/*.h)
     file(GLOB_RECURSE XILINX_TOOLBOX_SRC ${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp)
     file(GLOB_RECURSE XILINX_TOOLBOX_PYTHON_SRC ${CMAKE_CURRENT_SOURCE_DIR}/python/*.cpp)
@@ -8,5 +10,6 @@ if(PL_XILINX_TOOLBOX OR BUILD_ALL_PLUGINS)
                    SHARED
                    HEADER ${XILINX_TOOLBOX_INC}
                    SOURCES ${XILINX_TOOLBOX_SRC} ${XILINX_TOOLBOX_PYTHON_SRC}
-                   )
+                   PYDOC SPHINX_DOC_INDEX_FILE ${CMAKE_CURRENT_SOURCE_DIR}/documentation/xilinx_toolbox.rst
+                )
 endif()

plugins/xilinx_toolbox/documentation/xilinx_toolbox.rst

@@ -0,0 +1,8 @@
+Xilinx Toolbox
+==========================
+
+.. automodule:: xilinx_toolbox
+    :members: split_luts, split_shift_registers, parse_xdc_file
+
+.. autoclass:: xilinx_toolbox.XilinxToolboxPlugin
+    :members:

plugins/xilinx_toolbox/include/xilinx_toolbox/plugin_xilinx_toolbox.h

@@ -1,3 +1,33 @@
+// MIT License
+//
+// Copyright (c) 2019 Ruhr University Bochum, Chair for Embedded Security. All Rights reserved.
+// Copyright (c) 2019 Marc Fyrbiak, Sebastian Wallat, Max Hoffmann ("ORIGINAL AUTHORS"). All rights reserved.
+// Copyright (c) 2021 Max Planck Institute for Security and Privacy. All Rights reserved.
+// Copyright (c) 2021 Jörn Langheinrich, Julian Speith, Nils Albartus, René Walendy, Simon Klix ("ORIGINAL AUTHORS"). All Rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+/**
+ * @file plugin_xilinx_toolbox.h 
+ * @brief This file contains all functions related to the HAL plugin API.
+ */
+
 #pragma once
 
 #include "hal_core/plugin_system/plugin_interface_base.h"
@@ -7,13 +37,52 @@ namespace hal
 {
     class Netlist;
 
+    /**
+     * @class XilinxToolboxPlugin
+     * @brief Plugin interface for the Xilinx toolbox.
+     * 
+     * This class provides an interface to integrate the Xilinx toolbox as a plugin within the HAL framework.
+     */
     class PLUGIN_API XilinxToolboxPlugin : public BasePluginInterface
     {
     public:
+        /** 
+         * @brief Default constructor for `XilinxToolboxPlugin`.
+         */
+        XilinxToolboxPlugin() = default;
+
+        /** 
+         * @brief Default destructor for `XilinxToolboxPlugin`.
+         */
+        ~XilinxToolboxPlugin() = default;
+
+        /**
+         * @brief Get the name of the plugin.
+         *
+         * @returns The name of the plugin.
+         */
         std::string get_name() const override;
+
+        /**
+         * @brief Get the version of the plugin.
+         *
+         * @returns The version of the plugin.
+         */
         std::string get_version() const override;
 
-        void initialize() override;
+        /**
+         * @brief Get a short description of the plugin.
+         *
+         * @returns The short description of the plugin.
+         */
+        std::string get_description() const override;
+
+        /**
+         * @brief Get the plugin dependencies.
+         * 
+         * @returns A set of plugin names that this plugin depends on.
+         */
+        std::set<std::string> get_dependencies() const override;
 
         // preprocessing
 

plugins/xilinx_toolbox/include/xilinx_toolbox/preprocessing.h

@@ -0,0 +1,73 @@
+// MIT License
+//
+// Copyright (c) 2019 Ruhr University Bochum, Chair for Embedded Security. All Rights reserved.
+// Copyright (c) 2019 Marc Fyrbiak, Sebastian Wallat, Max Hoffmann ("ORIGINAL AUTHORS"). All rights reserved.
+// Copyright (c) 2021 Max Planck Institute for Security and Privacy. All Rights reserved.
+// Copyright (c) 2021 Jörn Langheinrich, Julian Speith, Nils Albartus, René Walendy, Simon Klix ("ORIGINAL AUTHORS"). All Rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+/**
+ * @file preprocessing.h 
+ * @brief This file contains functions specifically designed to preprocess Xilinx FPGA netlists.
+ */
+
+#pragma once
+
+#include "hal_core/defines.h"
+#include "hal_core/utilities/result.h"
+
+namespace hal
+{
+    class Netlist;
+
+    namespace xilinx_toolbox
+    {
+        /**
+         * @brief Split LUTs with two outputs into two separate LUT gates.
+         * 
+         * Replaces `LUT6_2` with a `LUT6` and a `LUT5` gate if the respective outputs of the `LUT6_2` are actually used, i.e., connected to other gates.
+         * 
+         * @param[in] nl - The netlist to operate on. 
+         * @returns The number of split `LUT6_2` gates on success, an error otherwise.
+         */
+        Result<u32> split_luts(Netlist* nl);
+
+        /**
+         * @brief Split shift register primitives and replaces them with equivalent flip-flops chains.
+         * 
+         * Currently only implemented for gate type `SRL16E`.
+         * 
+         * @param[in] nl - The netlist to operate on. 
+         * @return The number of split shift registers on success, an error otherwise.
+         */
+        Result<u32> split_shift_registers(Netlist* nl);
+
+        /**
+         * @brief Parse an `.xdc` file and extract the position LOC and BEL data of each gate.
+         * 
+         * Translates the coordinates extracted from the `.xdc` file into integer values.
+         * 
+         * @param[in] nl - The netlist to operate on. 
+         * @param[in] xdc_file - The path to the `.xdc` file.
+         * @return Ok() on success, an error otherwise.
+         */
+        Result<std::monostate> parse_xdc_file(Netlist* nl, const std::filesystem::path& xdc_file);
+    }    // namespace xilinx_toolbox
+}    // namespace hal

plugins/xilinx_toolbox/include/xilinx_toolbox/types.h

@@ -9,6 +9,10 @@ namespace hal
 {
     namespace xilinx_toolbox
     {
+        /**
+         * @enum BELType
+         * @brief BEL types relevant for XDC file parsing.
+         */
         enum BELType
         {
             A6LUT,
@@ -40,6 +44,10 @@ namespace hal
             OUTBUF,
         };
 
+        /**
+         * @enum LOCType
+         * @brief LOC types relevant for XDC file parsing.
+         */
         enum LOCType
         {
             SLICE,
@@ -49,6 +57,12 @@ namespace hal
             PIN,
         };
 
+        /**
+         * @enum LOC
+         * @brief Information on a LOC.
+         * 
+         * This struct contains all relevant information on a LOC that is needed to parse and apply a XDC file to an existing netlist.
+         */
         struct LOC
         {
             LOCType loc_type;
@@ -57,6 +71,12 @@ namespace hal
             u64 loc_y;
         };
 
+        /**
+         * @enum CellData
+         * @brief Data of a cell on the FPGA fabric.
+         * 
+         * This struct contains all location information on a cell on the FPGA fabric, including its LOC and BEL data.
+         */
         struct CellData
         {
             std::optional<LOC> loc;