SpiritEd: A Register Specification System integrating IP-XACT and Adobe FrameMaker

Jan Langer, Vasco Jerinic & Ulrich Heinkel, Chemnitz University of Technology, Germany
Frank Dresig, AMD Saxony LLC and Co. KG, Germany

Abstract

Current specification flows often use standard text processors to capture formal register and memory map information of hardware designs along with other less formal types of specification text. Extracting derived models or documents such as RTL code or customer documentation from this unstructured representation is a complex and error-prone task, that often is accomplished by semi-automatic proprietary scripting solutions.

In opposition to that, there exist register specification formats like IP-XACT^TM and SystemRDL^TM providing structured and unambiguous languages to store register data and enabling the generation of derived documents.

In this paper, we present a FrameMaker^TMbased environment that allows the entry of register data together with the remaining specification. Only the registers are captured by a specialized graphical user interface and stored in a XML database using IPXACT. Using the proposed flow, specification documents are handled as regular FrameMaker files, that automatically synchronize with the register database.

Additionally, a migration framework has been set up allowing fast and highly customizable extraction of register information from existing FrameMaker specification documents.

I. INTRODUCTION

In current System-on-Chip specification flows, a system specification is created by writing lengthy documents containing up to several thousands of pages using standard text processors such as FrameMaker or Microsoft WordTM . This is especially easy for system architects, since traditional text processing knowledge can be used to enter and maintain the specification and no special software training is required. Furthermore, it is common use to appoint special text processing staff to do the formatting and layout to achieve an easy to read and optically clean specification document.

However, there are several problems associated with this approach. First of all, there will be no explicit structural information assigned to the different elements of a specification. Often that structural information is only implicitly known to the writer and reader of the document. For example, it might be a common convention that register descriptions are represented as a subsection set in a specific layout. The heading of such a subsection contains the name of the register and the first table inside that section represents a list of all register slices.

For human readers of the document, it is often obvious which structural information is carried by a specific textual element. However, automatic tools have great difficulty to extract certain data and their semantics from a textual specification. It is frequently required to use the traditional textual specification data in other parts of the design flow. For example, the actual RTL hardware description code needs the address values of all registers and their access modes (read-only, read/write, ...). The embedded software components also need this information to define a mapping from a register name to the corresponding memory address.

However, in most design flows this data transfer from the specification into other parts of the design is done manually by the design or verification engineer, or semi-automatically using various kinds of extraction scripts. This process is very errorprone and leads to heavy consistency problems, i.e. there is no guarantee that manual changes in any documents are distributed to other documents or models. Furthermore, little discrepancies in the document’s layout can prevent semi-automatical extraction methods from working properly. Therefore, a specification environment capturing structural information together with the actual data is highly desireable.

Another problem is the usability viewpoint. Most specification engineers do not want a solution which only allows for a structured entry of predefined data. Todays specifications are very complex and many parts of it just do not fit into predefined fields of a given structure. Therefore, it is necessary to limit the use of pre-defined structures in specification documents to those sections where it is actually desired.

In this work, we present a methodology for an environment for developing a specification in standard unstructured FrameMaker which allows both, structured entry of register specifications and unstructured textual entry of the remaining document. This is achieved by using FrameMaker’s socalled Client Text Insets, which present a means to insert locked chunks of text and to connect them to an external application for register entry. This approach makes use of a XML database containing the only valid instance of the register data. A multitude of different generation scenarios is possible, e.g. for creating RTL code for address maps.

Fig. 1. Block diagram of the register specification environment

The paper is structured as follows. Section II presents some related work. In Section III the individual parts of our proposed system are described in detail. Section IV shows how existing specification documents can be migrated to the new flow. Some implementation notes are given in Section V. We conclude with a summary and remarks about future work.

II. RELATED WORK

In SPIRIT^TM , there exists an open, mainly industry-driven initiative, which develops a standard format for all kinds of data such as debugging information, hardware constraints and register descriptions [1], [2]. The consortium has proposed an XML Schema Definition called IP-XACT which can be used to store the register and memory map data as needed in our tool. Of course, IP-XACT can not accomodate all needs which are possibly needed in any commercial specification flow, i.e. there will be custom access modes, special memory spaces or hardware characteristics, which cannot be a priori incorporated in a standard. Therefore, IP-XACT has been developed to be extensible by means of so-called vendor-extension tags.

