Register System

This page describes the register system that was introduced with the NetFPGA 2.0.0 package release.

Show Contents...Hide Contents...

Overview

The register system assigns addresses to all registers in a project.

Each project has a configuration file that specifies the modules that it uses, and each module has a configuration file that specifies the registers that it provides. The register system reads a project's configuration file to identify the modules (and number of instances of each module); reads the individual module configuration files; allocates memory in the register address space to each module instance and it's registers; and finally outputs Verilog, C, and Perl files with the register allocation.

Operation

Operation of the register system is summarized in the diagram below.

Steps in the allocation process are:

1. Begin processing when the user invokes register generation via nf_register_gen.pl or when the user simulates or synthesizes a project.
2. Read all global configuration files from lib/verilog/core/common/xml.
3. Read the project's project.xml configuration file from projects/<project_dir>/include.
4. Read the configuration files for all modules specified in the project's nf:use_modules section.
5. Read the configuration files for any locally defined modules. (Configuration files for locally-defined modules are placed in the same directory as project.xml.)
6. Identify the modules used by the project as specified in the project's nf:mem_alloc section.
7. Identify and read any shared configuration files used by the modules. (Shared configuration files are used to share common constants and types.)
8. Identify all constants defined in the project and the modules. (Precedence from highest to lowest is: project, shared, module, global.)
9. Identify all types defined in the projects and modules. Types must be unique; it is an error for the same type to be defined in two different configuration files.
10. Expand all constants.
11. Verify that the specified module sizes are large enough to contain the specified number of registers.
12. Allocate memory to each module, and to each register within each module.
13. Output the Verilog, C, and Perl files.

Configuration files

Configuration files can be broadly classified as one of four types: project, module, global, and shared. Each of these files are explained below, with the elements listed in Configuration file elements.

Project configuration file

The project configuration file describes the project, listing the library modules, and specifying the memory layout. The file is named project.xml and is located in the project's include directory.

An example project configuration file is listed below. This file defines a project named "Project example", version 1.0.2, with the unique device ID 100. It uses two library modules (cpu_dma_queue and ethernet_mac), and it uses the reference memory layout. (For more information on memory layouts see FIXME.)

<nf:project ...> <nf:name>Project example</nf:name> <nf:description>Example of a project.xml file</nf:description> <nf:version_major>1</nf:version_major> <nf:version_minor>0</nf:version_minor> <nf:version_revision>2</nf:version_revision> <nf:dev_id>100</nf:dev_id> <nf:use_modules> core/io_queues/cpu_dma_queue core/io_queues/ethernet_mac </nf:use_modules> <nf:memalloc layout="reference"> <nf:group name="core1"> <nf:instance name="device_id" /> <nf:instance name="dma" base="0x0500000" /> <nf:instance name="nf2_mac_grp" count="4" /> </nf:group> <nf:group name="udp"> <nf:instance name="in_arb" /> <nf:instance name="router_op_lut" /> </nf:group> </nf:memalloc> </nf:project>

Valid elements that can be declared in a project configuration file are:

Element	Count	Comment
nf:name	1	Short name of the project
nf:description	0/1	Textual description of the project
nf:version_major	0/1	Version number (major)
nf:version_minor	0/1	Version number (minor)
nf:version_revision	0/1	Version number (revision)
nf:dev_id	0/1	Unique numeric identifier for the project (refer to the Device ID List)
nf:constants	0/1	Constant definitions
nf:types	0/1	Type definitions
nf:use_modules	0/1	Library modules used by the project
nf:memalloc	1	Memory layout/allocation

Module configuration file

Each module has a configuration file that specifies the list of registers that it provides. The configuration file may also specify constants and types, and may reference shared configuration files for additional constants and types. It also specifies the "location" (the region of the NetFPGA where the module should be used) and the size of the memory block that the module should be allocated.

Module configuration files should be located in the xml directory inside the module directory if the module is a library module, or within the project's include directory if the module is local to the project.

An example configuration file is provided below. This file declares a simple input arbiter. The module should be instantied within the user datapath (UDP), it should be allocated 256 bytes of memory, and it provides one register.

