214 lines
7.3 KiB
BNF
214 lines
7.3 KiB
BNF
; An RFC 7405 ABNF grammar for devicetree macros.
|
|
;
|
|
; This does *not* cover macros pulled out of DT via Kconfig,
|
|
; like CONFIG_SRAM_BASE_ADDRESS, etc. It only describes the
|
|
; ones that start with DT_ and are directly generated, not
|
|
; defined in a dts_fixup.h file.
|
|
|
|
; --------------------------------------------------------------------
|
|
; dt-macro: the top level nonterminal for a devicetree macro
|
|
;
|
|
; A dt-macro starts with uppercase "DT_", and is one of:
|
|
;
|
|
; - a <node-macro>, generated for a particular node
|
|
; - some <other-macro>, a catch-all for other types of macros
|
|
dt-macro = node-macro / other-macro
|
|
|
|
; --------------------------------------------------------------------
|
|
; node-macro: a macro related to a node
|
|
|
|
; A macro about a property value
|
|
node-macro = property-macro
|
|
; EXISTS macro: node has matching binding and "okay" status.
|
|
node-macro =/ %s"DT_N" path-id %s"_EXISTS"
|
|
; Bus macros: the plain BUS is a way to access a node's bus controller.
|
|
; The additional dt-name suffix is added to match that node's bus type;
|
|
; the dt-name in this case is something like "spi" or "i2c".
|
|
node-macro =/ %s"DT_N" path-id %s"_BUS" ["_" dt-name]
|
|
; The reg property is special and has its own macros.
|
|
node-macro =/ %s"DT_N" path-id %s"_REG_NUM"
|
|
node-macro =/ %s"DT_N" path-id %s"_REG_IDX_" DIGIT "_EXISTS"
|
|
node-macro =/ %s"DT_N" path-id %s"_REG_IDX_" DIGIT
|
|
%s"_VAL_" ( %s"ADDRESS" / %s"SIZE")
|
|
node-macro =/ %s"DT_N" path-id %s"_REG_NAME_" dt-name
|
|
%s"_VAL_" ( %s"ADDRESS" / %s"SIZE")
|
|
; The interrupts property is also special.
|
|
node-macro =/ %s"DT_N" path-id %s"_IRQ_NUM"
|
|
node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT "_EXISTS"
|
|
node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT
|
|
%s"_VAL_" dt-name [ %s"_EXISTS" ]
|
|
node-macro =/ %s"DT_N" path-id %s"_IRQ_NAME_" dt-name
|
|
%s"_VAL_" dt-name [ %s"_EXISTS" ]
|
|
; Macros are generated for each of the node's compatibles.
|
|
node-macro =/ %s"DT_N" path-id %s"_COMPAT_MATCHES_" dt-name
|
|
; The node identifier for the node's parent in the devicetree.
|
|
node-macro =/ %s"DT_N" path-id %s"_PARENT"
|
|
|
|
; --------------------------------------------------------------------
|
|
; property-macro: a macro related to a node property
|
|
;
|
|
; The "plain vanilla" macro for a property's value thus looks like:
|
|
;
|
|
; DT_N_<node path>_P_<property name>
|
|
;
|
|
; Components:
|
|
;
|
|
; - path-id: node's devicetree path converted to a C token
|
|
; - prop-id: node's property name converted to a C token
|
|
; - prop-suf: an optional property-specific suffix
|
|
property-macro = %s"DT_N" path-id %s"_P_" prop-id [prop-suf]
|
|
|
|
; --------------------------------------------------------------------
|
|
; path-id: a node's path-based macro identifier
|
|
;
|
|
; The path of the node converted to a C token by changing:
|
|
;
|
|
; - each slash (/) to _S_
|
|
; - all letters to lowercase
|
|
; - non-alphanumerics characters to underscores
|
|
;
|
|
; For example, the leaf node "bar-BAZ" in this devicetree:
|
|
;
|
|
; / {
|
|
; foo@123 {
|
|
; bar-BAZ {};
|
|
; };
|
|
; };
|
|
;
|
|
; has path-id "_S_foo_123_S_bar_baz".
|
|
path-id = 1*( %s"_S_" dt-name )
|
|
|
|
; ----------------------------------------------------------------------
|
|
; prop-id: a property identifier
|
|
;
|
|
; A property name converted to a C token by changing:
|
|
;
|
|
; - all letters to lowercase
|
|
; - non-alphanumeric characters to underscores
|
|
;
|
|
; Example node:
|
|
;
|
|
; chosen {
|
|
; zephyr,console = &uart1;
|
|
; WHY,AM_I_SHOUTING = "unclear";
|
|
; };
|
|
;
|
|
; The 'zephyr,console' property has prop-id 'zephyr_console'.
|
|
; 'WHY,AM_I_SHOUTING' has prop-id 'why_am_i_shouting'.
|
|
prop-id = dt-name
|
|
|
|
; ----------------------------------------------------------------------
|
|
; prop-suf: a property-specific macro suffix
|
|
;
|
|
; Extra macros are generated for properties:
|
|
;
|
|
; - that are special to the specification ("reg", "interrupts", etc.)
|
|
; - with array types (uint8-array, phandle-array, etc.)
|
|
; - with "enum:" in their bindings
|
|
; - zephyr device API specific macros for phandle-arrays
|
|
; - phandle specifier names ("foo-names")
|
|
;
|
|
; Here are some examples:
|
|
;
|
|
; - _EXISTS: property, index or name existence flag
|
|
; - _SIZE: logical property length
|
|
; - _IDX_<i>: values of individual array elements
|
|
; - _IDX_<DIGIT>_VAL_<dt-name>: values of individual specifier
|
|
; cells within a phandle array
|
|
; - _ADDR_<i>: for reg properties, the i-th register block address
|
|
; - _LEN_<i>: for reg properties, the i-th register block length
|
|
;
|
|
; The different cases are not exhaustively documented here to avoid
|
|
; this file going stale. Please see devicetree.h if you need to know
|
|
; the details.
|
|
prop-suf = 1*( "_" gen-name ["_" dt-name] )
|
|
|
|
; --------------------------------------------------------------------
|
|
; other-macro: grab bag for everything that isn't a node-macro.
|
|
|
|
; See examples below.
|
|
other-macro = %s"DT_N_" alternate-id
|
|
; Total count of enabled instances of a compatible.
|
|
other-macro =/ %s"DT_N_INST_" dt-name %s"_NUM"
|
|
; These are used internally by DT_INST_FOREACH, which iterates over
|
|
; each enabled instance of a compatible.
|
|
other-macro =/ %s"DT_FOREACH_INST_" dt-name
|
|
other-macro =/ %s"DT_FOREACH_IMPL_" DIGIT
|
|
; E.g.: #define DT_CHOSEN_zephyr_flash
|
|
other-macro =/ %s"DT_CHOSEN_" dt-name
|
|
; Declares that a compatible has at least one node on a bus.
|
|
;
|
|
; Example:
|
|
;
|
|
; #define DT_COMPAT_vnd_dev_BUS_spi 1
|
|
other-macro =/ %s"DT_COMPAT_" dt-name %s"_BUS_" dt-name
|
|
|
|
; --------------------------------------------------------------------
|
|
; alternate-id: another way to specify a node besides a path-id
|
|
;
|
|
; Example devicetree:
|
|
;
|
|
; / {
|
|
; aliases {
|
|
; dev = &dev_1;
|
|
; };
|
|
;
|
|
; soc {
|
|
; dev_1: device@123 {
|
|
; compatible = "vnd,device";
|
|
; };
|
|
; };
|
|
; };
|
|
;
|
|
; Node device@123 has these alternate-id values:
|
|
;
|
|
; - ALIAS_dev
|
|
; - NODELABEL_dev_1
|
|
; - INST_0_vnd_device
|
|
;
|
|
; The full alternate-id macros are:
|
|
;
|
|
; #define DT_N_INST_0_vnd_device DT_N_S_soc_S_device_123
|
|
; #define DT_N_ALIAS_dev DT_N_S_soc_S_device_123
|
|
; #define DT_N_NODELABEL_dev_1 DT_N_S_soc_S_device_123
|
|
;
|
|
; These mainly exist to allow pasting an alternate-id macro onto a
|
|
; "_P_<prop-id>" to access node properties given a node's alias, etc.
|
|
;
|
|
; Notice that "inst"-type IDs have a leading instance identifier,
|
|
; which is generated by the devicetree scripts. The other types of
|
|
; alternate-id begin immediately with names taken from the devicetree.
|
|
alternate-id = ( %s"ALIAS" / %s"NODELABEL" ) dt-name
|
|
alternate-id =/ %s"INST_" 1*DIGIT "_" dt-name
|
|
|
|
; --------------------------------------------------------------------
|
|
; miscellaneous helper definitions
|
|
|
|
; A dt-name is one or more:
|
|
; - lowercase ASCII letters (a-z)
|
|
; - numbers (0-9)
|
|
; - underscores ("_")
|
|
;
|
|
; They are the result of converting names or combinations of names
|
|
; from devicetree to a valid component of a C identifier by
|
|
; lowercasing letters (in practice, this is a no-op) and converting
|
|
; non-alphanumeric characters to underscores.
|
|
dt-name = 1*( lower / DIGIT / "_" )
|
|
|
|
; gen-name is used as a stand-in for a component of a generated macro
|
|
; name which does not come from devicetree (dt-name covers that case).
|
|
;
|
|
; - uppercase ASCII letters (a-z)
|
|
; - numbers (0-9)
|
|
; - underscores ("_")
|
|
gen-name = upper 1*( upper / DIGIT / "_" )
|
|
|
|
; "lowercase ASCII letter" turns out to be pretty annoying to specify
|
|
; in RFC-7405 syntax.
|
|
;
|
|
; This is just ASCII letters a (0x61) through z (0x7a).
|
|
lower = %x61-7A
|
|
|
|
; "uppercase ASCII letter" in RFC-7405 syntax
|
|
upper = %x41-5A
|