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, not 6; defined in a dts_fixup.h file. 7 8; -------------------------------------------------------------------- 9; dt-macro: the top level nonterminal for a devicetree macro 10; 11; A dt-macro starts with uppercase "DT_", and is one of: 12; 13; - a <node-macro>, generated for a particular node 14; - some <other-macro>, a catch-all for other types of macros 15dt-macro = node-macro / other-macro 16 17; -------------------------------------------------------------------- 18; node-macro: a macro related to a node 19 20; A macro about a property value 21node-macro = property-macro 22; A macro about the pinctrl properties in a node. 23node-macro =/ pinctrl-macro 24; EXISTS macro: node exists in the devicetree 25node-macro =/ %s"DT_N" path-id %s"_EXISTS" 26; Bus macros: the plain BUS is a way to access a node's bus controller. 27; The additional dt-name suffix is added to match that node's bus type; 28; the dt-name in this case is something like "spi" or "i2c". 29node-macro =/ %s"DT_N" path-id %s"_BUS" ["_" dt-name] 30; The reg property is special and has its own macros. 31node-macro =/ %s"DT_N" path-id %s"_REG_NUM" 32node-macro =/ %s"DT_N" path-id %s"_REG_IDX_" DIGIT "_EXISTS" 33node-macro =/ %s"DT_N" path-id %s"_REG_IDX_" DIGIT 34 %s"_VAL_" ( %s"ADDRESS" / %s"SIZE") 35node-macro =/ %s"DT_N" path-id %s"_REG_NAME_" dt-name 36 %s"_VAL_" ( %s"ADDRESS" / %s"SIZE") 37; The interrupts property is also special. 38node-macro =/ %s"DT_N" path-id %s"_IRQ_NUM" 39node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT "_EXISTS" 40node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT 41 %s"_VAL_" dt-name [ %s"_EXISTS" ] 42node-macro =/ %s"DT_N" path-id %s"_IRQ_NAME_" dt-name 43 %s"_VAL_" dt-name [ %s"_EXISTS" ] 44; Subnodes of the fixed-partitions compatible get macros which contain 45; a unique ordinal value for each partition 46node-macro =/ %s"DT_N" path-id %s"_PARTITION_ID" DIGIT 47; Macros are generated for each of a node's compatibles; 48; dt-name in this case is something like "vnd_device". 49node-macro =/ %s"DT_N" path-id %s"_COMPAT_MATCHES_" dt-name 50; Every non-root node gets one of these macros, which expands to the node 51; identifier for that node's parent in the devicetree. 52node-macro =/ %s"DT_N" path-id %s"_PARENT" 53; These are used internally by DT_FOREACH_CHILD, which iterates over 54; each child node. 55node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD" 56node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_VARGS" 57; These are used internally by DT_FOREACH_CHILD_STATUS_OKAY, which iterates 58; over each child node with status "okay". 59node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_STATUS_OKAY" 60node-macro =/ %s"DT_N" path-id %s"_FOREACH_CHILD_STATUS_OKAY_VARGS" 61; The node's status macro; dt-name in this case is something like "okay" 62; or "disabled". 63node-macro =/ %s"DT_N" path-id %s"_STATUS_" dt-name 64; The node's dependency ordinal. This is a non-negative integer 65; value that is used to represent dependency information. 66node-macro =/ %s"DT_N" path-id %s"_ORD" 67; The node's path, as a string literal 68node-macro =/ %s"DT_N" path-id %s"_PATH" 69; The node's name@unit-addr, as a string literal 70node-macro =/ %s"DT_N" path-id %s"_FULL_NAME" 71; The dependency ordinals of a node's requirements (direct dependencies). 72node-macro =/ %s"DT_N" path-id %s"_REQUIRES_ORDS" 73; The dependency ordinals of a node supports (reverse direct dependencies). 74node-macro =/ %s"DT_N" path-id %s"_SUPPORTS_ORDS" 75 76; -------------------------------------------------------------------- 77; pinctrl-macro: a macro related to the pinctrl properties in a node 78; 79; These are a bit of a special case because they kind of form an array, 80; but the array indexes correspond to pinctrl-DIGIT properties in a node. 81; 82; So they're related to a node, but not just one property within the node. 83; 84; The following examples assume something like this: 85; 86; foo { 87; pinctrl-0 = <&bar>; 88; pinctrl-1 = <&baz>; 89; pinctrl-names = "default", "sleep"; 90; }; 91 92; Total number of pinctrl-DIGIT properties in the node. May be zero. 93; 94; #define DT_N_<node path>_PINCTRL_NUM 2 95pinctrl-macro = %s"DT_N" path-id %s"_PINCTRL_NUM" 96; A given pinctrl-DIGIT property exists. 97; 98; #define DT_N_<node path>_PINCTRL_IDX_0_EXISTS 1 99; #define DT_N_<node path>_PINCTRL_IDX_1_EXISTS 1 100pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_IDX_" DIGIT %s"_EXISTS" 101; A given pinctrl property name exists. 102; 103; #define DT_N_<node path>_PINCTRL_NAME_default_EXISTS 1 104; #define DT_N_<node path>_PINCTRL_NAME_sleep_EXISTS 1 105pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_EXISTS" 106; The corresponding index number of a named pinctrl property. 107; 108; #define DT_N_<node path>_PINCTRL_NAME_default_IDX 0 109; #define DT_N_<node path>_PINCTRL_NAME_sleep_IDX 1 110pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_IDX" 111; The node identifier for the phandle in a named pinctrl property. 112; 113; #define DT_N_<node path>_PINCTRL_NAME_default_IDX_0_PH <node id for 'bar'> 114; 115; There's no need for a separate macro for access by index: that's 116; covered by property-macro. We only need this because the map from 117; names to properties is implicit in the structure of the DT. 118pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_IDX_" DIGIT %s"_PH" 119 120; -------------------------------------------------------------------- 121; property-macro: a macro related to a node property 122; 123; These combine a node identifier with a "lowercase-and-underscores form" 124; property name. The value expands to something related to the property's 125; value. 126; 127; The optional prop-suf suffix is when there's some specialized 128; subvalue that deserves its own macro, like the macros for an array 129; property's individual elements 130; 131; The "plain vanilla" macro for a property's value, with no prop-suf, 132; looks like this: 133; 134; DT_N_<node path>_P_<property name> 135; 136; Components: 137; 138; - path-id: node's devicetree path converted to a C token 139; - prop-id: node's property name converted to a C token 140; - prop-suf: an optional property-specific suffix 141property-macro = %s"DT_N" path-id %s"_P_" prop-id [prop-suf] 142 143; -------------------------------------------------------------------- 144; path-id: a node's path-based macro identifier 145; 146; This in "lowercase-and-underscores" form. I.e. it is 147; the node's devicetree path converted to a C token by changing: 148; 149; - each slash (/) to _S_ 150; - all letters to lowercase 151; - non-alphanumerics characters to underscores 152; 153; For example, the leaf node "bar-BAZ" in this devicetree: 154; 155; / { 156; foo@123 { 157; bar-BAZ {}; 158; }; 159; }; 160; 161; has path-id "_S_foo_123_S_bar_baz". 162path-id = 1*( %s"_S_" dt-name ) 163 164; ---------------------------------------------------------------------- 165; prop-id: a property identifier 166; 167; A property name converted to a C token by changing: 168; 169; - all letters to lowercase 170; - non-alphanumeric characters to underscores 171; 172; Example node: 173; 174; chosen { 175; zephyr,console = &uart1; 176; WHY,AM_I_SHOUTING = "unclear"; 177; }; 178; 179; The 'zephyr,console' property has prop-id 'zephyr_console'. 180; 'WHY,AM_I_SHOUTING' has prop-id 'why_am_i_shouting'. 181prop-id = dt-name 182 183; ---------------------------------------------------------------------- 184; prop-suf: a property-specific macro suffix 185; 186; Extra macros are generated for properties: 187; 188; - that are special to the specification ("reg", "interrupts", etc.) 189; - with array types (uint8-array, phandle-array, etc.) 190; - with "enum:" in their bindings 191; - that have zephyr device API specific macros for phandle-arrays 192; - related to phandle specifier names ("foo-names") 193; 194; Here are some examples: 195; 196; - _EXISTS: property, index or name existence flag 197; - _SIZE: logical property length 198; - _IDX_<i>: values of individual array elements 199; - _IDX_<DIGIT>_VAL_<dt-name>: values of individual specifier 200; cells within a phandle array 201; - _ADDR_<i>: for reg properties, the i-th register block address 202; - _LEN_<i>: for reg properties, the i-th register block length 203; 204; The different cases are not exhaustively documented here to avoid 205; this file going stale. Please see devicetree.h if you need to know 206; the details. 207prop-suf = 1*( "_" gen-name ["_" dt-name] ) 208 209; -------------------------------------------------------------------- 210; other-macro: grab bag for everything that isn't a node-macro. 211 212; See examples below. 213other-macro = %s"DT_N_" alternate-id 214; Total count of enabled instances of a compatible. 215other-macro =/ %s"DT_N_INST_" dt-name %s"_NUM_OKAY" 216; These are used internally by DT_FOREACH_STATUS_OKAY, 217; which iterates over each enabled node of a compatible. 218other-macro =/ %s"DT_FOREACH_OKAY_" dt-name 219other-macro =/ %s"DT_FOREACH_OKAY_VARGS_" dt-name 220; These are used internally by DT_INST_FOREACH_STATUS_OKAY, 221; which iterates over each enabled instance of a compatible. 222other-macro =/ %s"DT_FOREACH_OKAY_INST_" dt-name 223other-macro =/ %s"DT_FOREACH_OKAY_INST_VARGS_" dt-name 224; E.g.: #define DT_CHOSEN_zephyr_flash 225other-macro =/ %s"DT_CHOSEN_" dt-name 226; Declares that a compatible has at least one node on a bus. 227; Example: 228; 229; #define DT_COMPAT_vnd_dev_BUS_spi 1 230other-macro =/ %s"DT_COMPAT_" dt-name %s"_BUS_" dt-name 231; Declares that a compatible has at least one status "okay" node. 232; Example: 233; 234; #define DT_COMPAT_HAS_OKAY_vnd_dev 1 235other-macro =/ %s"DT_COMPAT_HAS_OKAY_" dt-name 236; Currently used to allow mapping a lowercase-and-underscores "label" 237; property to a fixed-partitions node. See the flash map API docs 238; for an example. 239other-macro =/ %s"DT_COMPAT_" dt-name %s"_LABEL_" dt-name 240 241; -------------------------------------------------------------------- 242; alternate-id: another way to specify a node besides a path-id 243; 244; Example devicetree: 245; 246; / { 247; aliases { 248; dev = &dev_1; 249; }; 250; 251; soc { 252; dev_1: device@123 { 253; compatible = "vnd,device"; 254; }; 255; }; 256; }; 257; 258; Node device@123 has these alternate-id values: 259; 260; - ALIAS_dev 261; - NODELABEL_dev_1 262; - INST_0_vnd_device 263; 264; The full alternate-id macros are: 265; 266; #define DT_N_INST_0_vnd_device DT_N_S_soc_S_device_123 267; #define DT_N_ALIAS_dev DT_N_S_soc_S_device_123 268; #define DT_N_NODELABEL_dev_1 DT_N_S_soc_S_device_123 269; 270; These mainly exist to allow pasting an alternate-id macro onto a 271; "_P_<prop-id>" to access node properties given a node's alias, etc. 272; 273; Notice that "inst"-type IDs have a leading instance identifier, 274; which is generated by the devicetree scripts. The other types of 275; alternate-id begin immediately with names taken from the devicetree. 276alternate-id = ( %s"ALIAS" / %s"NODELABEL" ) dt-name 277alternate-id =/ %s"INST_" 1*DIGIT "_" dt-name 278 279; -------------------------------------------------------------------- 280; miscellaneous helper definitions 281 282; A dt-name is one or more: 283; - lowercase ASCII letters (a-z) 284; - numbers (0-9) 285; - underscores ("_") 286; 287; They are the result of converting names or combinations of names 288; from devicetree to a valid component of a C identifier by 289; lowercasing letters (in practice, this is a no-op) and converting 290; non-alphanumeric characters to underscores. 291; 292; You'll see these referred to as "lowercase-and-underscores" forms of 293; various devicetree identifiers throughout the documentation. 294dt-name = 1*( lower / DIGIT / "_" ) 295 296; gen-name is used as a stand-in for a component of a generated macro 297; name which does not come from devicetree (dt-name covers that case). 298; 299; - uppercase ASCII letters (a-z) 300; - numbers (0-9) 301; - underscores ("_") 302gen-name = upper 1*( upper / DIGIT / "_" ) 303 304; "lowercase ASCII letter" turns out to be pretty annoying to specify 305; in RFC-7405 syntax. 306; 307; This is just ASCII letters a (0x61) through z (0x7a). 308lower = %x61-7A 309 310; "uppercase ASCII letter" in RFC-7405 syntax 311upper = %x41-5A 312
