degate  0.1.2
Module.h
Go to the documentation of this file.
00001 /* -*-c++-*-
00002 
00003  This file is part of the IC reverse engineering tool degate.
00004 
00005  Copyright 2008, 2009, 2010 by Martin Schobert
00006  Copyright 2012 Robert Nitsch
00007 
00008  Degate is free software: you can redistribute it and/or modify
00009  it under the terms of the GNU General Public License as published by
00010  the Free Software Foundation, either version 3 of the License, or
00011  any later version.
00012 
00013  Degate is distributed in the hope that it will be useful,
00014  but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00016  GNU General Public License for more details.
00017 
00018  You should have received a copy of the GNU General Public License
00019  along with degate. If not, see <http://www.gnu.org/licenses/>.
00020 
00021 */
00022 
00023 #ifndef __MODULE_H__
00024 #define __MODULE_H__
00025 
00026 #include <map>
00027 #include <memory>
00028 
00029 #include <LogicModelObjectBase.h>
00030 #include <LogicModel.h>
00031 #include <boost/optional.hpp>
00032 
00033 namespace degate {
00034 
00035   
00036   /**
00037    * Implements a container to build up higher level entities.
00038    */
00039 
00040   class Module : public LogicModelObjectBase, public DeepCopyable {
00041 
00042     friend void determine_module_ports_for_root(LogicModel_shptr lmodel);
00043     friend class LogicModelImporter;
00044 
00045   public:
00046 
00047     typedef std::set<Module_shptr, LMOCompare> module_collection;
00048     typedef std::set<Gate_shptr, LMOCompare> gate_collection;
00049 
00050     /**
00051      * This map defines module ports.
00052      * A port is identified by a name. A module port is 'connected' to
00053      * a list of gate ports.
00054      */
00055     typedef std::map<std::string, /* port name */
00056                      GatePort_shptr> port_collection;
00057 
00058   private:
00059 
00060     module_collection modules;
00061     gate_collection gates;
00062     port_collection ports;
00063     
00064     std::string entity_name; // name of a type
00065     bool is_root;
00066     
00067   private:
00068 
00069     /**
00070      * @throw InvalidPointerException This exception is thrown if the parameter is a NULL pointer.
00071      */
00072     void move_gates_recursive(Module * dst_mod);
00073 
00074     void automove_gates();
00075 
00076     /**
00077      * Check if there is a gate is the current module or any child module
00078      * that has a gate port with the object ID \p oid .
00079      */
00080     bool exists_gate_port_recursive(object_id_t oid) const;
00081     GatePort_shptr lookup_gate_port_recursive(object_id_t oid) const;
00082 
00083     
00084     void add_module_port(std::string const& module_port_name, GatePort_shptr adjacent_gate_port);
00085 
00086     bool net_feeded_internally(Net_shptr net) const;
00087     bool net_completely_internal(Net_shptr net) const;
00088 
00089   public:
00090 
00091     /**
00092      * Construct a new module.
00093      */
00094 
00095     Module(std::string const& module_name = "", 
00096            std::string const& _entity_name = "", 
00097            bool is_root = false);
00098 
00099     /**
00100      * Destroy the module.
00101      */
00102 
00103     virtual ~Module();
00104 
00105     //@{
00106     DeepCopyable_shptr cloneShallow() const;
00107     void cloneDeepInto(DeepCopyable_shptr destination, oldnew_t *oldnew) const;
00108     //@}
00109     
00110     /**
00111      * Check if module is the main module.
00112      */
00113     
00114     bool is_main_module() const;
00115 
00116     /**
00117      * Set a module as main module.
00118      * This will set the new state only in the current module and will not disable
00119      * the root-node-state of any other module.
00120      */
00121     void set_main_module();
00122 
00123     /**
00124      * Set an identifier for the module type.
00125      */
00126 
00127     void set_entity_name(std::string const& name);
00128 
00129 
00130     /**
00131      * Get name of the entity type.
00132      */
00133 
00134     std::string get_entity_name() const;
00135 
00136 
00137     /**
00138      * Add a gate to a module.
00139      * @param gate The gate to add.
00140      * @param detect_ports Switch for enabling or disabling automatic module port detection.
00141      * @exception InvalidPointerException This exception is thrown, if \p gate is a NULL pointer.
00142      */
00143 
00144     void add_gate(Gate_shptr gate, bool detect_ports = true);
00145 
00146 
00147     /**
00148      * Remove a gate from a module.
00149      * This method even works if the gate is not a direct child. Afterwards
00150      * the gate is completely removed from the module hierarchy (if you run this
00151      * method for the "right" root node). In most cases
00152      * you want to add the gate to the module hierarchy again. Therefore you have
00153      * to call method add_gate() on your own.
00154      * @return Returns true if a module was removed, else false.
00155      * @see add_gate()
00156      * @exception InvalidPointerException This exception is thrown, if \p gate is a NULL pointer.
00157      */
00158 
00159     bool remove_gate(Gate_shptr gate);
00160 
00161 
00162     /**
00163      * Add a sub-module to a module.
00164      * @exception InvalidPointerException This exception is thrown, if \p gate is a NULL pointer.
00165      */
00166 
00167     void add_module(Module_shptr module);
00168 
00169     /**
00170      * Remove a submodule.
00171      * This method even works if the submodule is not a direct child. If you remove
00172      * a child module that contains gates, the gates are moved one layer above.
00173      * @return Returns true if a module was removed, else false.
00174      * @exception InvalidPointerException This exception is thrown, if \p gate is a NULL pointer.
00175      */
00176 
00177     bool remove_module(Module_shptr module);
00178 
00179 
00180     module_collection::iterator modules_begin();
00181     module_collection::iterator modules_end();
00182     gate_collection::iterator gates_begin();
00183     gate_collection::iterator gates_end();
00184     port_collection::iterator ports_begin();
00185     port_collection::iterator ports_end();
00186 
00187     module_collection::const_iterator modules_begin() const;
00188     module_collection::const_iterator modules_end() const;
00189     gate_collection::const_iterator gates_begin() const;
00190     gate_collection::const_iterator gates_end() const;
00191     port_collection::const_iterator ports_begin() const;
00192     port_collection::const_iterator ports_end() const;
00193 
00194 
00195     /**
00196      * Determine ports of a module.
00197      */
00198     void determine_module_ports();
00199     
00200     /**
00201      * Determine ports of children and sub-children (not including the "local"
00202      * module, on which this function is called).
00203      */
00204     void determine_module_ports_recursive();
00205 
00206     /**
00207      * Lookup a sub-module.
00208      * @param module_path Path to the module, e.g. :
00209      *   an absolute path "main_module/crypto/lfsr_a"
00210      *   an relative path "crypto/lfsr_a"
00211      * @return Returns the module. In case of lookup failure a NULL pointer is returned.
00212      */
00213 
00214     Module_shptr lookup_module(std::string const& module_path) const;
00215 
00216     /**
00217      * Set module port name
00218      */
00219     void set_module_port_name(std::string const& module_port_name, GatePort_shptr adjacent_gate_port);
00220 
00221     /**
00222      * Check if a module port name exists.
00223      */
00224     bool exists_module_port_name(std::string const& module_port_name) const;
00225 
00226 
00227     /**
00228      * Lookup the module port name.
00229      * @return Returns the module port name.
00230      */
00231 
00232     boost::optional<std::string> lookup_module_port_name(GatePort_shptr gate_port);
00233 
00234   private:
00235 
00236     /**
00237      * Internal implementation of lookup_module().
00238      * @param path_elements Reference to a list of path elements. List is modified.
00239      * @return Returns a valid pointer on success. Else a null pointer is returned.
00240      */
00241     Module_shptr lookup_module(std::list<std::string> & path_elements) const;
00242 
00243   };
00244 
00245 
00246   /**
00247    * Determine ports of a root module.
00248    * Note: It would b more nice to have this function as a member function of class Module. But
00249    *  this would intorduce a dependency of LogicModel. The lmodel is neccessary for looking up
00250    *  objects, because main module's ports are modelled by having a special emarker in the net.
00251    *  I have no idea how the main module's ports could be identified else. (Using all ports
00252    *  is obviously not an option.)
00253    */
00254   void determine_module_ports_for_root(LogicModel_shptr lmodel);
00255 
00256 
00257 }
00258 
00259 #endif