schilkp/reginald

Reginald

Philipp Schilk 2022-2023

reginald's Issues

Documentation Model

Read the docs? MDBook? Integrate with GitHub pages?

Requires:

• overview
• quick start
• YAML map spec
• Per generator documentation
  • macromap
  • funcpack
  • MD docs
  • MD regdump
• Developing a generator documentation
• Driver template?

Do yourself a favour and lock everything else down a bit first.

Don't fun it - pip it

Rework internal Datamodel

"everything is a block including registers which are blocks with an unamed template" Figure it out. Blame @villanif.

Change block instantiation:

TemplateName:
   instances: {Instance name: adr, ...} 

Setup some for of unit/regression testing

At least verify that all examples are actually accepted.

Initial Draft re-design [The Fede Edition]

0. Split input and data model

1. Add "Register Block" system:

   CH1_SET: # Single register block instantiation
     start_adr: 0x01
     register_block_template: "CH_SETTINGS"

   CHn_SET: # Multiple register block instantiation
      start_adr: {1: 0x100, B: 0x200}
      replace_str_with_instance_name: "n" # Optional, Fallback: suffix w\o any padding char
      register_block_template: "CH_SETTINGS"

2. Move from set width to per-register with default:

default_register_bitwidth: 8

...
registers:
  REGA:
    bitwidth: 8 # Override

3. Enum:
   Refactor 'enums' to allow for brief+doc, and make syntax identical to field enum:

register:
  A:
    ...
    fields:
       SETTINGS:
         bits: []
         brief:
         doc:
          enum: 
            VALA:
              ..
       OTHERFIELD:
         ...
         enum: GPIO_MODE
       

shared_enums:
  GPIO_MODE:
    brief:
    doc:
    enum:
      OUTPUT:
        value: 0
        brief: Pin configured as output.
      INPUT:
        value: 1
        brief: Pin configured as input.

4. Device Name -> Map name

map_name: ADS129x

5. Field bit definitions:

# Add:
    bits: 1 # == [1]
    bits: 1-4 # == [1,2,3,4]
    bits: [1, 4-10] # == [1,4,5,6,7,8,9,10]

# Remove: 
    bits:
      lsb_position: 1
      width: 3

6. Access:

    access: [r, w]

Reginald specify default access at register level

Specify default access as:
access: r
at register level (currently only specified at field level)
fields can override it

Add register_field_templates

add nex register_field_templates feature, to quickly reproduce register fields. structure can be similar to already existing register_block_template:

register_field_templates:
  EXAMPLE_FIELD_n:
    bit_size: 3
    enum:
      SOMETHING:
        ...
      SOMETHINGELSE:
        ...

Change file interaction

Move from stdout piping to actual output file specification

Allow for "usercode" sections in generated file, if file exists, extract before re-gen.

c.funcpack: Add a "Unpack from map / by index" mechanism

Something to the effect of:

#define MYCOOLCHIP_MAPUNPACK_A(_map_)  MYCOOLCHIP_UNPACK_A((_map_)[MYCOOLCHIP_REG_A])

This would have to be generated for every physical register instance, unlike the UNPACK macros, which are generated for every register layout.

Would reduce clutter for the common 'Grab from map and modify' workflow:

struct mycoolchip_reg_a reg_a = MYCOOLCHIP_UNPACK_A(regs[MYCOOLCHIP_REG_A]);
// vs:
struct mycoolchip_reg_a reg_a = MYCOOLCHIP_MAPUNPACK_A(regs);

Pros:

• Reduces clutter/copy+paste/chance of forgetting to update index on snippet copy.

Cons:

• More crazy macro-magic.... Less explicit about what it actually does.
• Not every drive uses a map, likely should be gated?

YAML format: val vs value? adr vs address?

Be consistent.

Reginald Feature Proposal - Latex Register

It would fit the use case of Reginald to be able to output Latex compatible code to display register fields.
The package Registers (documentation) seems to be the perfect candidate for this.

python "map"standard function name used as variable in function

generate(cls, map: RegisterMap, cli: CLI) uses map as input variable, however this is a standard function in python.

Split multi-output generators.

c.funcpack improvements

• Improve regstruct doxygen comment:
  • Always gen a comment
  • Brief should always be present. Either auto-gen or prefix for actual brief?
  • Mention + link packing & unpacking funcs + generics?

Add Templating Engine

https://palletsprojects.com/p/jinja/

Avoid adding any YAML overhead, instead do generation & parameterization with a purpose-built tool.

Better error messages

Parse pydantic error msgs? Inject custom msgs into pydantic?
Ditch pydantic and write custom parser?

Better config model + cmd arg model

Allow for output name instead of output path ( Requires move to single file output. )

Setup some way for generators to spec their arguments, and allow all generator args (if not all args?) to be specified by a YAML file. This should likely include a way to generate a "default" YAML file to help with getting setup.