module.h

Go to the documentation of this file.

// 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/data_container.h"
#include "hal_core/netlist/event_system/event_handler.h"
#include "hal_core/netlist/gate_library/enums/pin_direction.h"
#include "hal_core/netlist/gate_library/enums/pin_type.h"
#include "hal_core/netlist/gate_library/enums/pin_event.h"
#include "hal_core/netlist/gate_library/gate_library.h"
#include "hal_core/netlist/pins/module_pin.h"
#include "hal_core/netlist/pins/pin_group.h"
#include "hal_core/utilities/enums.h"
#include "hal_core/utilities/result.h"
 
#include <functional>
#include <list>
#include <map>
#include <memory>
#include <string>
#include <tuple>
#include <type_traits>
#include <unordered_map>
#include <unordered_set>
 
namespace hal
{
    class Netlist;
    class NetlistInternalManager;
    class Net;
    class Grouping;
    class Gate;
 
    class NETLIST_API Module : public DataContainer
    {
    public:
        bool operator==(const Module& other) const;
 
        bool operator!=(const Module& other) const;
 
        ssize_t get_hash() const;
 
        u32 get_id() const;
 
        std::string get_name() const;
 
        void set_name(const std::string& name);
 
        std::string get_type() const;
 
        void set_type(const std::string& type);
 
        Grouping* get_grouping() const;
 
        int get_submodule_depth() const;
 
        Module* get_parent_module() const;
 
        std::vector<Module*> get_parent_modules(const std::function<bool(Module*)>& filter = nullptr, bool recursive = true) const;
 
        bool set_parent_module(Module* new_parent);
 
        bool is_parent_module_of(const Module* module, bool recursive = false) const;
 
        std::vector<Module*> get_submodules(const std::function<bool(Module*)>& filter = nullptr, bool recursive = false) const;
 
        bool is_submodule_of(const Module* module, bool recursive = false) const;
 
        bool contains_module(const Module* other, bool recursive = false) const;
 
        bool is_top_module() const;
 
        Netlist* get_netlist() const;
 
        /* 
         * ################################################################
         *      net functions
         * ################################################################
         */
 
        void update_nets();
 
        bool contains_net(Net* net, bool recursive = false) const;
 
        const std::unordered_set<Net*>& get_nets() const;
 
        std::unordered_set<Net*> get_nets(const std::function<bool(Net*)>& filter, bool recursive = false) const;
 
        const std::unordered_set<Net*>& get_input_nets() const;
 
        const std::unordered_set<Net*>& get_output_nets() const;
 
        const std::unordered_set<Net*>& get_internal_nets() const;
 
        bool is_input_net(Net* net) const;
 
        bool is_output_net(Net* net) const;
 
        bool is_internal_net(Net* net) const;
 
        /* 
         * ################################################################
         *      pin functions
         * ################################################################
         */
 
        u32 get_unique_pin_id();
 
        u32 get_unique_pin_group_id();
 
        Result<ModulePin*> create_pin(const u32 id, const std::string& name, Net* net, PinType type = PinType::none, bool create_group = true, bool force_name = false);
 
        Result<ModulePin*> create_pin(const std::string& name, Net* net, PinType type = PinType::none, bool create_group = true, bool force_name = false);
 
        std::vector<ModulePin*> get_pins(const std::function<bool(ModulePin*)>& filter = nullptr) const;
 
        std::vector<std::string> get_pin_names(const std::function<bool(ModulePin*)>& filter = nullptr) const;
 
        std::vector<ModulePin*> get_input_pins() const;
 
        std::vector<std::string> get_input_pin_names() const;
 
        std::vector<ModulePin*> get_output_pins() const;
 
        std::vector<std::string> get_output_pin_names() const;
 
        std::vector<PinGroup<ModulePin>*> get_pin_groups(const std::function<bool(PinGroup<ModulePin>*)>& filter = nullptr) const;
 
        ModulePin* get_pin_by_id(const u32 id) const;
 
        ModulePin* get_pin_by_name(const std::string& name) const;
 
        ModulePin* get_pin_by_net(Net* net) const;
 
        PinGroup<ModulePin>* get_pin_group_by_id(const u32 id) const;
 
        PinGroup<ModulePin>* get_pin_group_by_name(const std::string& name) const;
 
        bool set_pin_name(ModulePin* pin, const std::string& new_name, bool force_name = false);
 
        bool set_pin_type(ModulePin* pin, PinType new_type);
 
        Result<PinGroup<ModulePin>*> create_pin_group(const u32 id,
                                                      const std::string& name,
                                                      const std::vector<ModulePin*> pins = {},
                                                      PinDirection direction             = PinDirection::none,
                                                      PinType type                       = PinType::none,
                                                      bool ascending                     = true,
                                                      u32 start_index                    = 0,
                                                      bool delete_empty_groups           = true,
                                                      bool force_name                    = false);
 
