Page

TDML Developer Tutorial *

1.0 TDML Introduction *

2.0 Overview of TDML Structure *

3.0 XML Overview *

4.0 TDML Examples *

5.0 Encoding Information Not Defined in the Standard *

6.0 XML Parsers *

This document describes how Timing Diagram Markup Language (TDML) is used to represent timing diagrams. Timing diagrams consist of waveforms, timing specifications, and parameters which define relationships between signals. TDML is designed to be the interactive timing diagram format used in on-line datasheets. To accomplish this goal, it also includes information on presentation and objects normally found in printed datasheets such as text annotations and time compression markers.

TDML is being developed by an Electronic Component Information eXchange (ECIX) Working Group under the management of the Silicon Integration Initiative (Si2). Members of the Working Group include: Chronology Corporation, Denali Software Inc., SynaptiCAD Inc., IBM, and Mentor Graphics/Interconnectix Business Unit.

The TDML Working Group was formed in December 1997 with the goal of developing an interchange standard for timing diagram information that would:

Allow interchange between users and producers of timing diagrams using different timing diagram tools, and

Allow incorporation of timing diagram data as a strategic element of the ECIX Pinnacles Component Information Standard (PCIS).

TDML is an open industry standard language for the exchange of interactive timing diagrams. TDML allows exchange of interactive timing diagram information in a standard form. This standard form promotes the sharing and interchange of information between different organizations and allows interested parties to develop tools for generating, editing, and browsing these diagrams.

The standard resulting from this process will be designed for use by ECIX PCIS-compliant datasheets for representation of timing and waveform diagrams that describe component and intellectual property (IP) characteristics. This interchange format will be promoted as an industry-wide standard first through Si2 membership, then formally through the IEEE/IEC. The standard is openly available to companies worldwide for adoption and usage with both commercial and in-house software tools.

TDML is eXtensible Markup Language (XML) compliant. The choice of XML provides the format with several benefits. XML is a highly structured, easily parsed format. Several freely available XML browsers and parsers exist that provide file validity checking and simplify the creation of TDML parsers. The format also provides a method for adding and preserving extra information in a TDML file that has not yet been defined in the standard without breaking the ability of other tools to read the standard TDML information.

TDML is simple to parse because all the information is hierarchically organized and contained between begin and end tags. This structuring of the data and the fact that TDML is a text-based format makes it easy to write scripts to convert waveform data to and from TDML.

Several free XML parsers (with source code) are available, easing the incorporation of support for TDML by EDA vendors and test equipment manufacturers. One benefit of using an XML-based parser is the ability to "validate" TDML files, guaranteeing that a TDML file contains data that meets TDML file format requirements for structure and content. This ability dramatically reduces the chance for the inadvertent creation of incompatible versions of TDML files as a result of a misreading of the TDML specification standard and provides a "confidence check" for TDML users.

To make TDML a truly open standard, it supports a method for tools to ignore yet preserve information that they do not understand. That means that a waveform translator can write TDML files that include voltage threshold levels for generating SPICE files and VHDL and Verilog signal typing information for generating HDL test stimulus. Yet a timing diagram editor can still read the TDML file and ignore the information that it does not understand. Using the same methods, programs can store application-specific information in their TDML files without having to worry about breaking other tools that need to read the basic TDML information contained in the files.

TDML code consists of a number of nested elements. The main element is called timing.diagram. It contains all of the information needed to reconstruct the diagram, arranged into the following sub-elements:

This section contains the name and direction of signals.

Text annotations are stored in this section.

This section describes a viewable section of the diagram of potential interest to a user.

This section contains a list of name-value pairs to store aliases (macros) in.

XML is a mark-up language that provides a standardized framework with which to define a set of document tags. XML documents look similar to other mark-up language documents like HTML. The following sections provide a brief overview of XML syntax. For more in-depth information about XML and XML DTDs, see http://www.oasis-open.org/cover.

Each object in the TDML code is contained within matching tags. For example, the code excerpt below is one of the first code blocks in a TDML file. The block begins with a <tdml.admin.info> tag and ends with a </tdml.admin.info> tag. The information between these two tags describes the type of program used to generate the TDML file. If a TDML reader does not understand a particular tag, it can ignore the information and continue to read the rest of the file.

The TDML language is formally defined by an XML Document Type Definition (DTD). The DTD is contained in several files: xml-pcistdml.dtd is the main file, referenced in the DOCTYPE element at the beginning of each TDML file; xml-tdmlbase.ent contains the majority of the TDML language definitions; the rest of the definitions are contained in PCIS DTD files. There are several other .ent files that are used for character lookup tables and other minor tasks.

