3. Developer Documentation¶
Developers manage the code generated by WupperCodeGen. The output is defined by Jinja2 template files, usually ending in ‘.template’.
3.1. Template Files¶
The template files should be written using Jinja2
syntax. Jinja2 statements can be either flow control commands such as {% for g
in groups %} or simple text substitutions such as {{ g.name }}. For a
detailed description of the Jinja2 language, please refer to the official
documentation, but look below for the
special codes to use for LaTeX templates.
The data retrieved from the input file (yaml) is available as variables in the template. Those variables are listed in the user documentation. Apart from these variables one may call a number of functions and filters as explained below.
The following global variables are available:
- metadata
- A dictionary with some metadata, available for the config file and the template.
- tree
- The root of all the nodes, e.g. the one named ‘Registers’.
- registers
- A list of all the registers. All registers are linked into the tree by their ‘parent’ attribute.
- nodes
- A lookup table of all nodes, stored by name or full_name. All nodes are linked
- into the tree by their ‘parent’ attribute.
3.2. Functions¶
Functions can be called on any node: bitfield, register, group or sequence. Functions without arguments can be called as if they were attributes (no parentheses).
- is_sequence
- True if node is a sequence. Sequences are also groups.
- is_group
- True if node is a group.
- is_register
- True if node is a register.
- is_bitfield
- True is node is a bitfield.
- lo
- The lowest bit in the bitfield range. Returns -1 if the range is ‘any’. On a Register lo will return the lowest of all bitfield ranges.
- hi
- The highest bit in the bitfield range. Returns 0 if the range is ‘any’. On a Register hi will return the highest of all bitfield ranges.
- bits
- The number of bits in the bitfield range. Returns 0 if the range is ‘any’.
- is_write
- Returns True if a group, register or bitfield is writeable.
- is_trigger
- Returns True if a group, register or bitfield is triggerable.
- is_read
- Returns True if a group, register or bitfield is readable.
- has_write_bitfields
- Return True if a register has any write bitfields
- has_trigger_bitfields
- Return True if a register has any trigger bitfields
- has_read_bitfields
- Return True if a register has any read bitfields
- in_group(group)
- Returns True if this bitfield, register, group or sequence belongs to ‘group’.
3.3. Filters¶
Filters are used to modify input (with or without parameters). They are handy for formatting and aligning the output.
- vhdl_constant(bits = 1)
- Formats the input value using ‘bits’ in binary of hexadecimal for VHDL.
- vhdl_logic_vector
- Formats the bitfield value as std_logic_vector(hi downto lo).
- vhdl_downto
- Formats the input value as (hi downto lo).
- vhdl_value(prefix)
- If the input value is a trigger, the input.value is returned (and must be specified in the YAML file) either as String or as constant and will be vhdl formatted. If the input value is not a trigger, then vhdl_downto is called prepended by prefix.
- vhdl_comment(indent = 0)
- Splits the input value in separate lines and indents each of them by ‘indent’ spaces. Every line is prepended by a comment delimiter (–).
- tex_comment(indent = 0)
- Splits the input value in separate lines and indents each of them by ‘indent’ spaces. Every line is prepended by a comment delimiter (%).
- html_comment(indent = 0)
- Splits the input value in separate lines and indents each of them by ‘indent’ spaces. The whole section is prefixed and suffixed by comment delimiters (<!– and –>).
- html_string
- Escapes YAML (multi-line) string into html
- version
- Converts MajorVersion.MinorVersion to MajorVersion*0x100+MinorVersion.
- hex(digits = 4)
- Formats the input value as hexadecimal: 0x01F40.
- c_comment(indent = 0)
- Splits the input value in separate lines and indents each of them by ‘indent’ spaces. Every line is prepended by a comment delimiter (//).
- c_string
- Escapes YAML (multi-line) string into a C string
- c_mask
- Returns the mask value based on the bitfield.hi and bitfield.lo values.
- semi(append = True)
- Appends a semicolon unless append = False
- tex_string
- Escapes YAML (multi-line) string into LaTeX and calls tex_escape
- tex_escape
- Escapes the input value for LaTeX
- tex_yaml_encode
- Encodes the standard codes (see below) as codes used in a LaTeX template. Use this filter for values of attributes set in the config file and used in a LaTeX template.
- camel_case_to_space
- Converts CamelCase to space separated text.
- inc(inc)
- Increments value by ‘inc’
- dec(dec)
- Decrements value by ‘dec’
- append(postfix)
- Formats the input value as valuepostfix.
- prepend(prefix)
- Formats the input value as prefix value.
- list_nodes_recursively(doc=False)
- Lists the input group recursively. Groups are listed before their children. Bitfield are NOT listed. If ‘doc’ is true, then registers with the ‘nodoc’ attribute (sequences) are not in the list, but an artificial group with name (...) is inserted where registers are left out. The latter is used for documentation.
3.4. Codes for LaTeX (templates where the output ends in .tex)¶
As LaTeX uses a lot of special characters WupperCodeGen redefines the standard JinJa2 delimeters to some others. Care must also be taken in a LaTeX template to escape all texts. An escape_tex filter is available to handle this.
| Delimiters | Standard | LaTeX |
|---|---|---|
| Statements | {% ... %} | ((* ... *)) |
| Expressions | {{ ... }} | ((( ... ))) |
| Comments | {# ... #} | ((= ... =)) |
| Line Statements | # ... ## |
3.4.1. Example¶
To iterate through all registers, the following snippet can be used:
All Registers:
{% for item in nodes['Registers']|list_nodes_recursively %}
{% if item.is_register %}
{{ "%-34s"|format(item.full_name) }} @ {{ item.address|hex}} ({{ item.offset|hex}})
{% endif %}
{% endfor %}