XML description

AGWB uses XML as file format for describing system registers. There are predefined element names, that must be used for valid description. Each element requires at least one mandatory attribute and may accept some optional attributes.

Why XML?

You may be wondering why XML, why not someting more buzzy like JSON or YAML. Well, XML has something, that is particularly useful for describing hierarchical systems that neither JSON nor YAML have. Namely, it distinguishes block attributes and elements. Attributes function like a metadata of a block and elements are independent entities existing within outter element/block. With JSON or YAML one would have to imitate this structure and it would feel somehow less intuitive. JSON also does not support comments, and with YAML it is a bit harder to spot indentation mistakes in long blocks.

Valid Elements

blackbox

blackbox element can be used for incorporating registers or blocks not generated by the AGWB.

Mandatory attributes:

name - name of the blackbox instance within outter block.
type - type of the blackbox.
addrbits - number of lower address bits used by blackbox for internal addressing.

Optional attributes:

desc - Text describing the block
reps - Number (or semicolon separated list of numbers, if you use variants) defining the number of repetitions (may contain “0” if in certain variant the block is not used). Presence of this attribute enforces implementation as the vector of blocks (even if the length 1 or 0).
used - Number (or semicolon separated list of numbers, if you use variants) defining if the block is used (‘1’) or not used (‘0’). Other values are prohibited. This attribute replaces reps for objects that should not be converted into vectors.
xmlpath - relative path to .xml file with registers not generated by the AGWB.

block

block element is used for grouping registers or other blocks.

Mandatory attribute:

name - name of the block.

#. name - Optional attributes: #. aggr_outs - If set to one, all outputs of the block are aggregated into a single output named out_regs. That functionality is useful, if you need to route the output of the block to another VHDL entity (you route a single record signal instead of multiple signals). #. reserved - This optional argument reserves certain number of words at the begining of the address space. #. testdev_ena - If this attribute is set to the true (non-zero) value, it enables generation of a test device at the begining of the address space of the block. #. desc - Text describing the block #. ignore - This attribute informs that this block, and all its children should be ignored in certain backend. Currently only the ‘forth’ value has a meaning. It protects the Forth vocabulary against the overflow by multiple names that are not going to be used by the Forth CPU. The value may be overriden by ignore argument in a subblock or a child.

Example

<block name="top">
   <blackbox name="EXTHUGE" type="HTEST" addrbits="16" />
   <subblock name="LINKS" type="SYS1" reps="NSEL_MAX"/>
   <creg name="CTRL" desc="Control register in the top block" default="0x11">
      <field name="CLK_FREQ" width="4"/>
      <field name="PLL_RESET" width="1"/>
   </creg>
</block>

creg can contain field elements, see field.

constant

constant allows for definig constant number, which can later be used for parameterizing registers or blocks.

Mandatory attributes:

name - name of the constant.
val- value of the constant.
desc - extra description of the constant.

Example

<constant name="NUMBER_OF_BITS" val="3" />

creg

creg stands for control register and should be used to describe registers that are supposed to be both written and read by the software.

Mandatory attribute:

name - name of the control register.

Optional attributes:

default - default value stored in the register, this value is also applied after reset.
desc - extra description of the control register.
mode - special attribute, directly passed to the generated IPbus XML file.
reps - Number (or semicolon separated list of numbers, if you use variants) defining the number of repetitions (may contain “0” if in certain variant the block is not used). Presence of this attribute enforces implementation as the vector of registers (even if the length 1 or 0).
used - Number (or semicolon separated list of numbers, if you use variants) defining if the register is used (‘1’) or not used (‘0’). Other values are prohibited. This attribute replaces reps for objects that should not be converted into vectors.
stb - setting this to 1 enables the stb signal, that is asserted for one clock pulse whenever the new value is written. Useful for FIFO write.
stype - Allows the user to define non-standard type name for the register. Otherwise the type is obtained from the register name, which may lead to collisions in the HDL namespace (if two blocks, have registers with the same name, but with different fields, width, or other properties).
type - type of the register. The default value is ‘std_logic_vector’. May be also seto to ‘signed’ or ‘unsigned’.
width - width of the register in bits.
ignore - This attribute informs that this register, and all its fields should be ignored in certain backend. Currently only the ‘forth’ value has a meaning. It protects the Forth vocabulary against the overflow by multiple names that are not going to be used by the Forth CPU. The value may be overriden by ignore argument in a field.

field

field element is used to define bit fields within register.

Mandatory attributes:

name - name of the field.
width - width of the field in bits.

Optional attribute:

type - type of the bit field. The default value is ‘std_logic_vector’. May be also seto to ‘signed’ or ‘unsigned’.
desc - description of the bit field.
default - defaut value of the bit field.
ignore - This attribute informs that this field. Currently only the ‘forth’ value has a meaning. It protects the Forth vocabulary against the overflow by multiple names that are not going to be used by the Forth CPU.
trigger - This attribute if set to true, informs that this field is a ‘trigger’. It means, that if written, the written value is available only for one clock period. It is always read as zero. The ‘trigger’ fields should be used for launching certain actions in the hardware.

Example

<sreg name="throughput">
   <field name="val" width="30" type="unsigned" />
   <field name="prev_missed" width="1" />
   <field name="read" width="1" />