The complete list of files is as follows:

xml-pcistdml.dtd , iso-amsa.ent, iso-amsb.ent, iso-amsc.ent, iso-amsn.ent, iso-amso.ent, iso-amsr.ent, iso-dia.ent, iso-grk3.ent, iso-lat1.ent, iso-lat2.ent, iso-num.ent, iso-pub.ent, iso-tech.ent, xml-exchange.ent, xml-padmin.ent, xml-pcharset.ent, xml-pinnbase.ent, xml-psources.ent, xml-tdmlbase.ent.

The catalog file is a file that contains links between formal public identifiers and the associated DTD files. Public identifiers are "logical names" that can be converted to physical storage locations where the DTD files are stored.

An XML Document Type Definition (DTD) is a set of rules that can be used to ensure that all documents within a class governed by that DTD are constructed in the same way. DTDs range from completely enforcing (where a specific and highly detailed set of rules is enforced throughout the document structure) to enabling (where as many existing documents as possible are legal under the rules of the DTD). The TDML DTD is an enabling DTD. Each relevant information element has been named and given an identifier, so that different companies can name information of the same type consistently. However very little information is actually required to be identified.

The following sub-sections describe the three main types of objects contained in the TDML DTD: elements, attributes, and entities.

Elements in XML are similar to classes in C++. They can contain both sub-elements and attributes (member variables). They are the core of XML, and define the TDML language. They are found in the .dtd and .ent files mentioned above, and allow XML parsers to understand what is a proper TDML grammar. In the example below, the timing.diagram element contains several sub-elements. Regular expressions are used to define how an element is composed of sub-elements. An asterisk following a sub-element means that the element can appear zero or more times in that place, a plus sign indicates one or more times, and a question mark indicates it may appear once or not at all. Commas separate consecutive sub-elements and parentheses denote a grouping of sub-elements.

Attributes describe properties of an element. An Attribute list, or ATTLIST as it appears in the code, defines the attributes that may be attached to the element. Attributes appear inside of the element's start tag. An attribute defined as #IMPLIED is not required in a TDML document, while a #REQUIRED attribute must be present and have a value. It is up to the application parsing a TDML document to determine the default value of an #IMPLIED attribute.

Entities are the XML equivalent of macros. They are replaced by their value throughout the .dtd file. In the example below, the entity show.atts is replaced with the string in quotes, effectively adding those attributes to the timing.diagram element where it is instantiated.

The following sections contain examples of some of the basic elements of TDML documents, along with descriptions of how the elements are related.

Figure 1 represents a timing diagram consisting of one signal with a waveform. Explanations for each section are shown:

1. The first element in a TDML file is the DOCTYPE object, which identifies the document as a TDML file. This is to reference the document to the xml-pcistdml.dtd file, which in turn references the various *.ent files. It also identifies the version number of TDML used. This document, for example, is a TDML 1.0 document.
2. The timing.diagram section contains all of the code necessary to describe the timing diagram. The attributes contained in the timing.diagram begin tag set properties of the entire timing diagram. For example, the attribute default.time.units sets the default time units for time values in the timing diagram.
3. The tdml.admin.info section contains information about the tool used to generate the TDML code. In this case a tool called Timing Diagram Tool was used to generate the TDML code. This information can be useful if a tools uses user.defined elements to store additional information not yet included in the TDML standard (for example, VHDL or Verilog typing information associated with a signal).
4. The sources section contains information about the type of connections represented by the signals in the timing diagram. The conn.source section contains a number of connection objects, each defining the direction and name of a signal. The conn.name element is the formal location of the signal name. The id of the connection is referenced in the signal object. The conn.type attribute stores the direction of the associated signal. Possible values for conn.type are: "O" (output), "I" (input), and "IO" (inout).
5. The signal section contains two subsections: conn.ptr and waveform. The conn.ptr element references the connection in the sources section where the signal name and direction are stored. Also within the conn.ptr element is the name of the signal (placed there to make the file more easily read by humans). The formal location of the signal name is within the conn.name element (see 4.)
6. The waveform section contains an id that allows it to be referenced by other elements in the file. The waveform consists of signal transitions or "edges" that represent a change of state. An edge (e) contains the state (s) of the signal after a transition, and the earliest time and latest time that the transition can occur (te, tl). Edges can contain an optional id attribute that enables an edge to be referenced by other objects in the TDML file. Edges can also be specified as being driven, which means that the signal waveform containing the transition is acting as an output at the given transition time (the driven flag is only meaningful on IO signals which may drive output data or receive input data at any given time).
7. The view.group section describes the visible area of the diagram in terms of signals and time. Signals are referenced by their ids.

