Feature/word level structures

.clang-format

@@ -32,6 +32,7 @@ BraceWrapping:
   BeforeCatch:     true
   BeforeElse:      true
   IndentBraces:    false
+InsertBraces: true
 BreakBeforeBinaryOperators: NonAssignment
 BreakBeforeBraces: Custom
 # BreakBeforeInheritanceComma: false
@@ -90,7 +91,7 @@ SpacesInContainerLiterals: false
 SpacesInCStyleCastParentheses: false
 SpacesInParentheses: false
 SpacesInSquareBrackets: false
-Standard:        Cpp11
+Standard:        Cpp17
 TabWidth:        4
 UseTab:          Never
 ...

CHANGELOG.md

@@ -36,6 +36,7 @@ All notable changes to this project will be documented in this file.
   * added extended gate library picker when importing a netlist
   * added keyboard shortcut for delete-item action from toolbar
   * added parameter `force_name` to enforce pin (group) renaming to `Module::set_pin_name`, `Module::set_pin_group_name`, `Module::create_pin`, and `Module::create_pin_group`
+  * added Python bindings for `GateLibrary::create_gate_type` (cannot handle `GateTypeComponent` parameter as pybind cannot accept `std::unique_ptr` as parameter)
   * changed supported input file formats for import from hard coded list to list provided by loadable parser plugins
   * changed behavior of import netlist dialog, suggest only non-existing directory names and loop until an acceptable name was entered
   * changed appearance and behavior of import project dialog, make sure existing hal projects don't get overwritten

CMakeLists.txt

@@ -67,13 +67,6 @@ option(BUILD_TESTS "Enable test builds" OFF)
 option(BUILD_COVERAGE "Enable code coverage build" OFF)
 option(BUILD_DOCUMENTATION "Create and install the HTML based API documentation")
 option(ENABLE_INSTALL_LDCONFIG "When installing via make/ninja install, also install and run the LDCONFIG post_install scripts" ON)
-option(UPLOAD_PPA "Upload package to ppa" OFF)
-option(PACKAGE_DEB "Package DEB Package" OFF)
-option(ENABLE_PPA "Prepare PPA" ON)
-option(PACKAGE_TGZ "Package TGZ archive" OFF)
-option(PACKAGE_ZIP "Package ZIP archive" OFF)
-option(PACKAGE_RPM "Package RPM package" OFF)
-option(PACKAGE_MACOS "Package for macOS" OFF)
 
 # Include Helper Modules
 include(hal_cmake_tools) # Version helper
@@ -112,13 +105,9 @@ project(hal
 set(PROJECT_VENDOR "hal")
 set(PROJECT_WEBSITE "https://github.com/emsec/hal")
 set(PROJECT_MAINTAINER "Sebastian Wallat <[email protected]>")
-set(PROJECT_DESCRIPTION_SUMMARY "Hardware Reverse engineering framework")
+set(PROJECT_DESCRIPTION_SUMMARY "Hardware reverse engineering framework")
 set(PROJECT_DESCRIPTION "hal - Hardware Analyzer")
 
-# set(CHANGELOG_MESSAGE ${CHANGELOG_LAST_MESSAGE})
-set(PROJECT_PPA "ppa:sebastian-wallat/hal")
-set(PROJECT_PPA_USER "sebastian-wallat")
-
 # Use C11 and C++17 as minimum standard
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED on)
@@ -192,10 +181,11 @@ if(UNIX)
     SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pthread")
     SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -pthread")
 
-    # set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-omit-frame-pointer -fsanitize=address")
+    # set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-omit-frame-pointer -fsanitize=thread -fsanitize=undefined")
+
+    # SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=thread -fsanitize=undefined")
+    # SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fsanitize=thread -fsanitize=undefined")
 
-    # SET(CMAKE_CXX_FLAGS  "${CMAKE_CXX_FLAGS} -fsanitize=address")
-    # SET(CMAKE_EXE_LINKER_FLAGS  "${CMAKE_EXE_LINKER_FLAGS} -fsanitize=address")
     if(USE_LIBCXX)
         enable_cxx_compile_option_if_supported("-stdlib=libc++" "" "PUBLIC")
         enable_c_compile_option_if_supported("-stdlib=libc++" "" "PUBLIC")
