2. User Documentation¶

2.1. Command Line Interface¶

A Makefile is provided that calls WupperCodeGen with the correct parameters to generate the output files. A simple make in the WupperCodeGen directory is enough to produce the output, which is stored in the directory ‘output’.

If there is a need to do so, the tool can be called manually in the following way:

usage: wuppercodegen [-h] [--version] config_file template_file output_file

The following parameters have to be set:

config_file: An input file containing a description of all configuration registers and grouping thereof in YAML format.
template_file: A Jinja2 template file, used to describe the output file.
output_file: The filename of the output file that is to be generated.

2.2. Input Files¶

Input files are located in the current directory. There are two types of input files:

data files, containing a description of the desired bitfields, registers and groups in YAML format,
template files, describing how the generated code should look like.

Users normally only deal with the YAML file.

The Register Description File is a YAML (‘registers.yaml’) file containing a description of Groups, Registers and Bitfields. The top-level group is named ‘Registers’. Groups are named, and may contain other Groups and or Registers. Groups can be repeated to create a Sequence of Groups/Registers. Registers are also named and contain one or more Bitfields. Bitfields are named if there are more than one. Groups, Registers and BitFields are commonly referred to as Nodes. Below a description of each of these types:

2.2.1. Group¶

Groups are declared in yaml by their name, followed by a number of key-value pairs, referred to as attributes. The only obliged attribute is ‘entries’ which lists all the subgroups or registers contained in this group. ‘entries’ is a list. The top-level group is called ‘Registers’, all other groups can have any name, but it needs to be unique.

Subgroups are declared just like groups and referred to by name in the ‘entries’ array under the key ‘ref’. A group that needs repeating may contain the key ‘number’, which is added as a index-parameter in the lookup of the subgroup, and used in the name of its registers, see under registers. Below is group example:

Registers:
  type: R
  step: 0x010
  default: 0
  entries:
    - ref: Bar0
      offset: 0x0000
    - ref: Bar1
      offset: 0x0000
    - ref: Bar2
      offset: 0x0000

Bar0:
  entries:
...

2.2.2. Register and Bitfields¶

Registers are declared directly inside the ‘entries’ attribute of a group. They need a ‘name’ and a ‘bitfield’ attribute. Bitfield is in fact a list of one or more bitfields, which must contain ‘range’ as attribute and ‘name’, if there is more than one bitfield in the list. Range is given as a single bit or as a range of high to low bits (both included in the range).

Below is a register and bitfield example:

GenericBoardInformation:
  entries:
    - name: BOARD_ID
      bitfield:
        - range: 79..64
          name: SVN
          desc: Build SVN Revision
        - range: 39..0
          name: BUILD
          desc: Build Date / Time in BCD format YYMMDDhhmm

    - name: STATUS_LEDS
      type: W
      bitfield:
        - range: 7..0
          default: 0xAB
          desc: Board GPIO Leds

...

The name attribute of a register may contain one % operator to use the repeat-index-parameter to give repeated registers a unique name.

Bar1:
  entries:
    - ref: INT_VEC
      number: 8
...

INT_VEC:
  entries:
    - name: INT_VEC_%01d
...

2.2.3. Attributes¶

Attributes in Bitfields, Registers and Groups are inherited, which means that if you set them on a group, all sub-groups, sequences, registers and bitfield inherit them. This way you can set defaults for a particular group. The following attributes do NOT inherit: ‘name’, ‘full_name’, ‘offset’, ‘address’, ‘index’, ‘entries’, ‘number’, ‘ref’, ‘is_bitfield’, ‘is_register’, ‘is_group’.

The following attributes are used/available:

name (not inherited)

The name of the bitfield, group or register. The name may include fields such as {index} for sequences and {bitfield} for bitfield names.

full_name (not inherited)

For Sequences, the formatted name of the sequence name and the index, if the

sequence name includes {index}.
For Registers, the formatted name of the register name and the index, if the

register name includes {index}.
For Bitfields, the formatted name of the parent register and the bitfield name

if the register name includes {bitfield}. The bitfield part is separated from the name by an underscore. Bitfields of which the parent register is part of a sequence may use also {index} in the parent register’s name to format that name.

dot_name (not inherited)

For Bitfields only, separating the bitfield part from the name by a dot.

prefix_name (not inherited)

For Registers only, the part of the name without the {bitfield} specifier. To be used if you just want the generic name of the register.

desc

A description of the register or bitfield. The ‘|’ operator can be used for multi-line descriptions, which if used as end-of-line comments in the template will properly format.

type

The type of register/bitfield, which can be R: read-only, W: read/write or T: trigger (any write results in something happening, e.g. reset...)

default

The default value to be used to initialize the register or bitfield.

value

Value (or string) to be used for Trigger registers.

offset (not inherited)

Sets the offset used for a register or group.

address (not inherited, calculated)