Clocks are a special form of repetitive signal that can be described using period, duty cycle, offset, and edge uncertainty values.

1. The clock="1" statement in the signal section defines this signal as a clock.
2. The clock.info element describes the clock attributes. It is not used in signals that are not clocks. For simplicity, its member elements are displayed here as simple numbers, though it is better to express the values as tdml.expressions. The period is the period of the clock. The duty.cycle expresses the percentage of the period that the clock spends in its initial state. The time.offset is the time that the clock starts to oscillate. The amount of uncertainty on clock edges is determined by uncertainty.falling, uncertainty.rising, jitter.falling, and jitter.rising.
3. The waveform section is included so that the TDML diagram can be displayed without having to calculate the clock waveform. Programs will either calculate the clock waveform using the attributes or just draw the waveform using the data in the waveform section. It is also necessary when relationships are attached to the edges of the clock.

The diagram in figure 3 adds a delay parameter to the timing diagram of the previous section. The code fragment in figure 3 contains only the sections that are relevant to the discussion of the parameter.

1. The signal definition is similar to the code in the previous section, except that the two signal edges involved with the delay now have id values which allow then to be referenced by the parameter.
2. The edge.relationships section contains the parameters that define an edge relationship. Within the relationship tag, the example parameter is defined as a "delay". Other possible values are "setup", "hold", "constraint", "measure", "sample", "break", "end", "wait", "guarantee", and "marker." In a two.edge relationship, the source (source.e) and target (target.e) edges are referenced to the edge ids defined in the signal element. In a one.edge relationship (i.e. a sample or a marker), there can be a target.signal.ptr, which shows the signal the relationship is associated. An e.ptr will be referenced if the relationship is attached to an edge.
3. The cc.list section contains the name, min, and max values of the delay. The name is stored in the parm.symbol element, while the min and max are stored in tdml.value elements. The value.type element indicates if a tdml.value contains a min or max value. The values are stored in a tdml.expression structure. The expression.handling attribute in the tdml.expression element denotes which program's format is being used in the expression field. Programs that do not read this format may read the last calculated value of the expression from the evaluated.to element.

Figure 3: Delay Parameter



 

<sources>

<conn.source id="X4">

<connection conn.type="O" id="ID1">

<conn.name id="X5">SIG0</conn.name>

</connection>

</conn.source>

</sources>

<signal id="ID2" show="1" show.grid="0">

<conn.ptr conn.id="ID1">SIG0</conn.ptr>

<waveform id="ID3" locked="0">

<e id="ID3V" driven="1" s="1" te="0" tl="0"></e>

<e id="ID4" driven="1" s="0" te="55000" tl="55000"></e>

<e id="ID5" driven="1" s="1" te="65000" tl="75000"></e>

<e driven="1" s="0" te="140000" tl="140000"></e>

<e te="190000" tl="190000"></e>

</waveform>

</signal>

<edge.relationships>

<relationship type="delay" tdml.cc.ptr="ID6" show="1">

<two.edge source.e="ID4" target.e="ID5"></two.edge>

<relationship.label label.type="default">%n v=%mv,%Mv f=%mf,%Mf m=%mm,%Mm d=%md,%Md %c </relationship.label>

</relationship>

</edge.relationships>

<cc.list>

<title id="X6">Parameter Data Table</title>

<tdml.cc id="ID6" static="1" show="1">

<parm id="X7">

<parm.symbol id="X8">D0</parm.symbol>

</parm>

<tdml.value id="X9" value.type="MIN">

<tdml.expression expression.handling="SynaptiCAD">

<expression id="X10">10</expression>

<evaluated.to>10000</evaluated.to>

</tdml.expression>

</tdml.value>

<tdml.value value.type="MAX">

<tdml.expression expression.handling="SynaptiCAD">

<expression id="X11">20</expression>

<evaluated.to>20000</evaluated.to>

</tdml.expression>

</tdml.value>

</tdml.cc>

</cc.list>

 

4.4 Marker Elements

Markers are vertical lines in the timing diagram that can compress a section of a timing diagram. The two diagrams show the display of a time marker with and without compression. In the first diagram, one of the D0 delays is not visible because the marker is compressing 20ns of time. The second timing diagram shows a time marker without compression. The TDML code for the marker looks a lot like the code for the delay parameter. Here are a few things to notice:

1. The edge relationships element defines the marker and assigns an id value for external referencing. In this case, a user defined type defines a curved style for the marker (another tool might display the marker as a single vertical line).
2. The cc list section defines the properties of the marker such as the marker text and beginning and ending times. A plain marker has only a min value, denoting the time position it occupies.

Figure 4: Markers with and without time compression



 



<edge.relationships>

<relationship type="marker" tdml.cc.ptr="ID21">

<one.edge></one.edge>

<user.defined><key>DefaultType</key><user.value>Documentation</user.value></user.defined>

<user.defined><key>Type</key><user.value>Timebreak(Curved)</user.value></user.defined>

</relationship>

... //more code

</edge.relationships>

<cc.list>

... //more code

<tdml.cc id="ID21" static="0">

<parm id="X24">

<parm.symbol id="X25">MARK0</parm.symbol>

</parm>

<tdml.value value.type="MIN">

<tdml.expression expression.handling="SynaptiCAD">

<expression id="X26">70</expression>

<evaluated.to>70000.0</evaluated.to>

</tdml.expression>

</tdml.value>

<tdml.value value.type="MAX">

<tdml.expression expression.handling="SynaptiCAD">

<expression id="X27">90</expression>

<evaluated.to>90000.0</evaluated.to>

</tdml.expression>

</tdml.value>

</tdml.cc>

</cc.list>

 

4.5 Text Annotation

TDML Annotations are text objects that can be placed anywhere in the waveform portion of a timing diagram. This example shows the different attachments and different styles of annotations available in TDML.

1. The y.offset and the signal.ptr determine the vertical placement of an annotation. Vertical placement of text annotations is stored in units of slots. A slot is the height of a single signal. The y.offset is the number of slot positions, going downward, from the top of the signal specified by the signal.ptr. If there is no signal.ptr attribute then y.offset is the number of slots from the top of the diagram.
2. Annotations can be attached to a time, a signal, a waveform segment, or an edge. The x.offset value changes depending on the type of attachment. In figure 5, each of the three annotations is attached to the diagram in a different way:
3. The annotation "TDML Annotations (Text Objects)" is attached to the time stored in x.offset. The time unit of x.offset is set by the default.time.units attribute of the diagram (picoseconds in this example).
4. The annotation "support superscripts and subscripts" has a segment.centered attribute to indicate that the annotation is attached and centered within a segment of the waveform. The e.ptr specifies the left edge of the segment. Since centering an annotation inside a segment is dependent on the zoom level and font size, the TDML reader determines how to center the text within the segment. x.offset is set equal to zero and can be ignored.
5. The annotation "for realistic databook names like tdHL" is attached to an edge indicated by the e.ptr attribute. The x.offset is the number of default.time.units from the edge to the beginning of the annotation.
6. Annotations support Bold and Italic highlights using the highlight.pref="bold" and highlight.pref="italic" attributes. Annotations support super and subscript using the <super> and <sub> tags. The super and subscript elements where implement by using SGML elements previously defined by PCIS.

TDML includes the capability to add extra information to objects in the timing diagram beyond that currently defined in the standard. This is achieved by using user.defined elements. This mechanism enables timing diagram tools to store additional information which is either unique to the tool or too new to have yet been made part of the standard. The user.defined elements can be entered as sub-elements of timing.diagram, signals, relationship, and tdml.cc. For example, a tool might attach a VhdlType and a VerilogType name-value pair to each signal in a diagram using user-defined elements so that the VHDL and Verilog signal type information is saved in the TDML file. As long as a tool reads and writes user-defined elements, the non-standard information will be preserved even by tools that do not make use of the information (except in the case where two tools use a name-value pair with the same name but different meanings).

While user.defined elements can be used as a short term solution for storing information which has not been assigned tags in the standard, most information of this type should eventually be migrated into the standard and assigned new tags.

To contact the TDML working group about suggestions for additions or changes to future revisions of the TDML standard, visit http://www.si2.org/.

A list of publicly available SGML and XML parsers can be found at http://www.oasis-open.org/cover/publicSW.html.

A list of commercially available parsers can be found at http://www.infotek.no/sgmltool/guide.htm.

SP is an SGML/XML parser written by James Clark. It performs many of the tasks of parsing the TDML file automatically, such as checking it against the specification in the .dtd and .ent files, and tokenizing files that are correct TDML. Information on SP can be found at http://www.jclark.com.