        Result<PinGroup<ModulePin>*> create_pin_group(const std::string& name,
                                                      const std::vector<ModulePin*> pins = {},
                                                      PinDirection direction             = PinDirection::none,
                                                      PinType type                       = PinType::none,
                                                      bool ascending                     = true,
                                                      u32 start_index                    = 0,
                                                      bool delete_empty_groups           = true,
                                                      bool force_name                    = false);
 
        bool delete_pin_group(PinGroup<ModulePin>* pin_group);
 
        bool move_pin_group(PinGroup<ModulePin>* pin_group, u32 new_index);
 
        bool set_pin_group_name(PinGroup<ModulePin>* pin_group, const std::string& new_name, bool force_name = false);
 
        bool set_pin_group_type(PinGroup<ModulePin>* pin_group, PinType new_type);
 
        bool set_pin_group_direction(PinGroup<ModulePin>* pin_group, PinDirection new_direction);
 
        bool assign_pin_to_group(PinGroup<ModulePin>* pin_group, ModulePin* pin, bool delete_empty_groups = true);
 
        bool move_pin_within_group(PinGroup<ModulePin>* pin_group, ModulePin* pin, u32 new_index);
 
        bool remove_pin_from_group(PinGroup<ModulePin>* pin_group, ModulePin* pin, bool delete_empty_groups = true);
 
        /*
         * ################################################################
         *      gate functions
         * ################################################################
         */
 
        bool assign_gate(Gate* gate);
 
        bool assign_gates(const std::vector<Gate*>& gates);
 
        bool remove_gate(Gate* gate);
 
        bool remove_gates(const std::vector<Gate*>& gates);
 
        bool contains_gate(Gate* gate, bool recursive = false) const;
 
        Gate* get_gate_by_id(const u32 id, bool recursive = false) const;
 
        const std::vector<Gate*>& get_gates() const;
 
        std::vector<Gate*> get_gates(const std::function<bool(Gate*)>& filter, bool recursive = false) const;
 
        EventHandler* get_event_handler() const;
 
    private:
        friend class NetlistInternalManager;
        Module(NetlistInternalManager* internal_manager, EventHandler* event_handler, u32 id, Module* parent, const std::string& name);
 
        Module(const Module&)            = delete;    //disable copy-constructor
        Module& operator=(const Module&) = delete;    //disable copy-assignment
 
        struct NetConnectivity
        {
            bool has_internal_source;
            bool has_internal_destination;
            bool has_external_source;
            bool has_external_destination;
        };
 
        std::string m_name;
        std::string m_type;
 
        NetlistInternalManager* m_internal_manager;
        u32 m_id;
 
        /* grouping */
        Grouping* m_grouping = nullptr;
 
        Module* m_parent;
        std::unordered_map<u32, Module*> m_submodules_map;
        std::vector<Module*> m_submodules;
 
        // pins
        u32 m_next_pin_id;
        std::set<u32> m_used_pin_ids;
        std::set<u32> m_free_pin_ids;
        u32 m_next_pin_group_id;
        std::set<u32> m_used_pin_group_ids;
        std::set<u32> m_free_pin_group_ids;
 
        u32 m_next_input_index  = 0;
        u32 m_next_inout_index  = 0;
        u32 m_next_output_index = 0;
 
        std::vector<std::unique_ptr<ModulePin>> m_pins;
        std::unordered_map<u32, ModulePin*> m_pins_map;
        std::unordered_map<std::string, ModulePin*> m_pin_names_map;
        std::vector<std::unique_ptr<PinGroup<ModulePin>>> m_pin_groups;
        std::unordered_map<u32, PinGroup<ModulePin>*> m_pin_groups_map;
        std::unordered_map<std::string, PinGroup<ModulePin>*> m_pin_group_names_map;
        std::list<PinGroup<ModulePin>*> m_pin_groups_ordered;
 
        /* stores gates sorted by id */
        std::unordered_map<u32, Gate*> m_gates_map;
        std::vector<Gate*> m_gates;
 
        std::unordered_set<Net*> m_nets;
        std::unordered_set<Net*> m_input_nets;
        std::unordered_set<Net*> m_output_nets;
        std::unordered_set<Net*> m_internal_nets;
 
        EventHandler* m_event_handler;
 
        NetConnectivity check_net_endpoints(const Net* net) const;
        Result<std::monostate> check_net(Net* net, bool recursive = false);
        bool assign_pin_net(const u32 pin_id, Net* net, PinDirection direction);
        bool remove_pin_net(Net* net);
        Result<ModulePin*> create_pin_internal(const u32 id, const std::string& name, Net* net, PinDirection direction, PinType type, bool force_name);
        bool delete_pin_internal(ModulePin* pin);
        Result<PinGroup<ModulePin>*> create_pin_group_internal(const u32 id, const std::string& name, PinDirection direction, PinType type, bool ascending, u32 start_index, bool force_name);
        bool delete_pin_group_internal(PinGroup<ModulePin>* pin_group);
    };
}    // namespace hal