Regpict

Abstract

The Regpict library draws register pictures in specifications. An example such figure is shown in Figure 1.

This library consists of two levels:

A JSON to SVG conversion layer.
Converts a JSON formatted description of a hardware register into the corresponding SVG diagram.

This layer supports inheritance.
A variety of JSON extraction layers.
These extract information from a variety of input formats and produce JSON usable by the JSON to SVG conversion layer. Input formats include:
- <table class="regpict-pcisig">...</table> as used in recent [PCISIG] specifications.
- <pre class="regpict-json">...</pre> containing the JSON code.
- <pre class="regpict-refman">...</pre> containing Nvidia refman formatted text.

Using the JSON extraction layer is optional. The JSON to SVG conversion layer can be used standalone.

The generated SVG is designed to be styled using CSS. Proper representation requires some CSS. A minimal CSS file is provided as well as a more complete example. Section 3 describes the classes contained in the generated SVG.

The initial implementation is in JavaScript. This version was integrated into a fork [RESPEC-Fork] of the respec library [RESPEC].

A version in Ruby that works as a plugin filter for [ASCIIDOCTOR] is anticipated.

2 JSON Format Details

The JSON intermediate format contains a collection of properties related to the overall register as well as a fields property with details for each register field. The each property of fields describes the corresponding register field.

2.1 Register Properties

The following register properties are defined:

width: Width of the register, in bits. Default is 32.
defaultUnused: Name to apply to unused bits in the register. Default is "RsvdP".
defaultAttr: Attribute to apply to fields that do not specify one. Default is "other".
cellWidth: Width of a bit cell, in pixels. Default is 16px.
cellHeight: Height of a bit cell, in pixels. Default is 32px.
cellInternalHeight: Height of the bit separator lines with a multi-bit cell. Default is 8px.
cellTop: Location of top of every bit cell, in pixels. Default is 40px.
figLeft: Location of the left edge of the register, in pixels. Default is 32px.
cellValueTop: Top of the text for a multi-bit field value relative to cellTop. This applies to bit fields that are wider than one bit and that have a value property that does not specify individual bit values. Default is 16px.
cellBitValueTop: Top of the text for a single bit value relative to cellTop. This applies to all bit fields that are one bit wide. This also applies to wider fields that contain a value that contains individual bit values. Default is 20px.
cellBitNameTop: Top of the text for a bit name that's displayed inside the register field. This applies to bit fields that bit fields where the text fits in the bit cell(s) that do not have a value specified. Default is 16px.
bracketHeight: Height of the bracket drawn below the bit field when the field name is displayed outside the register field. Default is 4px.
figName: Prefix to use when generating id values for fields in the generated SVG. Default is "???".
maxFieldWidth: Maximum width of the figure. Default is 720px (approximately 7.5 inches).
visibleLSB: Least Significant bit that will be displayed. Default is 0.
visibleMSB: Most Significant Bit that will be displayed. Fields that start above this value will not be displayed. Fields that start below this value and end above this value will be partially displayed. Default is width (i.e. one greater than the register width).
table: Contains the locator for a PCISIG formatted table to parse. Includes the leading ‘#” character (e.g. “#tbl-pcisig-style-table“). See Section 4.1.7 Figure data-table attribute and Section 4.4 PCISIG Style Table.
href: Contains the locator for an Nvidia formatted refman file to parse. See Section 4.1.6 Figure data-href attribute and Section 4.5 NVidia Refman.
register: Contains the locator for an external <pre>, <div> or <span> element containing JSON to parse. See Section 4.1.8 Figure data-register attribute and Section 4.3 JSON outside the
.
fields: JSON Object containing one property per register field. Default is the empty property { }.

2.2 Field Properties

The following properties are defined for register fields:

name

Name of the field. If the name fits in the field box and no value is provided for the field, the name is drawn in the field box, centered horizontally, with the top edge of the name text at cellNameTop. Otherwise, the field name is drawn to the right of bit visibleLSB with a line connecting the field name to the middle of the bit field.

If name is not specified, the default is the property name of the field within the fields property of the register. Note: all fields in Figure 1 do not have a name property.

