Vregs Example Specification

# 1 Vregs

This document shows example register layouts that the SystemC::Vregs package understands.

Please see

man vreg

and

man SystemC::Vregs

and/or

http://www.veripool.org/vregs

for information on the program and package.

# 2 Package Attributes

Description

A “package” header specifies an optional global header which vregs uses to establish overall information about the specification. This may be put into “hidden” text if the word processor supports it.

Package

vregs_spec

Attributes

-netorder

A header called “Attributes” specifies special actions for the entire package.

Attribute | Description
-v2k | For Verilog files, use Verilog-2001 constructs, namely localparam instead of parameter.
-netorder | Store all structures in network order. Have all accessor functions pack and unpack to host order.

# 3 Definitions

## 3.1 Description

A definition section starts with the word “Defines” alone on a line. Vregs will create #define statements for each mnemonic/constant pair. The name following the Defines header is prepended to all defines, thus in the example below CMP_ will be prepended. If this is not desired, use a single _ instead of the “CMP” below.

A header called “Attributes” before the header specifies special actions for the enum.

Attribute | Description
-freeform | Allow free-form text in the constant section. Without this attribute, vregs will assume all constants are Verilog-format numbers.

There are three columns for each define. Columns can be in any order.

The constant column is the value for the define. Numeric values are in Verilog format, with the width and a h/d/b for hex, decimal and binary, respectively. Underscores can be used to separate digits; they are ignored. String and other formats are not supported yet.

The mnemonic column is the name of the define, appended to the Defines prefix. The Mnemonic must be all upper case.

The definition column is a comment on what the define is used for. The first sentence is added as a comment to the output files. Italizing this first sentence is useful in highlighting this extraction.

Any additional columns must have header titles in parenthesis. If data in that column contains alphanumeric data, the data will be added as an attribute to the define. This is not used by vregs itself, but is useful for locally written extentions.

If constants are being defined for a series of values, a enumeration is probably a better way to do it.

## 3.2 Example Definitions

Description

This table shows an example definition table. The information in the header below is prepended with a underscore to all mnemonics, to prevent the global name space of defines from causing trouble.

Defines

CMP

Constant | Mnemonic | Definition (header comments in parenthesis)
4’d1 | DEFINED_ONE | Definition One. Text up to the first period will be annotated into the output files.
48’hfeed | DEFINED_FOOD | Definition of Food.

## 3.3 More Definitions

Description

This table shows an example freeform definition table.

Defines

FREE

Attributes

-allowlc -freeform

Constant | Mnemonic | Definition (header comments in parenthesis)
-1.2345 | DOUBLE | Definition. Text up to the first period will be annotated into the output files.
Foobar | Stringdef | Definition.

# 4 Enumerations

## 4.1 Description

A enumeration triggers off from the word “Enum” alone on a line. Vregs will create a C++ enumeration for the values, and Verilog #defines for each of the values in the enumeration.

A header called “Attributes” before the header specifies special actions for the enum.

Attribute | Description
-descfunc | Create a C++ function to retrieve the description given the enumeration value.

There are three columns for each value in the enumeration. Columns can be in any order.

The constant column is the value for the mnemonic. Values are in Verilog format, with the width and a h/d/b for hex, decimal and binary, respectively. Underscores can be used to separate digits; they are ignored.

The mnemonic column is the name of this enumeration value. The Mnemonic must be all upper case. Underscores are acceptable, but discouraged.

The definition column is a comment on what the enumeration value is used for. The first sentence is added as a comment to the output files. Italizing this first sentence is useful in highlight ing this extraction.

Any additional columns must have header titles in parenthesis. If data in that column contains alphanumeric data, the data will be added as an attribute to the define. This is not used by vregs itself, but is useful for locally written extentions.

A table row may have a empty mnemonic column if the definition contains the text “reserved”.

## 4.2 Example Enumeration (This header is ignored)

Description

This table shows an example enumeration table.

Enum

ExEnum

Attributes

-descfunc

Constant (comments) | Mnemonic | Definition (header comments in parenthesis)
4’b0000 |  | Reserved
4’b0001 | ONE | Command One. Text up to the first period will be annotated into the output files.
4’b0010 | TWO | Command Two.
4’d5 | FIVE | Command Five. Number in decimal.
4’he | FOURTEEN | Command Fourteen. Number in hex.

## 4.3 Another Enumeration

Description

This table shows an enumeration that references another enumeration.

Enum

ExSuperEnum

Attributes

-descfunc

