I'm currently working on a customer project, participating in the development of a complex medical device.  The device contains several different embedded processor cores, DSPs, FPGAs and ASICs.  In short, it's a complex undertaking.

On this project, I'm currently driving the development of a specification that describes how the system software will interface with the main FPGA in the system.  This specification is an example of an *interface definition document* or IDD.

As a side-note, in the book "Moon Launch" by Charles Benson D. and William B. Faherty, there is an interesting comment about the use of "Interface Control Documents" (ICDs) on the Apollo program:

"Interface control documentation, an essential activity during site activation, was another responsibility of KSC's Apollo Program Office. Apollo configuration control dated from February 1963, when the manned spaceflight centers had agreed to consolidate and store interface control documents. During the next several years, Apollo-Saturn subpanels placed hundreds of such documents in a Huntsville repository. Through the interface control documents, Apollo managers made sure that thousands of items, built in many different places, would fit and work together. The documents provided design requirements and criteria for hardware and software interfaces, describing the parameters and constraints under which the interfacing items functioned. The information in the documents varied and might include physical and functional design details and operational and procedural requirements. Where an interface involved two NASA centers, a level A document applied - for example, the interface between a command module (Houston responsibility) and the mobile service structure (KSC responsibility). Level B documents pertained to intra-center interfaces such as the S-IVB-Instrument Unit interface covered by Marshall's Saturn ICD, 13M06307 (October 1965). When changes affected performance, cost, or schedule accomplishment, the centers prepared interface revision notes."

Now, when we think of spec writing, I suppose most of us think of using Word or FrameMaker or some other documentation tool to create a text document.

In this case, I'm using Python -- a powerful scripting language -- to create the specification.

What I'm doing is the following.

First, I've defined a simple object model of the FPGA.  So, I have a handful of Python classes, representing things like an FPGA, a Register within the FPGA, a space within the FPGA, bitfields, bitfield enumerated values, etc.

After developing the object model, I wrote a short script (again, in Python) to convert the text-based representation of the previous specification into (rough) Python code.  Through this script, I was able to automate the import of the previous specification revision (for a previous product) and saved myself a great deal of pick and shovel work.

(So here's a tip.  When you are faced with some boring, pick-and-shovel task, see if there is a way to automate it.  If it will take just as long to automate the task as to do it manually, you might as well automate it.  By doing this, you will accomplish the task and improve your software engineering (or, at least, your programming knowledge) at the same time.)

Once I had the executable code for the device model itself, I turned to the work of generating the specification itself.

I chose ReStructuredText as my output format.  This is a very easy format to generate and results in fairly good looking output in both HTML and Adobe's PDF.

To generate HTML from ReStructuredText, one uses a script named rst2html.py.  This script is a part of the Docutils package.

Generating a PDF is a bit more tedious, but not much.

First, the document is converted from ReStructuredText to LaTeX.  LaTeX (which is pronounced "lah-tech", by the way, and not "lay-tex") is a set of TeX macros originally crafted by Leslie Lamport.

Once a LaTeX source file is available, it's fed through pdflatex, which is an implementation of Don Knuth's TeX typesetting software.  The pdflatex program generates a PDF file as output.

Now, at this point, you may be questioning my sanity.  "He writes a program to write a specification?  How crazy is that?"

Actually, I don't think it's all that crazy.  Here's why.

First, by writing the specification as an executable program, I'm able to take better advantage of the powerful version control system (ClearCase) used on this project.  This makes it easy for me to keep track of exactly what changes are being made to the document as it evolves.  No more messy and error-prone schemes for naming twenty different versions of a Word document, or screwing around with "Track Changes."

Second, with an executable program we can do other things, including automatically generating the .h and .cpp files that define the interface between the embedded software and the FPGA.

These source files are not just a set of ordinary #defines.  Since we have access to the bitfields within registers, we can write (inlined, for performance) C++ member functions to read and write fields within individual registers.

I've already started generating these files.  With only a couple hours work, I now have a much more comprehensive set of sources than existed previously.  And, there is still plenty of low-hanging fruit to be picked.

Third, the existence of an executable program -- and some basic code generation capabilities -- it's possible to generate a set of debugger scripts to facilitate the integration of the FPGA.

I don't know about you, but I'm tired of wasting my time typing in register addresses to the debugger and then playing "Let's Decode Some Bitfields" with the resulting value.

With this approach, I can type the following into the debugger:

     B:: dump_video_capture_control

and get a nicely formatted dump of the clock control register.

There will be other benefits from this work -- such as the ability to ensure that there are no errors as a result of mismatches between the IDD and the code -- as well.  But for now, I'm going to wrap up this article with the following thought.

Every day, we strive to work in an efficient manner.  The very idea of writing a program to write a specification seems grossly inefficient.

In practice, I think it can be exactly the opposite.  Sometimes, it is not writing a program to write a specification that turns out to be a huge waste.