€•TjŒ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 treat device node names as a stable ABI, but instead use phandles or compatibles to find sibling devices. Exception: sub-nodes of given device could be treated as ABI, if explicitly documented in the bindings. ”h]”hÊ)”}”(hŒ×DON'T treat device node names as a stable ABI, but instead use phandles or compatibles to find sibling devices. Exception: sub-nodes of given device could be treated as ABI, if explicitly documented in the bindings.”h]”hŒÙDON’T treat device node names as a stable ABI, but instead use phandles or compatibles to find sibling devices. Exception: sub-nodes of given device could be treated as ABI, if explicitly documented in the bindings.”…””}”(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 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&hjubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhhúhžhhŸh³h Nubhþ)”}”(hŒíDON'T use 'simple-mfd' compatible for non-trivial devices, where children depend on some resources from the parent. Similarly, 'simple-bus' should not be used for complex buses and even 'regs' property means device is not a simple bus. ”h]”hÊ)”}”(hŒëDON'T use 'simple-mfd' compatible for non-trivial devices, where children depend on some resources from the parent. Similarly, 'simple-bus' should not be used for complex buses and even 'regs' property means device is not a simple bus.”h]”hŒùDON’T use ‘simple-mfd’ compatible for non-trivial devices, where children depend on some resources from the parent. Similarly, ‘simple-bus’ should not be used for complex buses and even ‘regs’ property means device is not a simple bus.”…””}”(hj«hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K*hj§ubah}”(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 K1ubhù)”}”(hhh]”(hþ)”}”(hXDO make 'compatible' properties specific. - DON'T use wildcards or device-family names in compatible strings. - DO use fallback compatibles when devices are the same as or a superset of prior implementations. - DO add new compatibles in case there are new features or bugs. - DO use a SoC-specific compatible for all SoC devices, followed by a fallback if appropriate. SoC-specific compatibles are also preferred for the fallbacks. - DON'T use bus suffixes to encode the type of interface device is using. The parent bus node already implies that interface. DON'T add the type of device, if the device cannot be anything else. ”h]”(hÊ)”}”(hŒ)DO make 'compatible' properties specific.”h]”hŒ-DO make ‘compatible’ properties specific.”…””}”(hjçhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K3hjãubhŒ block_quote”“”)”}”(hXX- DON'T use wildcards or device-family names in compatible strings. - DO use fallback compatibles when devices are the same as or a superset of prior implementations. - DO add new compatibles in case there are new features or bugs. - DO use a SoC-specific compatible for all SoC devices, followed by a fallback if appropriate. SoC-specific compatibles are also preferred for the fallbacks. - DON'T use bus suffixes to encode the type of interface device is using. The parent bus node already implies that interface. DON'T add the type of device, if the device cannot be anything else. ”h]”hù)”}”(hhh]”(hþ)”}”(hŒBDON'T use wildcards or device-family names in compatible strings. ”h]”hÊ)”}”(hŒADON'T use wildcards or device-family names in compatible strings.”h]”hŒCDON’T use wildcards or device-family names in compatible strings.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K5hjþubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhjûubhþ)”}”(hŒaDO use fallback compatibles when devices are the same as or a superset of prior implementations. ”h]”hÊ)”}”(hŒ`DO use fallback compatibles when devices are the same as or a superset of prior implementations.”h]”hŒ`DO use fallback compatibles when devices are the same as or a superset of prior implementations.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K7hjubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhjûubhþ)”}”(hŒ?DO add new compatibles in case there are new features or bugs. ”h]”hÊ)”}”(hŒ>DO add new compatibles in case there are new features or bugs.”h]”hŒ>DO add new compatibles in case there are new features or bugs.”…””}”(hj2hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K:hj.ubah}”(h]”h ]”h"]”h$]”h&]”uh1hýhjûubhþ)”}”(hŒœDO use a SoC-specific compatible for all SoC devices, followed by a fallback if appropriate. SoC-specific compatibles are also preferred for the fallbacks. ”h]”hÊ)”}”(hŒ›DO use a SoC-specific compatible for all SoC devices, followed by a fallback if appropriate. SoC-specific compatibles are also preferred for the fallbacks.”h]”hŒ›DO use a SoC-specific compatible for all SoC devices, followed by a fallback if appropriate. SoC-specific compatibles are also preferred for the fallbacks.”…””}”(hjJhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K