Constant (comments) | Mnemonic | Definition (header comments in parenthesis)
8’h0_0 |  | Reserved.
8’h2_0 | A | Sub Enum A ENUM:ExEnum. References that values under the enumeration ExEnum should be included here, starting at 8’h2_0 upto 8’h2_F.
(8’h2_F) |  | (Just a comment so users know that the previous enum extends up through 2F.)
8’h3_0 | B | Sub Enum B ENUM:ExEnum. References that values under the enumeration ExEnum should be included here, starting at 8’h3_0 upto 8’h3_F.
(8’h3_F) |  | (Just a comment so users know that the previous enum extends up through 3F.)
8’hF_E | PRELAST | Simple values. Simple values are fine too.

# 5 Class Definitions

## 5.1 Description

Class Declarations key off the word “Class” alone on a line. Classes can inherit other classes by using C++ syntax: “DerrivedClass : BaseClass”

A header called “Attributes” before the header specifies special actions for the class.

Attribute | Description
-variablelen | The class is of variable length, with data words appended to the end of the structure. (Future)
-netorder | The structure longwords are in network order. (Big endian).
-noarray | For register types, declares the region as consisting of raw bytes, rather than a array of memory. Thus when asking what the name of a address within the space is, the return will be something like “Ram+0x10” rather than “Ram[4]”.
-stretchable | Allow derrived classes to increase the size of the final structure, rather than just overlaying.

There are six columns for each bitfield in the class. Columns can be in any order.

The bit column defines which bits the field occupies. Bit numbers are then expressed in MSB:LSB order. Bits can be of any width; there is no restriction of their being less than 32. For readability w#[] indicates the bits in the brackets are in a given 32-bit word, 32 times the # will be added to the bit numbers in the brackets. Likewise b# for 8-bit bytes, h# for 16-bit halfwords, and d# for 64-bit doublewords. For example w3[10] is bit 10 in longword 3, equivalent to writing [106] (3*32+10 = 106). Fields may consist of multiple disjoint segments, separated by commas. (w0[15:13] or w0[15,14,13] or w0[15],w0[14],w0[13] are all equivalent.)

The mnemonic column is the name of this field. The Mnemonic must begin with upper case, and can contain mixed case. Underscores are not acceptable, use mixed case instead.

The type is the C++ type of the field. If left blank, single bit fields will be assumed to be “bool” and multiple bit fields will be unsigned integers. The entire column may be deleted if the default is acceptable for all of the fields.

The constant column is used to specify the given bit range always contains a certain value. Often it will be expressed as a enumeration, such as when specifing a command number field inside the layout of one specific command.

The optional product column is used to select which product the definition applies to. Entries in this column will add the “-Product={x}” attribute to the bit entries. When vregs is run with the –if-product option, this setting if specified must match the if-product setting. For example a bitfield with Product=Chipb+ will only be included in the output files when there is no –if-product, when –if-product=Chipb, or when –if-product is anything lexically greater than “Chipb” (because of the + appended to Chipb.)

The definition column is a comment on what the field is used for. The first sentence is added as a comment to the output files. Italizing this first sentence is useful in highlight ing this extraction.

Any additional columns must have header titles in parenthesis. If data in that column contains alphanumeric data, the data will be added as an attribute to the define. This is not used by vregs itself, but is useful for locally written extentions.

## 5.2 Example Base Class

Description

This is an example base class definition. In this example, we’ll define ExBase which is a generic format of a message, then we’ll define specific messages.

Class

ExBase

Attributes

-netorder -stretchable

Bit | Mnemonic | Product | Type | Constant | Definition
w0[31:28] | Cmd |  | ExEnum |  | Command Number. Encoding is in the ExMnem table. You’ll see in later derived classes how this specifies which command this generic class represents.
w0[28] | CmdAck |  |  |  | Command Needs Acknowledge. Overlaps Cmd. This is a Boolean field, since it’s one bit and has no specified type. The “overlaps Cmd” field turns off the normal warning that bit 28 is used twice. This is done in this example as one bit of the command always indicates a specific piece of information that we want to extract.
w0[27:24] | FiveBits | Chipb+ |  |  | Five Bits. This field will become a unsigned int.
w0[15:0], w1[31:0] | Address |  | Address |  | Address. This field spans two words to make a wide 48-bit field.

## 5.3 Example Class

Description

This shows a class which inherits the base class defined earlier.

Class

ExClassOne : ExBase

Bit | Mnemonic | Type | Constant | Definition
w0[31:28] | Cmd | ExEnum | ONE | Command Number. This field is a constant, as it indicates that this is message type ONE.

## 5.4 Another Example Class

Description

This is another example class. Note it extends the size of the base class.

Class

ExClassTwo : ExBase