<nf:module ... > <nf:name>in_arb</nf:name> <nf:prefix>in_arb</nf:prefix> <nf:location>udp</nf:location> <nf:description>Simple round-robin input arbiter</nf:description> <nf:blocksize>256</nf:blocksize> <nf:registers> <nf:register> <nf:name>num_pkts_sent</nf:name> <nf:description>Number of packets sent</nf:description> <nf:type>counter32</nf:type> </nf:register> </nf:registers> </nf:module>

Valid elements that can be declared in a module configuration file are:

Element	Count	Comment
nf:name	1	Short name of the module (used in the nf:memalloc section of the project configuration)
nf:prefix	1	Prefix to prepend to all registers
nf:location	1	Location within the NetFPGA where the module can be instantiated
nf:description	0/1	Longer description of the module
nf:blocksize	1	Memory to allocate to each instance (bytes)
nf:preferred_base	0/1	Preferred base address. Do not use with nf:force_base.
nf:force_base	0/1	Force this base address. Do not use with nf:preferred_base.
nf:registers	0/1	Registers definitions
nf:constants	0/1	Contstant defnitions
nf:types	0/1	Type definitions
nf:use_shared	0/1	Shared configuration files to include

Global configuration file

Global configuration files specify constants and types that should be used by all projects. Projects (and modules) can override global constants. Global configuration files are located in lib/verilog/core/common/xml.

An example global configuration file is provided below. The file defines one constant and one type.

<nf:global ... > <nf:constants> <nf:constant> <nf:name>MAX_PHY_PORTS</nf:name> <nf:description>Maximum number of phy ports</nf:description> <nf:value>4</nf:value> </nf:constant> </nf:constants> <nf:types> <nf:type xsi:type="nf:SimpleType"> <nf:name>ethernet_addr</nf:name> <nf:width>48</nf:width> </nf:type> </nf:types> </nf:global>

Valid elements that can be declared in a global configuration file are:

Element	Count	Comment
nf:constants	0/1	Contstant defnitions
nf:types	0/1	Type definitions

Shared configuration file

Shared configuration files specify constants and types that are shared by some modules. Each module should reference the shared configuration file to include the constants and types.

Note: Shared configuration files and global configurations are almost identical in structure.

An example shared configuration file is provided below. The file defines one constant.

<nf:shared ... > <nf:description>Example shared constants</nf:description> <nf:constants> <nf:constant> <nf:name>ETHERTYPE</nf:name> <nf:description>Example ethertype</nf:description> <nf:value>0xffab</nf:value> <nf:width>16</nf:width> </nf:constant> </nf:constants> </nf:shared>

Valid elements that can be declared in a shared configuration file are:

Element	Count	Comment
nf:description	0/1	Description of shared configuration
nf:constants	0/1	Contstant defnitions
nf:types	0/1	Type definitions

Example configuration files

• Reference router project
• Input arbiter module
• SRAM output queues module

Configuration file elements (XML elements)

Configuration file elements are listed in the Configuration file elements.

Types

Types were introduced for two reasons: to aid the understanding of the "kind" of data that particular registers hold, and to generate code to simplify register processing in C and Perl. Strictly speaking types are not needed. All registers could be defined by specifying the width of the register.

There are three main categories of types: simple, compound, and table. (See nf:type)

Simple types represent a single "thing", such as a MAC or IP address, or a collection of "things" identified by their bit positions, such as an interrupt vector.

Compound types represent collections of things. A compound type is composed of fields, each field can be either another type or a width. Compound types and simple types with bitmasks are very similar, the main difference is that a compound type can be composed of other types. (A simple type with bitmasks could be equivalently expressed as a compound type with fields specified by widths.)

Table types represent table data structures. A table is an element composed of rows, with each row containing data of the same type. Tables have multiple rows, the number of which is defined by the table's depth.

Predefined types

Nine simple data types are predefined in the global configuration files. Those types are:

Type	Width (bits)	Description
ethernet_addr	48	Ethernet MAC address
ip_addr	32	IP address
counter32	32	32-bit counter
software32	32	32-bit register written to by software
generic_counter32	32	32-bit counter Implemented as part of a generic registers instance
generic_hardware32	32	32-bit register controlled by hardware (read-only by software) Implemented as part of a generic registers instance
generic_software32	32	32-bit register controlled by software (written by software, read-only by hardware) Implemented as part of a generic registers instance
dataword	64 (DATA_WIDTH)	Data word in the data path
ctrlword	8 (CTRL_WIDTH)	Control word in the data path