From 4a5656041e783216b4e0eecb0a969be0bcc90384 Mon Sep 17 00:00:00 2001 From: Damien Dupuis Date: Fri, 25 Mar 2011 13:08:53 +0000 Subject: [PATCH] Adding the OpenChams documentation (at last !) Minor changes/corrections is other documentations. --- vlsisapd/doc/Contact.dox | 2 +- vlsisapd/doc/agds/agds.dox | 2 +- vlsisapd/doc/cif/cif.dox | 2 +- vlsisapd/doc/doxyfile | 2 +- vlsisapd/doc/dtr/dtr.dox | 2 +- vlsisapd/doc/header.html | 1 + vlsisapd/doc/mainPage.dox | 7 +- vlsisapd/doc/openChams/Circuit.dox | 129 ++++++++++++++++++++++++ vlsisapd/doc/openChams/Device.dox | 48 +++++++++ vlsisapd/doc/openChams/Exception.dox | 9 ++ vlsisapd/doc/openChams/Instance.dox | 70 +++++++++++++ vlsisapd/doc/openChams/Layout.dox | 34 +++++++ vlsisapd/doc/openChams/Name.dox | 39 ++++++++ vlsisapd/doc/openChams/Net.dox | 103 +++++++++++++++++++ vlsisapd/doc/openChams/Netlist.dox | 80 +++++++++++++++ vlsisapd/doc/openChams/Operator.dox | 109 +++++++++++++++++++++ vlsisapd/doc/openChams/Parameters.dox | 55 +++++++++++ vlsisapd/doc/openChams/Port.dox | 43 ++++++++ vlsisapd/doc/openChams/Schematic.dox | 61 ++++++++++++ vlsisapd/doc/openChams/SimulModel.dox | 53 ++++++++++ vlsisapd/doc/openChams/Sizing.dox | 53 ++++++++++ vlsisapd/doc/openChams/Transistor.dox | 85 ++++++++++++++++ vlsisapd/doc/openChams/Wire.dox | 136 ++++++++++++++++++++++++++ vlsisapd/doc/openChams/openChams.dox | 80 +++++++++++++++ 24 files changed, 1197 insertions(+), 8 deletions(-) create mode 100644 vlsisapd/doc/openChams/Circuit.dox create mode 100644 vlsisapd/doc/openChams/Device.dox create mode 100644 vlsisapd/doc/openChams/Exception.dox create mode 100644 vlsisapd/doc/openChams/Instance.dox create mode 100644 vlsisapd/doc/openChams/Layout.dox create mode 100644 vlsisapd/doc/openChams/Name.dox create mode 100644 vlsisapd/doc/openChams/Net.dox create mode 100644 vlsisapd/doc/openChams/Netlist.dox create mode 100644 vlsisapd/doc/openChams/Operator.dox create mode 100644 vlsisapd/doc/openChams/Parameters.dox create mode 100644 vlsisapd/doc/openChams/Port.dox create mode 100644 vlsisapd/doc/openChams/Schematic.dox create mode 100644 vlsisapd/doc/openChams/SimulModel.dox create mode 100644 vlsisapd/doc/openChams/Sizing.dox create mode 100644 vlsisapd/doc/openChams/Transistor.dox create mode 100644 vlsisapd/doc/openChams/Wire.dox create mode 100644 vlsisapd/doc/openChams/openChams.dox diff --git a/vlsisapd/doc/Contact.dox b/vlsisapd/doc/Contact.dox index a5fd589d..ee57f222 100644 --- a/vlsisapd/doc/Contact.dox +++ b/vlsisapd/doc/Contact.dox @@ -1,5 +1,5 @@ /*! \page Contact Links & Contacts - VLSI SAPD prject is developped at the Pierre & Marie Curie University in Paris, France (http://www.upmc.fr).\n\n + VLSI SAPD project is developped at the Pierre & Marie Curie University in Paris, France (http://www.upmc.fr) at the LIP6 laboratory (http://www.lip6.fr).\n\n It is used by: - Coriolis 2 Project: http://www-soc.lip6.fr/recherche/cian/coriolis-2/ diff --git a/vlsisapd/doc/agds/agds.dox b/vlsisapd/doc/agds/agds.dox index bd362d02..8585fba8 100644 --- a/vlsisapd/doc/agds/agds.dox +++ b/vlsisapd/doc/agds/agds.dox @@ -52,6 +52,6 @@ Here is the Python code (\c driveAgds.py) used to generate the transistor.agds file. (Source is available in examples directory). \include driveAgds.py - \note In order to run the \c driveAgds.py script, user must ensure that $PYTHONPATH variable points to the directory containing pyAGDS.so module. + \note In order to run the \c driveAgds.py script, user must ensure that $PYTHONPATH variable points to the directory containing AGDS.so module. */ diff --git a/vlsisapd/doc/cif/cif.dox b/vlsisapd/doc/cif/cif.dox index 60a58197..24e94e59 100644 --- a/vlsisapd/doc/cif/cif.dox +++ b/vlsisapd/doc/cif/cif.dox @@ -40,5 +40,5 @@ Here is the Python code (\c driveCif.py) used to generate the transistor.cif file. (Source is available in examples directory). \include driveCif.py - \note In order to run the \c driveCif.py script, user must ensure that $PYTHONPATH variable points to the directory containing pyCIF.so module. + \note In order to run the \c driveCif.py script, user must ensure that $PYTHONPATH variable points to the directory containing CIF.so module. */ diff --git a/vlsisapd/doc/doxyfile b/vlsisapd/doc/doxyfile index 1232dfaa..851e3eb6 100644 --- a/vlsisapd/doc/doxyfile +++ b/vlsisapd/doc/doxyfile @@ -568,7 +568,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = "." "../src/cif" "../src/agds" "../src/dtr" +INPUT = "." "../src/cif" "../src/agds" "../src/dtr" "../src/openChams" # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/vlsisapd/doc/dtr/dtr.dox b/vlsisapd/doc/dtr/dtr.dox index c031b326..cf64b3a5 100644 --- a/vlsisapd/doc/dtr/dtr.dox +++ b/vlsisapd/doc/dtr/dtr.dox @@ -55,6 +55,6 @@ This python script (\c driveDtr.py) generates a out.dtr.xml file equivalent to the previous example.dtr.xml. \include driveDtr.py - \note In order to run these two scripts (\c parseDtr.py & driveDtr.py), user must ensure that $PYTHONPATH variable points to the directory containing pyDTR.so module. + \note In order to run these two scripts (\c parseDtr.py & driveDtr.py), user must ensure that $PYTHONPATH variable points to the directory containing DTR.so module. */ diff --git a/vlsisapd/doc/header.html b/vlsisapd/doc/header.html index e5892fee..08e57ede 100644 --- a/vlsisapd/doc/header.html +++ b/vlsisapd/doc/header.html @@ -13,6 +13,7 @@ AGDS CIF DTR + OPENCHAMS Links & Contact diff --git a/vlsisapd/doc/mainPage.dox b/vlsisapd/doc/mainPage.dox index 5ac1b69b..37b99dde 100644 --- a/vlsisapd/doc/mainPage.dox +++ b/vlsisapd/doc/mainPage.dox @@ -31,8 +31,9 @@ To quickly access to documentation of a format, one can use the following links : - - \subpage AGDS AGDS Format - - \subpage CIF CIF Format - - \subpage DTR DTR Format + - \subpage AGDS + - \subpage CIF + - \subpage DTR + - \subpage OPENCHAMS */ diff --git a/vlsisapd/doc/openChams/Circuit.dox b/vlsisapd/doc/openChams/Circuit.dox new file mode 100644 index 00000000..11bd166a --- /dev/null +++ b/vlsisapd/doc/openChams/Circuit.dox @@ -0,0 +1,129 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Circuit + * + * This class is the root class whihch means that having this object in hand allows to get/set any information contained in the OpenChams file parsed/drived. + */ + +/*! \fn Circuit::Circuit(Name name, Name techno) + * \brief creates a new technology + * + * \param name the name of the circuit. + * \param techno the technology used to descibe the circuit. + */ + +/*! \fn inline Name Circuit::getName() + * \brief returns the name of the circuit. + */ + +/*! \fn inline Name Circuit::getTechno() + * \brief returns the technology. + */ + +/*! \fn inline Netlist* Circuit::getNetlist() + * \brief returns the Netlist object associated to the circuit or NULL if it does not exist. + */ + +/*! \fn inline Schematic* Circuit::getSchematic() + * \brief returns the Schematic object associated to the circuit or NULL if it does not exist. + */ + +/*! \fn inline Sizing* Circuit::getSizing() + * \brief returns the Sizing object associated to the circuit or NULL if it does not exist. + */ + +/*! \fn inline Layout* Circuit::getLayout() + * \brief returns the Layout object associated to the circuit or NULL if it does not exist. + */ + +/*! \fn inline double Circuit::getValue(Name name) + * \brief returns the value of the circuit's parameter named \c name. + * + * \param name the name of the parameter. + */ + +/*! \fn inline void Circuit::addParameter(Name name, double value) + * \brief adds a parameter to the circuit. + * + * \param name the name of the parameter. + * \param value the value of the parameter. + */ + +/*! \fn inline void Circuit::addParameter(Name name, std::string equation) + * \brief adds an equation parameter to the circuit. + * + * \param name the name of the parameter. + * \param equation the equation string of the parameter. + */ + +/*! \fn inline Parameters Circuit::getParameters() + * \brief returns all circuit's parameters. + */ + +/*! \fn inline void Circuit::addSubCircuitPath(std::string path) + * \brief adds a path to circuit's subcircuit paths list. + * + * SubCircuitPaths are used to define where to search the xml file describing subcircuits used in current circuit. + */ + +/*! \fn void Circuit::addSimulModel(unsigned id, SimulModel::Base base, SimulModel::Version version, std::string filePath) + * \brief adds a SimulModel to the circuit. + * + * \param id the simulation model id. + * \param base the simulation model base. + * \param version the simulation model version. + * \param filePath the path to the netlist used by simulation model. + */ + +/*! \fn inline void Circuit::setSizing(Sizing* sizing) + * \brief sets the circuit's sizing. + * + * \param sizing the sizing of the circuit. + */ + +/*! \fn inline void Circuit::setLayout(Layout* layout) + * \brief sets the circuit's layout. + * + * \param layout the layout of the circuit. + */ + +/*! \fn Netlist* Circuit::createNetlist() + * \brief creates a new empty netlist and associates it to the circuit. + * + * \return the newly created netlist. + */ + +/*! \fn Schematic* Circuit::createSchematic() + * \brief creates a new empty schematic and associates it to the circuit. + * + * \return the newly created schematic. + */ + +/*! \fn Sizing* Circuit::createSizing(; + * \brief creates a new empty sizing and associates it to the circuit. + * + * \return the newly created sizing. + */ + +/*! \fn Layout* Circuit::createLayout() + * \brief creates a new empty layout and associates it to the circuit. + * + * \return the newly created layout. + */ + +/*! \fn bool Circuit::writeToFile(std::string filePath) + * \brief writes the database to file. + * + * \param filePath the destination file. + */ + +/*! \fn static Circuit* Circuit::readFromFile(const std::string filePath) + * \brief creates and returns a Circuit object based on a database source file. + * + * \param filePath the source file name. + * + * \return the newly created Circuit. + */ + +} diff --git a/vlsisapd/doc/openChams/Device.dox b/vlsisapd/doc/openChams/Device.dox new file mode 100644 index 00000000..4f9a967d --- /dev/null +++ b/vlsisapd/doc/openChams/Device.dox @@ -0,0 +1,48 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Device + * + * This class describes a Device. + * + * A device is a leaf instance which means its model is not defined in a external file but is described inside the device. + * As an instance, the Device inherits all Instance methods and adds specific properties: mos type, bulk connection and list of internal transistors. + * + * \note Althought today Device object only consider TransistorFamily devices, it will have to consider other devices, such as Capacitor when CHAMS project will. + */ + +/*! \fn Device::Device(Name name, Name model, Name mosType, Netlist* netlist) + * \brief creates a new device. + * + * \param name the name of the instance. + * \param model the model of the instance. + * \param mosType the mos type (NMOS or PMOS). + * \param netlist the netlist to which the instance belongs. + */ + +/*! \fn inline Name Device::getMosType() + * \brief returns the mos type of the device. + */ + +/*! \fn inline bool Device::isSourceBulkConnected() + * \brief returns true if the device's bulk is source connected. + */ + +/*! \fn Transistor* Device::addTransistor(Name name) + * \brief adds a Transistor to the device. + * + * \param name the name of the transistor. + * + * \return the newly created Transistor. + */ + +/*! \fn inline bool Device::hasNoTransistors() + * \brief returns true if the device has no transistors. + */ + +/*! \fn inline const std::vector& Device::getTransistors() + * \brief returns the list of device's transistors. + */ + +} + diff --git a/vlsisapd/doc/openChams/Exception.dox b/vlsisapd/doc/openChams/Exception.dox new file mode 100644 index 00000000..cfcae03c --- /dev/null +++ b/vlsisapd/doc/openChams/Exception.dox @@ -0,0 +1,9 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class OpenChamsException + * + * This class describes the exceptions throwed by the OpenChams library in case of errors. + */ + +} diff --git a/vlsisapd/doc/openChams/Instance.dox b/vlsisapd/doc/openChams/Instance.dox new file mode 100644 index 00000000..45e1ebc7 --- /dev/null +++ b/vlsisapd/doc/openChams/Instance.dox @@ -0,0 +1,70 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Instance + * + * This class describes an instance. + * + * Basicaly an instance is a subcircuit of the current (top) circuit. + */ + +/*! \fn Instance::Instance(Name name, Name model, Netlist* netlist) + * \brief creates a new instance. + * + * \param name the name of the instance. + * \param model the model of the instance. + * \param netlist the netlist to which the instance belongs. + */ + +/*! \fn void Instance::addConnector(Name name) + * \brief adds a connector to the instance. + * + * \param name the name of the connector. + */ + +/*! \fn void Instance::connect(Name connectorName, Name netName) + * \brief connects a net to one of the instance's connectors. + * + * \param connectorName the name of the connector. + * \param netName the name of the net. + */ + +/*! \fn inline void Instance::addParameter(Name name, double value) + * \brief adds a parameter to the instance. + * + * \param name the name of the parameter. + * \param value the value of the parameter. + */ + +/*! \fn inline void Instance::addParameter(Name name, std::string equation) + * \brief adds an equation parameter to the instance. + * + * \param name the name of the parameter. + * \param equation the equation string of the parameter. + */ + +/*! \fn Name Instance::getName() + * \brief returns the name of the instance. + */ + +/*! \fn Name Instance::getModel() + * \brief returns the model of the instance. + */ + +/*! \fn inline Netlist* Instance::getNetlist() + * \brief returns the netlist to which the instance belongs. + */ + +/*! \fn inline Parameters Instance::getParameters() + * \brief returns the parameters of the instance. + */ + +/*! \fn inline bool Instance::hasNoConnectors() + * \brief returns true if the instance has no connectors. + */ + +/*! \fn inline const std::map& Instance::getConnectors() + * \brief returns the map of instance's connectors. + */ + +} diff --git a/vlsisapd/doc/openChams/Layout.dox b/vlsisapd/doc/openChams/Layout.dox new file mode 100644 index 00000000..a5d1741f --- /dev/null +++ b/vlsisapd/doc/openChams/Layout.dox @@ -0,0 +1,34 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Layout + * + * This class describes layout informations for an Instance. + * + * The Layout object is used to store all informations relative to physical layout of the instance (such as the layout style). + * + * \note The Layout object is optionnal in Circuit. + */ + +/*! \fn Layout::Layout(Circuit* circuit) + * \brief creates a new layout. + * + * \param circuit the circuit to which the layout belongs. + */ + +/*! \fn void Layout::addInstance(Name name, Name style) + * \brief adds layout informations for a instance. + * + * \param name the instance's name to which the layout is associated. + * \param style the layout style. + */ + +/*! \fn inline bool Layout::hasNoInstance() + * \brief returns true if the layout has no Instance. + */ + +/*! \fn inline const std::map& Layout::getInstances() + * \brief returns the map of Instances. + */ +} + diff --git a/vlsisapd/doc/openChams/Name.dox b/vlsisapd/doc/openChams/Name.dox new file mode 100644 index 00000000..caa83f22 --- /dev/null +++ b/vlsisapd/doc/openChams/Name.dox @@ -0,0 +1,39 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Name + * + * This class provides an automatic management of shared name. + */ + +/*! \fn Name::Name(std::string str) + * \brief gets a shared Name, creates it if it does not exist. + * + * \param str the string associated to the name. + */ + +/*! \fn Name::Name(const char* cstr) + * \brief gets a shared Name, creates it if it does not exist. + * + * \param cstr the character string associated to the name. + * + * \note this method is not yet available in python + */ + +/*! \fn bool Name::operator==(const Name&) + * \brief redifines the '==' operator. + */ + +/*! \fn bool Name::operator==(const std::string&) + * \brief redifines the '==' operator. + */ + +/*! \fn bool Name::operator<(const Name) const + * \brief redifines the '<' operator. + */ + +/*! \fn inline const std::string& Name::getString() const + * \brief returns the string associated to the Name. + */ + +} diff --git a/vlsisapd/doc/openChams/Net.dox b/vlsisapd/doc/openChams/Net.dox new file mode 100644 index 00000000..87497ff9 --- /dev/null +++ b/vlsisapd/doc/openChams/Net.dox @@ -0,0 +1,103 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Net::Connection + * + * This class describe a Connection in a Net. + * A connection is a couple (instanceName, connectorName) used to represent all the connectors linked to a net. + */ + +/*! \fn Net::Connection::Connection(Name instanceName, Name connectorName) + * \brief creates a new connection. + * + * \param instanceName the name of the instance. + * \param connectorName the name of the instance's connector. + */ + +/*! \fn inline Name Net::Connection::getInstanceName() const + * \brief returns the name of the instance. + */ + +/*! \fn inline Name Net::Connection::getConnectorName() const + * \brief returns the name of the connector. + */ + +/*! \class Net + * + * This class describes a Net. + */ + +/*! \fn Net::Net(Name name, Name type, bool external, Netlist* netlist) + * \brief creates a new net. + * + * \param name the name of the net. + * \param type the type of the net (LOGICAL, POWER, GROUND, ...). + * \param external if true, then the net is set as external. + * \param netlist the netlist to which the transistor belongs. + */ + +/*! \fn void Net::connectTo(Name instanceName, Name connectorName) + * \brief adds a connection to the net. + * + * \param instanceName the instance's name of the Net::Connection. + * \param connectorName the connector's name ot the Net::Connection. + */ + +/*! \fn inline Name Net::getName() const + * \brief returns the name of the net. + */ + +/*! \fn inline Name Net::getType() + * \brief returns the type of the net. + */ + +/*! \fn inline bool Net::isExternal() + * \brief returns true if the net is external. + */ + +/*! \fn inline Netlist* Net::getNetlist() + * \brief returns the Netlist to which the net belongs. + */ + +/*! \fn inline bool Net::hasNoConnections() + * \brief returns true if the net has no Net::Connection. + */ + +/*! \fn inline const std::vector& Net::getConnections() + * \brief returns the list of net's connections. + */ + +/*! \fn Port* Net::addPort(Name type, unsigned idx, double x, double y, Name orient) + * \brief adds a Port to the net. + * + * \param type the type of the port. + * \param idx the index of the port. + * \param x the x coordinate of the port. + * \param y the y coordinate of the port. + * \param orient the orientation of the port. + * + * \return the newly created Port. + */ + +/*! \fn Wire* Net::addWire() + * \brief adds a Wire to the net. + * + * \return the newly create Wire. + */ + +/*! \fn inline bool Net::hasNoPorts() + * \brief returns true if net has no Port. + */ + +/*! \fn inline const std::vector& Net::getPorts() + * \brief returns the list of net's Port. + */ + +/*! \fn inline bool Net::hasNoWires() + * \brief returns true if net has no Wire. + */ + +/*! \fn inline const std::vector& Net::getWires() + * \brief returns the list of net's Wire. + */ +} diff --git a/vlsisapd/doc/openChams/Netlist.dox b/vlsisapd/doc/openChams/Netlist.dox new file mode 100644 index 00000000..6ecc7bee --- /dev/null +++ b/vlsisapd/doc/openChams/Netlist.dox @@ -0,0 +1,80 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Netlist + * + * This class describes a netlist. + * + * A netlist contains the list of all circuit's instances and nets. + * + * \note A Circuit must have one and only netlist. If no netlist is defined the Circuit cannot be driven to file. + */ + +/*! \fn Netlist::Netlist(Circuit* circuit) + * \brief creates a new netlist. + * + * \param circuit the circuit to which the netlist belongs. + */ + +/*! \fn Instance* Netlist::addInstance(Name name, Name model) + * \brief adds an Instance (subcircuit) to the netlist. + * + * \param name the name of the instance. + * \param model the model of the instance. + * + * \return the newly created Instance. + */ + +/*! \fn Device* Netlist::addDevice(Name name, Name model, Name mosType, bool connected) + * \brief adds a Device to the netlist. + * + * \param name the name of the device. + * \param model the model of the device. + * \param mosType the mos type of the device (NMOS or PMOS). + * \param connected if true, then device's bulk is source connected. + * + * \return the newly created Device. + */ + +/*! \fn Net* Netlist::addNet(Name name, Name type, bool external) + * \brief adds a Net to the netlist. + * + * \param name the name of the net. + * \param type the type of the net (LOGICAL, POWER, GROUND, ...). + * \param external if true, then the net is set as external. + * + * \return the newly created Net. + */ + +/*! \fn Instance* Netlist::getInstance(Name name) + * \brief returns the Instance named \c name or NULL it does not exist. + * + * \param name the name of the instance to get. + */ + +/*! \fn Net* Netlist::getNet(Name name) + * \brief returns the Net named \c name or NULL it does not exist. + * + * \param name the name of the net to get. + */ + +/*! \fn inline bool Netlist::hasNoInstances() + * \brief returns true if netlist has no instances. + */ + +/*! \fn inline bool Netlist::hasNoNets() + * \brief returns true if netlist has no nets. + */ + +/*! \fn inline const std::vector& Netlist::getInstances() + * \brief returns the list of netlist's instances. + */ + +/*! \fn inline const std::vector& Netlist::getNets() + * \brief returns the list of netlist's nets. + */ + +/*! \fn inline Circuit* Netlist::getCircuit() + * \brief returns the Circuit the netlist is associated to. + */ +} diff --git a/vlsisapd/doc/openChams/Operator.dox b/vlsisapd/doc/openChams/Operator.dox new file mode 100644 index 00000000..12c2a7a2 --- /dev/null +++ b/vlsisapd/doc/openChams/Operator.dox @@ -0,0 +1,109 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Operator::Constraint + * + * This class describes a constraint. + * A constraint is used to set that a parameter's value is defined relative to another parameter value or to an equation: + * deviceA.paramI = deviceB.paramJ * factor + * deviceA.paramI = equation * factor + */ + +/*! \fn Operator::Constraint::Constraint(Name ref, Name refParam, double factor) + * \brief creates a new constraint. + * + * \param ref the reference object (device, instace or circuit). + * \param refParam the reference parameter. + * \param factor the factor of the constraint. + */ + +/*! \fn inline Name Operator::Constraint::getRef() + * \brief returns the name of the object referenced by the constraint. + */ + +/*! \fn inline Name Operator::Constraint::getRefParam() + * \brief returns the name of the parameter referenced by the constraint. + */ + +/*! \fn inline double Operator::Constraint::getFactor() + * \brief returns the factor of the constraint. + */ + +/*! \class Operator + * + * This class describes an operator of a sizing procedure. + */ + +/*! \fn Operator::Operator(Name name, Name simulModel, unsigned callOrder) + * \brief creates a new operator. + * + * \param name the name of the operator. + * \param simulModel the simulation model of the operator. + * \param callOrder the call order of the operator in the sizing procedure. + */ + +/*! \fn void Operator::addConstraint(Name paramName, Name ref, Name refParam) + * \brief adds a Constraint to the operator. + * + * Constraint formula is : paramName = ref.refParam. + * Since the operator is associated to an instance, it is not necessaray to precise the name of this instance. + * + * \param paramName the name of the parameter to set. + * \param ref the name of the referenced object. + * \param refParam the name of the referenced parameter. + */ + +/*! \fn void Operator::addConstraint(Name paramName, Name ref, Name refParam, double factor) + * \brief adds a Constraint to the operator. + * + * Constraint formula is : paramName = ref.refParam * factor. + * Since the operator is associated to an instance, it is not necessaray to precise the name of this instance. + * + * \param paramName the name of the parameter to set. + * \param ref the name of the referenced object. + * \param refParam the name of the referenced parameter. + * \param factor the multiplicty factor. + */ + +/*! \fn void Operator::addConstraint(Name paramName, Name refEquation) + * \brief adds an equation Constraint to the operator. + * + * Constraint formula is : paramName = equation. + * Since the operator is associated to an instance, it is not necessaray to precise the name of this instance. + * + * \param paramName the name of the parameter to set. + * \param refEquation the referenced equation. + */ + +/*! \fn void Operator::addConstraint(Name paramName, Name refEquation, double factor) + * \brief adds an equation Constraint to the operator. + * + * Constraint formula is : paramName = equation * factor. + * Since the operator is associated to an instance, it is not necessaray to precise the name of this instance. + * + * \param paramName the name of the parameter to set. + * \param refEquation the referenced equation. + * \param factor the multiplicty factor. + */ + +/*! \fn inline Name Operator::getName() + * \brief returns the name of the operator. + */ + +/*! \fn inline Name Operator::getSimulModel() + * \brief returns the SimulModel of the operator. + */ + +/*! \fn inline unsigned Operator::getCallOrder() + * \brief returns the call order of the operator in the sizing procedure. + */ + +/*! \fn inline bool Operator::hasNoConstraints() + * \brief returns true if operator has no Constraint. + */ + +/*! \fn inline const std::map& Operator::getConstraints() + * \brief returns the map of operator's constraints. + */ + +} diff --git a/vlsisapd/doc/openChams/Parameters.dox b/vlsisapd/doc/openChams/Parameters.dox new file mode 100644 index 00000000..a8c2507d --- /dev/null +++ b/vlsisapd/doc/openChams/Parameters.dox @@ -0,0 +1,55 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Parameters + * + * This class describes a set of Parameters. + * Parameters consist in two maps associating a parameter name to a double value or a std::string (equation). + */ + +/*! \fn Parameters::Parameters() + * \brief creates a new set of parameters. + */ + +/*! \fn double Parameters::getValue(Name name) + * \brief returns the value of the parameter named \c name. + * + * \param name the name of the parameter. + * + * \return the parameter double value. + */ + +/*! \fn std::string Parameters::getEqValue(Name name) + * \brief returns the equation value of the parameter named \c name. + * + * \param name the name of the parameter. + * + * \return the parameter equation value (std::string). + */ + +/*! \fn void Parameters::addParameter(Name name, double value) + * \brief adds a new value parameter. + * + * \param name the name of the parameter. + * \param value the value of the parameter. + */ + +/*! \fn void Parameters::addParameter(Name name, std::string equation) + * \brief adds a new equation parameter. + * + * \param name the name of the parameter. + * \param equation the equation of the parameter. + */ + +/*! \fn inline bool Parameters::isEmpty() + * \brief returns true if Parameters has no value parameter nor equation parameter. + */ + +/*! \fn inline const std::map& Parameters::getValues() + * \brief returns the map of value parameters. + */ + +/*! \fn inline const std::map& Parameters::getEqValues() + * \brief returns the map of equation parameters. + */ +} diff --git a/vlsisapd/doc/openChams/Port.dox b/vlsisapd/doc/openChams/Port.dox new file mode 100644 index 00000000..612b4a80 --- /dev/null +++ b/vlsisapd/doc/openChams/Port.dox @@ -0,0 +1,43 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Port + * + * This class describes port. + * + * A port is used by schematic to position the input/output ports of the circuit. + * + * \note Althought the Port object is related to Schematic, it is handled by Net object since a port always belongs to a Net. + */ + +/*! \fn Port::Port(Name type, unsigned idx, double x, double y, Name orient) + * \brief creates a new port. + * + * \param type the type of the port. + * \param idx the index of the port (index of nets belonging to the same net must be different). + * \param x the x coordinate of the port. + * \param y the y coordinate of the port. + * \param orient the orientation of the port. + */ + +/*! \fn inline Name Port::getType() const + * \brief returns the type of the port. + */ + +/*! \fn inline unsigned Port::getIndex() const + * \brief returns the index of the port. + */ + +/*! \fn inline double Port::getX() const + * \brief returns the x coordinate of the port. + */ + +/*! \fn inline double Port::getY() const + * \brief returns the y coordinate of the port. + */ + +/*! \fn inline Name Port::getOrientation() const + * \brief returns the orientation of the port. + */ + +} diff --git a/vlsisapd/doc/openChams/Schematic.dox b/vlsisapd/doc/openChams/Schematic.dox new file mode 100644 index 00000000..8b4a884c --- /dev/null +++ b/vlsisapd/doc/openChams/Schematic.dox @@ -0,0 +1,61 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Schematic::Infos + * + * This class describes schematic informations for an instance. + * It contains x and y coordinates and the orientation of the instance. + */ + +/*! \fn Schematic::Infos::Infos(double x, double y, Name orient) + * \brief creates a new Infos object. + * + * \param x the x coordinate. + * \param y the y corrdinate. + * \param orient the orientation. + */ + +/*! \fn inline double Schematic::Infos::getX() + * \brief returns the x coordinate. + */ + +/*! \fn inline double Schematic::Infos::getY() + * \brief returns the y coordinate. + */ + +/*! \fn inline Name Schematic::Infos::getOrientation() + * \brief returns the orientation. + */ + +/*! \class Schematic + * + * This class describes schematic informations. + * + * The Schematic object is used to store all informations relative to schematic of the circuit. + * + * \note The Schematic object is optionnal in Circuit. + */ + +/*! \fn Schematic::Schematic(Circuit* circuit) + * \brief creates a new schematic. + * + * \param circuit the circuit to which the schematic belongs. + */ + +/*! \fn void Schematic::addInstance(Name name, double x, double y, Name orient) + * \brief adds schematic informations for an instance. + * + * \param name the instance's name to which the schematic informations are associated. + * \param x the x coordinate. + * \param y the y coordinate. + * \param orient the orientation. + */ + +/*! \fn inline bool Schematic::hasNoInstances() + * \brief returns true if the schematc has no Infos. + */ + +/*! \fn inline const std::map& Schematic::getInstances() + * \brief returns the map of instance's Infos. + */ +} diff --git a/vlsisapd/doc/openChams/SimulModel.dox b/vlsisapd/doc/openChams/SimulModel.dox new file mode 100644 index 00000000..4dcbdca2 --- /dev/null +++ b/vlsisapd/doc/openChams/SimulModel.dox @@ -0,0 +1,53 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \enum SimulModel::Base + * + * This enum describes the base of a simulation model. + * Available values are: + * - BSIM3V3 = 0 + * - BSIM4 = 1 + * - PSP = 2 + */ + +/*! \enum SimulModel::Version + * + * This enum describes the transistor version of a simulation model. + * Available values are: + * - UNDEFINED = 0 + * - SVT = 1 + * - HVT = 2 + * - LVT = 3 + */ + +/*! \class SimulModel + * + * This class describes a simulation model used by Operator in Sizing procedure. + */ + +/*! \fn SimulModel::SimulModel(unsigned id, Base base, Version version, std::string filePath) + * \brief creates a new simulation model. + * + * \param id the id of the simulation model. + * \param base the base of the simulation model. + * \param version the version of the simulation model. + * \param filePath the file path to the spice netlist used by simulation model. + */ + +/*! \fn inline unsigned SimulModel::getId() const + * \brief returns the id of the simulation model. + */ + +/*! \fn inline Base SimulModel::getBase() + * \brief returns the base of the simulation model. + */ + +/*! \fn inline Version SimulModel::getVersion() + * \brief returns the version of the simulation model. + */ + +/*! \fn inline std::string SimulModel::getFilePath() + * \brief returns the file path of the spice netlist used by the simulation model. + */ + +} diff --git a/vlsisapd/doc/openChams/Sizing.dox b/vlsisapd/doc/openChams/Sizing.dox new file mode 100644 index 00000000..a20e796a --- /dev/null +++ b/vlsisapd/doc/openChams/Sizing.dox @@ -0,0 +1,53 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Sizing + * + * This class describes a sizing procedure. + * + * The Sizing object is used to store all informations relative to sizing procedure as we defined it in \b CHAMS. + * + * \note The Sizing object is optionnal in Circuit. + */ + +/*! \fn Sizing::Sizing(Circuit* circuit) + * \brief creates a new sizing procedure. + * + * \param circuit the circuit to which the sizing belongs. + */ + +/*! \fn Operator* Sizing::addOperator(Name instanceName, Name operatorName, Name simulModel, unsigned callOrder) + * \brief adds an Operator to the sizing. + * + * \param instanceName the instance's name to which the operator is associated. + * \param operatorName the name of the operator. + * \param simulModel the simulation model associated to the operator. + * \param callOrder the call order of the operator in sizing procedue. + * + * \return the newly created Operator. + */ + +/*! \fn void Sizing::addEquation(Name name, std::string equation) + * \brief adds an equation to the sizing. + * + * \param name the name of the equation. + * \param equation the equation string. + */ + +/*! \fn inline bool Sizing::hasNoOperators() + * \brief returns true if the sizing has no Operator. + */ + +/*! \fn inline bool Sizing::hasNoEquations() + * \brief returns true if the sizing has no equation. + */ + +/*! \fn inline const std::map& Sizing::getOperators() + * \brief returns the map of sizing's Operator. + */ + +/*! \fn inline const std::map& Sizing::getEquations() + * \brief returns the map of sizing's equations. + */ + +} diff --git a/vlsisapd/doc/openChams/Transistor.dox b/vlsisapd/doc/openChams/Transistor.dox new file mode 100644 index 00000000..0d518fc5 --- /dev/null +++ b/vlsisapd/doc/openChams/Transistor.dox @@ -0,0 +1,85 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class Transistor + * + * This class describes a Transistor. + * + * The transistor object is used to describe the inside of a Device. The goal is to explicit the connection between the transistor and the device's nets. + */ + +/*! \fn Transistor::Transistor(Name name, Instance* instance) + * \brief creates a new transistor. + * + * \param name the name of the transistor. + * \param instance the instance (device) to which the transistor belongs. + */ + +/*! \fn inline void Transistor::addParameter(Name name, double value) + * \brief adds a parameter to the instance. + * + * \param name the name of the parameter. + * \param value the value of the parameter. + */ + +/*! \fn inline void Transistor::addParameter(Name name, std::string equation) + * \brief adds an equation parameter to the instance. + * + * \param name the name of the parameter. + * \param equation the equation string of the parameter. + */ + +/*! \fn inline Parameters Transistor::getParameters() + * \brief returns the parameters of the instance. + */ + +/*! \fn inline Name Transistor::getName() + * \brief returns the name of the transistor. + */ + +/*! \fn inline Name Transistor::getGate() + * \brief returns the name of the net connected to the transistor's gate. + */ + +/*! \fn inline Name Transistor::getSource() + * \brief returns the name of the net connected to the transistor's source. + */ + +/*! \fn inline Name Transistor::getDrain() + * \brief returns the name of the net connected to the transistor's drain. + */ + +/*! \fn inline Name Transistor::getBulk() + * \brief returns the name of the net connected to the transistor's bulk. + */ + +/*! \fn inline void Transistor::setName(Name name) + * \brief sets the transistor's name. + * + * \param name the name of the transistor. + */ + +/*! \fn void Transistor::setGate (Name name) + * \brief sets the net of the transistor's gate. + * + * \param name the name of the net to connect to the gate. + */ + +/*! \fn void Transistor::setSource(Name name) + * \brief sets the net of the transistor's source. + * + * \param name the name of the net to connect to the source. + */ + +/*! \fn void Transistor::setDrain (Name name) + * \brief sets the net of the transistor's drain. + * + * \param name the name of the net to connect to the drain. + */ + +/*! \fn void Transistor::setBulk (Name name) + * \brief sets the net of the transistor's bulk. + * + * \param name the name of the net to connect to the bulk. + */ +} diff --git a/vlsisapd/doc/openChams/Wire.dox b/vlsisapd/doc/openChams/Wire.dox new file mode 100644 index 00000000..835a3c73 --- /dev/null +++ b/vlsisapd/doc/openChams/Wire.dox @@ -0,0 +1,136 @@ +// -*- C++ -*- + +namespace OpenChams { +/*! \class WirePoint + * + * This class describes wire point. + * A wire point is an abstract object used to define all "direction changing" points of a wire. + */ + +/*! \class InstancePoint + * + * This class describes a wire point associated to an instance's connector. + */ + +/*! \fn InstancePoint::InstancePoint(Name name, Name connector) + * \brief creates a new wire point associated to an instance's connector. + * + * \param name the name of the instance. + * \param connector the name of the connector. + */ + +/*! \fn inline Name InstancePoint::getName() + * \brief returns the name of the instance associated to the instancePoint. + */ + +/*! \fn inline Name InstancePoint::getPlug() + * \brief returns the name of the connector associated to the instancePoint. + */ + +/*! \class PortPoint + * + * this class describes a wire point associated to a Port. + */ + +/*! \fn PortPoint::PortPoint(unsigned idx) + * \brief creates a new wire point associated to a port. + * + * \param idx the index of the port associated to the portPoint. + * + * \note The index of the port is only valid considering the net to which the wire is relative. + */ + +/*! \fn inline unsigned PortPoint::getIndex() + * \brief returns the index of the port associated to the portPoint. + */ + +/*! \class IntermediatePoint + * + * This class describes a wire point defined by its (x,y) coordinates. + */ + +/*! \fn IntermediatePoint::IntermediatePoint(double x, double y) + * \brief creates a new wire point based on its (x,y) coordinates. + * + * \param x the x coordinate. + * \param y the y coordinate. + */ + +/*! \fn inline double IntermediatePoint::getX() + * \brief returns the x coordinate. + */ + +/*! \fn inline double IntermediatePoint::getY() + * \brief returns the y coordinate. + */ + + + + + +/*! \class Wire + * + * This class describes wire. + * + * A wire is used by schematic to the connections between instances. + * It is defined by: + * - a start point (InstancePoint or PortPoint), + * - a end point (InstancePoint or PortPoint), + * - a list of IntermediatePoint, this list may be empty. + * + * \note Althought the Wire object is related to Schematic, it is handled by Net object since a wire is always associated to a Net. + */ + +/*! \fn Wire::Wire() + * \brief creates a new wire. + */ + +/*! \fn inline WirePoint* Wire::getStartPoint() + * \brief returns the start point of the wire. + */ + +/*! \fn inline WirePoint* Wire::getEndPoint() + * \brief returns the end point of the wire. + */ + +/*! \fn inline bool Wire::hasNoIntermediatePoints() + * \brief returns true if the wire has no IntermediatePoint. + */ + +/*! \fn inline const std::vector& Wire::getIntermediatePoints() + * \brief returns the list of wire's IntermediatePoint. + */ + +/*! \fn void Wire::setStartPoint(Name name, Name connector) + * \brief sets the wire's start point as an InstancePoint. + * + * \param name the name of the instance associated to the InstancePoint. + * \param connector the name of the connector associated to the InstancePoint. + */ + +/*! \fn void Wire::setStartPoint(unsigned idx) + * \brief sets the wire's start point as a PortPoint. + * + * \param idx the index of the port associated to the PortPoint. + */ + +/*! \fn void Wire::setEndPoint(Name name, Name connector) + * \brief sets the wire's end point as an InstancePoint. + * + * \param name the name of the instance associated to the InstancePoint. + * \param connector the name of the connector associated to the InstancePoint. + */ + +/*! \fn void Wire::setEndPoint(unsigned idx) + * \brief sets the wire's end point as a PortPoint. + * + * \param idx the index of the port associated to the PortPoint. + */ + +/*! \fn void Wire::addIntermediatePoint(double x, double y) + * \brief adds an IntermediatePoint to the wire. + * + * \param x the x coordinate of the IntermediatePoint. + * \param y the y coordinate of the IntermediatePoint. + */ +} diff --git a/vlsisapd/doc/openChams/openChams.dox b/vlsisapd/doc/openChams/openChams.dox new file mode 100644 index 00000000..d6ebd5d0 --- /dev/null +++ b/vlsisapd/doc/openChams/openChams.dox @@ -0,0 +1,80 @@ +/*! \page OPENCHAMS OPENCHAMS Format + + \section openChamsPres Presentation + The OpenCHAMS format was developped as a part of the Chams Project (http://www-soc.lip6.fr/recherche/cian/chams/). + It aims at offering a convenient way to describe analogic circuits' netlists and is based on XML. + Some CHAMS specific informations, such as schematic properties, layout properties or sizing procedure, can be described in this format.\n + + \subsection openChamsAutrhos Author + Damien Dupuis: damien.dupuis(at)lip6(.)fr + + \section openChamsDB Stand alone database structure + The database has many objects that can be arranged in five categories: + - General + - OpenChams::Circuit + - OpenChams::Name + - OpenChams::OpenChamsException + - Netlist + - OpenChams::Netlist + - OpenChams::Instance + - OpenChams::Device + - OpenChams::Transistor + - OpenChams::Parameters + - OpenChams::Net + - Sizing + - OpenChams::Sizing + - OpenChams::Operator + - OpenChams::SimulModel + - Schematic + - OpenChams::Schematic + - OpenChams::Port + - OpenChams::Wire + - OpenChams::WirePoint + - OpenChams::InstancePoint + - OpenChams::PortPoint + - OpenChams::IntermediatePoint + - Layout + - OpenChams::Layout + + \subsection openChamsParser Using the parser + Simply load an OPENCHAMS file using the static function OpenChams::Circuit::readFromFile() and then get the netlist object (OpenChams::Circuit::getNetlist()) or the sizing procedure (OpenChams::Circuit::getSizing(), might be NULL) or any other useful information (see OpenChams::Circuit). + + \subsection openChamsDriver Using the driver + Using the driver is very simple, user has to create a DTR::Techno object and simply add DTR::Rule or DTR::ARule to it. + The adding methods return the newly created Rule so user can set the rule type (DTR::Rule::setType()) if necessary. Finally use the DTR::Techno::writeToFile() method to dump the database to file. + + \section openChamsExamples Examples + As said is the global presentation, VLSI SAPD project provides C++ libraries and Python modules for each supported format. In this section we present simple code examples to parse and drive a OPENCHAMS file using C++ or Python. The OPENCHAMS files considered are the same for all examples: \c inverter.xml and \c buffer.xml + \include inverter.xml + \include buffer.xml + + All source codes are available in the \c examples directory. + + \subsection openChamsC C++ + \subsubsection openChamsParseC Parser + The following code (\c parseOpenChams.cpp) is an example of how to parse a OPENCHAMS file using C++ library. + \include parseOpenChams.cpp + + \subsubsection openChamsDriveC Driver + This C++ code (\c driveOpenChams.cpp) generates an inverter.xml file equivalent to the included one. + \include driveOpenChams.cpp + + \note In order to compile these codes, a CMakeLists.txt file is provided. User must set the $VLSISAPD_TOP variable before running these commands in the directory containing the CMakeLists.txt file: + \code + %> mkdir build; cd build + %> cmake .. + %> make + \endcode + + \subsection openChamsPython Python + \subsubsection openChamsParsePython Parser + The following python script (\c parseOpenChams.py) is an example of how to parse a OPENCHAMS file using python module. + \include parseOpenChams.py + + \subsubsection openChamsDrivePython Driver + This python script (\c driveOpenChams.py) generates an inverter.xml file equivalent to the included one. + \include driveOpenChams.py + + \note In order to run these two scripts (\c parseOpenChams.py & driveOpenChams.py), user must ensure that $PYTHONPATH variable points to the directory containing OPENCHAMS.so module. +*/ +