cmake: modules: shields: Introducing shield options

[soburi]

With this change, the shield specified by --shield can receive
a connector name and various options.
This allows you to adapt the shield to your board at compile time.

Command line options:

which connects this device by appending @ after its name.
It can also append options separated with ":" to specify shield-specific
options. Multiple options can be assigned.

The format is as follows:

<shield_identifier>[@<connector>][:<option>{:<option>}]

Derived overlay:

When you specify the connector to connect to, an overlay file is
generated that includes the @connector_name part of the connector name.
Here, we will call this a "derived overlay".

The derived overlay defines the SHIELD_DERIVED_NAME and
SHIELD_DERIVED_NAME_DEFINED macros and including the original overlay
file. The overlay author can use helper macros to reflect options per
the derived definition.

Options and helper macros:

Options are defined in the format [key]=[value]. The value will be
treated as 1 if only the key is specified.
Helper macros are also defined to handle these options in overlays.

• SHIELD_OPTION_DEFINED(opt) returns 0 or 1 to indicate whether
  opt is defined.
• SHIELD_OPTION(opt) returns the macro value corresponding to opt if it
  is defined. Otherwise, it returns the value of SHIELD_DEFAULT_[opt].
• SHIELD_DEFAUILT_[opt] is automatically It is not generated,
  so you must explicitly define it in the overlay file.

Example:

For example, if you specify something like:

--shield seeed_grove_lis3dhtr:addr=1f
--shield seeed_grove_lis3dhtr@grove_i2c1

the automatically generated header will have a definition like

#define SHIELD_SEEED_GROVE_LIS3DHTR_ADDR 1f
#define SHIELD_SEEED_GROVE_LIS3DHTR_ADDR_DEFINED 1
#define SHIELD_SEEED_GROVE_LIS3DHTR_GROVE_I2C1_CONNECTOR_NAME grove_i2c1
#define SHIELD_SEEED_GROVE_LIS3DHTR_GROVE_I2C1_CONNECTOR_NAME_DEFINED 1

A derived overlay is also created with the file name
seeed_grove_lis3dhtr@grove_i2c1.overlay.
In this case, the derived overlay will include
SHIELD_OPTION(CONNECTOR_NAME), You can reference these with
SHIELD_OPTION(ADDR).
To ensure that the helper macros work correctly in the original
overlay and not in a derived overlay,
you must define SHIELD_DEFAULT_CONNECTOR_NAME and
SHIELD_DEFAULT_ADDR.

You also need to take care not to duplicate labels, etc.

Finally, It will look like this:

#define SHIELD_DEFAULT_CONNECTOR_NAME grove_i2c
#define SHIELD_DEFAULT_ADDR 19

&SHIELD_CONNECTOR_NAME {
  SHIELD_CONCAT(lis3dh_, SHIELD_OPTION(ADDR)):
    lis3dh@SHIELD_OPTION(ADDR) {
      compatible = "st,lis3dh", "st,lis2dh";
      reg = <SHIELD_PREFIX_0X(SHIELD_OPTION(ADDR))>;
      ...
  };
};

#undef SHIELD_DEFAULT_ADDR
#undef SHIELD_DEFAULT_CONNECTOR_NAME

By defining it like this,
you can connect this seeed_grove_lis3dhtr to any
grove connector.

As a result, you got processed dts such as follows.

i2c0: grove_i2c: i2c@40044000 {
  lis3dh_1f: lis3dh@1f {
    compatible = "st,lis3dh", "st,lis2dh";
    reg = < 0x1f >;
  };
};
i2c1: grove_i2c1: i2c@40048000 {
  lis3dh_19: lis3dh@19 {
    compatible = "st,lis3dh", "st,lis2dh";
    reg = < 0x19 >;
  };
};