dts: bindings: improve base.yaml descriptions

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 <u32> 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 <u32> 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