This document shows example register layouts that the SystemC::Vregs package understands.
Please see
man vreg
and
man SystemC::Vregs
and/or
for information on the program and package.
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. |
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.
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 |
|
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. |
Description
This table shows an example freeform definition table.
Defines
FREE
Attributes
-allowlc -freeform
|
Constant |
Mnemonic |
Definition |
|
-1.2345 |
DOUBLE |
Definition. Text up to the first period will be annotated into the output files. |
|
Foobar |
Stringdef |
Definition. |
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”.
Description
This table shows an example enumeration table.
Enum
ExEnum
Attributes
-descfunc
|
Constant |
Mnemonic |
Definition |
|
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. |
Description
This table shows an enumeration that references another enumeration.
Enum
ExSuperEnum
Attributes
-descfunc
|
Constant |
Mnemonic |
Definition |
|
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. |
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.
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], |
Address |
Address |
Address. This field spans two words to make a wide 48-bit field. |
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. |
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. |
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. |
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. |
|
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. |
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. |
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. |