Linux Device tree

• The kernel no longer contains the description of the hardware, it is located in a separate binary: the device tree blob
• The bootloader loads two binaries: the kernel image and the DTB
  • Kernel image remains uImage or zImage
  • DTB located in arch/arm/boot/dts, one per board
• The bootloader passes the DTB address through r2. It is supposed to adjust the DTB with memory information, kernel command line, and potentially other info.
• No more machine type
• U-Boot command: bootm <kernel img addr> - <dtb addr>

• A device tree is a tree data structure with nodes that describe the physical devices in a system.
• An ePAPR(Embedded Power Architecture Platform Requirements)-compliant device tree describes device information in a system that cannot be dynamically detected by a client program.

• On ARM, all Device Tree Source files (DTS) are for now located in arch/arm/boot/dts
  • .dts files for board-level definitions
  • .dtsi files for included files, generally containing SoC-level definitions
• A tool, the Device Tree Compiler compiles the source into a binary form.
  • Source code located in scripts/dtc
• The Device Tree Blob is produced by the compiler, and is the binary that gets loaded by the bootloader and parsed by the kernel at boot time.
• arch/arm/boot/dts/Makefile lists which DTBs should be generated at build time.

  dtb-$(CONFIG_ARCH_MVEBU) += armada-370-db.dtb \
  armada-370-mirabox.dtb \
  ...
  

The Device Tree side:

The compatible string used to bind a device with the driver:

static struct of_device_id mxs_auart_dt_ids[] = {
   {
     .compatible = "fsl,imx28-auart",
     .data = &mxs_auart_devtype[IMX28_AUART]
   }, {
     .compatible = "fsl,imx23-auart",
     .data = &mxs_auart_devtype[IMX23_AUART]
   }, { /* sentinel */ }
   };
   MODULE_DEVICE_TABLE(of, mxs_auart_dt_ids);
  // [...]
   static struct platform_driver mxs_auart_driver = {
   .probe = mxs_auart_probe,
   .remove = mxs_auart_remove,
   .driver = {
   .name = "mxs-auart",
   .of_match_table = mxs_auart_dt_ids,
     },
   };
// Code from drivers/tty/serial/mxs-auart.c

• of_match_device allows to get the matching entry in the mxs_auart_dt_ids table.
• Useful to get the driver-specific data field, typically used to alter the behavior of the driver depending on the variant of the detected device.
• of_match_device allows to get the matching entry in the mxs_auart_dt_ids table
• Useful to get the driver-specific data field, typically used to alter the behavior of the driver depending on the variant of the detected device.

  static int mxs_auart_probe(struct platform_device *pdev)
  {
    const struct of_device_id *of_id =
        of_match_device(mxs_auart_dt_ids, &pdev->dev);
    if (of_id) {
      /* Use of_id->data here */
      // [...]
    }
    // [...]
  }
  

some driver examples:

• Getting a reference to the clock
  • described by the clocks property
  • s->clk = clk_get(&pdev->dev, NULL);
• Getting the I/O registers resource
  • described by the reg property
  • r = platform_get_resource(pdev, IORESOURCE_MEM, 0);
• Getting the interrupt
  • described by the interrupts property
  • s->irq = platform_get_irq(pdev, 0);
• Get a DMA channel
  • described by the dmas property
  • s->rx_dma_chan = dma_request_slave_channel(s->dev, "rx");
  • s->tx_dma_chan = dma_request_slave_channel(s->dev, "tx");
• Check some custom property
  • struct device_node *np = pdev->dev.of_node;
  • if (of_get_property(np, "fsl,uart-has-rtscts", NULL))

• Device Tree files are not monolithic, they can be split in several files, including each other.
• .dtsi files are included files, while .dts files are final Device Trees.
• Typically, .dtsi will contain definition of SoC-level information.
• The .dts file contains the board-level information.
• The inclusion works by overlaying the tree of the including file over the tree of the included file.
• Inclusion using the DT operator /include/, or since a few kernel releases, the DTS go through the C preprocessor, so #include is recommended.

Device Tree inclusion example:

• bindings, for how specific types and classes of devices are represented in the device tree.
• The compatible property of a device node describes the specific binding (or bindings) to which the node complies.
• When creating a new device tree representation for a device, a binding should be created that fully describes the required properties and value of the device. This set of properties shall be sufficiently descriptive to provide device drivers with needed attributes of the device.

• Device Tree for Dummies - The Linux Foundation
• Device Tree Usage: how to write a device tree for a new machine
• DeviceTree.org website, http://www.devicetree.org
• Device Tree Specification Release 0.1
• Device Tree documentation in the kernel sources, Documentation/devicetree