degate  0.1.2
GateTemplate.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 __GATETEMPLATE_H__
00024 #define __GATETEMPLATE_H__
00025 
00026 #include <degate.h>
00027 
00028 #include <Layer.h>
00029 #include <Image.h>
00030 #include <GateTemplatePort.h>
00031 
00032 #include <set>
00033 #include <memory>
00034 #include <map>
00035 
00036 namespace degate {
00037 
00038   /**
00039    * A gate template is a container for common properties, that physically placed gates of that type share.
00040    */
00041 
00042   class GateTemplate : public LogicModelObjectBase, public ColoredObject, public DeepCopyable {
00043 
00044     friend class Gate;
00045 
00046   public:
00047 
00048     /**
00049      * Implementation types for a template.
00050      */
00051     enum IMPLEMENTATION_TYPE {
00052       UNDEFINED = 0,
00053       TEXT = 1,
00054       VHDL = 2,
00055       VHDL_TESTBENCH = 3,
00056       VERILOG = 4,
00057       VERILOG_TESTBENCH = 5
00058     };
00059 
00060     typedef std::map<IMPLEMENTATION_TYPE, std::string /* code */> implementation_collection;
00061     typedef implementation_collection::iterator implementation_iter;
00062 
00063     typedef std::map<Layer::LAYER_TYPE, GateTemplateImage_shptr> image_collection;
00064     typedef image_collection::iterator image_iterator;
00065 
00066   private:
00067 
00068     BoundingBox bounding_box;
00069     unsigned int reference_counter;
00070 
00071     std::set<GateTemplatePort_shptr, LMOCompare> ports;
00072 
00073     implementation_collection implementations;
00074     image_collection images;
00075 
00076     std::string logic_class; // e.g. nand, xor, flipflop, buffer, oai
00077 
00078   protected:
00079 
00080     /**
00081      * Increment the reference counter.
00082      */
00083 
00084     virtual void increment_reference_counter();
00085 
00086     /**
00087      * Decrement the reference counter.
00088      */
00089 
00090     virtual void decrement_reference_counter();
00091 
00092 
00093   public:
00094 
00095     typedef std::set< GateTemplatePort_shptr >::iterator port_iterator;
00096 
00097     /**
00098      * The constructor to set up a new gate template.
00099      * @deprecated A gate template should not rely on positions. Instead it should
00100      *   have a the region as a copy.
00101      */
00102 
00103     GateTemplate(unsigned int width, unsigned int height);
00104 
00105 
00106     /**
00107      * The constructor to set up a new gate template.
00108      * @deprecated A gate template should not rely on positions. Instead it should
00109      *   have a the region as a copy.
00110      */
00111 
00112     GateTemplate(int _min_x, int _max_x, int _min_y, int _max_y);
00113 
00114     /**
00115      * Default constructor.
00116      */
00117 
00118     GateTemplate();
00119 
00120     /**
00121      * The destructor.
00122      */
00123 
00124     virtual ~GateTemplate();
00125 
00126     //@{
00127     DeepCopyable_shptr cloneShallow() const;
00128     void cloneDeepInto(DeepCopyable_shptr destination, oldnew_t *oldnew) const;
00129     //@}
00130 
00131     /**
00132      * Get the width of a gate template.
00133      */
00134 
00135     virtual unsigned int get_width() const;
00136 
00137     /**
00138      * Get the height of a gate template.
00139      */
00140 
00141     virtual unsigned int get_height() const;
00142 
00143 
00144     /**
00145      * Set the width of a gate template.
00146      * It does not adjust dimensions of gates that reference this template.
00147      */
00148 
00149     virtual void set_width(unsigned int width);
00150 
00151     /**
00152      * Set the height of a gate template.
00153      * It does not adjust dimensions of gates that reference this template.
00154      */
00155 
00156     virtual void set_height(unsigned int);
00157 
00158     /**
00159      * Get the bounding box of the template.
00160      * @deprecated
00161      */
00162 
00163     virtual BoundingBox const & get_bounding_box() const;
00164 
00165     /**
00166      * Set a reference image for the template.
00167      * You can store reference images for different layers, that is for
00168      * the transistor layer, for the logic layer and for a metal layer.
00169      * The images must have equal image dimensions. It is not checked here.
00170      *
00171      * @todo: Here we might need a hook for storing different image types,
00172      *   e.g. a template image that is an average image or sth. like that.
00173      * @exception InvalidPointerException Throws this excpetion, if \p img is NULL.
00174      */
00175 
00176     virtual void set_image(Layer::LAYER_TYPE layer_type, GateTemplateImage_shptr img);
00177 
00178     /**
00179      * Get a reference image for the template.
00180      * @see set_image()
00181      * @exception CollectionLookupException Throws this exception, if there is no image.
00182      */
00183 
00184     virtual GateTemplateImage_shptr get_image(Layer::LAYER_TYPE layer_type);
00185 
00186 
00187     /**
00188      * Check if there is a reference image for a layer type.
00189      */
00190 
00191     virtual bool has_image(Layer::LAYER_TYPE layer_type) const;
00192 
00193     /**
00194      * Add a template port to a gate template.
00195      * This is an isolated function. The port is just added to the gate template.
00196      * Nothing else. Adding a port to a template requires some updates in the logic
00197      * model. Therefore you should prefer the corresponding method from the LogicModel
00198      * class.
00199      * @exception InvalidObjectIDException This exception is thrown if the template port
00200      *   has no valid object ID.
00201      * @todo In order to make the API hard to misuse, this method might be made private.
00202      * @see LogicModel::add_template_port
00203      */
00204 
00205     virtual void add_template_port(GateTemplatePort_shptr template_port);
00206 
00207     /**
00208      * Remove a port from a gate template.
00209      * This is an isolated function. The port is just removed from the gate template.
00210      * Nothing else. Removing a port from a template requires some updates in the logic
00211      * model. Therefore you should prefer the corresponding method from the LogicModel
00212      * class.
00213      * @todo In order to make the API hard to misuse, this method might be made private.
00214      * @see LogicModel::remove_template_port
00215      */
00216 
00217     virtual bool remove_template_port(GateTemplatePort_shptr template_port);
00218 
00219     /**
00220      * Remove a port from a gate template.
00221      * @exception InvalidObjectIDException This exception is thrown if the template port
00222      *   has no valid object ID.
00223      * @see remove_template_port(GateTemplatePort_shptr template_port)
00224      */
00225 
00226     virtual bool remove_template_port(object_id_t object_id);
00227 
00228     /**
00229      * Get a template port.
00230      * @exception InvalidObjectIDException This exception is thrown if the
00231      *   object ID is invalid.
00232      * @exception CollectionLookupException This exception is thrown if a
00233      *   template port with object ID \p object_id was not found.
00234      */
00235 
00236     virtual GateTemplatePort_shptr get_template_port(object_id_t object_id);
00237 
00238 
00239     /**
00240      * Check if a template has a specific template port.
00241      * @exception InvalidObjectIDException This exception is thrown if the
00242      *   object ID is invalid.
00243      */
00244 
00245     virtual bool has_template_port(object_id_t object_id) const;
00246 
00247     /**
00248      * Get an iterator.
00249      */
00250 
00251     virtual port_iterator ports_begin();
00252 
00253 
00254     /**
00255      * Get end marker for the iteration over ports.
00256      */
00257 
00258     virtual port_iterator ports_end();
00259 
00260 
00261     /**
00262      * Get an iterator to iterate over images.
00263      */
00264 
00265     virtual image_iterator images_begin();
00266 
00267     /**
00268      * Get end marker for the iteration over images.
00269      */
00270 
00271     virtual image_iterator images_end();
00272 
00273     /**
00274      * Get the reference counter.
00275      * @return Returns how many gates reference this gate template.
00276      */
00277 
00278     virtual unsigned int get_reference_counter() const;
00279 
00280 
00281     /**
00282      * Get an iterator to iterate over implementations.
00283      */
00284 
00285     virtual implementation_iter implementations_begin();
00286 
00287     /**
00288      * Get an end marker for the iteration.
00289      */
00290 
00291     virtual implementation_iter implementations_end();
00292 
00293 
00294     /**
00295      * Set VHDL/Verilog implementation for the gate template.
00296      * @param impl_type Set VHDL or Verilog.
00297      * @param code The implementation.
00298      */
00299 
00300     virtual void set_implementation(IMPLEMENTATION_TYPE impl_type, std::string const& code);
00301 
00302     /**
00303      * Get code for an implementation type.
00304      * @exception CollectionLookupException Throws an exception, if there is no code for the requested type.
00305      */
00306 
00307     std::string get_implementation(IMPLEMENTATION_TYPE impl_type) const;
00308 
00309     /**
00310      * Print gate template's meta information to an output stream.
00311      */
00312 
00313     virtual void print(std::ostream & os);
00314 
00315 
00316     /**
00317      * Get number of defined ports.
00318      */
00319 
00320     virtual unsigned int get_number_of_ports() const;
00321 
00322 
00323     /**
00324      * Set logic class for a standard cell.
00325      *
00326      * There are two reasons for having this kind of tagging. First we
00327      * want to render dedicated electronic symbols for standard gates, e.g.
00328      * nands, xors and flipflops, independed of the standard cells name.
00329      * Second we want to search for common building blocks, e.g.
00330      * linear feedback shift registers, that we basically describe as
00331      * a set of connected flipflops with some xor gates between them,
00332      * independend of the gate's naming.
00333      */
00334 
00335     virtual void set_logic_class(std::string const& logic_class);
00336 
00337     /**
00338      * Get logic class for a standard cell.
00339      */
00340 
00341     virtual std::string get_logic_class() const;
00342 
00343 
00344     /**
00345      * Convert an implementation-type constant to a printable string.
00346      */
00347     static std::string get_impl_type_as_string(IMPLEMENTATION_TYPE impl_type);
00348 
00349     /**
00350      * Convert an implementation type string to a correspondig constant.
00351      * @exception DegateRuntimeException Throws this exception, if the string cannot be parsed.
00352      */
00353     static IMPLEMENTATION_TYPE get_impl_type_from_string(std::string const& impl_type_str);
00354 
00355   };
00356 
00357 
00358 
00359 }
00360 
00361 #endif