As the SPIRIT consortium consists of some major EDA companies, there is developing tool support for the data format. For example, the tool Denali Blueprint^TM supports IP-XACT to read register descriptions [3]. It can generate all sorts of documents and source codes and lately even provides a graphical interface for register entry. Unfortunately, it lacks integration into existing specification tools like FrameMaker making it unfeasible for use in the given environment.

Recently, Denali has donated the specification of its open SystemRDL language to the SPIRIT consortium [4]. In contrast to the current IP-XACT definition, SystemRDL concentrates on register specifications only. It provides many constructs that have already a corresponding counterpart in IP-XACT, such as registers, fields and complete address maps. Additionally, SystemRDL has a much wider range of constructs to model functional interdependencies between registers, enabling the generation of more detailed and complex models of registers. On the other hand, due to its rich language, the processing overhead for SystemRDL descriptions is higher than for the common XML format.

Starting in version 7, Adobe integrated its structured authoring tool FrameMaker+SGML into the regular FrameMaker product [5], [6]. In structured mode, FrameMaker assigns semantic information to each text element. The resulting document is similar to an XML file annotated with formatting and layout directives. However, the resulting FrameMaker file is not an XML file. A so-called structured application must define import and export rules to interact with the desired XML files. The two modes of FrameMaker can not be mixed within a single document. Hence, it will not be possible to write parts of a specification, e.g. the register descriptions, as structured elements and the remaining parts as conventional unstructured text. Furthermore, the effort of learning how to effectively use Structured FrameMaker is very high, so taking all those facts into account, we decided not to use it for our register specification environment.

III. CONCEPT

In order to realize a specification flow for register descriptions, a concept has been developed which is depicted in Figure 1. The specification system consists of three major parts. First, there is a XML database for all the structured data of the system’s registers.

Second, there is a graphical user interface (GUI) to view and edit the register data inside database. It is designed to be used not only within the FrameMaker based specification flow but as a stand-alone tool without FrameMaker as well.

The last component of the system is a FrameMaker API Client. This is a plugin-like FrameMaker extension which is created with the FrameMaker Development Kit (FDK) [7]. This client enables FrameMaker to create locked Client Text Insets for each register and provides hooks to edit or update the register. The Inset itself actually only contains a reference to the database and the identifier of the register it holds

All editing actions of the Inset are forwarded to the GUI. After the editing is done, the GUI saves the data to the database, so the FrameMaker Client can read it back and generate the new visual appearance of the register in the FrameMaker document. In addition to these three parts, the system must be able to generate all required types of documents from its stored register information. Therefore, an interface is provided which enables users to write generation engines for specific tasks.

Relying on the standardized IP-XACT format, all parts of the system are interchangeable and integratable with future tools. For example, a more advanced register editing tool may become available in the future which directly manipulates IPXACT XML. Then, our existing specification flow can be easily adapted to use that new tool.

Ultimately, the question arises why the integration of FrameMaker is such a vital part of the system. To give an answer, one has to consider that FrameMaker has a large group of users within the community of system architects. It is a very mature and stable tool and it can easily handle the huge sizes of todays specification documents. Therefore, despite the lack of structured entry of information, many specification engineers are used to FrameMaker and appreciate its expressive flexibility and stability and are not willing to switch to another unproven tool of probably limited flexibility with respect to layout, formatting, graphics and other features available in modern text processors.

A. XML Database

There are several options for the database to be used in our specification flow. After all, a plain XML text file is used for two reasons. First, the possibility to easily move the complete database together with the FrameMaker document to another site was very important for our industrial partner. The need to set up any database server or other specialized software would only compromise user acceptance. Additionally, a plain text file can be more easily accessed for manual modifications. Although, such modifications are not recommended at all to maintain consistency, it may sometimes be necessary in practice and required by users.

However, there are several drawbacks of the single file concept. For example, it will be impossible to realize a distributed specification environment where multiple GUI and FrameMaker API Clients respectively access a common specification database. Furthermore, when using a file instead of a database application, the required validation code, such as XML Schema validation or other custom consistency checks, must be implemented outside the database, i.e. as part of the GUI or FrameMaker Client application.

On the other hand, we do not want users to handle all the tedious XML processing tasks, such as parsing the file, doing XML Schema validation, checking the data for consistency, and walking the general XML tree in search for specific information. Therefore, an application programming interface (API) has been developed, which hides all those tasks from the user. Hence, with the help of this API, it becomes possible to transparently iterate over all registers in a file and print their name, size and slices writing only a few lines of code.

Algorithm 1 IP-XACT XML fragment of a register