id

This property contains a string value that specified the id attribute for the <g> element in the generated SVG. If this property is not explicitly defined and field is not isUnused, an id attribute will be be created for the field using rules defined in Section 3.4.

lsb

Least Significant Bit number. If omitted, field is 1 bit wide containing just the msb. At least one of lsb or msb must be specified.

msb

Most Significant Bit number. If omitted, field is 1 bit wide containing just the lsb. At least one of lsb or msb must be specified.

value

The value for the field. This property takes on the following forms:

Single string value, and the field with is greater than 1 bit. The value property is displayed in the field box, centered horizontally, with its top edge at cellValueTop.
Single string value, and the field width is exactly 1 bit. The value property is displayed in the field box, centered horizontally, with its top edge at cellBitValueTop.
JSON array value where the array length equals the field width in bits and the array values are all strings. The string values are typically 1 character due to space limitations. You can make more room by increasing cellWidth or decreasing the font size for the class regBitFieldValue. Each array item is drawn centered horizontally in the corresponding bit cell, with its top edge at cellBitValueTop.

attr

This property is a string that indicates the type of this field. If this property contains x, the generated SVG has class regAttr_xxx. This permits styling of register fields based on field attribute (Read Only, Read Write, etc.). This value is converted to lower case so it's irrelevant what case is used for this property. This property must be a valid class name (e.g. no spaces, etc.). Common values are: rw, rws, ro, ros, rw1c, rw1cs, rw1s, rw1ss, wo, wos, hardwired, fixed, hwinit, rsvd, rsvdp, rsvdz, reserved, unused, and other. The default value of attr is "other".

isUnused

Unused field indicator. If isUnused is present and has the value true, this bits that comprise this field are some flavor of undefined (e.g. Reserved, RsvdP, RsvdZ). The the drawn field has the class regFieldUnused to permit styling using CSS. Unused field indicator. If isUnused is present and has the value true, this bits that comprise this field are some flavor of undefined (e.g. Reserved, RsvdP, RsvdZ). The the drawn field has the class regFieldUnused to permit styling using CSS.

addClass

If addClass is present, it MUST contain a string value. This value contains one or more class names. Each of these class names is appended to the list of classes for the generated <g> element. A good application for the addClass property is to highlight particular fields, when this highlighting is not an intrinsic property of the field. For example, if the same figure is used in multiple places, with each usage explaining some of the fields, the addClass property can be used to highlight the appropriate fields. Intrinsic properties of a field are better indicated through the attr property.

3 SVG Class Structure

This section describes the structure of the generated SVG. Knowing this structure permits more flexible styling of the resulting diagram using CSS.

The generated SVG contains a <g> element for every field. This includes fields that are explicitly defined as well as fields that are created to represent unused register bits.

3.1 External Field

Regpict will generate an External Field when the field name doesn't fit in the bit field box or the field has a value property.

An example External Field is shown below. This is the bit 12:15 field from Figure 1.

Example 2

<g id="regpict-json-register-example-bit-12-15"
   class="regFieldExternal regAttr_other regLink regFieldExternal1">
    <text x="358" y="36" class="regBitNumEnd">12</text>
    <text x="298" y="36" class="regBitNumStart">15</text>
    <line x1="360" y1="40" x2="360" y2="26.5" class="regBitNumLine_Hide"></line>
    <line x1="296" y1="40" x2="296" y2="26.5" class="regBitNumLine"></line>
    <rect x="296" y="40" width="64" height="32" class="regFieldBox"></rect>
    <line x1="344" y1="64" x2="344" y2="72" class="regFieldBox"></line>
    <line x1="328" y1="64" x2="328" y2="72" class="regFieldBox"></line>
    <line x1="312" y1="64" x2="312" y2="72" class="regFieldBox"></line>
    <text x="328" y="20" class="regBitWidth">4 bits</text>
    <text x="568" y="152" class="regFieldName">bit 12:15</text>
    <text x="328" y="56" class="regFieldValue">value</text>
    <path d="M296,72l32,4L360,72" class="regBitBracket" fill="none"></path>
    <path d="M328,76V147.5H566.4" class="regBitLine" fill="none"></path>
