michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: dts: improve bindings-upstream

Browse source 
Splitting up the 'general rules' section into subsections makes it
possible to link directly to a particular rule. This is useful when
pointing out an issue during code review, sharing with another
colleague, etc. Adding a local table of contents makes the page
skimmable (it's buried too deeply in the toctree to have sections
listed in the HTML sidebar).

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Marti Bolivar 2023-01-11 15:26:02 -08:00
commit 0d827a8f50
1 changed files with 43 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

25
doc/build/dts/bindings-upstream.rst vendored
View file

@ -12,6 +12,9 @@ Decisions made by the Zephyr devicetree maintainer override the contents of
this section. If that happens, though, please let them know so they can update this section. If that happens, though, please let them know so they can update
this page, or you can send a patch yourself. this page, or you can send a patch yourself.
.. contents:: Contents
:local:
Always check for existing bindings Always check for existing bindings
********************************** **********************************
@ -38,21 +41,30 @@ In particular, this rule applies if:
General rules General rules
************* *************
- Bindings which match a compatible must have file names based on the compatible. File names
==========
Bindings which match a compatible must have file names based on the compatible.
- For example, a binding for compatible ``vnd,foo`` must be named ``vnd,foo.yaml``. - For example, a binding for compatible ``vnd,foo`` must be named ``vnd,foo.yaml``.
- If the binding is bus-specific, you can append the bus to the file name; - If the binding is bus-specific, you can append the bus to the file name;
for example, if the binding YAML has ``on-bus: bar``, you may name the file for example, if the binding YAML has ``on-bus: bar``, you may name the file
``vnd,foo-bar.yaml``. ``vnd,foo-bar.yaml``.
- All recommendations in :ref:`dt-bindings-default` are requirements when Recommendations are requirements
================================
All recommendations in :ref:`dt-bindings-default` are requirements when
submitting the binding. submitting the binding.
In particular, if you use the ``default:`` feature, you must justify the In particular, if you use the ``default:`` feature, you must justify the
value in the property's description. value in the property's description.
- There are two ways to write property ``description:`` strings that are always Descriptions
OK. ============
There are only two acceptable ways to write property ``description:``
strings.
If your description is short, it's fine to use this style: If your description is short, it's fine to use this style:
@ -74,9 +86,10 @@ General rules
multi-line descriptions. This in turn makes these long strings multi-line descriptions. This in turn makes these long strings
display properly in the :ref:`devicetree_binding_index`. display properly in the :ref:`devicetree_binding_index`.
Do not use any other style for long or multi-line strings. Naming conventions
==================
- Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in
property names. Use lowercase letters (``a`` through ``z``) instead of property names. Use lowercase letters (``a`` through ``z``) instead of
uppercase. Use dashes (``-``) instead of underscores. (The one exception to uppercase. Use dashes (``-``) instead of underscores. (The one exception to
this rule is if you are replicating a well-established binding from somewhere this rule is if you are replicating a well-established binding from somewhere