Bit | Mnemonic | Type | Constant | Definition
w0[31:28] | Cmd | ExEnum | TWO | Command Number. Indicates the second command.
w0[27:24] | FiveBits |  |  | Five Bits. You can redeclare fields in the base class, but they must have the same name and mnemonic.
w2[31:0] | Payload |  |  | Another field that this message tacks onto the end of the base class.

## 5.5 Expanded Class

Description

This shows an example class which expands its subclasses.

Class

ExExpand

Bit | Mnemonic | Type | Constant | Definition
w0[0] | Base1 | ExBase |  | Base 1. Expand Class. The ‘expand class’ keyword causes the entire contents of ExBase to be expanded into this class.
w2[0] | Base2 | ExBase |  | Base 2. Expand Class.

# 6 Register Declarations

## 6.1 Definition

Register declarations key off the word “Register” alone on a line. Registers always start with R_, then a name beginning with a capital, and containing no additional underscores. They can also have attributes like the Class Declarations.

Registers can also inherit other registers using the C++ like “DerrivedReg : BaseReg” format. This allows a field definition to be shared among many nearly identical registers. If all the fields are identical to the base register, the derrived register can completely eliminate it’s field table. As a extension of this, you can specify a wildcard “Derrived* : Base*”; which will pull all Base registers into the Derrived section; when this is done, the address specified is added to the address specified in the Base’s declaration, and the end address is checked against the Base’s ending address.

The address is specified in hex, with a leading 0x. The maximum width of the address is coded into the vregs program; it defaults to 40 bits, which is sufficient for most projects.

A attribute of –noimplementation specifies the register has not been implemented, and should be ignored by Vregs. A attribute of –noregtest specifies testing for the register should be suppressed.

The table indicates the bit layout, in the same format as a Class declaration. The Bit, Mnemonic, Type, and Definition columns are all described in the Class declaration chapter. The other columns are as follows:

Reset indicates the value after chip reset. X or N/A indicates not reset. FW0 or FW-(some perl expression) indicates that the value is loaded in by firmware during initialization.

Access indicates read/write, read-only, etc. Read side effects indicate that reading the register can change the value in the register or cause other effects. Write side effects indicate that changing the value may change other registers, and is only used to tell the register testing to skip writing this register.

Access | Read Action | Write Action
R (or RO) | Read Only | Ignored
RW | Read | Write
RWS | Read | Write Side Effect
RS | Read Side Effect | Ignored
RSW | Read Side Effect | Write
RW1C | Read | Write 1 to clear
RH | Read Hardwired (never changes) | Ignored
W (or RO) | Indeterminate return | Write
WS | Indeterminate return | Write Side Effect
L | Flag on any other access indicates this field needs to be written after all other registers. For example a unit “enable” needs to be written after all of the unit’s other registers are written.

## 6.2 Example Register

Description

This is an example register declaration.

Register

R_ExReg1

Address

0x18_FFFF_0000

Bit | Mnemonic | Access | Reset | Type | Definition
31:28 | LastCmd | RW | X | ExEnum | Enumerated field. This field has a value represented by a complex type, in this case an enumeration.
21 | ReadHard | RH | X |  | Read Only Bits. This field is not writable and is not initialized during reset.
20 | ReadOnly | R | 1 |  | Read hardwired Bits. This field is not writable and is hardwired; the read result will never change.
3:0 | LowBits | RW | 0 |  | Random Low Bits. This field takes the whole register. As with Enums and everywhere else, only the first sentence is used to comment the output code.

## 6.3 Another Register, Ranged

Description

This is another register, but it consists of 8 identical arrayed registers. The special optional comment (Add 0x10 per entry) indicates that each entry is 16 bytes apart, rather than the default dense packing of 4 bytes.

Register

R_ExRegTwo[7:0]

Address

0x18_FFFF_1000 – 0x18_FFFF_1070 (Add 0x10 per entry)

Bit | Mnemonic | Access | Reset | Type | Definition
31:0 | WideField | RW | 0 |  | Wide Field. This field takes the whole register.

## 6.4 Another Register, 64 bits

Description

This is another register, but it consists of a 64 bit wide register. The special optional comment (Add 0x8 per entry) indicates that each entry is 8 bytes apart, rather than the default dense packing of 4 bytes.

Register

R_ExRegQuad[7:0]

Address

0x18_FFFF_2000 – 0x18_FFFF_2038 (Add 0x8 per entry)

Bit | Mnemonic | Access | Reset | Type | Definition
31:0 | WideField | RW | 0 |  | Wide Field. This field takes the whole register.
63 | Bit63 | RW | 0 |  | Bit 63.
w1[30] | Bit62 | RW | 0 |  | Bit 62. Using alternate syntax to indicate bit 30 in word number 1.