diff --git a/dts/bindings/base/base.yaml b/dts/bindings/base/base.yaml index 485c4dfe7d12..dbc2feb14839 100644 --- a/dts/bindings/base/base.yaml +++ b/dts/bindings/base/base.yaml @@ -5,7 +5,16 @@ include: [pm.yaml] properties: status: type: string - description: indicates the operational status of a device + description: | + Indicates the operational status of the hardware or other + resource that the node represents. In particular: + + - "okay" means the resource is operational and, for example, + can be used by device drivers + - "disabled" means the resource is not operational and the system + should treat it as if it is not present + + For details, see "2.3.4 status" in Devicetree Specification v0.4. enum: - "ok" # Deprecated form - "okay" @@ -17,93 +26,189 @@ properties: compatible: type: string-array required: true - description: compatible strings + description: | + This property is a list of strings that essentially define what + type of hardware or other resource this devicetree node + represents. Each device driver checks for specific compatible + property values to find the devicetree nodes that represent + resources that the driver should manage. + + The recommended format is "vendor,device", The "vendor" part is + an abbreviated name of the vendor. The "device" is usually from + the datasheet. + + The compatible property can have multiple values, ordered from + most- to least-specific. Having additional values is useful when the + device is a specific instance of a more general family, to allow the + system to match the most specific driver available. + + For details, see "2.3.1 compatible" in Devicetree Specification v0.4. reg: type: array - description: register space + description: | + Information used to address the device. The value is specific to + the device (i.e. is different depending on the compatible + property). + + The "reg" property is typically a sequence of (address, length) pairs. + Each pair is called a "register block". Values are + conventionally written in hex. + + For details, see "2.3.6 reg" in Devicetree Specification v0.4. reg-names: type: string-array - description: name of each register space + description: | + Optional names given to each register block in the "reg" property. + For example: + + / { + soc { + #address-cells = <1>; + #size-cells = <1>; + + uart@1000 { + reg = <0x1000 0x2000>, <0x3000 0x4000>; + reg-names = "foo", "bar"; + }; + }; + }; + + The uart@1000 node has two register blocks: + + - one with base address 0x1000, size 0x2000, and name "foo" + - another with base address 0x3000, size 0x4000, and name "bar" interrupts: type: array - description: interrupts for device + description: | + Information about interrupts generated by the device, encoded as an array + of one or more interrupt specifiers. The format of the data in this property + varies by where the device appears in the interrupt tree. Devices with the same + "interrupt-parent" will use the same format in their interrupts properties. + + For details, see "2.4 Interrupts and Interrupt Mapping" in + Devicetree Specification v0.4. # Does not follow the 'type: phandle-array' scheme, but gets type-checked # by the code. Declare it here just so that other bindings can make it # 'required: true' easily if they want to. interrupts-extended: type: compound - description: extended interrupt specifier for device + description: | + Extended interrupt specifier for device, used as an alternative to + the "interrupts" property. + + For details, see "2.4 Interrupts and Interrupt Mapping" in + Devicetree Specification v0.4. interrupt-names: type: string-array - description: name of each interrupt + description: | + Optional names given to each interrupt generated by a device. + The interrupts themselves are defined in either "interrupts" or + "interrupts-extended" properties. + + For details, see "2.4 Interrupts and Interrupt Mapping" in + Devicetree Specification v0.4. interrupt-parent: type: phandle - description: phandle to interrupt controller node + description: | + If present, this refers to the node which handles interrupts generated + by this device. + + For details, see "2.4 Interrupts and Interrupt Mapping" in + Devicetree Specification v0.4. # description of label should be given in bindings inheriting base.yaml # label property is included here to help enforce its type being string label: type: string - description: No description provided for this label + description: | + Human readable string describing the device. Use of this property is + deprecated except as needed on a case-by-case basis. + + For details, see "4.1.2 Miscellaneous Properties" in Devicetree + Specification v0.4. clocks: type: phandle-array - description: Clock gate information + description: | + Information about the device's clock providers. In general, this property + should follow conventions established in the dt-schema binding: + + https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml clock-names: type: string-array - description: name of each clock + description: | + Optional names given to each clock provider in the "clocks" property. "#address-cells": type: int - description: number of address cells in reg property + description: | + This property encodes the number of cells used by address fields + in "reg" properties in this node's children. + + For details, see "2.3.5 #address-cells and #size-cells" in Devicetree + Specification v0.4. "#size-cells": type: int - description: number of size cells in reg property + description: | + This property encodes the number of cells used by size fields in + "reg" properties in this node's children. + + For details, see "2.3.5 #address-cells and #size-cells" in Devicetree + Specification v0.4. dmas: type: phandle-array - description: DMA channels specifiers + description: | + DMA channel specifiers relevant to the device. dma-names: type: string-array - description: Provided names of DMA channel specifiers + description: | + Optional names given to the DMA channel specifiers in the "dmas" property. io-channels: type: phandle-array - description: IO channels specifiers + description: | + IO channel specifiers relevant to the device. io-channel-names: type: string-array - description: Provided names of IO channel specifiers + description: | + Optional names given to the IO channel specifiers in the "io-channels" property. mboxes: type: phandle-array - description: mailbox / IPM channels specifiers + description: | + Mailbox / IPM channel specifiers relevant to the device. specifier-space: mbox mbox-names: type: string-array - description: Provided names of mailbox / IPM channel specifiers + description: | + Optional names given to the mbox specifiers in the "mboxes" property. power-domains: type: phandle-array - description: Power domain specifiers + description: | + Power domain specifiers relevant to the device. power-domain-names: type: string-array - description: Provided names of power domain specifiers + description: | + Optional names given to the power domain specifiers in the "power-domains" property. "#power-domain-cells": type: int - description: Number of cells in power-domains property + description: | + Number of cells in power-domains property zephyr,deferred-init: type: boolean