#./pddd # -*-pd-*- EDDA #### CVS revision 1.4 <> <> Electronic Design Description Automation ======================================== The EDDA documentation system is a collection of scripts created to simplify the process of running ocean simulations and create design documentation. The system consists of two parts: 1. Skill +scripts+ to be used in the Cadence +OCEAN+ environment to launch simulations and log simulation results. 2. The +PlainDoc+ script +pddd+ (based on the <> tool written by Sampo Kellomäki) to capture the simulation results into graphs and tables and create human readable design documentation (HTML and PDF documents). PlainDoc is a tool to convert text files having a to nicely formatted HTML and PDF documents. PlainDoc is powerfull enough to allows the user to create cross references, insert figures, tables and equations. An example EDDA design description may look like <>. There are several advantages using the documentation system: * Speed up documentation process. Simulation results are automatically compared to specification and inserted into the simulation document. This minimise the risk of human errors. * Batch simulations over several corners can easily be simulated over night using scripts. * Simple to update results. When a schematic is modified or model file is updated the simulation script can be relaunched and all new results are automatically inserted into the documents. * Both HTML and PDF documents are automatically created for easy sharing of information within design group. This tutorial is written using PlainDoc by Fredrik Jonsson. You can view the source of this document <>. If you have any comments or suggestions, please contact me at <> Also, it would be interresting to know if you sucessfully used EDDA in a project Download -------- Click <> EDDA. Extract the tar file using > tar -zxvf edda.tar.gz Copy the file edda/log_data.il to a directory where you store SKILL files, and put the file edda/pddd in your executable search path. The EDDA system use a number of Unix tools like Perl, LaTeX and image magick when creating the documents. Most of these tools are standard on common Linux distributions. If the tools are not available they have to be downloaded and installed separately. EDDA have succesfully been tested on sevral different Redhat, Fedora and Cygwin installations. License ------- The EDDA documentation system is created by Fredrik Jonsson. The EDDA version of PlainDoc is an extension of the PlainDoc tool created by Sampo Kellomäki. Information about PlainDoc can be found at http://mercnet.pt/plaindoc/pd.html EDDA is offered under the Gnu Public License (GPL). 2. Using EDDA ============= Below will follow a short overview how to run simulations and create design documentation using EDDA. In order to use the EDDA system it is assumed you are familiar with running Cadence simulations using Ocean. For information regarding how to configure these tools, please read the cadence documentation. To create a EDDA document from an existing Cadence simulation testbench we need to: 1. Create a documentation directory where the simulation files and documents will be generated 2. Create an OCEAN simulation script file and run the simulations 3. Create a PlainDoc document 4. Generate the HTML and PDF documents The following chapters will explain each step. Directory structure ------------------- Since the EDDA system generates a large number of files the simulations and documents are created in a special directory structure. An example directory looks like figure <> <> The *doc_directory* is the documentation directory. This directory can have any name and location. The *.pd* directory stores temporary information when running PlainDoc. *corners* store files defining the different simulation corners. *html* will contain the HTML output Simulations scripts are stored in *testbench* directories. The testbench directory contains the netlist and the Ocean scripts. In the testbech directory a subdirectory for each simulation corner will be created containing simulation results. A documentation directory can contain any number of testbenches, but each testbench directory can only have one netlist. The *tex* directory contains temporary data when creating a PDF document using LaTeX. Finally *edda.pd* is the document source file. The generated HTML and PDF documents will have the same name as the source file. The directory structure can be generated using the command: > pddd -init OCEAN file ---------- When running a cadence within the ~Virtuoso~ analog design environment you can create an OCEAN script using the menu command Session->Save Script ... In order to use the OCEAN script in the EDDA environment you need to modify the script according to the following steps: 1. Move corner definitions to a corner file 2. Create a symbolic link to the netlist in the testbench directory 3. Remove information regarding simulator and result directory 4. Add commands to log simulation results The steps will be described in more detail below: A typical automatic generated OCEAN script can look like this: <> This example script run an simple AC and a DC simulation and plots the result. We will now copy this file to the testbench directory and modify it to be compatible with EDDA. Corner file ~~~~~~~~~~~ In order to use the script in the EDDA environment we first extract the corner definition. The corner definition files are located in the ~corners~ directory. The corner file can have any name, but the the name ~typ~ is reserved for the typical corner. Extracting the corner information from the example OCEAN file into a corner file. The final file corners/typ may look like this: modelFile( '("/pkg/designkits/umc/MM018/MM180_REG18_V123.lib.scs" "tt") ) desVar("Vsupply" 1.8) temp( 27 ) Create symbolic link ~~~~~~~~~~~~~~~~~~~~ The ~sim~ script will look for a link to the netlist in the test bench directory. When not using EDDA the design will be loaded using the line design( "/home/fjon/simulation/simple/spectre/schematic/netlist/netlist") in the ocean script. The actual location of the design file of course depend on the cadence configuration and the user. The design definition must be removed from the script file and be replaced by a symbolic link. The symbolic link is created using the Unix command > cd testbench1 > ln -s home/fjon/simulation/simple/spectre/schematic/netlist/netlist . Don't forget the . at the end of the line. Remove simulator and directory information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ~sim~ script automatically configures the simulator and results directory so this information can be removed from the scripts file. Remove the lines ocnWaveformTool( 'wavescan ) simulator( 'spectre ) design( "/home/fjon/simulation/simple/spectre/schematic/netlist/netlist") resultsDir( "/home/fjon/simulation/simple/spectre/schematic" ) from the script file. The ~sim~ script will use the directory /tmp/USER/simulation/SCRIPT to store simulation results, where ~USER~ and ~SCRIPT~ will be replaced by the user name and name of the script file. Log simulation results ~~~~~~~~~~~~~~~~~~~~~~ The EDDA system have a set of skill functions to log simulation results. Scalar data can be stored using ~log_data~ and waveforms are stored using ~log_wave~. Data from simulation loops can be combined to generate a waveform using ~log_data_point~. The simulation results are stored as text files within the testbench directory. A subdirectory for each corner will be generated. To log the DC voltage and the AC response in the example ocean script we can use the following lines: log_data(VDC("/out") "Vdc") log_wave(dB20(VF("/out")) "ACmag") If simulation is performed using these commands in the typ corner the files testbench1/typ/Vdc and testbench1/typ/ACmag will be created. Plot commands from the original ocean script can be removed. Now all the modifications to the script file is ready and the final script testbench1/script.ocn may look like this: <> Running the simulation ---------------------- The simulation script are simulated using ocean. Start ocean within the testbench directory. > cd testbench1 > ocean Load the EDDA skill functions using > load "log_data.il" Now we can run the simulation using > sim "script.ocn" If we don't specify a corner the default corner "typ" will be used. To specify another corner we can type > sim "script.ocn" "fast" Assuming we have a cornerfile named "fast" in the ~corners~ directory. If the schematic is modified we recreate the netlist from Analog artist using the menu Simulation->Netlist->Recreate To rerun the simulation script using the previous script file and corner it is enough to type > sim A batch simulation simulating many corners can be created, for example by creating a file ~all~ containing the lines sim "script.ocn" "typ" sim "script.ocn" "fast" sim "script.ocn" "slow" and simulating this file using sim "all" will simulate over corners typ, fast and slow. Creating the simulation report ------------------------------ The simulation results can be documented in a design document. The document is written in PlainDoc which is a simple text-file containing a few special "tags" to include simulation results, plots, equations, schematics etc. Document structure ~~~~~~~~~~~~~~~~~~ In the document we first insert the document title: Example simulation ################## After this we insert information indicating the paper format, information about the author etc: <> <> Plain doc use a very simple yet powerful markup structure. Different headings are indicated by the way they are underlined: 1 Heading 1 =========== 1.1 Heading 2 ------------- 1.1.1 Heading 3 ~~~~~~~~~~~~~~~ The numbers at the beginning of the line are ignored when compiling the document, and sections are renumbered automatically. Lists is created by inserting a * or a number at the beginning of a line * Bulted list 1. Numbered list 2. Item 2 *Bold* +italic+ and ~computer~ output is created by inserting *+ or ~ around a word: *Bold* +italic+ and ~computer~ output. Verbatim text blocks Verbatim text is created by inserting a single space at the beginning of a line. Lines beginning with a % are commented out and will not be included in the output documents. For more detailed information about the PlainDoc syntax, please see the appendix or the <> documentation. Inserting simulation results ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Simulation results are inserted using the tags ~data~ and ~plot~. Scalar data is inserted into a table like table <> <> using the ~data~ command: The ~slow~ and ~fast~ tags indicates in which corner the simulation result was found. To insert the DC voltage from the previous simulation we can use the following lines: <> The first line <> are inserted using the command ~plot~ <> The plots are created using gnuplot. By clicking on a plot in the HTML document a magnified version of the graph is presented. To plot the AC magnitude in the example simulation we use the following line: <> The syntax of the plot command is: waveform(s), Title, X label, Y label, Plot option *waveform* is the waveforms to be plotted. *Title* is the title of the plot *X axis* and *Y axis* is the labels on the x and y axis. The *set* and *Plot option* commands can be used to specify plot options in gnuplot. All Gnuplot ~set~ and ~unset~ commands can be used to control the graph. Another useful ~set~ command is set xrange [10:100] that can be used to control the range on the axis. For more details regarding available set commands, please refer to the Gnuplot documentation at http://www.gnuplot.info/ Several plots can be specified in one plot statement by adding plot specifications. Set commands must be specified for each plot. Several waveforms can be plotted in the same graph by putting an & between the plot names. No space is allowed between the names. Specific simulation corners can be selected by putting the corner in parenthesis after the waveform name. The waveform caption can be specified by putting the caption within "". The corner is omitted from the caption if only simulation result from one corner is found. *Example:* The following example creates two plots. The first plot (Figure <>) have two waveforms, the first incluing data from the ~typ~ and ~slow~ corner and label it "Mag" and the second ~fast~ corner and label it "Gain fast". The second plot (Figure <>) is a zoomed in version haing only one wave from the ~slow~ corner. <> <> By default simulation data from all available corners and testbench directories are collected. You can specify a specific corner or directory by inserting ~dir~ and ~corners~ lines the same way as in the ~data~ table. If we only want the ~typ~ corner from ~testbench1~ we can write: dir=testbench1 corners=typ Generating the HTML and PDF outputs ----------------------------------- The HTML and DPF outputs are generated using the command > pddd example.pd The HTML document by viewed by opening the file ~html/index.html~ in a web browser. The PDF document is copied both to the HTML directory and to the documentation directory. Example ======= An example EDDA design description may look like <>. The document is generated using the following <>. <> Appendix ======== PlainDoc tags ------------- Design variables ~~~~~~~~~~~~~~~~ It is sometime useful to include design variables in the design documentation. Design variables are included using the command <> The command extracts lines containing desVar("variable" Value); Comment and creates a table <> The variables are automatically extracted from an ocean script file. Only variable definitions printed at the beginning of a line will be included. This is in order to allow variables to be omitted from a table by simply adding a space in front of the variable name. Log files ~~~~~~~~~ Output log-files can be inserted using <> The log file is formatted using typewriter type font. Long lines are broken in order to not overflow the paper. Schematics ~~~~~~~~~~ Schematics are included using <> where *Schematic* is the name of the schematic and *Library* is the library name. You currently have to specify the name of each schematic and library manually. Schematics should be printed using hierarchical print from cadence to the directory ~sch~ in the documentation directory. Plot the schematics without header and remember the last / when specifying the plot path. Images ~~~~~~ Figures and images are inserted using the command <> where *image* is the name of the image *without* suffix specifying file type. .eps, .png, and .jpg images are recognised automatically. The optional *position* and *size* are used to control the position and size of the image in the PDF output. Please consult the PlainDoc documentation for details. *Caption* is the caption of the image. Images can be referenced using the image name. Currently all images have to be located in the documentation directory, including images fron sub-directories do not work. *Example:* <> includes the file hotdogs.jpg from the documentation directory. <> The size "3" makes the image fill 1/3 of the page width in the PDF document. Tables ~~~~~~ Tables are inserted using the ~table~ command: <> Will insert a table: <> Equations ~~~~~~~~~ Equations are inserted using the ~eqn~ tag. *Syntax:* <> *equation* is the equation definition using TeX syntax. There are numerous sources of information regarding TeX on the internet. one good starting point is http://www.artofproblemsolving.com/LaTeX/AoPS_L_GuideCommands.php *tag* is an optional tag in order to allow referencing of the equation. *Example:* <> Generates the equation <> References ~~~~~~~~~~ The ~see~ command is used to insert a reference < > The tag is replaced by the number of the figure, plot or table. Referencing is done by name matching, where the tag that have the closest match is used. If the match is not exact a warning is generated when generating the document but the reference is still valid. Skill functions --------------- The skill scripts are a collection of scripts to launch simulations and to log simulation results. These scripts are used as commands within an ocean script. Table <> lists the available skill scripts. <> log_data Log data point <> log_wave Log waveform <> log_data_point Creates waveform from data points <> log_data_gap Creates a gap in a waveform <> >> 1.1.1 sim ~~~~~~~~~ Load simulation script and run simulation. *Syntax:* sim "ocean_script" "corner" *Example:* > sim "test.ocn" "slow" The example above simulates the script ~test.ocn~ in corner ~slow~. > sim "test.ocn" runs the simulation in the same corner as previous simulation. Default corner is ~typ~. > sim repeats the simulation using previous script file and corner. 1.1.2 log_data ~~~~~~~~~~~~~~ Log single value data point. *Syntax:* log_data( data "filename" ) Data will be saved in the folder corresponding to the current simulation corner. *Example:* log_data(IDC("/V0/PLUS") "Isupply") 1.1.3 log_wave ~~~~~~~~~~~~~~ Log waveform data *Syntax:* log_wave( waveform "filename") Save *waveform* data to a file named *filename*. Data will be saved in the folder corresponding to the current simulation corner. *Example:* log_wave(VT("/Vout") "Vout") 1.1.4 log_data_point ~~~~~~~~~~~~~~~~~~~~ Save numerical data-point to waveform file *Syntax:* log_data_point(xdata ydata "filename") This function is useful in simulation loops, where each iteration creates a new data-point. *Example:* foreach(vbias '(0.8 0.9 1.0) desVar("Vbias" vbias) run() log_data_point(vbias value(dB20(VF("/out")),10M) "ACgain10M_vs_bias") ) runs three simulations for vbias = 0.8, 0.9 and 1.0. A waveform ACgain10M_vs_bias is created. 1.1.5 log_data_gap ~~~~~~~~~~~~~~~~~~ Lifts the pen in a waveform. *Syntax:* log_data_gap(output) This is useful if the plot should not be a continues line. *Example:* log_data_gap("ACgain10M_vs_bias") Command line scripts -------------------- pddd ~~~~ pddd is a ~pearl~ script to generate the HTML and PDF files from the PlainDoc document. pddd plaindoc.pd : Convert plaindoc.pd to PDF and HTML pddd -init : Creates simulation directories The ~pddd~ script is based on the PlainDoc system script ~pd2tex~ originally created by Sampo Kellomäki, but with several extensions and improvements. The modifications was initially only intended for personal use, but as the project grew I decided to make the modifications public. Since documents created for ~pddd~ are not fully compatible with ~pd2tex~ I decided to make ~pddd~ a branch of the PlainDoc project. The added features do currently not support DBX output. Change log ========== <>