<spirit:register>
   <spirit:name>RegisterA</spirit:name>
   <spirit:addressOffset>
      0x17
   </spirit:addressOffset>
   <spirit:size>8</spirit:size>
   <spirit:field>
      <spirit:name>SliceA</spirit:name>
      <spirit:bitOffset>0</spirit:bitOffset>
      <spirit:bitWidth>2</spirit:bitWidth>
      <spirit:access>read-only</spirit:access>
   </spirit:field>
   <spirit:field>
      <spirit:name>SliceB</spirit:name>
      <spirit:bitOffset>5</spirit:bitOffset>
      <spirit:bitWidth>3</spirit:bitWidth>
      <spirit:access>read-write</spirit:access>
   </spirit:field>
   <spirit:vendorExtensions>
      <spiritAMD:swMode>
         read-clear
      </spiritAMD:swMode>
   </spirit:vendorExtensions>
</spirit:register>

We chose the IP-XACT format as the corresponding XML schema because its gaining acceptance in industry and tools. The IP-XACT XML Schema Definition (XSD) can be used to do basic validation of the database [8]. Algorithm 1 shows a small fragment of a register description using IP-XACT. In the code, the XML namespace spirit is used to indicate the IPXACT Schema.

There exists a corresponding element in IP-XACT for nearly all information items of a register. However, our industrial use case needed some additional elements which are not considered in IP-XACT. For such cases, IP-XACT provides an extension mechanism. The specific XML tag <spirit:vendorExtensions> is available at certain levels of the IP-XACT XSD. All additional data can be put inside this tag and it is redefined to force the exact structure of the additional elements. A dedicated namespace spiritAMD with a corresponding site-specific XML Schema definition allows the joint validation of the IP-XACT and extension elements.

B. Generation Scenarios

In order to efficiently use the structured specification data in the design flow, many different generation scenarios are possible. Generally, the register information is needed at all levels of design implementation and verification. Parts of the documentation, RTL code and C language header files for embedded software development can be created, as well as code to stimulate and verify all registers.

One of our use cases is the generation of corresponding RTL code for registers as seen in Algorithm 2. Using our XML Access API, this code has been generated with a small script which mainly consists of the template code for each desired type of register (read-write, hardwired, interupt, etc.). Another use case is the generation of SystemC register verification code which eventually stimulates each read-write register by writing values to it, reading them back and comparing the result. Other types of registers can be validated accordingly.

Algorithm 2 Verilog fragment of a register slice

always @(posedge clock or negedge reset_l)
   if ( ˜reset_l )
      RegisterA_SliceB <= 3’h0;
   else
      if (wstrobe & (addr == 10’h17))
      RegisterA_SliceB <=
     RegisterA_SliceB & ˜mask[7:5] |
         wdata[7:5] & mask[7:5];

Furthermore, each slice of a register can be verified individually.

A potential problem, which can be avoided when using an unique XML database is inconsistency. For example, a change in the specification automatically triggers a change in the database. And all files generated from the database can be automatically regenerated. That can be ensured by a Makefile describing the dependency between database and generated file. In contrast to that, manually changing each dependent file is very error-prone.

C. FrameMaker Integration

The FrameMaker Development Kit has been used to write a FrameMaker extension (API client) which enables the text processor to support special Client Text Insets for individual registers. Client Text Insets are one possible way a FDK API client can be used to extend FrameMaker in a user-defined fashion. Others are special document reports or import/export filters for custom file formats. They can interact with the user, either by using commands in FrameMaker’s pull-down menus or by a number of notifications FrameMaker will send to the client at certain events, such as double-clicking on an inset or saving the document.

Client Text Insets are usually used for custom extensions like SQL database connections or graphical objects having formats not natively supported by FrameMaker. They represent a locked portion of a paragraph inside the regular text flow of FrameMaker. Text insets consist of two parts.

First, there is the visual part which determines its appearance, i.e. the actual content of the inset. This part can contain all sorts of character layout and formatting directives. Additionally, the content of an inset may contain markers of tables, which in this case also belong to the content of the inset. The entire content of the inset is locked, i.e. it can not be edited by the user. The only way to directly interact with an inset is to double-click it. In this case, FrameMaker sends a notification to the corresponding API client that the inset has requested interaction (usually displaying a properties dialog).

Second, there is a small number of fields in each inset which are not visible to the FrameMaker user and can be used to store the meta data of the inset. For example, the name of the associated API client is stored as well as information about the automatic updating functionality. Furthermore, two fields, namely TiClientSource and TiClientData are used to store the path of the XML database file and the unique identifier of the corresponding register inside the database.