</sreg>

include

include element allows including .xml files. This is very useful functionality, as different modules can be placed in different repositories and reused in different projects. Each module (entity) can have its own .xml file with block definition related strictly to this module.

Example

<include path="relative/path/to/block.xml"/>

sreg

sreg stands for status register and should be used to describe registers that are supposed to be read only by software.

Mandatory attribute:

name - name of the status register.

Optional attributes:

ack - setting this to 1 enables the ack signal, that is asserted for one clock pulse when the value is read.
desc - extra description of the register.
mode - special attribute, directly passed to the generated IPbus XML file.
reps - Number (or semicolon separated list of numbers, if you use variants) defining the number of repetitions (may contain “0” if in certain variant the block is not used). Presence of this attribute enforces implementation as the vector of registers (even if the length 1 or 0).
used - Number (or semicolon separated list of numbers, if you use variants) defining if the register is used (‘1’) or not used (‘0’). Other values are prohibited. This attribute replaces reps for objects that should not be converted into vectors.
stype - Allows the user to define non-standard type name for the register. Otherwise the type is obtained from the register name, which may lead to collisions in the HDL namespace (if two blocks, have registers with the same name, but with different fields, width, or other properties).
type - type of the register. The default value is ‘std_logic_vector’. May be also seto to ‘signed’ or ‘unsigned’.
width - width of the register in bits.
ignore - This attribute informs that this register, and all its fields should be ignored in certain backend. Currently only the ‘forth’ value has a meaning. It protects the Forth vocabulary against the overflow by multiple names that are not going to be used by the Forth CPU. The value may be overriden by ignore argument in a field.

Example

<sreg name="my_reg" ack="1" default="0x0" desc="Some diagnostic registers." reps="8" width="16" />

sreg can contain field elements, see field.

subblock

subblock element is used to include some block into another block.

Mandatory attributes:

name- name of the subblock instance within outter block.
type- type of the subblock. This is name of the subblock definition.

Optional attributes:

desc - extra description of the subblock.
ignore - This attribute informs that this register, and all its fields should be ignored in certain backend. Currently only the ‘forth’ value has a meaning. It protects the Forth vocabulary against the overflow by multiple names that are not going to be used by the Forth CPU. The value may be overriden by ignore argument in a field.
reps - Number (or semicolon separated list of numbers, if you use variants) defining the number of repetitions (may contain “0” if in certain variant the block is not used). Presence of this attribute enforces implementation as the vector of registers (even if the length 1 or 0).
used - Number (or semicolon separated list of numbers, if you use variants) defining if the register is used (‘1’) or not used (‘0’). Other values are prohibited. This attribute replaces reps for objects that should not be converted into vectors.

Example

<block name="data_processing">
   <creg name="enable" width="1" />
   <sreg name="throughput" reps="9" ack="1">
      <field name="val" type="unsigned" width="30" />
      <field name="prev_missed" width="1" />
      <field name="read" width="1" />
   </sreg>
</block>

<block name="wfifo">
   <creg name="data" mode="non-incremental" stb="1" />
   <sreg name="unused" ack="1" type="unsigned" />
   <sreg name="valid_writes" type="unsigned" />
</block>

<block name="main">
   <subblock name="write_fifo" type="wfifo" desc="Some extra description." />
   <subblock name="dproc" type="data_processing" reps="2" />
</block>

sysdef

sysdef must be a root element.

Mandatory attribute:

top - designates the block which should be used as a top level for registers generation.

Optional attribute:

masters - number of Wishbone masters controlling the local bus (default value is 1).

Example

<sysdef top="foo" masters="2">
   <block name="foo">
      ...
   </block>

   <block name="bar">
      ...
   </block>
</sysdef>

Math within attribute value

The attribute values may be specified as a valid Python number, ar as a valid Python expression. The expressions are evaluated using the code based on https://stackoverflow.com/a/30516254/1735409 . Therefore, only certain subset of Python functions are available. The expression make make use of the constants defined in the system description XML. However, one must be aware, that as epxressions are stored in the XML file, so certain characters mas be escaped:

& with &amp;
< with &lt;
> with &gt;
" with &quot;

That may affect legibility of certain expressions. For example the expression: 1 << ADDRWIDTH must be written as 1 << ADDRWIDTH

Notes

reps attribute

The reps attribute is used for defining vectors of blocks/registers. It enforces the implementation of the particular instance to be treated as a vector even if the value equals 1 or 0. This is useful for parametrized designs, when sometimes the parameter describing the number of implemented blocks or registers may equal 1, and sometimes may equal value greater than 1. With such approach implemented codes are very flexible and need no modification.

ignore attribute

The ignore attribute is used for ignoring generation of definitions for certain blocks for particular backends. The atribute may be specified either in the definition of the block (igoring all its instances) or in the instantiation of the block, or in the definition of a register. Currently ignore attribute has effect only in case of Forth backend. It is possible to extend that functionality to other backends.

Example

<block name="my_block">
  <subblock name="links" type="sys1" reps="N_SEL_MAX" ignore="forth"/>
  <subblock name="olinks" type="sys1"/>
</block>

variants

To be described. At the moment, please look at https://github.com/wzab/agwb/wiki/Multiple-AGWB-trees for information about the reason for introducing the variants.