dts: bindings: improve base.yaml descriptions #70701
Conversation
zephyrbot
added
the
area: Devicetree Binding
dts/bindings/base/base.yaml
Outdated
| The compatible property can have multiple values. Additional values are | ||
| useful when the device is a specific instance of a more general family, to | ||
| allow the system to match from most- to least-specific device drivers. |
There was a problem hiding this comment.
Perhaps explicitly mention that the list goes from "most specific" to "least specific"?
There was a problem hiding this comment.
please check reworded version
dts/bindings/base/base.yaml
Outdated
|
|
||
| "#size-cells": | ||
| type: int | ||
| description: number of size cells in reg property | ||
| description: | | ||
| This property encodes the number of bits required by register block |
There was a problem hiding this comment.
Technically, it encodes the number of u32 cells required by register block sizes. As far as I know, there is no established convention that these must be concatenated in order to form a total number of bits (i.e. #size-cells = <2> meaning 64 bit size)?
There was a problem hiding this comment.
I think we should reword both the #size-cells and #address-cells descriptions to be more like what is in the devicetree spec 0.4, section 2.3.5:
The #address-cells property defines the number of <u32> cells used to encode the address field in a childnode’s reg property. The #size-cells property defines the number of <u32> cells used to encode the size field in a childnode’s reg property.
|
This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time. |
|
@mbolivar-ampere Ping |
|
@mbolivar-ampere will you be able to come back to this PR? |
|
This pull request has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 14 days. Note, that you can always re-open a closed pull request at any time. |
|
Assigning to myself to help get this to mergeable |
kartben
force-pushed
the
improve-dt-binding-docs
branch
from
e7b48b0 to
786faf0
Compare
|
simple rebase for now -- will follow-up with more changes |
kartben
force-pushed
the
improve-dt-binding-docs
branch
from
786faf0 to
45ee122
Compare
|
Implemented some of @henrikbrixandersen requested changes and also proposed descriptions for the power domain properties that have been introduced since this PR was last touched. |
dts/bindings/base/base.yaml
Outdated
| an abbreviated name of the vendor. The "device" is usually from | ||
| the datasheet. | ||
|
|
||
| The compatible property can have multiple values, usually ordered from |
There was a problem hiding this comment.
Not usually, always.
| The compatible property can have multiple values, usually ordered from | |
| The compatible property can have multiple values, ordered from |
dts/bindings/base/base.yaml
Outdated
|
|
||
| "#size-cells": | ||
| type: int | ||
| description: number of size cells in reg property | ||
| description: | | ||
| This property encodes the number of bits required by register block |
There was a problem hiding this comment.
I think we should reword both the #size-cells and #address-cells descriptions to be more like what is in the devicetree spec 0.4, section 2.3.5:
The #address-cells property defines the number of <u32> cells used to encode the address field in a childnode’s reg property. The #size-cells property defines the number of <u32> cells used to encode the size field in a childnode’s reg property.
|
@mbolivar you might be able to help push this one over the finish line |
This file defines some of the most important properties in the devicetree, including core concepts like 'compatible', 'reg', and 'interrupts'. For some reason, we've never prioritized writing up proper descriptions that indicate their importance or show where the user can get more information about them in the specs or elsewhere. Give this file a once-over to improve the situation. Signed-off-by: Martí Bolívar <[email protected]> Signed-off-by: Martí Bolívar <[email protected]>
mbolivar
force-pushed
the
improve-dt-binding-docs
branch
from
45ee122 to
df9528c
Compare
This file defines some of the most important properties in the devicetree, including core concepts like 'compatible', 'reg', and 'interrupts'. For some reason, we've never prioritized writing up proper descriptions that indicate their importance or show where the user can get more information about them in the specs or elsewhere.
Give this file a once-over to improve the situation.