@@ -329,7 +319,6 @@ install(DIRECTORY ${CMAKE_SOURCE_DIR}/deps/pybind11 DESTINATION ${HAL_CMAKECONFI
 install(DIRECTORY ${CMAKE_SOURCE_DIR}/deps/spdlog-${spdlog_VERSION} DESTINATION ${HAL_CMAKECONFIG_INSTALL_DIR})
 install(DIRECTORY ${CMAKE_SOURCE_DIR}/deps/subprocess DESTINATION ${HAL_CMAKECONFIG_INSTALL_DIR})
 
-
 if(NOT(CMAKE_VERSION VERSION_LESS 3.0))
     install(EXPORT hal
         FILE halTargets.cmake

documentation/sphinx_doc/netlist_traversal_decorator.rst

@@ -0,0 +1,7 @@
+Netlist Traversal Decorator
+==================================
+
+.. autoclass:: hal_py.NetlistTraversalDecorator
+   :members:
+
+   .. automethod:: __init__

include/hal_core/doxy_groups.h

@@ -33,10 +33,15 @@
  */
 
 /**
- * @defgroup pins Pins
+ * @defgroup decorators Decorators
  * @ingroup core
  */
 
+/**
+ * @defgroup pins Pins
+ * @ingroup netlist
+ */
+
 /**
  * @defgroup netlist_parser Netlist Parser
  * @ingroup netlist

include/hal_core/netlist/boolean_function/solver.h

@@ -103,6 +103,15 @@ namespace hal
 			 */
             Result<SolverResult> query_local(const QueryConfig& config) const;
 
+			/**
+			 * Queries a local SMT solver with the specified query configuration and the provided smt2 representation of the query.
+			 *
+			 * @param[in] config - The SMT solver query configuration.
+			 * @param[in] smt2   - The SMT solver query as smt2 string.
+			 * @returns OK() and the result on success, Err() otherwise.
+			 */
+            static Result<SolverResult> query_local(const QueryConfig& config, std::string& smt2);
+
             /**
 			 * Queries a remote SMT solver with the specified query configuration.
 			 *

include/hal_core/netlist/boolean_function/types.h

@@ -70,7 +70,7 @@ namespace hal
             /// Controls whether the SMT query is performed on a local or a remote machine.
             bool local = true;
             /// Controls whether the SMT solver should generate a model in case formula is satisfiable.
-            bool generate_model = true;
+            bool generate_model = false;
             /// The timeout after which the SMT solver is killed in seconds.
             u64 timeout_in_seconds = 10;
 

include/hal_core/netlist/decorators/boolean_function_decorator.h

@@ -33,6 +33,11 @@
 
 namespace hal
 {
+    /**
+     * A Boolean function decorator that provides functionality to operate on the associated Boolean function.
+     *
+     * @ingroup decorators
+     */
     class NETLIST_API BooleanFunctionDecorator
     {
     public:

include/hal_core/netlist/decorators/boolean_function_net_decorator.h

@@ -31,6 +31,11 @@
 
 namespace hal
 {
+    /**
+     * A net decorator that provides functionality to translate between nets and Boolean function variables.
+     *
+     * @ingroup decorators
+     */
     class NETLIST_API BooleanFunctionNetDecorator
     {
     public:

include/hal_core/netlist/decorators/netlist_modification_decorator.h

@@ -32,6 +32,11 @@
 
 namespace hal
 {
+    /**
+     * A netlist decorator that provides functionality to modify the associated netlist.
+     *
+     * @ingroup decorators
+     */
     class NETLIST_API NetlistModificationDecorator
     {
     public:
@@ -86,6 +91,22 @@ namespace hal
          */
         Result<Net*> connect_nets(Net* master_net, Net* slave_net);
 
+        /**
+         * Searches for a GND net in the netlist.
+         * If there are no existing ones then the function will try to search for a GND gate type in the gate library and create a GND net with corresponding gate source. 
+         * 
+         * @returns A vector containing the either newly created or all already existing GND nets.
+         */
+        Result<std::vector<Net*>> create_gnd_net();
+
+        /**
+         * Searches for a VCC net in the netlist.
+         * If there are no existing ones then the function will try to search for a VCC gate type in the gate library and create a VCC net with corresponding gate source. 
+         * 
+         * @returns A vector containing the either newly created or all already existing VCC nets.
+         */
+        Result<std::vector<Net*>> create_vcc_net();
+
     private:
         Netlist& m_netlist;
     };

include/hal_core/netlist/decorators/netlist_traversal_decorator.h

@@ -0,0 +1,144 @@
+// 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.
+
+#pragma once
+
+#include "hal_core/defines.h"
+#include "hal_core/netlist/netlist.h"
+#include "hal_core/utilities/result.h"
+
+namespace hal
+{
+    /**
+     * A netlist decorator that provides functionality to traverse the associated netlist without making any modifications.
+     *
+     * @ingroup decorators
+     */
+    class NETLIST_API NetlistTraversalDecorator
+    {
+    public:
+        /**
+         * Construct new NetlistTraversalDecorator object.
+         * 
+         * @param[in] netlist - The netlist to operate on.
+         */
+        NetlistTraversalDecorator(const Netlist& netlist);
+
+        /**
+         * Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
+         * Stop traversal if (1) the `target_gate_filter` evaluates to `true`, (2) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
+         * Both the `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted.
+         * 
+         * @param[in] net - Start net.
+         * @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
+         * @param[in] target_gate_filter - Filter condition that must be met for the target gates.
+         * @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
+         * @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_next_gates(const Net* net,
+                                               bool successors,
+                                               const std::function<bool(const Gate*)>& target_gate_filter,
+                                               const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
+                                               const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
+
+        /**
+         * Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
+         * Stop traversal if (1) the `target_gate_filter` evaluates to `true`, (2) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
+         * Both the `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted.
+         * 
+         * @param[in] gate - Start gate.
+         * @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
+         * @param[in] target_gate_filter - Filter condition that must be met for the target gates.
+         * @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
+         * @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_next_gates(const Gate* gate,
+                                               bool successors,
+                                               const std::function<bool(const Gate*)>& target_gate_filter,
+                                               const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
+                                               const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
+
+        /**
+         * Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
+         * Stop traversal if (1) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (2) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
+         * The target_gate_filter may be ommitted in which case all traversed gates will be returned.
+         * Both `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted as well.
+         * 
+         * @param[in] net - Start net.
+         * @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
+         * @param[in] target_gate_filter - Filter condition that must be met for the target gates.
+         * @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
+         * @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_subgraph_gates(const Net* net,
+                                                   bool successors,
+                                                   const std::function<bool(const Gate*)>& target_gate_filter                                 = nullptr,
+                                                   const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
+                                                   const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
+
+        /**
+         * Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
+         * Stop traversal if (1) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (2) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
+         * The target_gate_filter may be ommitted in which case all traversed gates will be returned.
+         * Both `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted as well.
+         * 
+         * @param[in] gate - Start gate.
+         * @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
+         * @param[in] target_gate_filter - Filter condition that must be met for the target gates.
+         * @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
+         * @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_subgraph_gates(const Gate* gate,
+                                                   bool successors,
+                                                   const std::function<bool(const Gate*)>& target_gate_filter                                 = nullptr,
+                                                   const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
+                                                   const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
+
+        /**
+         * TODO document
+         */
+        Result<std::set<Net*>> get_subgraph_input_nets(const Net* net,
+                                                       bool successors,
+                                                       const std::function<bool(const Net*)>& target_net_filter,
+                                                       const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
+                                                       const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
+
+        /**
+         * TODO document
+         */
+        Result<std::set<Net*>> get_subgraph_input_nets(const Gate* gate,
+                                                       bool successors,
+                                                       const std::function<bool(const Net*)>& target_net_filter,
+                                                       const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
+                                                       const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
+
+    private:
+        const Netlist& m_netlist;
+    };
+}    // namespace hal