€•îIŒsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ8/translations/zh_CN/devicetree/bindings/writing-bindings”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ8/translations/zh_TW/devicetree/bindings/writing-bindings”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ8/translations/it_IT/devicetree/bindings/writing-bindings”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ8/translations/ja_JP/devicetree/bindings/writing-bindings”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ8/translations/ko_KR/devicetree/bindings/writing-bindings”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ8/translations/sp_SP/devicetree/bindings/writing-bindings”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1h¡hhhžhhŸŒR/var/lib/git/docbuild/linux/Documentation/devicetree/bindings/writing-bindings.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒDOs and DON’Ts for designing and writing Devicetree bindings”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ paragraph”“”)”}”(hŒ’This is a list of common review feedback items focused on binding design. With every rule, there are exceptions and bindings have many gray areas.”h]”hŒ’This is a list of common review feedback items focused on binding design. With every rule, there are exceptions and bindings have many gray areas.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hŒ_For guidelines related to patches, see Documentation/devicetree/bindings/submitting-patches.rst”h]”hŒ_For guidelines related to patches, see Documentation/devicetree/bindings/submitting-patches.rst”…””}”(hhÙhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K hh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒOverall design”h]”hŒOverall design”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhçhžhhŸh³h KubhŒ bullet_list”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hŒÏDO attempt to make bindings complete even if a driver doesn't support some features. For example, if a device has an interrupt, then include the 'interrupts' property even if the driver is only polled mode. ”h]”hÊ)”}”(hŒÎDO attempt to make bindings complete even if a driver doesn't support some features. For example, if a device has an interrupt, then include the 'interrupts' property even if the driver is only polled mode.”h]”hŒÔDO attempt to make bindings complete even if a driver doesn’t support some features. For example, if a device has an interrupt, then include the ‘interrupts’ property even if the driver is only polled mode.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khhÿubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhhúhžhhŸh³h Nubhþ)”}”(hŒ•DON'T refer to Linux or "device driver" in bindings. Bindings should be based on what the hardware has, not what an OS and driver currently support. ”h]”hÊ)”}”(hŒ”DON'T refer to Linux or "device driver" in bindings. Bindings should be based on what the hardware has, not what an OS and driver currently support.”h]”hŒšDON’T refer to Linux or “device driver†in bindings. Bindings should be based on what the hardware has, not what an OS and driver currently support.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khjubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhhúhžhhŸh³h Nubhþ)”}”(hŒŒDO use node names matching the class of the device. Many standard names are defined in the DT Spec. If there isn't one, consider adding it. ”h]”hÊ)”}”(hŒ‹DO use node names matching the class of the device. Many standard names are defined in the DT Spec. If there isn't one, consider adding it.”h]”hŒDO use node names matching the class of the device. Many standard names are defined in the DT Spec. If there isn’t one, consider adding it.”…””}”(hj3hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj/ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhhúhžhhŸh³h Nubhþ)”}”(hŒ\DO check that the example matches the documentation especially after making review changes. ”h]”hÊ)”}”(hŒ[DO check that the example matches the documentation especially after making review changes.”h]”hŒ[DO check that the example matches the documentation especially after making review changes.”…””}”(hjKhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhjGubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhhúhžhhŸh³h Nubhþ)”}”(hŒàDON'T create nodes just for the sake of instantiating drivers. Multi-function devices only need child nodes when the child nodes have their own DT resources. A single node can be multiple providers (e.g. clocks and resets). ”h]”hÊ)”}”(hŒßDON'T create nodes just for the sake of instantiating drivers. Multi-function devices only need child nodes when the child nodes have their own DT resources. A single node can be multiple providers (e.g. clocks and resets).”h]”hŒáDON’T create nodes just for the sake of instantiating drivers. Multi-function devices only need child nodes when the child nodes have their own DT resources. A single node can be multiple providers (e.g. clocks and resets).”…””}”(hjchžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj_ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhhúhžhhŸh³h Nubhþ)”}”(hŒÉDON'T use 'syscon' alone without a specific compatible string. A 'syscon' hardware block should have a compatible string unique enough to infer the register layout of the entire block (at a minimum). ”h]”hÊ)”}”(hŒÇDON'T use 'syscon' alone without a specific compatible string. A 'syscon' hardware block should have a compatible string unique enough to infer the register layout of the entire block (at a minimum).”h]”hŒÑDON’T use ‘syscon’ alone without a specific compatible string. A ‘syscon’ hardware block should have a compatible string unique enough to infer the register layout of the entire block (at a minimum).”…””}”(hj{hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K"hjwubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhhúhžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1høhŸh³h Khhçhžhubeh}”(h]”Œoverall-design”ah ]”h"]”Œoverall design”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ Properties”h]”hŒ Properties”…””}”(hj¢hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjŸhžhhŸh³h K(ubhù)”}”(hhh]”(hþ)”}”(hŒóDO make 'compatible' properties specific. DON'T use wildcards in compatible strings. DO use fallback compatibles when devices are the same as or a subset of prior implementations. DO add new compatibles in case there are new features or bugs. ”h]”hÊ)”}”(hŒòDO make 'compatible' properties specific. DON'T use wildcards in compatible strings. DO use fallback compatibles when devices are the same as or a subset of prior implementations. DO add new compatibles in case there are new features or bugs.”h]”hŒøDO make ‘compatible’ properties specific. DON’T use wildcards in compatible strings. DO use fallback compatibles when devices are the same as or a subset of prior implementations. DO add new compatibles in case there are new features or bugs.”…””}”(hj·hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K*hj³ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj°hžhhŸh³h Nubhþ)”}”(hŒµDO use a vendor prefix on device-specific property names. Consider if properties could be common among devices of the same class. Check other existing bindings for similar devices. ”h]”hÊ)”}”(hŒ´DO use a vendor prefix on device-specific property names. Consider if properties could be common among devices of the same class. Check other existing bindings for similar devices.”h]”hŒ´DO use a vendor prefix on device-specific property names. Consider if properties could be common among devices of the same class. Check other existing bindings for similar devices.”…””}”(hjÏhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K/hjËubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj°hžhhŸh³h Nubhþ)”}”(hŒoDON'T redefine common properties. Just reference the definition and define constraints specific to the device. ”h]”hÊ)”}”(hŒnDON'T redefine common properties. Just reference the definition and define constraints specific to the device.”h]”hŒpDON’T redefine common properties. Just reference the definition and define constraints specific to the device.”…””}”(hjçhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K3hjãubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj°hžhhŸh³h Nubhþ)”}”(hŒÉDO use common property unit suffixes for properties with scientific units. Recommended suffixes are listed at https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml ”h]”hÊ)”}”(hŒÈDO use common property unit suffixes for properties with scientific units. Recommended suffixes are listed at https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml”h]”(hŒnDO use common property unit suffixes for properties with scientific units. Recommended suffixes are listed at ”…””}”(hjÿhžhhŸNh NubhŒ reference”“”)”}”(hŒZhttps://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml”h]”hŒZhttps://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j uh1jhjÿubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K6hjûubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj°hžhhŸh³h Nubhþ)”}”(hŒmDO define properties in terms of constraints. How many entries? What are possible values? What is the order? ”h]”hÊ)”}”(hŒlDO define properties in terms of constraints. How many entries? What are possible values? What is the order?”h]”hŒlDO define properties in terms of constraints. How many entries? What are possible values? What is the order?”…””}”(hj(hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K:hj$ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj°hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”j•j–uh1høhŸh³h K*hjŸhžhubeh}”(h]”Œ properties”ah ]”h"]”Œ properties”ah$]”h&]”uh1h´hh¶hžhhŸh³h K(ubhµ)”}”(hhh]”(hº)”}”(hŒTypical cases and caveats”h]”hŒTypical cases and caveats”…””}”(hjMhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjJhžhhŸh³h K>ubhù)”}”(hhh]”(hþ)”}”(hŒüPhandle entries, like clocks/dmas/interrupts/resets, should always be explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is more than one phandle. When used, both of these fields need the same constraints (e.g. list of items). ”h]”hÊ)”}”(hŒûPhandle entries, like clocks/dmas/interrupts/resets, should always be explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is more than one phandle. When used, both of these fields need the same constraints (e.g. list of items).”h]”hŒûPhandle entries, like clocks/dmas/interrupts/resets, should always be explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is more than one phandle. When used, both of these fields need the same constraints (e.g. list of items).”…””}”(hjbhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K@hj^ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj[hžhhŸh³h Nubhþ)”}”(hŒ{For names used in {clock,dma,interrupt,reset}-names, do not add any suffix, e.g.: "tx" instead of "txirq" (for interrupt). ”h]”hÊ)”}”(hŒzFor names used in {clock,dma,interrupt,reset}-names, do not add any suffix, e.g.: "tx" instead of "txirq" (for interrupt).”h]”hŒ‚For names used in {clock,dma,interrupt,reset}-names, do not add any suffix, e.g.: “tx†instead of “txirq†(for interrupt).”…””}”(hjzhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KEhjvubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj[hžhhŸh³h Nubhþ)”}”(hŒ€Properties without schema types (e.g. without standard suffix or not defined by schema) need the type, even if this is an enum. ”h]”hÊ)”}”(hŒProperties without schema types (e.g. without standard suffix or not defined by schema) need the type, even if this is an enum.”h]”hŒProperties without schema types (e.g. without standard suffix or not defined by schema) need the type, even if this is an enum.”…””}”(hj’hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KHhjŽubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj[hžhhŸh³h Nubhþ)”}”(hŒ¥If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use "unevaluatedProperties:false". In other cases, usually use "additionalProperties:false". ”h]”hÊ)”}”(hŒ¤If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use "unevaluatedProperties:false". In other cases, usually use "additionalProperties:false".”h]”hŒ¬If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use “unevaluatedProperties:falseâ€. In other cases, usually use “additionalProperties:falseâ€.”…””}”(hjªhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KKhj¦ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj[hžhhŸh³h Nubhþ)”}”(hŒîFor sub-blocks/components of bigger device (e.g. SoC blocks) use rather device-based compatible (e.g. SoC-based compatible), instead of custom versioning of that component. For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2". ”h]”hÊ)”}”(hŒíFor sub-blocks/components of bigger device (e.g. SoC blocks) use rather device-based compatible (e.g. SoC-based compatible), instead of custom versioning of that component. For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".”h]”hŒõFor sub-blocks/components of bigger device (e.g. SoC blocks) use rather device-based compatible (e.g. SoC-based compatible), instead of custom versioning of that component. For example use “vendor,soc1234-i2c†instead of “vendor,i2c-v2â€.”…””}”(hjÂhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KOhj¾ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj[hžhhŸh³h Nubhþ)”}”(hŒ]"syscon" is not a generic property. Use vendor and type, e.g. "vendor,power-manager-syscon". ”h]”hÊ)”}”(hŒ\"syscon" is not a generic property. Use vendor and type, e.g. "vendor,power-manager-syscon".”h]”hŒd“syscon†is not a generic property. Use vendor and type, e.g. “vendor,power-manager-sysconâ€.”…””}”(hjÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KThjÖubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj[hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”j•j–uh1høhŸh³h K@hjJhžhubeh}”(h]”Œtypical-cases-and-caveats”ah ]”h"]”Œtypical cases and caveats”ah$]”h&]”uh1h´hh¶hžhhŸh³h K>ubhµ)”}”(hhh]”(hº)”}”(hŒBoard/SoC .dts Files”h]”hŒBoard/SoC .dts Files”…””}”(hjÿhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjühžhhŸh³h KXubhù)”}”(hhh]”(hþ)”}”(hŒCDO put all MMIO devices under a bus node and not at the top-level. ”h]”hÊ)”}”(hŒBDO put all MMIO devices under a bus node and not at the top-level.”h]”hŒBDO put all MMIO devices under a bus node and not at the top-level.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KZhjubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj hžhhŸh³h Nubhþ)”}”(hŒŒDO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit platforms don't need all devices to have 64-bit address and size.”h]”hÊ)”}”(hŒŒDO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit platforms don't need all devices to have 64-bit address and size.”h]”hŒ’DO use non-empty ‘ranges’ to limit the size of child buses/devices. 64-bit platforms don’t need all devices to have 64-bit address and size.”…””}”(hj,hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K\hj(ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhj hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”j•j–uh1høhŸh³h KZhjühžhubeh}”(h]”Œboard-soc-dts-files”ah ]”h"]”Œboard/soc .dts files”ah$]”h&]”uh1h´hh¶hžhhŸh³h KXubeh}”(h]”Œ