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.
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 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.
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. |
|
|
|
|
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”.
Description
This table shows an example enumeration table.
Enum
ExEnum
|
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. |
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.
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], |
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.
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. |
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. |
|
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. |
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. |