Define a consistent naming convention for device tree defines

[galak]

We have a mish-mash of defines today and there are places that we can have possible naming conflicts. So define a consistent name space for the various node defines that we generate.

Related to #21369

[galak]

# For props not 'regs', 'interrupts', 'clocks', SPI 
DT_PATH_P_<PATH>_<PROP>:
				
				string	"foo"
				int		3
				boolean	1/0 (always defined)
				array	{ 1, 2, 3, 4 }
				uint8-array { 0x12, 0x34, 0x45 }
				string-array { "foo", "bar"}
				phandle	<PATH> to referenced node
				
				phandles - nothing
				phandles-array - nothing
				compound - nothing

/* bool */
#define DT_PATH_P_SOC_FLASH_CONTROLLER_40020000_FLASH_0_PARTITIONS_PARTITION_0_READ_ONLY 1
/* int */
#define DT_PATH_P_SOC_I2C_40066000_CLOCK_FREQUENCY                      100000
/* string */
#define DT_PATH_P_SOC_I2C_40066000_LABEL                                "I2C_0"
/* array */
#define DT_PATH_P_SOC_USART_4000C400_LOCATION_RX                        {4, 0, 0}
/* uint8-array */
#define DT_PATH_P_SOC_SPI_40004000_SSD16XXFB_0_LUT_INITIAL              {0x22, 0x55, 0xaa, 0x55}
/* string-array */
#define DT_PATH_P_SOC_RTC_4003D000_INTERRUPT_NAMES                      {"alarm", "seconds" }
/* phandle */
#define DT_PATH_P_SOC_GPIO_400FF080_NXP_KINETIS_PORT                    SOC_PINMUX_4004B000

				
regs:	
DT_PATH_X_REG_NUM_<n>_ADDRESS_<path>
DT_PATH_X_REG_NUM_<n>_SIZE_<path>
DT_PATH_X_REG_NAME_<name>_ADDRESS_<path>
DT_PATH_X_REG_NAME_<name>_SIZE_<path>
DT_PATH_X_REG_CNT_<path>

/* regs */

#define DT_PATH_X_REG_NUM_0_SOC_INTERRUPT_CONTROLLER_C000000_ADDRESS            0xc000000
#define DT_PATH_X_REG_NUM_0_SOC_INTERRUPT_CONTROLLER_C000000_SIZE               8192
#define DT_PATH_X_REG_NAME_PRIO_SOC_INTERRUPT_CONTROLLER_C000000_ADDRESS        0xc000000
#define DT_PATH_X_REG_NAME_PRIO_SOC_INTERRUPT_CONTROLLER_C000000_SIZE           8192
 
#define DT_PATH_X_REG_NUM_1_SOC_INTERRUPT_CONTROLLER_C000000_ADDRESS            0xc002000
#define DT_PATH_X_REG_NUM_1_SOC_INTERRUPT_CONTROLLER_C000000_SIZE               2088960
#define DT_PATH_X_REG_NAME_IRQ_EN_SOC_INTERRUPT_CONTROLLER_C000000_ADDRESS      0xc002000
#define DT_PATH_X_REG_NAME_IRQ_EN_SOC_INTERRUPT_CONTROLLER_C000000_SIZE         2088960
 
#define DT_PATH_X_REG_CNT_SOC_INTERRUPT_CONTROLLER_C000000                      3

interrupts:
DT_PATH_X_INTERRUPTS_NUM_<n>_ADDRESS_<path>
DT_PATH_X_INTERRUPTS_NUM_<n>_SIZE_<path>
DT_PATH_X_INTERRUPTS_NAME_<name>_ADDRESS_<path>
DT_PATH_X_INTERRUPTS_NAME_<name>_SIZE_<path>
DT_PATH_X_INTERRUPTS_CNT_<path>

phandles:
DT_PATH_X_PHANDLES_<n>_<path>_<prop>   <path>

/* phandles */
#define DT_PATH_X_PHANDLES_0_SOC_GPIO_400FF080_NXP_KINETIS_PORTS                SOC_PINMUX_4004B000
#define DT_PATH_X_PHANDLES_1_SOC_GPIO_400FF080_NXP_KINETIS_PORTS                SOC_PINMUX_4004C000

phandle-array:
DT_PATH_X_PHA_PHANDLE_<n>_<path>_<prop>
DT_PATH_X_PHA_<name from binding for cell>_<n>_<path>_<prop>

/* phandle array */
DT_PATH_X_PHA_PHANDLE_0_SOC_I2C_40066000_FXOS8700_1D_INT1_GPIOS	
DT_PATH_X_PHA_PIN_0_SOC_I2C_40066000_FXOS8700_1D_INT1_GPIOS
DT_PATH_X_PHA_FLAGS_0_SOC_I2C_40066000_FXOS8700_1D_INT1_GPIOS