</g>

3.2 Internal Field

Regpict will generate an Internal Field when the field name fits in the bit field box and there is no value property.

An example Internal Field is shown below. This is the field 4:0 field from Figure 1.

Example 3

<g id="regpict-json-register-example-field-4-0"
   class="regFieldInternal regAttr_ro regLink">
    <text x="550" y="36" class="regBitNumEnd">0</text>
    <text x="474" y="36" class="regBitNumStart">4</text>
    <line x1="552" y1="40" x2="552" y2="26.5" class="regBitNumLine"></line>
    <line x1="472" y1="40" x2="472" y2="26.5" class="regBitNumLine"></line>
    <rect x="472" y="40" width="80" height="32" class="regFieldBox"></rect>
    <line x1="536" y1="64" x2="536" y2="72" class="regFieldBox"></line>
    <line x1="520" y1="64" x2="520" y2="72" class="regFieldBox"></line>
    <line x1="504" y1="64" x2="504" y2="72" class="regFieldBox"></line>
    <line x1="488" y1="64" x2="488" y2="72" class="regFieldBox"></line>
    <text x="512" y="20" class="regBitWidth">5 bits</text>
    <text x="512" y="56" class="regFieldName">field 4:0</text>
</g>

3.3 Generated `<g>` element: `class` attributes

The generated SVG has a variety of classes available. This allows customizing the styling of the diagram using CSS.

The following classes are defined:

g .regFieldInternal: Applied to the <g> element to indicate an Internal Field.
g .regFieldExternal: Applied to the <g> element to indicate and External Field.
g .regFieldExternal0
g .regFieldExternal1: Applied to the <g> element of an External Field. The two least significant External Fields have regFieldExternal0. The next two External Fields have regFieldExternal1. The pattern repeats with next two External Fields have regFieldExternal0, followed by two with regFieldExternal1. These classes can be used to format the lines differently to enhance readability.
g .regLink: Applied to the <g> element to indicate a defined field that can be referenced externally. These fields have an id attribute).
g .regFieldOverflowLSB: Applied to the <g> element to indicate that the field is partially visible because its lsb is less than visibleLSB.
g .regFieldOverflowMSB: Applied to the <g> element to indicate that the field is partially visible because its msb is greater than visibleMSB.
g .regFieldHidden: Applied to the <g> element to indicate that the field is not visible either because its lsb is greater than visibleMSB or its msb is less than visibleLSB.
g .regAttr_xxx: Applied to the <g> element to convey the attributes of the corresponding field. The xxx is the attr value converted to lower case.
g .regFieldUnused: Applied to the <g> element of an Internal Field to indicate that the isUnused property was present and true. Not applicable to an External Field.
text .regBitNumStart: Applied to the <text> element that contains the msb bit number of the field. Used only for multi-bit fields.
text .regBitNumEnd: Applied to the <text> element that contains the lsb bit number of the field. Used only for multi-bit fields.
text .regBitNumMiddle: Applied to the <text> element that contains the bit number of the field. Used only for single bit fields.
line .regBitNumLine: Applied to the <line> element that represents the line adjacent to the lsb and msb bit numbers of the field.
line .regBitNumLine_Hide: Same as regBitNumLine. Applied to the line adjacent to the lsb bit number of all fields except for the least significant visible field (i.e. lsb == visibleLSB). This element should be hidden by default and should become visible when the user hovers over the <g> element.
rect .regFieldBox: Applied to the <rect> element that represents the bit field box.
line .regFieldBox: Applied to the <line> element that represents the bit divider lines within the bit field box. Used only for multi-bit fields.
text .regFieldName: Applied to the <text> element that contains the field name.
text .regBitWidth: Applied to the <text> element that contains the width of the field. This element should be hidden by default and should become visible when the user hovers over the <g> element.
text .regFieldValue: Applied to the <text> element that contains the field value. Used for all fields that contain a value property.
text .regBitFieldValue: Applied to the <text> element that contains a single bit of the field value. Used for fields that contain individual bit field values. These fields also have class regFieldValue.
text .regBitFieldValue-N: Applied to the <text> element that contains bit N of the field value. Permits formatting individual bit values differently.
text .regBitFieldValue-msb: Applied to the <text> element that contains the value of the most significant bit of the field value. Permits formatting the msb value differently. The lsb equivalent is regBitFieldValue-0.
path .regBitBracket: Applied to the <path> element of an External Field that is the bracket immediately below the bit field box. Not applicable to Internal Fields.
path .regBitLine: Applied to the <path> element of an External Field that connects the bracket to the field name. Not applicable to Internal Fields.
text .svg_error: Applied to invalid value properties.

