gsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget8/translations/zh_CN/devicetree/bindings/dts-coding-stylemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/zh_TW/devicetree/bindings/dts-coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/it_IT/devicetree/bindings/dts-coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/ja_JP/devicetree/bindings/dts-coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/ko_KR/devicetree/bindings/dts-coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget8/translations/sp_SP/devicetree/bindings/dts-coding-stylemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhR/var/lib/git/docbuild/linux/Documentation/devicetree/bindings/dts-coding-style.rsthKubhsection)}(hhh](htitle)}(h%Devicetree Sources (DTS) Coding Styleh]h%Devicetree Sources (DTS) Coding Style}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hWhen writing Devicetree Sources (DTS) please observe below guidelines. They should be considered complementary to any rules expressed already in the Devicetree Specification and the dtc compiler (including W=1 and W=2 builds).h]hWhen writing Devicetree Sources (DTS) please observe below guidelines. They should be considered complementary to any rules expressed already in the Devicetree Specification and the dtc compiler (including W=1 and W=2 builds).}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hlIndividual architectures and subarchitectures can define additional rules, making the coding style stricter.h]hlIndividual architectures and subarchitectures can define additional rules, making the coding style stricter.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hhh](h)}(hNaming and Valid Charactersh]hNaming and Valid Characters}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hThe Devicetree Specification allows a broad range of characters in node and property names, but this coding style narrows the range down to achieve better code readability.h]hThe Devicetree Specification allows a broad range of characters in node and property names, but this coding style narrows the range down to achieve better code readability.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhenumerated_list)}(hhh](h list_item)}(hxNode and property names can use only the following characters: * Lowercase characters: [a-z] * Digits: [0-9] * Dash: - h](h)}(h>Node and property names can use only the following characters:h]h>Node and property names can use only the following characters:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubh bullet_list)}(hhh](j )}(hLowercase characters: [a-z]h]h)}(hj&h]hLowercase characters: [a-z]}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj$ubah}(h]h ]h"]h$]h&]uh1j hj!ubj )}(h Digits: [0-9]h]h)}(hj=h]h Digits: [0-9]}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj;ubah}(h]h ]h"]h$]h&]uh1j hj!ubj )}(hDash: - h]h)}(hDash: -h]hDash: -}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjRubah}(h]h ]h"]h$]h&]uh1j hj!ubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhKhj ubeh}(h]h ]h"]h$]h&]uh1j hjhhhNhNubj )}(hmLabels can use only the following characters: * Lowercase characters: [a-z] * Digits: [0-9] * Underscore: _ h](h)}(h-Labels can use only the following characters:h]h-Labels can use only the following characters:}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjxubj )}(hhh](j )}(hLowercase characters: [a-z]h]h)}(hjh]hLowercase characters: [a-z]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjubj )}(h Digits: [0-9]h]h)}(hjh]h Digits: [0-9]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjubj )}(hUnderscore: _ h]h)}(h Underscore: _h]h Underscore: _}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjubah}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]jpjquh1jhhhKhjxubeh}(h]h ]h"]h$]h&]uh1j hjhhhNhNubj )}(hzUnless a bus defines differently, unit addresses shall use lowercase hexadecimal digits, without leading zeros (padding). h]h)}(hyUnless a bus defines differently, unit addresses shall use lowercase hexadecimal digits, without leading zeros (padding).h]hyUnless a bus defines differently, unit addresses shall use lowercase hexadecimal digits, without leading zeros (padding).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hsHex values in properties, e.g. "reg", shall use lowercase hex. The address part can be padded with leading zeros. h]h)}(hrHex values in properties, e.g. "reg", shall use lowercase hex. The address part can be padded with leading zeros.h]hvHex values in properties, e.g. “reg”, shall use lowercase hex. The address part can be padded with leading zeros.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhhhhhhhKubh)}(h Example::h]hExample:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hhhhubh literal_block)}(hgpi_dma2: dma-controller@a00000 { compatible = "qcom,sm8550-gpi-dma", "qcom,sm6350-gpi-dma"; reg = <0x0 0x00a00000 0x0 0x60000>; }h]hgpi_dma2: dma-controller@a00000 { compatible = "qcom,sm8550-gpi-dma", "qcom,sm6350-gpi-dma"; reg = <0x0 0x00a00000 0x0 0x60000>; }}hj*sbah}(h]h ]h"]h$]h&]hhuh1j(hhhK*hhhhubeh}(h]naming-and-valid-charactersah ]h"]naming and valid charactersah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hOrder of Nodesh]hOrder of Nodes}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@hhhhhK0ubj)}(hhh](j )}(hXNodes on any bus, thus using unit addresses for children, shall be ordered by unit address in ascending order. Alternatively for some subarchitectures, nodes of the same type can be grouped together, e.g. all I2C controllers one after another even if this breaks unit address ordering. h]h)}(hXNodes on any bus, thus using unit addresses for children, shall be ordered by unit address in ascending order. Alternatively for some subarchitectures, nodes of the same type can be grouped together, e.g. all I2C controllers one after another even if this breaks unit address ordering.h]hXNodes on any bus, thus using unit addresses for children, shall be ordered by unit address in ascending order. Alternatively for some subarchitectures, nodes of the same type can be grouped together, e.g. all I2C controllers one after another even if this breaks unit address ordering.}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjTubah}(h]h ]h"]h$]h&]uh1j hjQhhhhhNubj )}(hNodes without unit addresses shall be ordered alpha-numerically by the node name. For a few node types, they can be ordered by the main property, e.g. pin configuration states ordered by value of "pins" property. h]h)}(hNodes without unit addresses shall be ordered alpha-numerically by the node name. For a few node types, they can be ordered by the main property, e.g. pin configuration states ordered by value of "pins" property.h]hNodes without unit addresses shall be ordered alpha-numerically by the node name. For a few node types, they can be ordered by the main property, e.g. pin configuration states ordered by value of “pins” property.}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK8hjlubah}(h]h ]h"]h$]h&]uh1j hjQhhhhhNubj )}(hWhen extending nodes in the board DTS via &label, the entries shall be ordered either alpha-numerically or by keeping the order from DTSI, where the choice depends on the subarchitecture. h]h)}(hWhen extending nodes in the board DTS via &label, the entries shall be ordered either alpha-numerically or by keeping the order from DTSI, where the choice depends on the subarchitecture.h]hWhen extending nodes in the board DTS via &label, the entries shall be ordered either alpha-numerically or by keeping the order from DTSI, where the choice depends on the subarchitecture.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK; ranges = <0x0 0x0 0x06789abc 0x1000>; #dma-cells = <1>; clocks = <&clock_controller 0>, <&clock_controller 1>; clock-names = "bus", "host"; #address-cells = <1>; #size-cells = <1>; vendor,custom-property = <2>; status = "disabled"; child_node: child-class@100 { reg = <0x100 0x200>; /* ... */ }; }; /* Board DTS */ &device_node { vdd-0v9-supply = <&board_vreg1>; vdd-1v8-supply = <&board_vreg4>; vdd-3v3-supply = <&board_vreg2>; vdd-12v-supply = <&board_vreg3>; status = "okay"; }h]hX/* SoC DTSI */ device_node: device-class@6789abc { compatible = "vendor,device"; reg = <0x0 0x06789abc 0x0 0xa123>; ranges = <0x0 0x0 0x06789abc 0x1000>; #dma-cells = <1>; clocks = <&clock_controller 0>, <&clock_controller 1>; clock-names = "bus", "host"; #address-cells = <1>; #size-cells = <1>; vendor,custom-property = <2>; status = "disabled"; child_node: child-class@100 { reg = <0x100 0x200>; /* ... */ }; }; /* Board DTS */ &device_node { vdd-0v9-supply = <&board_vreg1>; vdd-1v8-supply = <&board_vreg4>; vdd-3v3-supply = <&board_vreg2>; vdd-12v-supply = <&board_vreg3>; status = "okay"; }}hj'sbah}(h]h ]h"]h$]h&]hhuh1j(hhhKhjhhubeh}(h]"order-of-properties-in-device-nodeah ]h"]"order of properties in device nodeah$]h&]uh1hhhhhhhhKqubh)}(hhh](h)}(hIndentation and wrappingh]hIndentation and wrapping}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj=hhhhhKubj)}(hhh](j )}(hSUse indentation and wrap lines according to Documentation/process/coding-style.rst.h]h)}(hSUse indentation and wrap lines according to Documentation/process/coding-style.rst.h]hSUse indentation and wrap lines according to Documentation/process/coding-style.rst.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQubah}(h]h ]h"]h$]h&]uh1j hjNhhhhhNubj )}(hdEach entry in arrays with multiple cells, e.g. "reg" with two IO addresses, shall be enclosed in <>.h]h)}(hdEach entry in arrays with multiple cells, e.g. "reg" with two IO addresses, shall be enclosed in <>.h]hhEach entry in arrays with multiple cells, e.g. “reg” with two IO addresses, shall be enclosed in <>.}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjiubah}(h]h ]h"]h$]h&]uh1j hjNhhhhhNubj )}(hFor arrays spanning across lines, it is preferred to split on item boundary and align the continued entries with opening < from the first line. Usually avoid splitting individual items unless they significantly exceed line wrap limit. h]h)}(hFor arrays spanning across lines, it is preferred to split on item boundary and align the continued entries with opening < from the first line. Usually avoid splitting individual items unless they significantly exceed line wrap limit.h]hFor arrays spanning across lines, it is preferred to split on item boundary and align the continued entries with opening < from the first line. Usually avoid splitting individual items unless they significantly exceed line wrap limit.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjNhhhhhNubeh}(h]h ]h"]h$]h&]jjjhjjuh1jhj=hhhhhKubh)}(h Example::h]hExample:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj=hhubj))}(hXthermal-sensor@c271000 { compatible = "qcom,sm8550-tsens", "qcom,tsens-v2"; reg = <0x0 0x0c271000 0x0 0x1000>, <0x0 0x0c222000 0x0 0x1000>; /* Lines exceeding coding style line wrap limit: */ interconnects = <&aggre1_noc MASTER_USB3_0 0 &mc_virt SLAVE_EBI1 0>, <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_USB3_0 0>; };h]hXthermal-sensor@c271000 { compatible = "qcom,sm8550-tsens", "qcom,tsens-v2"; reg = <0x0 0x0c271000 0x0 0x1000>, <0x0 0x0c222000 0x0 0x1000>; /* Lines exceeding coding style line wrap limit: */ interconnects = <&aggre1_noc MASTER_USB3_0 0 &mc_virt SLAVE_EBI1 0>, <&gem_noc MASTER_APPSS_PROC 0 &config_noc SLAVE_USB3_0 0>; };}hjsbah}(h]h ]h"]h$]h&]hhuh1j(hhhKhj=hhubeh}(h]indentation-and-wrappingah ]h"]indentation and wrappingah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hOrganizing DTSI and DTSh]hOrganizing DTSI and DTS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hThe DTSI and DTS files shall be organized in a way representing the common, reusable parts of hardware. Typically, this means organizing DTSI and DTS files into several files:h]hThe DTSI and DTS files shall be organized in a way representing the common, reusable parts of hardware. Typically, this means organizing DTSI and DTS files into several files:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh](j )}(hXDTSI with contents of the entire SoC, without nodes for hardware not present on the SoC.h]h)}(hXDTSI with contents of the entire SoC, without nodes for hardware not present on the SoC.h]hXDTSI with contents of the entire SoC, without nodes for hardware not present on the SoC.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(haIf applicable: DTSI with common or re-usable parts of the hardware, e.g. entire System-on-Module.h]h)}(haIf applicable: DTSI with common or re-usable parts of the hardware, e.g. entire System-on-Module.h]haIf applicable: DTSI with common or re-usable parts of the hardware, e.g. entire System-on-Module.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hDTS representing the board. h]h)}(hDTS representing the board.h]hDTS representing the board.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]jjjhjjuh1jhjhhhhhKubh)}(hXHardware components that are present on the board shall be placed in the board DTS, not in the SoC or SoM DTSI. A partial exception is a common external reference SoC input clock, which could be coded as a fixed-clock in the SoC DTSI with its frequency provided by each board DTS.h]hXHardware components that are present on the board shall be placed in the board DTS, not in the SoC or SoM DTSI. A partial exception is a common external reference SoC input clock, which could be coded as a fixed-clock in the SoC DTSI with its frequency provided by each board DTS.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]organizing-dtsi-and-dtsah ]h"]organizing dtsi and dtsah$]h&]uh1hhhhhhhhKubeh}(h]#devicetree-sources-dts-coding-styleah ]h"]%devicetree sources (dts) coding styleah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjterror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jNjKj=j:jjj:j7jjjFjCu nametypes}(jNj=jj:jjFuh}(jKhj:hjj@j7jjj=jCju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.