-
Notifications
You must be signed in to change notification settings - Fork 141
RegisterSystem20
%INCLUDE{"RegisterSystem20Contents"}%
This page describes a proposed register system to replace the current register system within NetFPGA. The proposed system uses XML to describe the registers within modules and designs -- these XML files are then translated into Verilog, C and Perl as appropriate. The new system allows each module to define a set of registers; a project is then able to combine the register declarations from it's constituent modules.
Current status and tasks are summarized in this section.
- Define XML schema (mostly complete)
- Note: will not be considered complete until the reference router registers has been expressed in XML
- Generate XML definitions for the reference router (mostly complete)
- Create tools to convert XML to:
- Verilog
- C
- Perl
Blocked by: definition of XML schema
- Define requirements
The current register system is one of the most difficult components of the NetFPGA system to understand and work with. Registers are declared in either a global or project-specific register definition file. Within either file, register blocks must be declared for the containing module, the register must be declared within the block, a section must be added that combines the individual register with the block address to create a globally-unique address, and finally a statement must be added to print the register to allow it to be copied into the C and Perl defines files. The process of adding new registers or blocks of registers is error prone because of the number of steps and because of the need to manually ensure that register blocks don't overlap.
The current register system also makes it very difficult for end-users to contribute modules back to the community since the registers need to be added to the global register defines file. (A user can contribute a project containing one or more custom modules if the registers are declared in the project-specific register defines file.)
Additionally, the primary register defines files are Verilog files. A simulator must be invoked to execute the Verilog defines file to enable the generation of the C and Perl defines files.
The following list outlines the main features of the proposed system:
XML-based definition files:
The primary register definition files would be written in XML. The Verilog, C and Perl definition files would be automatically generated from the appropriate XML files. The eliminates the need to invoke a Verilog simulator to update the C/Perl defines files. Applications may also chose to work directly with the XML file instead of the language-specific files, enabling generic utilities to be written to view/manipulate registers within designs.
There would be multiple XML files:
<br /> '''Module-specific''' : describes registers/types/constants in a single module.
<br /> '''Project-specific''' : describes global constants/types/registers for a project and how modules are connected.
<br /> '''Common''' : describes types/registers/constants that are available in or common to all projects.
Modules have associated defines files:
A particular set of registers are instantiated within a module--as such it makes sense to associate the defines file with the module. This better enables sharing of modules as a register defines file would be distributed with each module. It also eliminates the problem of having one central location where all registers must be declared.
Projects pull in the defines files from the modules they use:
Projects specify the modules they use and the module-specific defines files will be pulled in
Automatic address allocation with hints/preferred addresses:
The register system should automatically allocate address ranges to each block to ensure conflict-free address allocation. A "hinting" or preferred address mechanism should exist to enable a developer to specify a preferred address for a module to enable the module to have a consistent address across projects.
Automatic conflict detection:
The system should detect conflicting addresses and warn the user.
User defined types:
The system should allow the user to define types to improve readability and to enable centralized changes to a set of registers that have a common meaning.
Replacement of lib_modules.txt:
The modules to be included in a project are listed in the XML files described in this proposal. lib_modules.txt serves no other purpose than to list the modules to include and can be replaced by the project XML file.
A number of abstractions are useful when considering the register system. These abstractions are useful both for the purposes of discussion and as useful decompositions for hierarchical organization. This section describes some abstractions.
Types are used to classify the data contained within registers. They provide information about the content of a register or group of registers in addition to a name and width. Types provide a mechanism that:
- provides meaning beyond the name and width when declaring a register
- ensures uniform properties across a group of registers that should store data of the same type
- allows for the description of bit masks
- can be used to describe a group of registers that belong together such as a table entry or an equivalent of a C struct.
name : Name to describe the data type (should be unique across all types included in a project):
- width : Width in bits
bitmasks : ''(Optional)'' :
Bitmasks to assist in manipulating fields within the type
Examples:
- Ethernet address (48 bits)
- IP address (32 bits)
It is often useful to create a grouping of a of elements that form a logical whole. An example is an entry in a switch MAC table—the entry consists of a MAC address and a port.
Compound types should be treated identically to basic types. Compound types should be usable wherever basic types can be used. Elements:
name : Name to describe the compound data type (should be unique across all types included in a project):
- fields: Fields contained in the compound type where each element is described by:
- name : Name to describe the field
- type/width : The data type or width of the field
Tables are common data structures that used in numerous designs. Special data types have been created to help describe and to aid in the use of generic table modules.
Elements:
name : Name to describe the table data type (should be unique across all types included in a project):
- type : Table type that describes how rows are accessed. Currently the only supported type is:
<br />* <tt>indirect</tt> —access to rows is indirect. To write into the table the row is written into a set of shadow registers and then an address is written into a ''write'' register. To read from the table an address is written into a ''read'' register and then the data is read from the set of shadow registers. depth : Number of rows in the table:
- type/width : Data type or width of each row
Registers are the basic elements that provide a mechanism for communication between hardware and software.
Elements:
name : Name of register:
- width / type
Either a width or a type may be specified. A width is specified in bits; a type refers to a previously declared data type.
Modules provide zero or more registers to enable software to observe and control the behavior of the module. A module should provide a description of the register block that it wishes to export.
Elements:
name : Name of the module:
- location : Location of the module. The location can be either " core " or " udp " (User Data Path).
blocksize : ''(optional)'' :
Specifies the size of the block in bytes. If this parameter is specified the block will be allocated an address range of this size. An error will be reported if the blocksize if too small for the number of registers. If this parameter is omitted, the register system will allocate an address range that is large enough to address all declared registers.
preferred base : ''(optional)'' :
The preferred base address for this module.
force base : ''(optional)'' :
Force the base address for this module to the specified value.
Note: preferred base and force base should not be specified at the same time
types : ''(optional)'' :
The list of new types defined by the module.
registers : The list of registers exported by the module. As much as possible, these should be specified as typed variables rather than as generic 32-bit registers.:
- constants : (optional)
A list of any constants
Projects combine modules to process packets in whatever manner is appropriate for the project. A project should export the entire set of registers offered by it's modules.
Elements:
name : Project name:
- modules : List of modules. This list should contain:
- module path
- number of instances (optional -- defaults to 1)
- base address (optional)
constants : ''(optional)'' :
List of constants exported by project
registers : ''(optional)'' :
The list of registers exported by the module. As much as possible, these should be specified as typed variables rather than as generic 32-bit registers.
types : ''(optional)'' :
List of new types defined by the project
Types and constants that are useful across most/all projects should be declared in a global defines file.
Elements:
constants : ''(optional)'' :
List of constants exported by project
types : ''(optional)'' :
List of new types defined by the project
The proposed XML schema can be found on the XML schema page.
The Verilog output produced by the translation process from the project XML files should contain:
- All project-specific constants. Names should be identical to those declared in the project XML.
- For each module:
- An address width that indicates how many bits of the address represent the individual registers within the module.
- A list of register/address pairs. The address is relative to the module only . Each register name should be a concatenation of the module name and the register name.
- All module-specific constants. Names should be a concatenation of the module name and the constant name.
- For each module instance :
- An address tag that uniquely identifies the instance
- For each referenced type:
- Widths for each type. Name should be a concatenation of the type name and the word "_width"
- List of bitmasks. Names should be a concatenation of the type name and the bitmask name.
- Low and high positions for fields within compound types. Names should be a concatenation of the type name and the words "_lo" and "_hi"
The C/Perl output produced by the translation process from the project XML files should contain:
- All project-specific constants. Names should be identical to those declared in the project XML.
- For each module:
- All module-specific constants. Names should be a concatenation of the module name and the constant name.
- For each module instance :
- The base address of the instance.
- A list of register/address pairs. The address is the global address of the register. Each register name should be a concatenation of the module name, instance number (if there is more than one instance) and the register name.
- For each referenced type:
- List of bitmasks. Names should be a concatenation of the type name and the bitmask name.
- struct/hashes/lists if it makes sense to enable easier manipulation of data types that span multiple registers.
This section presents an example project and associated modules to illustrate the new register system in action. The example project is a basic learning switch, consisting of modules for Ethernet MACs, an input arbiter, a learning switch output port lookup module, and SRAM output queues. The registers defined within the modules are:
'''Ethernet MAC''' :
|
|
| RX_QUEUE_NUM_PKTS_DROPPED | Total number of packets dropped in the RX queue |
| RX_QUEUE_NUM_PKTS_ENQUEUED | Total number of packets stored in the RX queue |
| RX_QUEUE_NUM_PKTS_DEQUEUED | Total number of packets removed from the RX queue |
| TX_QUEUE_NUM_PKTS_ENQUEUED | Total number of packets stored in the TX queue |
| TX_QUEUE_NUM_PKTS_DEQUEUED | Total number of packets removed from the TX queue |
'''Input Arbiter''' :
|
|
| colspan="2" No registers |
'''Learning switch output port lookup''' :
|
|
| LAST_MAC | the MAC address in the last-seen packet |
| MAC_TABLE | specifies location where an entry in the MAC table consisting of the MAC address, the associated output port, and the index of the entry in the table can be written/read from. |
'''Output queues''' :
Per queue:
|
|
| CTRL | Queue control |
| RD_ADDR | Read address of queue in SRAM |
| WR_ADDR | Write address of queue in SRAM |
| LO_ADDR | Low address of queue in SRAM |
| HI_ADDR | High address of queue in SRAM |
Note: The modules listed above are examples only. The registers within the modules differ from the registers in the modules distributed with the NetFPGA system.
Note: The following code snippets are placeholder only. It may not reflect the descriptions above. It should be updated to represent a real example.
Refer to XML examples for the XML register definitions for the reference router.