Open IC Register Description Language (a proposal)

Summary: Many modern digital ICs are interacted with through memory mapped registers. Writing maintainable code demands a header file with well structured constants for register addresses, bit field masks, field values etc. But even that on its own doesn't guarantee readable code. It is often desirable to have a summary of the register function, and values in a comment block above the code. But this can be very onerous, involving lots of cutting/pasting/formatting from the datasheet. My proposal is a standard machine-readable way to describe a ICs registers using an open format. These descriptions can be used to generate constant header files for any language, automatically document code and provide useful plugins for IDEs. I also propose to crowd-source an open source data repository of such description files for popular ICs. 

I've been writing some embedded C recently, and trying to document my code as I go along. When I access an IC register I include the following information above the code block:

• The datasheet document name and revision number
• The relevant section / table number/ page number in the datasheet
• A short description of the register / bit field being accessed and allowed values

This can get quite tedious cutting/pasting text from the datasheet. Any time something is cut/paste more than twice is a strong indicator that you are doing something wrong.

I went looking for any standard machine-readable way to document IC registers and found nothing (so far). So I'm proposing an open standard and open database to document IC registers.

This will have several benefits for developers:

• automatically generate header files for what ever language is being used with register addresses, bit masks, field values etc. Automatic generation guarantees a consistent format.
• automatically generate data structures for large/complex registers
• automatically document code by making a single reference to a register / bit field
• allow tight integration with IDEs (eg debugger can display annotated register values along with the actual meaning of that value)

I'm not a big fan of XML, but it does seem to be the standard for this kind of thing. So my proposed IC register description will look something like this:

<?xml encoding="utf-8">
<device name="RFM69">

<description>
HopeRF RFM69/RFM69HW radio module
</description>

<register>
<sname>OpMode</sname>
<name>Operation Mode</name>
<address>0x01</address>

<bitfield bit="7" rwmode="rw">
<sname>SequencerOff</sname>
<description>Controls the automatic Sequencer (see section 4.2)
<value val="0"></value>
<value val="1">Mode is forced by user</value>
</bitfield>

<bitfield bit="6" rwmode="rw" type="onoff">
<sname>ListenOn</sname>
<description>Enables Listen Mode, should be enabled whilst in Standby mode.</description>
</bitfield>

<bitfield bit="4:2" rwmode="rw">
<sname>Mode</sname>
<description>Tranceiver's operating mode</description>
<reference>section 6.2</reference>
<fieldvalue><value>0</value><sname>SLEEP</sname><name>Sleep mode</name></fieldvalue>
<fieldvalue><value>1</value><sname>STDBY</sname><name>Standby mode</name></fieldvalue>
<fieldvalue><value>2</value><sname>FS</sname><name>Frequency Synthesis mode</name></fieldvalue>
<fieldvalue><value>3</value><sname>TX</sname><name>Transmitter mode</name></fieldvalue>
<fieldvalue><value>4</value><sname>RX</sname><name>Receiver mode</name></fieldvalue>
</bitfield>

</register>

<register>
<sname>DataModul</sname>
<description>Data modulation settings</description>
.... etc....
</register>

</device>


Some notes about the schema: Along with a human friendly register name, I've got a short-name. This will conform to C identifier specification and is used in header file generation.

The resulting header files can be generated from rules (which can be changed according to house style). For example my rule is: <IC>_<REG> for register address, <IC>_<REG>_<FIELD>_MASK for bit field masks, and for each field value <IC>_<REG>_<FIELD>_<FIELDVALUE>. So from the XML example above I get something like this for the C language header file:

#define RFM69_OPMODE (0x01) /* Operation mode register */
#define RFM69_OPMODE_MODE_MASK (7 <<2)
#define RFM69_OPMODE_MODE_SLEEP (0<<2) /* Sleep mode */
#define RFM69_OPMODE_MODE_STDBY (1<<2) /* Standby mode */
#define RFM69_OPMODE_MODE_FS (2<<2) /* Frequency synthesiser mode */
#define RFM69_OPMODE_MODE_TX (3<<2) /* Transmitter mode */
#define RFM69_OPMODE_MODE_RX (4<<2) /* Receiver mode */

Code documentation.

Comment annotations can instruct a code post-processor to insert/update the necessary documentation. For example:

/**
 * Set transceiver mode to transmit
 * @register RFM69_OPMODE.MODE
 */

Will get expanded to something like this:

/**
 * Set transceiver mode to receive
 *
 * @register RFM69_OPMODE.MODE
 *
 * RFM69_OPMODE.MODE autodoc. Do not edit. ****
 * RFM69 datasheet, section 6.3
 * OPMODE MODE (bits 4:2). Read and write allowed. Values:
 * SLEEP (0) : Sleep mode ;  STDBY(1) : Standby mode ;
 * FS (2): Frequency synthesis mode ; TX (4): Transmitter mode;
 * RX (4): Receiver mode
 * End RFM69_OPMODE.MODE autodoc
 */

Note the auto generated sections are delimited by a marker. While this may generate verbose source code it will be easier to read (especially for someone new to the hardware) and can be easily maintained/updated or removed as required.

This can also be helpful for non-english speaking developers. Any text element in the register description can have a lang (language) attribute. So a developer can switch out the english descriptions for one in their native language (either permanently or temporarily with an IDE plugin).

The open database:

I propose that these IC description files are uploaded and maintained on something like GitHub repositories. For ease of maintenance, it might be an idea to split the description file into a separate file for each register. A suitable licence must be used to ensure the generated header files and documentation do not cause any licencing restriction on developers.

Other features/ideas:

• Chip variants or silicon revisions can be accommodated by linking to a root document and then including only items that have been changed.
• IDEs can generate convenience routines eg in the example above function rfm69_mode_set (mode); rfm69_mode_get(); etc
• IDEs can use this description to visually annotate register bit fields in the debugger
• Complex configurations and sequences can be documented by the manufacturer in a machine-readable but language neutral way.
• Support i18n, allowing a language attribute for any text fields.
• Editing XML directly is tedious and error prone. A web app could be used as a front end for editing and maintaining such a database.
• What I've proposed is only for registers, but other common information could also be included (pin outs, voltage/current ratings etc)

I've stared writing some utilities to implement some of these ideas for an internal project which I'll release as an open source project soon (probably under a BSD style licence). I'd be delighted to hear from anyone who is aware of any similar efforts (I really don't want to reinvent the wheel here), or would like to critique or contribute.

Updates:

3 Sep 2014: I've created a GitHub respository for this project at https://github.com/jdesbonnet/ICRDL