devicetree: improved support for enum values

[pabigot]

Extracted from #17309 where this was originally proposed:

Currently there is one in-tree use of the enum type in bindings, for the usb controller field maximum-speed:

maximum-speed:
  type: string
  enum:
     - "low-speed"
     - "full-speed"
     - "high-speed"
     - "super-speed"

It generates symbols like this:

#define DT_NXP_KINETIS_USBD_402E0000_MAXIMUM_SPEED  "full-speed"
#define DT_NXP_KINETIS_USBD_402E0000_MAXIMUM_SPEED_ENUM 1

This is not robust. The symbol that identifies the selection has a string value that is not readily usable to control compilation or initialize runtime data structures. The symbol that provides an integer identifier is dependent on the order values were listed in the binding, which is not visible to the application or driver source and might change over time.

The sole in-tree users of this are sam and stm32 USB controllers, which have to do string comparisons against the enum value to determine the selected value.

I would like to use the enum type for properties that are constrained to one of a small set of values, but in its current form this is not possible. Below are the original potential solution paths extracted from #17309. Implementing either or both would make it much easier to use such properties.

Tokenizable Values

NOTE: The "Generated Enums" feature below may be a better solution to the underlying problem.

Waveshare's e-paper displays use the same API with a large number of device-specific values, including initialization sequences and look-up tables. I would like the driver I'm developing to allow selection of the display like this:

    variant:
      type: string
      category: required
      generation: define
      enum:
        - "epd1p54"
        - "epd1p54b"
        - "epd1p54c"
        - "epd4p2"
        # ...

Currently what I get is:

#define DT_NORDIC_NRF_SPI_40004000_WAVESHARE_EPD_0_VARIANT "epd1p54b"

In the driver I have things like:

static u8_t epd1p54b_init[] = { /* lots of bytes here */};

Since the value of the property is expressed as a string rather than a token, I can't use it in something like:

   .init = CONCAT(DT_INST_0_WAVESHARE_EPD_VARIANT, _init),

So I want an option to generate string-valued properties as tokens.

Generated Enums

Alternative to "Tokenizable Values" changing the property define value from a string to a (sequence of) tokens, a define for a string enum value could be generated like this:

#define DT_NORDIC_NRF_SPI_40004000_WAVESHARE_EPD_0_VARIANT "epd1p54b"
#define DT_NORDIC_NRF_SPI_40004000_WAVESHARE_EPD_0_VARIANT_EPD1P54B 1

This would also allow preprocessor detection of the variant, more convenient then token catenation in most cases, but also more limiting.

For this approach we need a clear description of how string enum values are converted to a character sequence suitable as a macro name suffix, e.g. anything not isalnum becomes _.

[ulfalizer]

As a cop-out, I wonder if it could just be documented that *_ENUM is based on the order that values are listed in enum:.

The code could then have something like this:

#define LOW_SPEED   0
#define FULL_SPEED  1
#define HIGH_SPEED  2
#define SUPER_SPEED 3

A warning could be added in the binding re. keeping it in sync with the code.

Note that enum: also works for other types btw (int, array, etc.) That makes it a bit iffy to special-case it for strings.

[ulfalizer]

Maybe just some light special-casing for strings could be added too, with an additional ..._ENUM_ID that gets generated, like this:

#define ..._ENUM_ID LOW_SPEED

Guess that could be done for all strings too, and not just for enums, though it'd get very spammy.

[pabigot]

As a cop-out, I wonder if it could just be documented that *_ENUM is based on the order that values are listed in enum:.

That would be a policy that would prevent me from ever using enum. It's far to trusting and fragile.

I think it's reasonable that the generated enum like DT_NORDIC_NRF_SPI_40004000_WAVESHARE_EPD_0_VARIANT_EPD1P54B be provided only when the value of the enum is a string.

[ulfalizer]

Thinking about it, just outputting an additional concat-friendly macro for all type: string properties might not be so bad, because e.g. compatible is a string-array.

I'll implement and check.

[ulfalizer]

Hmm... that might not solve the compile-time-test-by-name part though. Will poke around a bit.