In a semiconductor company, the ASIC engineers design the hardware, and the hardware specification is distributed to other teams for hardware validation, embedded software development, and data-sheet documentation. Unfortunately, no standardized tools to document and distribute the specification exist. ASIC engineers often use common tools, such as Microsoft's Word or Excel, or even a plain text editor; these “tools” have many shortcomings when used to create a hardware specification.
First, these tools cannot easily convey the structure of a hardware specification. The hardware design of a chip typically has a tree-like hierarchy–the chip has several logical blocks, each block contains many registers, and each register has multiple bitfields, as shown in Figure 1 .
Click on image to enlarge.
In a Word document, to show the hierarchical relationship between data, a significant amount of formatting using headings, tables, fonts, and highlights is needed. Formatting this type of content is tedious and repetitive.
The main problem, however, is the difficulty in extracting data from the specification created from these common tools. Typically the different teams that use the specification are only interested in a subset of the data: validation wants the register power-on value and read/write accessibility data, the software team is interested in register addresses and bitfield locations, while the field application team is interested only in registers exposed to external customers. It's difficult for a scripting language or tools to parse and extract data from a Word or Excel document, so the extraction is often done manually. The manual extraction is error-prone and must be done each time the hardware design or specification changes and is, therefore, often not done.
This lack of automatic propagation of specification updates creates errors and inefficiency in the product development process. Every embedded software engineer has had the frustrating experience of lots of time spent on debugging a mysterious issue only to discover a bitfield was incorrectly programmed due to a typo or an outdated hardware specification document.
Other shortcomings of these common tools are that the resulting documents become:
- Platform-dependent, making them inconvenient to access across different platforms;
- Binary, not diff-able or merge-able, and difficult for revision control when multiple engineers are editing the specification;
- Not scalable–when the design or specification grows in size, a Word document of hundreds of pages is slow to load and browse.
An ideal hardware specification tool provides:
- Formatting that easily represents the hierarchical structure of the hardware specification data.
- A single source of specification and automatic data extraction and propagation.
- Platform independence.
- Diff-ability, merge-ability, and revision control.
- Ease in loading and browsing as the specification grows in size.
As proposed by others in the past, XML (Extensible Markup Language), the de facto format for storing and exchanging data in web and software applications, meets all the criteria.1 XML allows tree-like structural representation of the data that matches the hardware specification structure. The XML files are text files, accessible across platforms and can be easily revision-controlled. In addition, two XML-related technologies, Schema and XSLT, bring the benefits of data error-checking and automatic data extraction and presentation. The XML technologies are well integrated with web and Internet, which facilitate the distribution of the XML specification data.
Due to the popularity of XML, many commercial XML tools are available. For example, FrameMaker has comprehensive features for authoring and publishing XML documents.
In this article, I describe the XML-based hardware specification flow, show how it can improve the development process, and present an easy-to-set-up implementation of the flow using open-source tools.
XML: Since its creation in 1998, XML has become the de facto format for storing, exchanging, and processing data in web and software applications. It stores data in plain text, and uses tags (labels enclosed in < > ) to structure and annotate the data. An XML document for a hardware specification might look like the code in Listing 1 .
Click on image to enlarge.
Like HTML, XML is a markup language, but unlike HTML, which defines a web page, XML stores data. XML lets users define customized tags and the document structure that best describe the user data. The tags have self-explanatory names such as
The element content may be empty or contain literal data or child elements. An element can be further qualified by attributes, such as
With customizable tags and document structure, XML is both simple and versatile to define any arbitrary set of data.
Schema: An XML document is valid if all tags are closed with end-tags, but it's also important that the data in the document be valid. This is where a schema can help. The schema accompanies the XML document and contains the rules and restrictions on the data in the XML document. A schema defines:
- The elements that can appear in a document.
- The attributes that can appear in an element.
- Which elements are valid child elements.
- The order of child elements.
- The number of child elements.
- Whether a child element/attribute is optional or mandatory.
- Whether an element can be empty.
- The data types for elements and attributes.
The default and allowed values for elements and attributes.
A schema file is a text file and is written in XML or a XML-like language. A schema file can be configured to accompany one or multiple XML documents. Many XML editors have plug-ins that perform run-time error-checking against the schema as the XML document is being edited. Schema and the run-time error check are tremendously useful in maintaining a valid data repository in XML.
XSLT: XML is not optimized for displaying data. You can see this by opening an XML document in a web browser. Even though the browsers can collapse and expand the XML tree, it's difficult to browse and search through hundreds or thousands of XML elements.
XSLT (Extensible Stylesheet Language Transformation) is a transformation language for processing XML. It consists of two parts–stylesheets and the XSLT processor. The XSLT stylesheet specifies how to process the XML data and the format in which to present the processed data. The XSLT processor takes the XML document and a stylesheet as inputs and generates an output file in the format specified by the stylesheet.
The XSLT language traverses the XML tree and processes each node (element) of the tree according to a template. Listing 2 shows an example stylesheet template that transforms each
Click on image to enlarge.
The output of this transformation is:
#define LOGIC_BLOCK_A_ADDR (0x1000)#define LOGIC_BLOCK_B_ADDR (0x2000)#define LOGIC_BLOCK_C_ADDR (0x3000)
The stylesheet is written in the XML format. The stylesheets can specify for a wide range of output formats: text, HTML, Word, PDF, or XML containing a filtered set of the original data.
XML is for data storage, XSLT for data presentation: they separate content from presentation. This allows the same data source to generate a variety of outputs for different purposes.
Most web browsers (IE, Firefox) have a built-in XSLT processor. If a line specifying the stylesheet is added at the beginning of the XML file, for example:
. . .
then when the XML file is opened in the browser, the browser transforms the data and displays the XSLT stylesheet output.
In summary, XML, schema, and XSLT are the three components of the XML-based hardware specification flow. Schema defines the type and structure of the data, XML stores the data, and XSLT transforms the data for presentation. Figure 2 is a diagram of the flow.
Click on image to enlarge.
The specification flow
There are several stages in the XML-based hardware specification flow and multiple roles to implement the flow.
The schema file and XSLT stylesheets are dependent only on the specification structure, not on the actual specification data; therefore they can be created in the early stage of hardware design, when the overall IC hierarchy, such as the main logic blocks, the types of registers, and the set of attributes for the registers and bitfields, are decided. When the hardware hierarchy is fixed, creating the schema and stylesheets is a one-time effort, and only small modifications and tweaks are required later on. Modifications are needed when the hardware design changes or new types of data are added to the specification. A hardware change may be a new logic block added to the design. A specification change may be adding an optional child element
The users of schema and the authors of the XML are the hardware engineers–they continuously add or modify the XML specification data as they design the hardware. The key benefit of schema is reaped here–the responsibility of error and validity checking of the data is distributed to the individual hardware engineer creating the data. If the data is valid according to the schema file, the XSLT generation of different output files is guaranteed to work. Generating an output file from the XML data is akin to the software build process, where an executable is compiled from the source code files. Schema and the distributed error-checking eliminate the situation where the “build” engineer has to chase down the developers whose code breaks the “build.”
The output files can be generated via XSLT processor in two ways: statically generated and stored for each revision of the XML data file, or dynamically rendered by a web server on-demand. The XSLT processor is available as a utility in major operating systems or a functionality of web-server scripts such as PHP. The web PHP script can retrieve the XML file and stylesheet from the revision-control repository, transform the data, and stream the output as a web page to the end user. The advantage of the dynamic rendering is that the entire flow only has a single source of specification data, which eliminates any discrepancy due to duplicate data copies.
The end users of the output files are the different teams that consume the specification data in different formats for different purposes. The RTL header and C header files may contain register defines and macros that make writing register-related RTL and C code more convenient for hardware and software engineers. The HTML file allows the specification to be accessible on any computer connected to the server via the company Intranet and easily browse-able with the HTML hyperlinks. The Word or PDF file can contain only a filtered set of data that can be released to external customers.
Benefits: Using XML technologies increases the accuracy and availability of the hardware specification data. The single-data-source model ensures consistency between the different the data sets published to different teams. For example, when hardware engineers use the RTL header files generated from the single specification source in developing the IC design code, it ensures the actual design indeed matches the specification used by the rest of the company. Combining XML and XSLT with web-server technology, allows the latest specification to be accessible anywhere over the network, suitable for collaboration between different teams located in different geographical areas, or using a variety of platforms.
The flow also automates the propagation of data. The teams subscribing to a specification can be notified via e-mails of any changes in the XML file checked into the revision control and can independently generate or retrieve the output file in the desired format. The revisions of the XML file can be compared to examine the changes between revisions and whether they relevant to the team.
Storing the specification data in XML file also has the advantage of being extensible to future design changes. If the design or the hardware hierarchy changes, using XSLT the data tree in XML can be mapped or transformed to a different tree structure, and with relevant data preserved and old data removed.
Implementing the flow
Given the widespread use of XML, free and open-source tools are available to implement the flow I've described.
RNG schema: RELAX NG (RNG) is a simple schema language for XML. A popular form of RNG is in the compact non-XML syntax.2 Listing 3 illustrates the syntax.
Click on image to enlarge.
The RNG language is easy to understand. The XML element
The data types include the W3C predefined data types3 (xsd:token, xsd:unsignedInt) and custom-defined enumerations (token “RO” | token “WO” | token “RW” | token “NA”). Constraints are applied to the data types: the “name” attribute of
GNU Emacs nXML-mode: The GNU Emacs editor has an nXML-mode package for editing XML files.4 The package works with schemas written in the RNG schema language.
The package is freely downloadable from the web and works on Windows and Unix/Linux systems. Once installed, Emacs can be configured to automatically load the mode whenever a XML document (.xml), schema (.rnc), or XSLT stylesheet (.xsl) is opened.
A schema locating file (written in XML) should be created in the same directory as the XML documents to associate the schema files with the XML files. See Listing 4 .
Click on image to enlarge.
When a XML document is opened for editing in Emacs, nXML-mode finds the associating schema file. Emacs constantly validates the document against the schema in the background as the document is being edited. The Emacs status bar also shows the schema validation result in real-time. Whenever a schema violation happens, the location of the violation in the document is highlighted with a red underline.
The nXML-mode also has special key-stroke commands convenient for editing and validating XML documents. For example:
- C-enter or M-tab: context-sensitive auto completion.
- C-c C-n : move the cursor to the next location where the document is invalid according to schema
- C-c C-i or C-c C-b : insert start and end C-c C-f : insert the end tag.
XSLT processor: The output files can be generated statically using XSLT processors. The Windows and Unix/Linux systems all have XSLT processor utility. For Windows XP, the command line transformation utility (msxsl.exe) is downloadable from the web, its usage is as follows:
msxsl my_register.xml stylesheethtml.xsl -o
The output files can be generated for each revision of the XML file and also checked into revision control along with the XML file.
A better approach is to generate output files dynamically and on-demand from the XML file to achieve the single-source data distribution. The popular web-server scripting language PHP has library for XSLT transformation, shown in Listing 5 .5
Click on image to enlarge.
The $path_xml and $path_style are hard-coded in the example, but they can be selected as user inputs. The XML, schema, and stylesheet files all can be retrieved from the revision control repository.
Go with the flow
The XML-based hardware specification flow improves efficiency in the hardware or hardware-related product development by increasing the accuracy and availability of the specification and automating the propagation of specification updates throughout the company.
In the implementation of the flow suggested in this article, the amount of training required for hardware engineers to use XML is relatively small. XML is easy and intuitive to learn. The Emacs editor may be unfamiliar; however, many hardware engineers being accustomed to Unix/Linux environment are already proficient at it. Expertise is only required in the schema creation and the stylesheet design, which can be owned by one or two engineers. For dynamic rendering of the specification, the web server script is another one-engineer effort, or can be done by the IT department.
Setting up the XML-based specification flow is a one-time effort that can bring lasting benefits to an ASIC/SoC company's product development process.
Karen H. Wang is a senior embedded software engineer at SiBEAM, Inc. The XML-based hardware specification system she developed has been in use at SiBEAM for the last three years. (email@example.com).
1. L Grassens, S. Ranganathan, D. Fechser, “XML provides language for hardware specification,” EETimes.com, 04/26/2002.
2. OASIS, “RELAX NG Tutorial,” www.relaxng.org/tutorial-20011203.html
3. W3C, XML Schema Part 2: Datatypes Second Edition www.w3.org/TR/xmlschema-2/
4. James Clark.”XML document authoring with emacs nxml-mode” http://infohost.nmt.edu/tcc/help/pubs/nxml/
5. PHP Manual, http://php.net/manual/en/index.php