=======================
Developer Documentation
=======================
Developers manage the code generated by WupperCodeGen. The output is defined by
Jinja2 template files, usually ending in '.template'.
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.
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'.
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 ().
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 *value*\ postfix.
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.
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 # ... ##
================= =========== =============
-------
Example
-------
To iterate through all registers, the following snippet can be used:
.. highlight:: none
.. include:: ../examples/register_list/register_list.txt.template
:code: