1; An RFC 7405 ABNF grammar for devicetree macros. 2; 3; This does *not* cover macros pulled out of DT via Kconfig, 4; like CONFIG_SRAM_BASE_ADDRESS, etc. It only describes the 5; ones that start with DT_ and are directly generated. 6 7; -------------------------------------------------------------------- 8; dt-macro: the top level nonterminal for a devicetree macro 9; 10; A dt-macro starts with uppercase "DT_", and is one of: 11; 12; - a <node-macro>, generated for a particular node 13; - some <other-macro>, a catch-all for other types of macros 14dt-macro = node-macro / other-macro 15 16; -------------------------------------------------------------------- 17; node-macro: a macro related to a node 18 19; A macro about a property value 20node-macro = property-macro 21; A macro about the pinctrl properties in a node. 22node-macro =/ pinctrl-macro 23; A macro about the GPIO hog properties in a node. 24node-macro =/ gpiohogs-macro 25; EXISTS macro: node exists in the devicetree 26node-macro =/ %s"DT_N" path-id %s"_EXISTS" 27; Bus macros: the plain BUS is a way to access a node's bus controller. 28; The additional dt-name suffix is added to match that node's bus type; 29; the dt-name in this case is something like "spi" or "i2c". 30node-macro =/ %s"DT_N" path-id %s"_BUS" ["_" dt-name] 31; The reg property is special and has its own macros. 32node-macro =/ %s"DT_N" path-id %s"_REG_NUM" 33node-macro =/ %s"DT_N" path-id %s"_REG_IDX_" DIGIT "_EXISTS" 34node-macro =/ %s"DT_N" path-id %s"_REG_IDX_" DIGIT 35 %s"_VAL_" ( %s"ADDRESS" / %s"SIZE") 36node-macro =/ %s"DT_N" path-id %s"_REG_NAME_" dt-name 37 %s"_VAL_" ( %s"ADDRESS" / %s"SIZE") 38node-macro =/ %s"DT_N" path-id %s"_REG_NAME_" dt-name "_EXISTS" 39; The interrupts property is also special. 40node-macro =/ %s"DT_N" path-id %s"_IRQ_NUM" 41node-macro =/ %s"DT_N" path-id %s"_IRQ_LEVEL" 42node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT "_EXISTS" 43node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT 44 %s"_VAL_" dt-name [ %s"_EXISTS" ] 45node-macro =/ %s"DT_N" path-id %s"_CONTROLLER" 46node-macro =/ %s"DT_N" path-id %s"_IRQ_NAME_" dt-name 47 %s"_VAL_" dt-name [ %s"_EXISTS" ] 48node-macro =/ %s"DT_N" path-id %s"_IRQ_NAME_" dt-name "_CONTROLLER" 49; The ranges property is also special. 50node-macro =/ %s"DT_N" path-id %s"_RANGES_NUM" 51node-macro =/ %s"DT_N" path-id %s"_RANGES_IDX_" DIGIT "_EXISTS" 52node-macro =/ %s"DT_N" path-id %s"_RANGES_IDX_" DIGIT 53 %s"_VAL_" ( %s"CHILD_BUS_FLAGS" / %s"CHILD_BUS_ADDRESS" / 54 %s"PARENT_BUS_ADDRESS" / %s"LENGTH") 55node-macro =/ %s"DT_N" path-id %s"_RANGES_IDX_" DIGIT 56 %s"_VAL_CHILD_BUS_FLAGS_EXISTS" 57node-macro =/ %s"DT_N" path-id %s"_FOREACH_RANGE" 58; Subnodes of the fixed-partitions compatible get macros which contain 59; a unique ordinal value for each partition 60node-macro =/ %s"DT_N" path-id %s"_PARTITION_ID" DIGIT 61; Macros are generated for each of a node's compatibles; 62; dt-name in this case is something like "vnd_device". 63node-macro =/ %s"DT_N" path-id %s"_COMPAT_MATCHES_" dt-name 64node-macro =/ %s"DT_N" path-id %s"_COMPAT_VENDOR_IDX_" DIGIT "_EXISTS" 65node-macro =/ %s"DT_N" path-id %s"_COMPAT_VENDOR_IDX_" DIGIT 66node-macro =/ %s"DT_N" path-id %s"_COMPAT_MODEL_IDX_" DIGIT "_EXISTS" 67node-macro =/ %s"DT_N" path-id %s"_COMPAT_MODEL_IDX_" DIGIT 68; Every non-root node gets one of these macros, which expands to the node 69; identifier for that node's parent in the devicetree. 70node-macro =/ %s"DT_N" path-id %s"_PARENT" 71; These are used internally by DT_FOREACH_PROP_ELEM(_SEP)(_VARGS), which 72; iterates over each property element. 73node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM" 74node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_SEP" 75node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_VARGS" 76node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_SEP_VARGS" 77; These are used by DT_CHILD_NUM and DT_CHILD_NUM_STATUS_OKAY macros 78node-macro =/ %s"DT_N" path-id %s"_CHILD_NUM" 79node-macro =/ %s"DT_N" path-id %s"_CHILD_NUM_STATUS_OKAY" 80; These are used internally by DT_FOREACH_CHILD, which iterates over 81; each child node. 82node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD" 83node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_SEP" 84node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_VARGS" 85node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_SEP_VARGS" 86; These are used internally by DT_FOREACH_CHILD_STATUS_OKAY, which iterates 87; over each child node with status "okay". 88node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_STATUS_OKAY" 89node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_STATUS_OKAY_SEP" 90node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_STATUS_OKAY_VARGS" 91node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS" 92; These are used internally by DT_FOREACH_NODELABEL and 93; DT_FOREACH_NODELABEL_VARGS, which iterate over a node's node labels. 94node-macro =/ %s"DT_N" path-id %s"_FOREACH_NODELABEL" [ %s"_VARGS" ] 95; These are used internally by DT_NUM_NODELABELS 96node-macro =/ %s"DT_N" path-id %s"_NODELABEL_NUM" 97; The node's zero-based index in the list of it's parent's child nodes. 98node-macro =/ %s"DT_N" path-id %s"_CHILD_IDX" 99; The node's status macro; dt-name in this case is something like "okay" 100; or "disabled". 101node-macro =/ %s"DT_N" path-id %s"_STATUS_" dt-name 102; The node's dependency ordinal. This is a non-negative integer 103; value that is used to represent dependency information. 104node-macro =/ %s"DT_N" path-id %s"_ORD" 105; The node's path, as a string literal 106node-macro =/ %s"DT_N" path-id %s"_PATH" 107; The node's name@unit-addr, as a string literal 108node-macro =/ %s"DT_N" path-id %s"_FULL_NAME" 109; The dependency ordinals of a node's requirements (direct dependencies). 110node-macro =/ %s"DT_N" path-id %s"_REQUIRES_ORDS" 111; The dependency ordinals of a node supports (reverse direct dependencies). 112node-macro =/ %s"DT_N" path-id %s"_SUPPORTS_ORDS" 113 114; -------------------------------------------------------------------- 115; pinctrl-macro: a macro related to the pinctrl properties in a node 116; 117; These are a bit of a special case because they kind of form an array, 118; but the array indexes correspond to pinctrl-DIGIT properties in a node. 119; 120; So they're related to a node, but not just one property within the node. 121; 122; The following examples assume something like this: 123; 124; foo { 125; pinctrl-0 = <&bar>; 126; pinctrl-1 = <&baz>; 127; pinctrl-names = "default", "sleep"; 128; }; 129 130; Total number of pinctrl-DIGIT properties in the node. May be zero. 131; 132; #define DT_N_<node path>_PINCTRL_NUM 2 133pinctrl-macro = %s"DT_N" path-id %s"_PINCTRL_NUM" 134; A given pinctrl-DIGIT property exists. 135; 136; #define DT_N_<node path>_PINCTRL_IDX_0_EXISTS 1 137; #define DT_N_<node path>_PINCTRL_IDX_1_EXISTS 1 138pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_IDX_" DIGIT %s"_EXISTS" 139; A given pinctrl property name exists. 140; 141; #define DT_N_<node path>_PINCTRL_NAME_default_EXISTS 1 142; #define DT_N_<node path>_PINCTRL_NAME_sleep_EXISTS 1 143pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_EXISTS" 144; The corresponding index number of a named pinctrl property. 145; 146; #define DT_N_<node path>_PINCTRL_NAME_default_IDX 0 147; #define DT_N_<node path>_PINCTRL_NAME_sleep_IDX 1 148pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_IDX" 149; The node identifier for the phandle in a named pinctrl property. 150; 151; #define DT_N_<node path>_PINCTRL_NAME_default_IDX_0_PH <node id for 'bar'> 152; 153; There's no need for a separate macro for access by index: that's 154; covered by property-macro. We only need this because the map from 155; names to properties is implicit in the structure of the DT. 156pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_IDX_" DIGIT %s"_PH" 157 158; -------------------------------------------------------------------- 159; gpiohogs-macro: a macro related to GPIO hog nodes 160; 161; The following examples assume something like this: 162; 163; gpio1: gpio@... { 164; compatible = "vnd,gpio"; 165; #gpio-cells = <2>; 166; 167; node-1 { 168; gpio-hog; 169; gpios = <0x0 0x10>, <0x1 0x20>; 170; output-high; 171; }; 172; 173; node-2 { 174; gpio-hog; 175; gpios = <0x2 0x30>; 176; output-low; 177; }; 178; }; 179; 180; Bindings fragment for the vnd,gpio compatible: 181; 182; gpio-cells: 183; - pin 184; - flags 185 186; The node contains GPIO hogs. 187; 188; #define DT_N_<node-1 path>_GPIO_HOGS_EXISTS 1 189; #define DT_N_<node-2 path>_GPIO_HOGS_EXISTS 1 190gpioshogs-macro = %s"DT_N" path-id %s"_GPIO_HOGS_EXISTS" 191; Number of hogged GPIOs in a node. 192; 193; #define DT_N_<node-1 path>_GPIO_HOGS_NUM 2 194; #define DT_N_<node-2 path>_GPIO_HOGS_NUM 1 195gpioshogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_NUM" 196; A given logical GPIO hog array index exists. 197; 198; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_EXISTS 1 199; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_1_EXISTS 1 200; #define DT_N_<node-2 path>_GPIO_HOGS_IDX_0_EXISTS 1 201gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_EXISTS" 202; The node identifier for the phandle of a logical index in the GPIO hogs array. 203; These macros are currently unused by Zephyr. 204; 205; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_PH <node id for 'gpio1'> 206; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_1_PH <node id for 'gpio1'> 207; #define DT_N_<node-2 path>_GPIO_HOGS_IDX_0_PH <node id for 'gpio1'> 208gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_PH" 209; The pin cell of a logical index in the GPIO hogs array exists. 210; 211; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_VAL_pin_EXISTS 1 212; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_1_VAL_pin_EXISTS 1 213; #define DT_N_<node-2 path>_GPIO_HOGS_IDX_0_VAL_pin_EXISTS 1 214gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_VAL_pin_EXISTS" 215; The value of the pin cell of a logical index in the GPIO hogs array. 216; 217; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_VAL_pin 0 218; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_1_VAL_pin 1 219; #define DT_N_<node-2 path>_GPIO_HOGS_IDX_0_VAL_pin 2 220gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_VAL_pin" 221; The flags cell of a logical index in the GPIO hogs array exists. 222; 223; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_VAL_flags_EXISTS 1 224; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_1_VAL_flags_EXISTS 1 225; #define DT_N_<node-2 path>_GPIO_HOGS_IDX_0_VAL_flags_EXISTS 1 226gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_VAL_flags_EXISTS" 227; The value of the flags cell of a logical index in the GPIO hogs array. 228; 229; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_VAL_flags 0x10 230; #define DT_N_<node-1 path>_GPIO_HOGS_IDX_1_VAL_flags 0x20 231; #define DT_N_<node-2 path>_GPIO_HOGS_IDX_0_VAL_flags 0x30 232gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_VAL_flags" 233 234; -------------------------------------------------------------------- 235; property-macro: a macro related to a node property 236; 237; These combine a node identifier with a "lowercase-and-underscores form" 238; property name. The value expands to something related to the property's 239; value. 240; 241; The optional prop-suf suffix is when there's some specialized 242; subvalue that deserves its own macro, like the macros for an array 243; property's individual elements 244; 245; The "plain vanilla" macro for a property's value, with no prop-suf, 246; looks like this: 247; 248; DT_N_<node path>_P_<property name> 249; 250; Components: 251; 252; - path-id: node's devicetree path converted to a C token 253; - prop-id: node's property name converted to a C token 254; - prop-suf: an optional property-specific suffix 255property-macro = %s"DT_N" path-id %s"_P_" prop-id [prop-suf] 256 257; -------------------------------------------------------------------- 258; path-id: a node's path-based macro identifier 259; 260; This in "lowercase-and-underscores" form. I.e. it is 261; the node's devicetree path converted to a C token by changing: 262; 263; - each slash (/) to _S_ 264; - all letters to lowercase 265; - non-alphanumerics characters to underscores 266; 267; For example, the leaf node "bar-BAZ" in this devicetree: 268; 269; / { 270; foo@123 { 271; bar-BAZ {}; 272; }; 273; }; 274; 275; has path-id "_S_foo_123_S_bar_baz". 276path-id = 1*( %s"_S_" dt-name ) 277 278; ---------------------------------------------------------------------- 279; prop-id: a property identifier 280; 281; A property name converted to a C token by changing: 282; 283; - all letters to lowercase 284; - non-alphanumeric characters to underscores 285; 286; Example node: 287; 288; chosen { 289; zephyr,console = &uart1; 290; WHY,AM_I_SHOUTING = "unclear"; 291; }; 292; 293; The 'zephyr,console' property has prop-id 'zephyr_console'. 294; 'WHY,AM_I_SHOUTING' has prop-id 'why_am_i_shouting'. 295prop-id = dt-name 296 297; ---------------------------------------------------------------------- 298; prop-suf: a property-specific macro suffix 299; 300; Extra macros are generated for properties: 301; 302; - that are special to the specification ("reg", "interrupts", etc.) 303; - with array types (uint8-array, phandle-array, etc.) 304; - with "enum:" in their bindings 305; - that have zephyr device API specific macros for phandle-arrays 306; - related to phandle specifier names ("foo-names") 307; 308; Here are some examples: 309; 310; - _EXISTS: property, index or name existence flag 311; - _SIZE: logical property length 312; - _IDX_<i>: values of individual array elements 313; - _IDX_<DIGIT>_VAL_<dt-name>: values of individual specifier 314; cells within a phandle array 315; - _ADDR_<i>: for reg properties, the i-th register block address 316; - _LEN_<i>: for reg properties, the i-th register block length 317; 318; The different cases are not exhaustively documented here to avoid 319; this file going stale. Please see devicetree.h if you need to know 320; the details. 321prop-suf = 1*( "_" gen-name ["_" dt-name] ) 322 323; -------------------------------------------------------------------- 324; other-macro: grab bag for everything that isn't a node-macro. 325 326; See examples below. 327other-macro = %s"DT_N_" alternate-id 328; Total count of enabled instances of a compatible. 329other-macro =/ %s"DT_N_INST_" dt-name %s"_NUM_OKAY" 330; These are used internally by DT_FOREACH_NODE and 331; DT_FOREACH_STATUS_OKAY_NODE respectively. 332other-macro =/ %s"DT_FOREACH_HELPER" 333other-macro =/ %s"DT_FOREACH_OKAY_HELPER" 334; These are used internally by DT_FOREACH_STATUS_OKAY, 335; which iterates over each enabled node of a compatible. 336other-macro =/ %s"DT_FOREACH_OKAY_" dt-name 337other-macro =/ %s"DT_FOREACH_OKAY_VARGS_" dt-name 338; These are used internally by DT_INST_FOREACH_STATUS_OKAY, 339; which iterates over each enabled instance of a compatible. 340other-macro =/ %s"DT_FOREACH_OKAY_INST_" dt-name 341other-macro =/ %s"DT_FOREACH_OKAY_INST_VARGS_" dt-name 342; E.g.: #define DT_CHOSEN_zephyr_flash 343other-macro =/ %s"DT_CHOSEN_" dt-name 344; Declares that a compatible has at least one node on a bus. 345; Example: 346; 347; #define DT_COMPAT_vnd_dev_BUS_spi 1 348other-macro =/ %s"DT_COMPAT_" dt-name %s"_BUS_" dt-name 349; Declares that a compatible has at least one status "okay" node. 350; Example: 351; 352; #define DT_COMPAT_HAS_OKAY_vnd_dev 1 353other-macro =/ %s"DT_COMPAT_HAS_OKAY_" dt-name 354; Currently used to allow mapping a lowercase-and-underscores "label" 355; property to a fixed-partitions node. See the flash map API docs 356; for an example. 357other-macro =/ %s"DT_COMPAT_" dt-name %s"_LABEL_" dt-name 358 359; -------------------------------------------------------------------- 360; alternate-id: another way to specify a node besides a path-id 361; 362; Example devicetree: 363; 364; / { 365; aliases { 366; dev = &dev_1; 367; }; 368; 369; soc { 370; dev_1: device@123 { 371; compatible = "vnd,device"; 372; }; 373; }; 374; }; 375; 376; Node device@123 has these alternate-id values: 377; 378; - ALIAS_dev 379; - NODELABEL_dev_1 380; - INST_0_vnd_device 381; 382; The full alternate-id macros are: 383; 384; #define DT_N_INST_0_vnd_device DT_N_S_soc_S_device_123 385; #define DT_N_ALIAS_dev DT_N_S_soc_S_device_123 386; #define DT_N_NODELABEL_dev_1 DT_N_S_soc_S_device_123 387; 388; These mainly exist to allow pasting an alternate-id macro onto a 389; "_P_<prop-id>" to access node properties given a node's alias, etc. 390; 391; Notice that "inst"-type IDs have a leading instance identifier, 392; which is generated by the devicetree scripts. The other types of 393; alternate-id begin immediately with names taken from the devicetree. 394alternate-id = ( %s"ALIAS" / %s"NODELABEL" ) dt-name 395alternate-id =/ %s"INST_" 1*DIGIT "_" dt-name 396 397; -------------------------------------------------------------------- 398; miscellaneous helper definitions 399 400; A dt-name is one or more: 401; - lowercase ASCII letters (a-z) 402; - numbers (0-9) 403; - underscores ("_") 404; 405; They are the result of converting names or combinations of names 406; from devicetree to a valid component of a C identifier by 407; lowercasing letters (in practice, this is a no-op) and converting 408; non-alphanumeric characters to underscores. 409; 410; You'll see these referred to as "lowercase-and-underscores" forms of 411; various devicetree identifiers throughout the documentation. 412dt-name = 1*( lower / DIGIT / "_" ) 413 414; gen-name is used as a stand-in for a component of a generated macro 415; name which does not come from devicetree (dt-name covers that case). 416; 417; - uppercase ASCII letters (a-z) 418; - numbers (0-9) 419; - underscores ("_") 420gen-name = upper 1*( upper / DIGIT / "_" ) 421 422; "lowercase ASCII letter" turns out to be pretty annoying to specify 423; in RFC-7405 syntax. 424; 425; This is just ASCII letters a (0x61) through z (0x7a). 426lower = %x61-7A 427 428; "uppercase ASCII letter" in RFC-7405 syntax 429upper = %x41-5A 430
