To do the generation of copyright headers, one needs to know both the copyright owner and the year of the copyright. Both can be represented as strings that we plop right into the header, as shown in #20.

As the templates increase in complexity, they will almost certainly be comprised of multiple files that will always be used together. We should allow the user to pass in a template directory.

Eventually, do we want to have a set of builtin templates that are referenced by name (e.g. python instead of a path to a directory)?

As template files grow more complex and customizable, it may be useful to have a standardized way of providing certain types of options through a config file while generating.

codegen ... --config ./my-config.yaml

This could be organized in a flat or extended way. This object would get passed into each template file to allow for different options to be selected.

Flat:

smbusLib: smbus

python:
  smbusLib: smbus2

Also, start generating files for MCP9808.yaml

If the communication protocol is i2c, there should be a way to specify endianness. Some devices are little endian, while others are big endian. If there's a mismatch, all of the data will be sent incorrectly.

i2c:
    addressType: '7-bit'
    address: 0x18
    addressMask: 0x78
    endian: little endian // or big endian

This will make it easier to integrate with Github pages.

Optionally add additional tools from the Git Presubmit Linter project to the Cloud Build configuration for additional verification of the source code and generation of resources such as changelogs.

What if I need an operation that pseduo-yaml doesn't support? Allow parameters to be of type function. In C this would be a function pointer. In Java this would be an interface. It's just some way of making the spec flexible enough to support the most esoteric operations.

Right now:

• enum

To add?

• twos complement?

https://github.com/hathach/tinyusb

Lint the Python code in this repo

Once we start tagging releases, we can add this to the cloud build sequence to get changelogs:

- name: 'gcr.io/cloud-builders/git'
  entrypoint: 'bash'
  args: ['-c', './git-presubmit-linter/tools/changelog.sh > changelog.txt']
  id: 'Generate changelog'
  waitFor: ['Download Git Presubmit Linter']

The top-level category of functions is probably not the best name, if its intention is to describe the various fields and properties in the register, as well as computed values. Functions elicits more of a general compute tool, such as a function called reset, whereas this section seems to describe something like virtual registers, fields, properties, values, parameters, or some other synonym.

Allow codegen to render something like:

A step 1 would allow for simple input/output and logic. Additional support for pseudo-yaml can be part of follow-up.

            - asTemp:
                input: test
                variables:
                    - temp: float32
                logic:
                    - if: value > 256
                        - temp:= value
                    - else:
                        - temp:= 0
                return: temp

Libraries are based around a logical hierarchy. In some languages, like Kotlin, this hierarchy is known as a package. Providing a package can help in the case of generating a variety of files in one command.

Package names are typically inverses of the owners' website.

info:
    title: Mcp4725
    package: com.microchip

http://pdfkit.org/

Some Python functions, like swapping endianness, assume the size of the variable. Others, like register setters, also assume the size and assume it can only be 8 or 16 bits.

The template should be scanned for these types of incomplete number operations and implemented for all possible integer sizes.

Make sure that, as we continue iterating, we're building a system that is internally consistent.

We should use a common file extension for Jinja 2 templates (if only to appease the linters). I'd suggest something like name.py.jina2 or name.py.j2.

Ansible uses .j2 for what it is worth. https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html#id11

We should probably support lower-level register access in the generated python code. There may be peripherals with edge cases that the value level access can not easily accommodate. Giving access at the register level ensures that the generated code is always usable.

If we do support register level access, the python generated code should use python's builtin getters and setters.

In the generated code, it uses sys.exit(1) if the smbus import cannot be found.

Is this a bit harsh? If the code is written this way, then it does not allow the end user to deal with the exception themselves.

Should we add wireless specs such as BLE as goals for communication protocols in the spec?

There should be a tool that validates possible fields. This could be done as a custom linter, or convert the YAML to JSON as part of the linter and use JSON Schema.

Once this happens, we should add CI tests for it and keep it up to date as we make spec changes.

In a color sensor, it doesn't make sense to set the color in a register

We should follow the Python snake case convention to aid readability.

There may be a need to manually add delays to execution of a pseudoyaml block.

This can be added as another function.

