Feature/clock tree extractor

README.md

@@ -40,6 +40,7 @@ This repository contains a selection of curated plugins:
   - 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](https://eprint.iacr.org/2020/751.pdf) that recovers high-level registers in an unstructured netlist
+- **Clock Tree Extractor:** A plugin to recover clock trees from an unstructured gate-level netlist
 - **Graph Algorithms:** [igraph](https://igraph.org) 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

install_dependencies.sh

@@ -115,6 +115,6 @@ elif [[ "$platform" == 'docker' ]]; then
     libqt5svg5-dev libqt5svg5* ninja-build lcov gcovr python3-sphinx \
     doxygen python3-sphinx-rtd-theme python3-jedi python3-pip \
     pybind11-dev python3-pybind11 python3-dateutil rapidjson-dev \
-    libspdlog-dev libz3-dev libreadline-dev \
+    libspdlog-dev libz3-dev libreadline-dev libgraphviz-dev \
     graphviz libomp-dev libsuitesparse-dev # For documentation
 fi

plugins/clock_tree_extractor/CMakeLists.txt

@@ -0,0 +1,24 @@
+option(PL_CLOCK_TREE_EXTRACTOR "PL_CLOCK_TREE_EXTRACTOR" ON)
+
+if(PL_CLOCK_TREE_EXTRACTOR OR BUILD_ALL_PLUGINS)
+
+    if(IWYU)
+        set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE "include-what-you-use")
+        message(STATUS "include-what-you-use turned ON")
+    else()
+        message(STATUS "include-what-you-use turned OFF")
+    endif()
+
+    file(GLOB_RECURSE CLOCK_TREE_EXTRACTOR_INC ${CMAKE_CURRENT_SOURCE_DIR}/include/*.h)
+    file(GLOB_RECURSE CLOCK_TREE_EXTRACTOR_SRC ${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp)
+    file(GLOB_RECURSE CLOCK_TREE_EXTRACTOR_PYTHON_SRC ${CMAKE_CURRENT_SOURCE_DIR}/python/*.cpp)
+
+    hal_add_plugin(clock_tree_extractor
+                    SHARED
+                    HEADER ${CLOCK_TREE_EXTRACTOR_INC}
+                    SOURCES ${CLOCK_TREE_EXTRACTOR_SRC} ${CLOCK_TREE_EXTRACTOR_PYTHON_SRC}
+                    LINK_LIBRARIES graph_algorithm
+                    COMPILE_OPTIONS "-march=native"
+                )
+
+endif()

plugins/clock_tree_extractor/include/clock_tree_extractor/clock_tree.h

@@ -0,0 +1,138 @@
+// 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.
+// Copyright (c) 2025-2026 Sascha Tommasone. 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.
+
+#pragma once
+
+#include "graph_algorithm/netlist_graph.h"
+#include "hal_core/defines.h"
+#include "hal_core/utilities/result.h"
+
+#include <igraph/igraph.h>
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <variant>
+#include <vector>
+
+namespace hal
+{
+    class Netlist;
+}
+
+namespace hal
+{
+    class Gate;
+}
+
+namespace hal
+{
+    class Net;
+}
+
+namespace hal
+{
+    namespace cte
+    {
+        enum PtrType { UNKNOWN, GATE, NET };
+
+        struct VoidPtrHash
+        {
+            std::size_t operator()( const std::pair<const void *, const void *> &pair ) const noexcept
+            {
+                return std::hash<const void *>()( pair.first ) ^ ( std::hash<const void *>()( pair.second ) << 1 );
+            }
+        };
+
+        struct PairPtrEq
+        {
+            bool operator()( const std::pair<const void *, const void *> &p1,
+                             const std::pair<const void *, const void *> &p2 ) const noexcept
+            {
+                return p1.first == p2.first && p1.second == p2.second;
+            }
+        };
+
+        class ClockTree
+        {
+          public:
+            ClockTree( const Netlist *netlist,
+                       igraph_t &&graph,
+                       std::unordered_set<igraph_integer_t> &&roots,
+                       std::unordered_map<igraph_integer_t, const void *> &&m_vertices_to_ptrs,
+                       std::unordered_map<const void *, PtrType> &&m_ptrs_to_types );
+
+            ~ClockTree();
+
+            static Result<std::unique_ptr<ClockTree>> from_netlist( const Netlist *netlist );
+
+            Result<std::monostate> export_dot( const std::string &pathname ) const;
+
+            Result<std::vector<std::pair<const void *, PtrType>>> get_neighbors( const void *ptr,
+                                                                                 igraph_neimode_t direction ) const;
+
+            Result<std::unique_ptr<ClockTree>> get_subtree( const void *ptr, const bool parent ) const;
+
+            Result<igraph_integer_t> get_vertex_from_ptr( const void *ptr ) const;
+
+            Result<std::pair<const void *, PtrType>> get_ptr_from_vertex( const igraph_integer_t vertex ) const;
+
+            Result<std::vector<igraph_integer_t>> get_vertices_from_ptrs( const std::vector<const void *> &ptrs ) const;
+
+            Result<std::vector<std::pair<const void *, PtrType>>>
+            get_ptrs_from_vertices( const std::vector<igraph_integer_t> &vertices ) const;
+
+            const std::vector<const Gate *> get_gates() const;
+
+            const std::vector<const Net *> get_nets() const;
+
+            const std::unordered_map<const void *, PtrType> get_all() const;
+
+            const Netlist *get_netlist() const;
+
+            const igraph_t *get_igraph() const;
+
+          private:
+            ClockTree() = delete;
+
+            ClockTree( const Netlist *netlist );
+
+            const Netlist *m_netlist;
+
+            igraph_t m_igraph;
+
+            igraph_t *m_igraph_ptr;
+
+            std::unordered_set<igraph_integer_t> m_roots;
+
+            std::unordered_map<igraph_integer_t, const void *> m_vertices_to_ptrs;
+
+            std::unordered_map<const void *, igraph_integer_t> m_ptrs_to_vertices;
+
+            std::unordered_map<const void *, PtrType> m_ptrs_to_types;
+        };
+    }  // namespace cte
+}  // namespace hal

plugins/clock_tree_extractor/include/clock_tree_extractor/plugin_clock_tree_extractor.h

@@ -0,0 +1,58 @@
+// 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.
+// Copyright (c) 2025-2026 Sascha Tommasone. 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.
+
+#pragma once
+
+#include "hal_core/defines.h"
+#include "hal_core/plugin_system/plugin_interface_base.h"
+
+#include <set>
+#include <string>
+
+namespace hal
+{
+    class PLUGIN_API ClockTreeExtractorPlugin : public BasePluginInterface
+    {
+      public:
+        ClockTreeExtractorPlugin() = default;
+
+        ~ClockTreeExtractorPlugin() = default;
+
+        std::string get_name() const override;
+
+        std::string get_version() const override;
+
+        std::string get_description() const override;
+
+        std::set<std::string> get_dependencies() const override;
+
+        void initialize() override;
+
+        void on_load() override;
+
+        void on_unload() override;
+    };
+}  // namespace hal