History

Special Comments in HDL Sources¶

Many HDL sources in the project (including the user's custom sources) will be automatically read and converted into xml block wrappers. The block wrappers contain all of the information about the HDL source that is needed by the GUI: parameters, ports, data types, etc... One may wish to define additional meta-data inside the source by using FlexHDR's special commenting system. These special comments are extracted automatically by the lexer and written into the xml block wrappers. Special comments begin with a --@ (vhdl only) and usually have a key then a value. Ex: --@key "value"

Note: the following are vhdl examples only, since there is currently no verilog lexer.

The Name Comment¶

The name comment defines the displayable name for blocks, parameters, or ports. When the name is not defined, the gui infers a displayable name from the other information.

Block Name¶

--@name "My Source" 
entity my_source_block is
    generic (

Param Name¶

generic (
    --@name "Data Width" 
    data_width: integer := 16;
    --@name "Address Width" 
    addr_width: integer := 4;

Port Name¶

port (
    clk: in std_logic;
    --@name "Reset (async)" 
    rst: in std_logic;
    --@name Accumulator
    accum: out signed(15 downto 0);

The Category Comment¶

The category comment defines the placement of the block into the category tree. The category is a unix-style pathname. The category comment line must come right before the entity declaration, but its ordering in relation to other comments does not matter. The following example will put a block named "My Source" into the /Sources/Demo category:

--@category Sources/Demo
--@name "My Source" 
entity my_source_block is
    generic (

Note: The starting slash (/) at the beginning of the category path is optional. However, to place the block into the root category itself, the slash is required: *--@category /

Aggregate Ports¶

Several ports can be grouped into one aggregate port. The gui will display the group of ports as one port, and all the connection logic will deal with the group of ports as a single port. Aggregate ports can be useful to group ports that commonly appear together. For example, suppose that there is a data bus with several status wires, and the bus + status wires always appear together for the IO in many different blocks. It would be useful to treat this bus + status wires as a single port because 1) this is a good abstraction and 2) this makes conceptual sense.

In FlexHDR, the most common type of aggregate port is the sfixed_stream (see example below). This aggregate port is a combination of a data, ready, and valid signal (see avalon streaming). Notice that the ports inside the aggregate port do not have to agree in direction. Also, the sub-ports inside the aggregate port must always appear in the same order for every instance of that type (ie sfixed_stream).

The sub-ports inside the aggregate port are encapsulated by the --{* and *--} comments. The --type <type>* and *--@direction <direction>* comments specify the type and directionality of the port. The <direction> can be +source+ or +sink+ and type must be a well known type identifier (to be documented). The +source+ direction can be thought of as output coming from the block; and the +sink+ direction can be thought of as input going into the block. The type and direction (and optionally name) comments must come before the opening comment, *--{ and can be in any order. The type and directionality of the aggregate port can be specified in the opening comment in the simplified format: --@<direction> <type>{.

--@name in
--@type sfixed_stream
--@direction sink
--@{
in_data: in sfixed(upper downto lower);
in_valid: in std_logic;
in_ready: out std_logic
--@}

Simplified Format

--@name in
--@sink sfixed_stream{
in_data: in sfixed(upper downto lower);
in_valid: in std_logic;
in_ready: out std_logic
--@}

The Doc Comment¶

The doc comment defines a documentation string for the entity. The doc comment must come before the entity declaration, but its ordering in relation to other comments does not matter.
Single Line Doc

--@name "My Source" 
--@doc "This is a block" 
entity my_source_block is
    generic (

Multi Line Doc

--@doc{
--@ This is a block.
--@ It can be useful.
--@}
--@name "My Source" 
entity my_source_block is
    generic (

FlexHDR

Wiki