As already mentioned, there exist several ways for an user to interact with an API Client, such as calling commands in the pull-down menu, triggering updates or double-clicking the inset’s content. In the following, all possible interactions of our register description client will be explained.

First, the user can create new insets by selecting the corresponding entry in the pull-down menu. The GUI will open and a dialog will be shown allowing the user to choose a file representing the XML database. Afterwards, the registers inside the database can be browsed and the desired one must be selected. The user can then edit its contents and by pressing OK the changed register is transferred to the database and the GUI is closed. Subsequently, the API client recreates the content of the inset and sets its meta data fields.
Second, if an user double-clicks the inset, its corresponding meta-data is read and the GUI is opened with the correct register selected. After the editing is done, the database is updated and the GUI closed. Now, the API client completely deletes the inset’s contents and regenerates them from scratch.
Third, the user can treat insets in many aspects like regular FrameMaker objects. For example, deleting the inset or copying works as expected. However, when an inset is copied using the normal FrameMaker copy&paste functionality, the corresponding register will not be copied as well. Afterwards, both insets will point to the same register in the XML database. Accordingly, deleting an inset does not delete the register in the database.
Lastly, deep copy and delete commands which work on the database are considered to be accessed through the menubar.

When FrameMaker tries to access an inset, but there is no corresponding client available it will replace the inset with its content, thus “converting” the inset to regular FrameMaker text flow elements. This is very useful in case the specification document is handed out to clients or partners, who do not have the API client and the XML database installed.

Furthermore, the FrameMaker application has a builtin update mechanism for cross references and text insets (not restricted to client text insets). This mechanism tries to update every inset when loading the document or upon special request of the user. Such updates trigger the register insets to clear their contents and regenerate them new, very much in the same way as after double-clicking and editing the inset.

There are several advantages of using client text insets. First, the approach is very flexible, such that it is possible to insert the register insets without interfering with the rest of the specification document. It is possible to put registers within existing sections or paragraphs, or additional explanatory text can be put before or after registers. Second, since the GUI is executable as a stand-alone tool and the actual register descriptions are stored outside the FrameMaker document in an XML database, it is possible to switch from FrameMaker to other text processing tools without losing a working register specification environment and access to the existing data. On the other hand, specification documents are also useable without the corresponding API client. So, documents can be freely transfered to other sites or to clients.

Fig. 2. The migration of existing FrameMaker documents into the IP-XACT database

IV. MIGRATION

An important criterion for the acceptance of the new specification environment is the existance of a solution to migrate old documents. Those are plain unstructured FrameMaker documents, containing complete specifications. Often, the layout contains predefined paragraph and table formats. Our approach to extract specification data from unstructured documents involves three major steps as illustrated in Fig. 2.

First, the document is converted into a parse tree which includes all elements of the document and can be easily traversed. FrameMaker supports the mif format which fits those requirements exactly and is compatible between different versions of the application. Every FrameMaker document can be easily saved as mif and parsed into a tree.

During the main step, this parse tree is traversed and all necessary data is collected. The result is a plain mostly redundant and inconsistent collection of data for each register. In order to figure out which elements of the specification contain the desired register data, paragraph and table formats are used in conjunction with heuristic layout informations. In our use case for example, two subsequent tables of table layout “Register”, where the first table contains two rows (register name and description) and the second table contains two columns with the headers “Bits” and “Description”, are considered a register description. However, such methods are not very robust, and it is necessary to adapt them for every specification document to be processed. Furthermore, the result must be carefully verified and in some instances even the FrameMaker document itself must be revised to fix and adjust the layout.

The third and last step processes the data collection of the previous step in order to remove redundancy and to clean up the data types, before it is saved into the IP-XACT XML database. For example, this step extracts the reset value and access mode of the register from the second row of the first table containing the register’s description.

In a perfect world, all documents would be set in a unique and unambigious layout and the register data could be extracted using a well-defined set of extraction rules. In practice however, we found that each company and even different projects within the same company use largely different layout styles, such that the rules used for one project can not be used to migrate another one. Despite the development of our extraction framework code, a lot of error-prone manual labour is necessary, especially for the verification of the migration result. The problems which were detected during the migraton of one project can help to enforce more discipline on system architects with regard to layout issues, such that other projects are easier to migrate.

V. IMPLEMENTATION