3.4 Generated `<g>` element: `id` attribute

Regpict will generate a unique id attribute for most fields. No id is generated for unused fields (i.e. fields that have an isUnused property with the value true. All other fields have an id attribute generated as follows:

Construct a preliminary id string from:
1. The id property of the field, if present.
2. The figName property of the register,
  followed by a dash (“-”),
  followed by the name property of the field.
Sanitize the preliminary id string by:
1. Converting upper case to lower case.
2. Removing leading and trailing spaces.
3. Replacing sequences of one or more invalid characters with “-”.
  For this purpose, characters that are not digits, letters, periods, dashs, or underscores are invalid.
4. Removing leading and trailing sequences of dashes.
5. If the last character is a period, append the letter “x”.
6. If the first character is not a letter, prepend the letter “x”.
7. If the value is the empty string at this point, use the string “generatedID”.
Prepend “regpict-” to the prelminary id.
Check to see if the preliminary id is unique or if duplicates a id attribute already present the document.
If the preliminary id is already present in the document, create a unique version of it by appending ”-N“ where ”N“ a is the smallest integer value greater 0 that is not already used in the document. For example, for the preliminary id “regpict-foo” is already present, the next one is “regpict-foo-1”, followed by “regpict-foo-2”, and so forth.

3.5 Unused Bits

Unused bits in a register cause a field to be invented by Regpict.

This field has the following properties:

name: the value of the defaultUnused property of the register.
If it doesn't fit, only the first character is defaultUnused is used, converted to upper case.
attr: the value of the defaultUnused property of the register, converted to lower case
isUnused: true
lsb: least significant bit of a string of one or more unused bits
msb: most significant bit in a string of one or more unused bits
value: not present
id: not present
addClass: not present

4 Respec Usage

This section describes usage of the regpict feature in Steve Glaser's fork of respec [RESPEC-Fork].

There are 4 ways to use regpict:

JSON directly in <figure>. Section 4.2 JSON directly in
JSON outside the <figure>. Section 4.3 JSON outside the
PCISIG style HTML <table>. Section 4.4 PCISIG Style Table
Register extracted from external file in Nvidia refman format. Section 4.5 NVidia Refman

Each usage is described in the following sections.

4.1 Common Rules for all <figure class="register"> elements

4.1.1 Figure figName property

The figName property of the register is computed as follows:

The id attribute of the <figure> element, removing the text “fig-” from the beginning of the value.
Otherwise, the title attribute of the <figure>.
Otherwise, the text contents of the <figcaption> element inside the <figure>.
Otherwise, the string “unnamed-regno” where regno is a number, starting at 1 and incrementing by 1 every time a string of this form is created.

This value is then sanitized by:

Removing leading and trailing white space characters.
Replacing strings of one or more illegal characters with a single “-”. For this purpose, illegal characters are anything except digits, letters, dash, underscore, and period.
Removing all leading and trailing dashes.
Appending “x” if the last character is not a letter.
Prepending “x” if the first character is not a letter.
Replacing the empty string with “generatedID”.

4.1.2 Figure `id` attribute

If the <figure> does not have an id attribute, it is set to “fig-figName” where figName is the figName property defined in Section 4.1.1 Figure figName property.

4.1.3 Figure `data-json` attribute

If the <figure> has a data-json attribute, it's value is parsed and merged into the figure's JSON.

4.1.4 Figure `data-width` attribute

If the <figure> has a data-width attribute, it's value becomes the width property of the figure's JSON.

4.1.5 Figure `data-unused` attribute

If the <figure> has a data-unused attribute, it's value becomes the defaultUnused property of the figure's JSON.

4.1.6 Figure `data-href` attribute

If the <figure> has a data-href attribute, it's value becomes the href property of the figure's JSON.

4.1.7 Figure `data-table` attribute

If the <figure> has a data-table attribute, it's value becomes the table property of the figure's JSON.

4.1.8 Figure `data-register` attribute

If the <figure> has a data-register attribute, it's value becomes the register property of the figure's JSON.

4.2 JSON directly in <figure>

If the <figure> contains one or more <pre class="json">, <div class="json">, or <span class="json"> elements, these elements are parsed and combined and the resulting figure is drawn. These elements are hidden as they are parsed (class “hide” added so they can be hidden by css).

If the JSON does not define a figName property, the <figcaption> value is used to invent one.

This situation is shown in Figure 2 and Example 4

{
    "fields": {
        "foo": {
            "lsb": 0,
            "msb": 7
        }
    }
}

Fig. 2 JSON directly in <figure>

Example 4: JSON directly in <figure>

<figure class="register" id="fig-json-directly-in-figure">
    <pre class="json">
        {
            "fields": {
                "foo": {
                    "lsb": 0,
                    "msb": 7
                }
            }
        }
    </pre>
    <figcaption>JSON directly in &lt;figure&gt;</figcaption>
</figure>

4.3 JSON outside the <figure>

If the <figure> contains one or more <pre class="render">, <div class="render">, or <span class="render"> elements, these elements are parsed a figure is drawn for each such element. This can result in a single <figure> element having multiple figure diagrams. This is particularly useful in conjunction with visibleLSB and visibleMSB to display very wide registers conveniently. These elements are hidden as they are parsed (class “hide” added so they can be hidden by css).

If the <pre>, <div>, or <span> element has the data-parents attribute, this contains a list of one or more locators for external field definitions. The parents are merged into a copy of the <figure> JSON, in the order shown and then the JSON in the element is merged in. The figure is drawn with the resulting JSON. The JSON associated with the <figure> element is not affected.

If the JSON does not define a figName property, the <figcaption> value is used to invent one.

This situation is shown in Figure 3 and Example 4

{
    "width": 64,
     "fields": {
        "lowByte": {
            "lsb": 0,
            "msb": 7
        },
        "highByte": {
            "lsb": 56,
            "msb": 63
        },
        "middle": {
            "lsb": 28,
            "msb": 39
        }
    }
}

{ }

                { "visibleLSB": 31 }

                { "visibleMSB": 32 }

Fig. 3 JSON outside the <figure>

Example 5

<pre id="pre-external-json" class="json">
{
    "width": 64,
    "fields": {
        "lowByte": {
            "lsb": 0,
            "msb": 7
        },
        "highByte": {
            "lsb": 56,
            "msb": 63
        },
        "middle": {
            "lsb": 28,
            "msb": 39
        }
    }
}
</pre>

<figure class="register">

    <pre class="render" data-parents="pre-external-json">{ }</pre>

    <pre class="render" data-parents="pre-external-json">
        { "visibleLSB": 31 }</pre>

    <pre class="render" data-parents="pre-external-json">
        { "visibleMSB": 32 }</pre>

    <figcaption>JSON outside the <figure></figcaption>

</figure>

4.4 PCISIG Style Table

If the <figure> element has the class pcisig_reg (in addition to the class register), and the table property is defined in the JSON the <table> element referenced by the table property is parsed and merged into the figure's JSON. The table property can either be specified directly in the JSON or via the data-table attribute on the <figure>.

The underlying <table> can have any formatting. No specific class attribute is required.

The first column contains the bit location of the field. This determines the lsb and msb properties of the field. The column cell contains either an integer or a pair of integers separated by a colon (e.g. “9”, “15:8” or “8:15”). If two numbers are shown, the MSB is usually first, but this is not required.

The second column determines the name property of the field. It also contains a description of the field. The name property is derived from:

The first word of the text content of the first <code> or <dfn> element.
If no <code> or <dfn> element is present, the first word of the column cell.

The third column determines the attr property of the field. This field is not case sensitive. Valid values are shown in the list below. If the third column does not on of the items, the attr property is “other”.

It the third column matches one of the items marked “(unused)”, the isUnused property is set to true, otherwise the isUnused property is not set.

rw
rws
ro
ros
rw1c
rw1cs
rw1s
rw1ss
wo
wos
hardwired
fixed
hwinit
rsvd (unused)
rsvdp (unused)
rsvdz (unused)
reserved (unused)
ignored (unused)
ign (unused)
unused (unused)
other (default)

is shown in and is based on PCISIG Example.

Fig. 4 PCISIG Example

PCISIG Example
Bit Location	Description	Attr
3:0	`field3_0` this field is shown as `<code>field3_0</code>`.	RO
4	field_4 this field is shown as `<dfn;>field_4</dfn>`.	rw
9	This is the description.	ros
16:19	bits_16_19 this field is shown as `<dfn class="field">bits_16_19</dfn>`. Because the <dfn> has the class field, it is automatically linked to the corresponding field in the figure. Similarly, that field in the figure is linked back to this definition.	rw
24:31	upper_bits	hardwired

4.5 NVidia Refman

If the <figure> element has the class nv_refman (in addition to the class register), and the href property is defined in the JSON, the file referenced by the href property is read and the register defined by the register property is drawn as a figure. The href and register properties can either be specified directly in the JSON or via the data-href and data-register attributes. The referenced file MUST be formatted as an Nvidia refman file and MUST contain a register of the corresponding name.

The width property is determined from the refman definition unless it is already specified in JSON.

The attributes of each field are determined from the refman definition. These will be one of "ro", "rw", or "wo".

Regpict

Unofficial Draft 24 August 2014

Abstract

Status of This Document

Table of Contents

Revision History and Notes

1 JSON Register Example

2 JSON Format Details

2.1 Register Properties

2.2 Field Properties

3 SVG Class Structure

3.1 External Field

3.2 Internal Field

3.3 Generated `<g>` element: `class` attributes

3.4 Generated `<g>` element: `id` attribute

3.5 Unused Bits

4 Respec Usage

4.1 Common Rules for all <figure class="register"> elements

4.1.1 Figure figName property

4.1.2 Figure `id` attribute

4.1.3 Figure `data-json` attribute

4.1.4 Figure `data-width` attribute

4.1.5 Figure `data-unused` attribute

4.1.6 Figure `data-href` attribute

4.1.7 Figure `data-table` attribute

4.1.8 Figure `data-register` attribute

4.2 JSON directly in <figure>

4.3 JSON outside the <figure>

4.4 PCISIG Style Table

4.5 NVidia Refman

A References

A.1 Informative references

Abstract

Status of This Document

Table of Contents

Revision History and Notes

1 JSON Register Example

2 JSON Format Details

2.1 Register Properties

2.2 Field Properties

3 SVG Class Structure

3.1 External Field

3.2 Internal Field

3.3 Generated <g> element: class attributes

3.4 Generated <g> element: id attribute

3.5 Unused Bits

4 Respec Usage

4.1 Common Rules for all <figure class="register"> elements

4.1.1 Figure figName property

4.1.2 Figure id attribute

4.1.3 Figure data-json attribute

4.1.4 Figure data-width attribute

4.1.5 Figure data-unused attribute

4.1.6 Figure data-href attribute

4.1.7 Figure data-table attribute

4.1.8 Figure data-register attribute

4.2 JSON directly in <figure>

4.3 JSON outside the <figure>

4.4 PCISIG Style Table

4.5 NVidia Refman

A References

A.1 Informative references

3.3 Generated `<g>` element: `class` attributes

3.4 Generated `<g>` element: `id` attribute

4.1.2 Figure `id` attribute

4.1.3 Figure `data-json` attribute

4.1.4 Figure `data-width` attribute

4.1.5 Figure `data-unused` attribute

4.1.6 Figure `data-href` attribute

4.1.7 Figure `data-table` attribute

4.1.8 Figure `data-register` attribute