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.
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. String and other formats are not supported yet.
The mnemonic must be all upper case.
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.
The mnemonic must be all upper case. Underscores are acceptable, but strongly discouraged.
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. Class names must begin with C_. The C_ prefix will be stripped for the real name of the class.
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 must begin with a capital, and contain no underscores.
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.
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.
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 48 bits, which is sufficient for most projects.
The table indicates the bit layout:
The Bit column is the bits the field occupies.
The Mnemonic is the name of the bit field. It begins with a underscore, then a capital. There must be no other underscores in it.
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. |