Rules-ng

Rules-ng is a hardware register description database format. This means it is primarily a specification document on how to describe registers in an XML document. The specification comes bundled with some tools and the same directory tree also hosts some actual register databases, most notably the one for Nouveau.

The source is in CVS: http://nouveau.cvs.sourceforge.net/nouveau/rules-ng/

The specification and tools are mainly developed by PekkaPaalanen, databases have many more contributors. If you need commit access to the CVS, contact StephaneMarchesin. In all other matters, contant PekkaPaalanen.

The Specification

The specification can be found in the CVS: rules-ng-format.txt

It is accompanied by an XML Schema: rules-ng.xsd which attempts to enforce most of the database specification.

Features

• associate a name with a register address
• named bitfields
• named values
• different types of representing a value
• variants: describe a family of hardware, that have similarities and differences
• indirect registers (enabled automatic decoding)
• embedded documentation

Included databases

• Nvidia GPU registers: nvregisters.xml

• VGA (indirect) registers: vga_crtc-regs.xml

• Radeon R300 registers: r300_reg.xml

and possibly others, in databases

Tools

The tools can be found the CVS directories parsers/ and staticdb/.

Staticdb

Staticdb is a chain of tools. staticdbgen.py is a Python script that takes a Rules-ng database XML file and converts it into static C-language structures. The structure files can be linked into a C library, which offers a lookup interface into the database. This is used in MmioTrace's mmio-parse to convert addresses and values into names and value descriptions.

Header generator

headergen.py is currently only a proof-of-concept Python script that transforms a Rules-ng database XML file into a C header file with #define's for everything. It is intended for helping in writing drivers.

HTML Documentation Generator

names2html.py is a Python script that generates a bunch of HTML files from Rules-ng databases.

To Do

• Indirect register access: implement index from bitfield.
• names2html.py generates sometimes incorrect variant lists. Fix it.
• Implement I2C parser: look at i2c code in randr-1.2 branch, related indirect VGA regs 0x36 and 0x3e
• Use integrated documentation in headergen.py.
• Enhance HTML document generator.
• Added a way to define absolute names, but now make all tools understand it.
• staticdb: the value string format is fixed, make it flexible by returning an array of structs (for bitfields). Should the bitfield value be raw (integer), string, or both? What about exposing value types to the application? Maybe not a good idea... but customizing query.c is too much.

Wishlist

Record here what is wrong about Rules-ng or what should be changed or developed.

• It is difficult to write the internal structure of a database XML file so that adding new variant specific registers would be easy.
• The specification is not easy to read.
• staticdb is too static, we need a dynamic database for e.g. parsing RAMIN contents