The graphical user interface has been implemented using wx- Python [9] and is therefore portable to all major platforms. We are using the complete system under Solaris and MS Windows, since the FrameMaker FDK is not available for other platforms. However, the graphical user interface and the database can be used on a wider range of systems. A screenshot of the SpiritEd graphical user interface can be seen in Fig. 3.

The FrameMaker FDK is a programming interface for FrameMaker written in C. It requires a restart of the FrameMaker application each time a client is modified. In order to reduce the turn-around time for the development of the client, we exported the C language API to Python using SWIG [10]. Thus, the FDK client can be implemented in Python alone, making it a much safer and faster task to manipulate the client source code, e.g. to change the visual appearance of the inset.

The XML Access API also relys on Python to provide a convenient scripting interface for users who want to write custom generation scenarios. Future work might replace the plain file access using the Python-internal DOM implementation [11] with more performance-centric database solutions. At the moment, we are working on a solution to enable XML Schema Validation on the XML files. This is accomplished with the XercesC XML library provided by the Apache project [12].

VI. CONCLUSION

This paper presented a formal specification flow for register descriptions. It aims at replacing the traditional approach of specifying registers using regular text processors such as Adobe FrameMaker or MicrosoftWord. Those applications are limited to unstructured specification flows that provide no way to reliably and automatically extract required register data from the document. Furthermore, it is difficult to keep multiple documents containing the same register data consistent. In general, an unstructured specification flow is a potential source for later design and specification errors.

The proposed flow introduces a new XML-based database using the IP-XACT standard for register data. This database represents a unique project wide source of the register data. Since each document derives all required information from this source, one major reason for inconsistency bugs is eliminated.

The specification system consists of the database itself, a graphical user interface to access the register contents and an Adobe FrameMaker client providing seamless integration of the database contents into the existing specification flow. Furthermore, a framework is provided to facilitate the creation of derived documents and source code, such as RTL design descriptions, verification code or header files for embedded software.

Fig. 3. The graphical user interface of SpiritEd under MacOS XTM

In order to support the migration of existing FrameMaker specification documents, we examined methods to extract the register data from such documents. Despite the fact that a huge amount of manual work is necessary to implement a working migration flow, the existing framework code and experiences can help to introduce the flow for new projects and even projects already started.

We have implemented a prototype of this system for demonstration purposes and are testing its performance and usability aspects on an up-to-date industrial example. Here the modularity of the system helps to gain user acceptance for the proposed methodology.

Future work will concentrate on performance issues and making the system more reliable and convenient according to user input. In case the file-based XML database does not meet the performance requirements, we will replace it with a more sophisticated database solution.

REFERENCES

[1] C. K. Lennard, V. Berman, S. Fazzari, M. Indovina, C. Ussery, M. Strik, J. Wilson, O. Florent, F. R´emond, and P. Bricaud, “Industrially proving the SPIRIT consortium specifications for design chain integration,” in DATE ’06: Proceedings of the conference on Design, Automation and Test in Europe, 2006, pp. 142–147.

[2] V. Berman, “Standards: The P1685 IP-XACT IP Metadata Standard,” IEEE Design & Test, vol. 23, no. 4, pp. 316–317, 2006.

[3] Denali Software, Inc., BlueprintTM, http://www.denali.com/products/blueprint.html.

[4] ——, SystemRDL, http://www.denali.com/.

[5] Scriptorium Publishing Services, Inc., Integrating XML and FrameMaker, White paper, http://www.scriptorium.com/papers.html.

[6] ——, Structured Authoring and XML, White paper, http://www.scriptorium.com/papers.html.

[7] Adobe Systems Inc., Adobe FrameMaker Developer Kit 7.1, http://www.adobe.com/devnet/framemaker/fdk.

[8] W3C, W3C: XML Schema (XSD), http://www.w3.org/XML/Schema.

[9] H. Talbot, “wxPython, a GUI Toolkit,” Linux Journal, vol. 2000, no. 74es, p. 5, 2000.

[10] D. M. Beazley, “Automated scientific software scripting with SWIG,” Future Generation Computer Systems, vol. 19, no. 5, pp. 599–609, 2003.

[11] W3C, W3C: Document Oject Model (DOM), http://www.w3.org/DOM.

[12] The Apache Software Foundation, Xerces XML parser for C++, http://xml.apache.org/xerces-c, 2007.

This research work was supported in part by the German Federal Ministry of Education and Research (BMBF) in the project URANOS under the contract number 01M3075.