# Datasheet Format ```{note} Prior to June 2024 CACE used the datasheet version 4.0 text format. This format is now deprecated, please export your datasheet in the new YAML format. ``` The CACE datasheet contains the specification of your design and other important information. It acts as both documentation for the specifiaction but also as input for CACE. The following sections describe the structure of the datasheet. ## Metadata Example entry: ```yaml name: ota-5t description: A simple 5 transistor OTA PDK: sky130A cace_format: 5.0 ``` - `name: ` > Name of the design (cell name) - `description: ` > Description of the design - `PDK: ` > Name of the PDK (no spaces) - `cace_format: ` > Format version of the datasheet. Current version: `5.2`. ## Authorship Example entry: ```yaml authorship: designer: Leo Moser company: Efabless creation_date: May 27, 2024 license: Apache 2.0 ``` - `designer: ` > The person to whom the design is attributed. - `company: ` (optional) > The name of a company, if applicable. - `institution: ` (optional) > The name of an institution, if applicable. - `email: ` (optional) > E-mail for contact information. - `creation_date: ` > Date that the CACE setup was made, or any meaningful date for the creation of the design. - `modification_date: ` > Generally handled by the tools to specify when the characterization file was last updated. - `license: ` > A known license type, such as "Apache 2.0". ## Paths The paths section is used to tell CACE where to find certain files of your design or where to generate files for simulation. Example entry: ```yaml paths: root: .. schematic: xschem layout: gds netlist: netlist documentation: doc ``` - `root: ` > This is the location of the project and the root of all the other paths in this dictionary. Normally it is set to `..` to refer to the parent directory of `cace/`. - `schematic: ` > Location of any schematics (xschem) and symbols for the design. The xschemrc should be located here. - `magic: ` (optional) > Location of any layout in magic (.mag) format. - `layout: ` > Location of any layout in GDS (.gds or .gds.gz) format. Note that any magic layout (if given) will be converted to GDS and saved here. - `netlist: ` > Location of all SPICE netlists. This netlist is usually automatically generated by cace, with subdirectories for each netlist type according to the netlist source (see `--source` option): "schematic", "layout" (for LVS), "pex" (C-parasitic extracted layout), and "rcx" (R-C-parasitic extracted layout). - `documentation: ` > Location for the auto-generated documentation of the design. - `runs: ` (optional) > Location for the run directory. ## Pins The pins of the design, mainly used for documentation purposes. The names of the pins are checked against the schematic. Example entry: ```yaml pins: VDD: description: Power supply direction: inout type: power Vmin: 1.7 Vmax: 1.9 Imin: 0 Imax: 0.01 ... ``` - `name: ` > The pin name. Must match the name on the schematic or netlist. Vectors should be indexed with ":" and will be expanded when needed. "b7:0" expands to "b7, b6, b5, ..." while "b[7:0]" expands to "b[7], b[6], b[5], ..." (Note that this is more flexible than the convention for condition names described below.) - `description: ` > Text description of the pin. May contain spaces. - `type: ` > The type may be one of "digital", "signal", "power", or "ground". - `direction: ` > The direction may be one of "input", "output", or "inout". - `Vmin: |` > The pin minimum voltage may be a value or may be referenced to another pin; and may be referenced to another pin with an offset (e.g., "vss - 0.3"). - `Vmax: |` > The pin maximum voltage may be a value or may be referenced to another pin; and may be referenced to another pin with an offset (e.g., "vdd + 0.3"). - `Imin: |` > The pin maximum sink current -a minimum value if specified as a negative current- may be a value or may be referenced to another pin; and may be referenced to another pin with an offset. - `Imax: |` > The pin maximum source current may be a value or may be referenced to another pin; and may be referenced to another pin with an offset. ## Default Conditions The default conditions under which to evaluate the parameters. Example entry: ```yaml default_conditions: corner: display: Corner description: The corner of the wafer typical: tt unit: V ... ``` - `name: ` > The name of the condition; this name is meaningful because it will match a variable name used in a schematic or netlist. The representation in the netlist is always ${} to prevent accidental substitutions of matching strings. Any set of signals can be bundled, but the delimiters for the bundle must be brackets; e.g., b[7:0], with single bits called out as, e.g., b[0]. - `description: ` > A description of the condition. - `display: ` > A short, typically one-word value to display for the condition. - `unit: ` > The unit of measure used to display the condition value. - `typical: ` > If present, the default typical value of the condition. - `maximum: ` > If present, the default maximum value of the condition. - `minimum: ` > If present, the default minimum value of the condition. - `enumerate: ` > If present, instead of min/typ/max values, the values are enumerated from a space-separated list supplied in (see above; long lists may be backslash-newline terminated). - `step: linear|logarithmic` > If not present, then only values min/typ/max are evaluated. If present, then values are automatically enumerated from min to max inclusive either in linear (default) or logarithmic progression. If typ exists and is not in the enumeration, then it is evaluated in addition. - `stepsize: ` > If not present, then a stepsize of 1 is assumed for linear enumeration or 2 for logarithmic enumeration. Otherwise, the enumeration steps by additive values for linear enumeration or multiplicative values for logarithmic enumeration. ## Parameters Example entry: ```yaml parameters: dc_params: spec: a0: display: DC gain description: The DC gain of the OTA unit: V/V minimum: value: 50 typical: value: any maximum: value: any ugf: display: Unity Gain Frequency description: The unity gain frequency of the OTA unit: Hz minimum: value: 1e6 typical: value: any maximum: value: any pm: display: Phase Margin description: The phase margin of the OTA unit: ° minimum: value: 60 typical: value: any maximum: value: any tool: ngspice: template: ac.sch format: ascii suffix: .data variables: [a0, ugf, pm] plot: gain_vs_temperature: type: xyplot xaxis: temperature yaxis: a0 phase_margin_vs_corner: type: xyplot xaxis: corner yaxis: pm conditions: corner: enumerate: [tt, ff, ss] # fs, sf temperature: minimum: -40 typical: 27 maximum: 130 ``` - `description: ` > A global description of the parameter. - `display: ` > A global short description to display for the parameter. - `unit: ` > The global unit measurement of the parameter. Same format as "unit" for conditions. - `spec: ` > The target specification for the parameter (see below). - `tool: ` > The tool which is used to run the parameter. It can either be a single name if the default settings are sufficient, or a dictionary with tool-specific settings. - `conditions: ` > All the conditions to be applied to the measurement of the parameter that are considered to be fixed with respect to the parameter result (see "variables" below). - `variables: ` > Used for specifying `display` and `unit` attributes for results that are used for plotting. - `plot: ` > Describes how to make data plots for the parameter (where result is plotted rather than generating a single set of min/typ/max values). ### Conditions Example entry: ```yaml conditions: vdd: typical: '1.8' vcm: typical: '0.9' corner: enumerate: [tt, ff, ss] ``` The "conditions" dictionary entries are the same as the `default_conditions` dictionary, above. The `default_conditions` dictionary is applied to every condition before adding or overwriting with the specific conditions listed for the parameter. Conditions are only meaningful when the condition name exists as a placeholder in the template file. ### Specification Example entry: ```yaml spec: area: display: Area description: Total circuit layout area unit: µm² maximum: value: 600 width: display: Width description: Total circuit layout width unit: µm maximum: value: any ``` The specification entry specifies the limits for results returned by the tool of the parameter. For example, if a tool returns `area` and `width` as a result, then the limits can be defined as seen above. Additionally, `display`, `description` and `unit` can be set per result and overwrite the global values. - ```yaml minimum: value: |any fail: calculation: limit: ``` > Specifies the target value for the parameter minimum value. If not specified, then no minimum is measured. If "any" is given as the value, then the minimum is measured but there is no target value. By default, the parameter is marked as failing if the measured value is out of spec. By setting `fail: false`, it is not checked agains the limit. If `calculation` and `limit` is specified, then it overrides the default calculation and limit of `minimum` and `above`. - ```yaml typical: value: |any fail: calculation: limit: ``` > Specifies the target value for the parameter typical value. If not specified, then no typical is measured. If "any" is given as the value, then the typical is measured but there is no target value. If "fail" is specified as "true", then parameter is marked as failing if the measured value is out of spec (failing on a typical value is rarely if ever used). If `calculation` and `limit` is specified, then it overrides the default calculation and limit of `average` and `exact`. - ```yaml maximum: value: |any fail: calculation: limit: ``` > Specifies the target value for the parameter maximum value. If not specified, then no maximum is measured. If "any" is given as the value, then the maximum is measured but there is no target value. If "fail" is also specified as "true", then parameter is marked as failing if the measured value is out of spec. If `calculation` and `limit` is specified, then it overrides the default calculation and limit of `maximum` and `below`. ### Tool For an overview of which tools are currently supported by CACE, please have a look at {doc}`tools`. Example entry: ```yaml tool: ngspice: template: ac.sch format: ascii suffix: .data variables: [a0, ugf, pm] ``` The toolname specififes which tool is used by CACE. Each tool may stay on its own or accept a range of arguments to change its behavior. ### Variables Example entry: ```yaml variables: time: display: Time unit: ms Vinp: display: Vinp unit: V result: display: Vout unit: V ``` Variable entries are used for plotting to specify the `display` and `unit` entry of results. - `display: ` > This value is text to display on the graph. - `unit: ` > This is the unit that will be displayed after the display string. ### Plots Example entry: ```yaml plot: transient: suffix: .svg xaxis: time yaxis: [Vout, Vinp] ``` - `type: ` (optional) > The type of plot to make. If this record is missing from the dictionary, then plot type "xyplot" is assumed by default. Otherwise, the value should be one of "xyplot", "histogram", "semilogx", "semilogy", or "loglog". - `xaxis: ` > Variable to be plotted on the graph X axis. - `yaxis: |` > Variables to be plotted on the graph Y axis. - `title: ` (optional) > A title for the graph. - `limits: ` (optional) - `false` - do not show limits - `true` - always show limits - `auto` - show limits if they are in the yrange The default setting for `limits` is auto. Plots are made from measured columnar data which may be from a "wrdata" command in ngspice or an "echo" statement directed to a file.