array:
DT_PATH_X_ARRAY_NUM_<n>_<path>_<prop>
DT_PATH_X_ARRAY_CNT_<path>_<prop>

/* array */
#define DT_PATH_X_ARRAY_NUM_0_SOC_USART_4000C400_LOCATION_RX	4
#define DT_PATH_X_ARRAY_NUM_1_SOC_USART_4000C400_LOCATION_RX	0
#define DT_PATH_X_ARRAY_NUM_2_SOC_USART_4000C400_LOCATION_RX	0
#define DT_PATH_X_ARRAY_CNT_SOC_USART_4000C400_LOCATION_RX		3

[galak]

Starts of my initial cut at a naming convention that is consistent and has limited conflicts.

[galak]

Thinking for things like DT_ALIAS, DT_IDENT, DT_NODELABEL would just be 'PATH' defines as such:

#define DT_ALIAS_UART0 SOC_UART_4006D000
#define DT_NODELABEL_UART0 SOC_UART_4006D000
#define DT_INST_0_NXP_KINETIS_UART SOC_UART_4006D000

Than you can use macro magic to do something like:

DT_ALIAS_PROP(UART0, LABEL) -> DT_PATH_P_SOC_UART_4006D000_LABEL

[pabigot]

I was hoping for something like this (draft status)

<name> ::= 'DT_' <node-id> [ '_' <suffix> ];

<init-id> ::= [A-Z]
<id-char> ::= [A-Z0-9]
<decimal> ::= [0-9]+ ;
<hexadecimal> ::= [0-9a-f]+ ;

<identifier> ::= <init-id> <id-char>* ;
<long-identifier> ::= <identifier> ( '_' <identifier> )* ;

<node-name> ::= <long-identifier> ;
<node-label> ::= <long-identifier> ;
<unit-address> ::= hexadecimal [ '_' <unit-address> ] ;

<property-name> ::= <long-identifier> ;

# An encoded vendor,model string from a "compatible" property
<compatible> ::= <long-identifier> ;

# A sequence meant to identify a specific node in the devicetree.
# Used as a prefix for node properties and to represent the node
# itself.
<node-id> ::= <node-alias> | <node-compat> | <node-inst> | <node-label> | <node-path> ;

# This name is used to reference a generic capability such as an LED
# or button.
<node-alias> ::= 'ALIAS_' + <alias> ;

# A property from the /aliases node
<alias> ::= <property-name>

# This name is used in driver instantiation
<node-inst> ::= 'INST_' <decimal> '_' <compatible> ;

# This name is used to reference by SOC-specific identifier
<node-label> ::= 'NODELABEL_' <long-identifier> ;

# This name is used to reference by full devicetree path
<node-path> ::= 'PATH_' <path> ;
<path> ::= ; # **TBD**

# Some old thing we probably want to get rid of.
<node-legacy> ::= [ <bus> '_' ] <compatible> '_' <unit_address> ;
<bus> ::= <long-identifier> ;

<suffix> ::= <property-suffix> ;

# Used to identify a property value (or value component)
<property-suffix> ::= <property-name> [ <ordinal> ] ;

[galak]

Example of what we generate today for a register w/current PR from marti:

#define DT_PATH_SOC_UART_4006A000_BASE_ADDRESS                          0x4006a000
#define DT_PATH_SOC_UART_4006A000_SIZE                                  4096
#define DT_NXP_KINETIS_UART_4006A000_BASE_ADDRESS                       DT_PATH_SOC_UART_4006A000_BASE_ADDRESS
#define DT_NXP_KINETIS_UART_4006A000_SIZE                               DT_PATH_SOC_UART_4006A000_SIZE
#define DT_INST_0_NXP_KINETIS_UART_BASE_ADDRESS                         DT_PATH_SOC_UART_4006A000_BASE_ADDRESS
#define DT_INST_0_NXP_KINETIS_UART_SIZE                                 DT_PATH_SOC_UART_4006A000_SIZE
#define DT_NODELABEL_UART0_BASE_ADDRESS                                 DT_PATH_SOC_UART_4006A000_BASE_ADDRESS
#define DT_NODELABEL_UART0_SIZE                                         DT_PATH_SOC_UART_4006A000_SIZE

[galak]

Based on what Peter had here's some examples of what PATH defines might look like using _p_:

#define DT_PATH_SOC_INTERRUPT_CONTROLLER_C000000_p_ADDRESS_idx_0
#define DT_PATH_SOC_INTERRUPT_CONTROLLER_C000000_p_ADDRESS_idx_1
#define DT_PATH_SOC_INTERRUPT_CONTROLLER_C000000_p_ADDRESS_name_PRIO
#define DT_PATH_SOC_INTERRUPT_CONTROLLER_C000000_p_ADDRESS_name_IRQ_EN
#define DT_PATH_SOC_INTERRUPT_CONTROLLER_C000000_p_ADDRESS_cnt_IRQ_EN

any array (string-array, uint8-array, array, phandles):

#define DT_PATH_SOC_GPIO_400FF080_p_NXP_KINETIS_PORTS_idx_0
#define DT_PATH_SOC_GPIO_400FF080_p_NXP_KINETIS_PORTS_idx_1
#define DT_PATH_SOC_GPIO_400FF080_p_NXP_KINETIS_PORTS_cnt

for phandle-array:

DT_PATH_SOC_I2C_40066000_FXOS8700_1D_p_INT1_GPIOS_idx_0		/* phandle */
DT_PATH_SOC_I2C_40066000_FXOS8700_1D_p_INT1_GPIOS_idx_0_pin
DT_PATH_SOC_I2C_40066000_FXOS8700_1D_p_INT1_GPIOS_idx_0_flags
DT_PATH_SOC_I2C_40066000_FXOS8700_1D_p_INT1_GPIOS_idx_cnt

[mbolivar]

I was hoping for something like this (draft status)
::= 'DT_' [ '_' ];

As discussed in #22966, an ABNF for what we have now is here: https://github.com/mbolivar/zephyr/blob/doc-dt-improvements/doc/guides/dts/macros.bnf

This will hopefully be merged to master soon.

[mbolivar]

@pabigot and any others interested in discussing.

I want to start with the grammar as defined in v2.2.0-rc2, and tackle node-id (used by property-macro) first as a warmup for the process:

https://github.com/zephyrproject-rtos/zephyr/blob/v2.2.0-rc2/doc/guides/dts/macros.bnf

I've created a dt-macros-ng branch in my fork, which contains this commit at time of writing with proposed node-id changes that keep the old names around, but introduce new (hopefully better) ones as well:

mbolivar@3a7dc57

Using these conveniently would require some macro magic à la @galak.

Comment welcome. Here are some notes on collisions in the meantime:

Node identifiers from two different namespaces (like "alias" and
"inst") cannot collide, since they have different prefixes.

"inst" macros for devices from two different vendors cannot collide as
long as compatibles follow rules in vendor-prefixes.txt, since those
lead to unique "VND_" prefixes (even in cases like "u-blox" where
"vnd" is not purely alphanumeric).

"inst" collisions between compatibles "vnd,device" and
"generic-device" (like "gpio-keys", "mmio-sram", etc.) cannot occur if
the "generic-device" namespace is properly managed, which I think we
can assume the maintainers will ensure. Similar comments apply to
collisions between two different "generic-device" compatibles.

"alias" collisions can occur only for two aliases differing only by
case, like this:

aliases {
	foo = &foo1;
	FOO = &foo2;
};

This follows because alias names may contain alphanumeric and "-"
(dash) characters only (at least per the devicetree specification).
The "foo vs. FOO" problem isn't worth solving IMO: the user should
just fix their devicetree to avoid it.

"nodelabel" collisions are only possible under the same conditions as
"alias" collisions, for a similar reason. Per specification, labels
can only contain "_" (underscore) and alphanumeric characters. The
"foo vs. FOO" problem isn't worth solving here, either, IMO.

"path" collisions are the likeliest of all, because of various types
of ambiguity that can occur when converting a path to a c-ident. For
example, the leaf nodes in this devicetree all have "path" prefix
DT_p_path_FOO_BAR_BAZ, and all names are legal per specification
AFAICT:

/ {
	foo {
		bar@baz {};
		bar {
			baz {};
		};
	};
	foo-bar-baz {};
	foo_bar_baz {};
	foo,bar,baz {};
	foo.bar+baz {};
};

We need to decide how seriously to take these problems.

We may want to send a patch to the devicetree specification which
explicitly recommends against such situations, at least at the same
level in the tree (so the answer to foo-bar-baz vs. foo_bar_baz at
least might just be "don't do that!").

If that patch is merged, we could then separate path components with a
special character (like "s" for "slash" as previously suggested by
@pabigot). Then the leaf nodes in this tree:

/ {
	foo {
		bar@baz {};
		bar {
			baz {};
		};
	};
	foo-bar-baz {};
};

Would have the following "path" prefixes (in the respective order they
are defined in the DTS):

• DT_n_path_s_FOO_s_BAR_BAZ
• DT_n_path_s_FOO_s_BAR_s_BAZ
• DT_n_path_s_FOO_BAR_BAZ