Requirements for driver devices generation using device tree

[erwango]

Aim of this issue is to settle on requirements for code generation solution that should be used to generate devices code for a driver configured by device tree. Most of the elements that will be listed here were discussed during OpenIoT 2018 in Edinburgh last week.

• User's acceptance/Ease of use:
  • Code generation solution should be easy to read and use. User should identify main elements and understand behavior with minimum effort.
  • User should be able to easily map elements from the EDTS file to the code generation template
  • Ideally, syntax should be easy to edit in IDE
• Versatility:
  • Code generation solution should fit to most of zephyr drivers, and at least in a first iteration work with all drivers using DEVICE_AND_API_INIT macro.
• Ease of review:
  • Solution should not bring significant overhead to the review process. It should be constrained and sufficiently defined so we don't loose time to comment on various possible ways on using the solution for a particular driver.
• Maintainability:
  • Code generation provided should be easy to maintain.
• Doc:
  • Solution should be fully documented
• Implementation basics:
  • Input:
    • EDTS Python library API (cf script/dts: Generate Extended Device Tree database #9876, and zephyr/topic-EDTS branch) exclusively. No use of the edts.json directly in order to avoid reliance on the JSON formatting
    • Clean, non-templated i2c_foo.c file with the driver implementation (not used by the templating engine, here for completeness)
    • Single template file i2c_foo_devices.h.in with the templated device structures.
  • Output:
    • Generated file : i2c_foo_devices.h in build/zephyr/drivers/<driver>/
    • Included in i2c_foo.c( #include i2c_foo_devices.h)
  • Invocation: Solution should be invoked from one liner, simple cmake macro:
    zephyr_library_sources_codegen_ifdef(CONFIG_I2C_STM32 i2c_ll_stm32.c)
  • Rendering
    • Time: Needs to be rendered at ninja time
    • Performance: Needs to render files one by one in parallel
• Standalone:
  • The tooling to take a device tree & yaml, plus some template description should not be zephyr specific or zephyr aware (ie any invocation of the tools should be able to exist and run outside of Zephyr)
  • The integration (cmake) and templates helpers can be zephyr aware.

Note:
While being targeted in the long term, pinmux generation using device tree input is not addressed here. It is likely this is one element of the discussion, but aim of the ticket is to sum up what we know/want on driver devices.

[erwango]

@b0661 , @evenl

[erwango]

@galak , @carlescufi, @mbolivar, @MaureenHelm, @nashif, feel free editing these lines.
Then, I think it is important that we're able to freeze a version of it.

[galak]

@b0661 mentioned use for out of tree drivers, so wondering what requirements that drives

[galak]

One template file per driver .c file

(if I have, i2c_foo.c, than just i2c_foo.h_template)

[galak]

Should be standalone from Zephyr (usable by other projects).

[galak]

Performance of rendering (Are we invoking python once for all files that need to be rendered or per file)?

[SebastianBoe]

Performance of rendering (Are we invoking python once for all files that need to be rendered or per file)?

Once per file in parallel. Note that this has already been implemented.