Vregs Example Specification

# 1 Vregs

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

man vregs

and

man SystemC::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

# 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.

There are three columns for each value in the enumeration. 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 highlight ing this extraction.

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.

# 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.

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.

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

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.

# 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 then 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 then “Ram[4]”.

There are five columns for each value in the enumeration. 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 then 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. For example w3[10] is bit 10 in longword 3, equivelent 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 equivelent.)

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 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.

## 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

Bit | Mnemonic | 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 |  |  | 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.

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.

# 6 Register Declarations

## 6.1 Definition

Register declarations key off the word “Mnemonic” 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 elimintate 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.

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
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
WO | 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.
20 | ReadOnly | RO | X |  | Read Only Bits. This field is not writable and is not initialized during reset.
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 then the default dense packing of 4 bytes.

Register

R_ExRegTwo[7:0]

Address

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

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