Address is a calculated value. It starts at 0 for the top-level group. The ‘offset’ attribute gets added to the address of a group to create the current address. Sub-groups and registers are located at the current address. The current address is incremented by ‘step’ for every register. One can place any register or group at a particular address by calculating the needed offset from the address of the parent group.

step

The address increase added to offset for every register.

entries (not inherited)

A list of registers or references to sub-groups.

ref (not inherited)

A reference (by name) to a sub-group.

number (not inherited)

Number of times a referred group needs to be repeated in a sequence.

index (not inherited)

The index for this group or register inside a sequence.

bitfield

List of (at least one) bitfields describing the bits in a register.

range

The bit range (even single bit) of a bitfield. Ranges can be expressed as single integers, as a high..low range, or with the word ‘any’.

any other

The value given, inherited from group to group to register to bitfield.

2.2.4. Metadata¶

You can use the following metadata which is available in the Metadata dictionary:

version: The version of WupperCodeGen
name:: The name of WupperCodeGen
exec:: The program executed
config:: The path of the config file
template:: The path of the template file
output:: The path of the output file
cmdline:: The full command line

Each of these can used inside the config file or in the template. Care must be taken when the output is in LaTeX as the codes change for LaTeX, so any variable in the config file (the template file is already coded for LaTeX) must be filtered through the tex_yaml_encode filter.

Below an example of setting up a warning how the output file is generated:

Registers:
  version: 1.3.0
  warning: |
    This file was generated from '{{ metadata.template }}', version {{ tree.version }}
    by the script '{{ metadata.name }}', version: {{ metadata.version }}, using the following commandline:

    {{ metadata.cmdline }}

    Please do NOT edit this file, but edit the source file at '{{ metadata.template }}'

  entries:
    ...

and the usage in a LaTeX the template

((( tree.warning|tex_yaml_encode|tex_comment )))
...

and its output

% This file was generated from 'warning.tex.template', version 1.3.0
% by the script 'WupperCodeGen', version: 0.3, using the following commandline:
%
% ../wupper_codegen.py warning.yaml warning.tex.template warning.tex
%
% Please do NOT edit this file, but edit the source file at 'warning.txt.template'
...

2.2.5. Example¶

Below is an example of a register description file. The format is yaml. Yaml files can be comfortably created and edited any text editor.

Registers:
  entries:
    - ref: Channel
      number: 8
      offset: 0x0000
    - ref: Egroup
      number: 7
      offset: 0x1000
    - ref: GBT
      number: 24
      offset: 0x2000


Channel:
  type: W
  default: 0
  entries:
    - name: Dir
      desc: null
      bitfield:
        - range: 0
    - name: ChWidth
      desc: '2,4,8,16,or 112, 120 bits'
      bitfield:
        - range: 6..0
    - name: ChStart
      desc: first bit of the channel in the GBT word
      bitfield:
        - range: 6..0
    - name: Ewidth
      desc: width of the E-link comprising the channel
      bitfield:
        - range: 3..0
    - name: hasStreams
      desc: null
      bitfield:
        - range: 0
    - name: hasChnkLen
      desc: null
      bitfield:
        - range: 0
    - name: MaxChnkLen
      desc: null
      bitfield:
        - range: 15..0
    - name: hasChkSum
      desc: "a 16-bit 1's-complement checksum is at the end of the packet"
      bitfield:
        - range: 0
    - name: FromSCA
      desc: Decode HDLC
      bitfield:
        - range: 0
    - name: DOLL
      desc: Direct Output Low Latency Link
      bitfield:
        - range: 0
    - name: Busy
      desc: BUSY commands may be sent on this channel
      bitfield:
        - range: 0
    - name: TTCin
      desc: source of raw TTC infor
      bitfield:
        - range: 0
    - name: chk8b10b
      desc: use commas and check 8b/10b encoding is valid
      bitfield:
        - range: 0
    - name: dec8b10
      desc: forward decoded 8b/10 data
      bitfield:
        - range: 0
    - name: SOPEOP
      desc: Start-of-Packet and End-of-Packet symbols define packet boundaries
      bitfield:
        - range: 0
    - name: ToSCA
      desc: encode HDLC
      bitfield:
        - range: 0
    - name: TTCopt
      desc: 'if >0, destination of TTC info: 0, 2 (A&B ch), 4, 8 bits'
      bitfield:
        - range: 1..0
    - name: DILL
      desc: Direct Input Low Latency Link
      bitfield:
        - range: 0
    - name: TDAT
      desc: destination for scheduled data transfers
      bitfield:
        - range: 0


Egroup:
  type: W
  default: 0
  entries:
    - name: EprocEnable
      desc: Enables for the E-procs in the group
      bitfield:
        - range: 14..0
    - name: EclockRate
      desc: 40,80,160, 320, (640)
      bitfield:
        - range: 2..0

GBT:
  entries:
    - name: gbt_format
      desc: Wide or Normal
      bitfield:
        - range: 0
          type: W
          default: 0

Table Of Contents

Previous topic

Next topic

This Page