exampleWhileLoop:
    input:
        - x: int32
    logic:
        - i:= 0
        - while: i < 10
            - acc := acc + i
            - i := 1
            - delay: 500 // milliseconds by default?
        - return: acc

How to call a different function, with parameters

calcFahrenheit:
  - logic:
    - a : = temp_celsius
      - i: 7

Becomes something like:

def calcFahrenheit():
  a = temp_celsius(i = 7)

Order matters for languages without named arguments.

We should standardize the python docstring format (and other style-related things). Thoughts on which type to use?

Curious if you've consider compatibility with the CMSYS-SVD spec for describing registers.

It's used by ARM to describe variant of hardware register of Cortex-M variant, but I believe most of the concept they're using could be applied to peripherals register as well:

Example:

...
  <register>
          <name>SR</name>
          <description>Status Register</description>
          <addressOffset>0x04</addressOffset>
          <size>16</size>
          <access>read-write</access>
          <resetValue>0x00000000</resetValue>
          <resetMask>0xD701</resetMask>

          <fields>
            <!-- RUN: Shows if Timer is running -->
            <field>
              <name>RUN</name>
              <description>Shows if Timer is running or not</description>
              <bitRange>[0:0]</bitRange>
              <access>read-only</access>
              <enumeratedValues>
                <enumeratedValue>
                  <name>Stopped</name>
                  <description>Timer is not running</description>
                  <value>0</value>
                </enumeratedValue>
                <enumeratedValue>
                  <name>Running</name>
                  <description>Timer is running</description>
                  <value>1</value>
                </enumeratedValue>
              </enumeratedValues>
            </field>
...

• More examples
• Python parser
• Rust codegen

If a peripheral omits a package name, or misspells it, the validator is fine. However, the codegen will throw an error if it cannot be found.

This issue is for the discussion on startBit, endBit, and bits as it keeps coming up. The key questions to answer are:

1. Should the ordering of startBit and endBit matter? Should we enforce that startBit > endBit or the other way around? Should we support both options? https://github.com/google/cyanobyte/pull/38/files#r271088948
2. If startBit == endBit, should we add the option to use bit? #56

Have some sort of way to provide additional peripheral data in the spec if it doesn't have a specific key.

Some I2C devices can have more than one possible hardware address, often with a jumper or pin you drive HIGH/LOW.

To handle these, we could have a constant address or a list. If it's a list, transform the constructor to have the address. This address is then validated before continuing.

i2c:
    address:
        - 0x18
        - 0x19 # If GPIO1 is logic HIGH

mcp9808 = Mcp9808(0x18)

Should this be an enum that is exported?

mcp9808 = Mcp9808(Mcp9808.I2C_ADDRESS_0x18)

Alright, this is more of a preference and don't really care if we make this change or not. I just find argparse easier to look at.

https://docs.python.org/3/library/argparse.html

Sensors have certain init commands which I'm not applying. Ideally these should run at start.

What should the list of valid function (should be renamed, see #9) types be? So far we have discussed adding:

• enum
• twos-complement

Should registers be contained within the I2C block instead of at the same level? This may make more sense when we support more communication protocols.

Add a template to generate .c and .h files.

We can create a Cloud Build configuration which only gets triggered when the requirements.txt is changed, to check the license for each one to verify that they are good OSS licenses like MIT or Apache-2.0. This can be through a shell script.

Should we add this extra CI task, or is it not worth the time?

Python black is a great tool to auto-format python source. We should enforce that all code is blackened to avoid spending time thinking about formatting.

We should incorporate CI tests on each pull request. If we go with Cloud Build, we should be able to easily hook into things like cloud storage to host generated files.

Using a standardized set of labels will promote the use of codegen and other automated tooling. SPDX has a formal list of licenses and identifiers.
https://spdx.org/licenses/

In the spec, we'd modify:

license:
        name: 'Apache-2.0'
        url: 'https://www.apache.org/licenses/LICENSE-2.0.html'

But since this is a standard, we could omit the url field as it'd only link to one place by default.

license:
        name: 'Apache-2.0'

Currently, all of the paths are hard-coded to use forward slashes. This may cause issues in Windows. We should us the os.path package when dealing with paths.

    packagePath = peripheralData['package'].replace('.', '/')
    outputFilePath = os.path.join(outputDir, os.path.normpath(packagePath))