Driver Model in U-Boot

---

Introduction

Driver model in U-Boot is to provide a consistent model for U-Boot drivers and the platform data / device tree information used by the drivers to instantiate devices.

The model is arranged by three concepts:

Uclass

A group of devices which operate in the same way. A uclass provides a way of accessing individual devices within the group, but always using the same interface.

Driver

Some code which talks to a peripheral and presents a higher-level interface to it.

Device

An instance of a driver, tied to a peripheral port or peripheral, created from some platform-specific information bound to a driver.

Configure U-Boot

To use U-Boot with driver model and device tree supported, you should to do,

1. First enable the driver model support, then enable the drivers after enabling the driver model for the corresponding sub-system.
2. Provide the run-time configuration of U-Boot via a flat device tree (fdt), and enables the FDT library as well.

Note: In the following configuration, we take sama5d2 Xplained boards for example.

Firstly, use your default kernel configuration:

make ARCH=arm sama5d2_xplained_spiflash_defconfig

You can configure the options by using U-Boot configuration interface.

make ARCH=arm menuconfig

Enable the Device Tree Support

First, you enable the device tree support by enabling the symbols CONFIG_OF_CONTROL

You should select the separate DTB for DT control ( CONFIG_OF_SEPARATE ), which is recommended for the production devices.

Then specify the default filename of the device tree source CONFIG_DEFAULT_DEVICE_TREE="at91-sama5d2_xplained"

    Device Tree Control  --->
        [*] Run-time configuration via Device Tree
        [*]   Enable run-time configuration via Device Tree in SPL
              Provider of DTB for DT control (Separate DTB for DT control)  --->
        (at91-sama5d2_xplained) Default Device Tree for DT control
        (pinctrl-0 pinctrl-names interrupt-parent) List of device tree properties to drop for SPL

Of course, the FDT library is required.

Make the FDT library available by enabling the symbols CONFIG_OF_LIBFDT, CONFIG_SPL_OF_LIBFDT.

    Library routines  --->
        [*] Enable the FDT library
        [ ] Enable the FDT library overlay support
        [*] Enable the FDT library for SPL

The FDT library provides functions for accessing binary device tree images in memory, such as adding and removing nodes and properties, scanning through the tree and finding particular compatible nodes.

Enable the Drivers

Enable the Driver Model

First of all, you can enable the driver model by enabling the symbol CONFIG_DM, CONFIG_SPL_DM.

     Device Drivers  ---> 
          Generic Driver Options  --->
              [*] Enable Driver Model
              [*]   Enable Driver Model for SPL
              [*]   Enable warnings in driver model
              [*]   Support device removal
              [*]   Support stdio registration
              [*]   Support numbered aliases in device tree

Enable the Individual Driver

Before enabling the driver with driver model support, you should enable the common clock framework and pinctrl framework.

Support the Clock Framework

Enable the clock framework by enabling the symbols CONFIG_CLK, CONFIG_SPL_CLK, CONFIG_CLK_AT91.

    Device Drivers  ---> 
        Clock  --->
            [*] Enable clock driver support 
            [*]   Enable clock support in SPL
            [*] AT91 clock drivers
            [*]   Support UTMI PLL Clock
            [*]   Support H32MX 32-bit Matrix Clock
            [*]   Support Generic Clock

Support the Pinctrl Framework

Enable the pinctrl framework by enabling the symbols, CONFIG_PINCTRL, CONFIG_PINCTRL_AT91PIO4.

    Device Drivers  ---> 
        Pin controllers  --->
            [*] Support pin controllers
            [*]   Support full pin controllers
            [*]     Support generic pin controllers
            [*]       Support pin multiplexing controllers

            [*] AT91 PIO4 pinctrl driver

Enable the Individual Driver with Driver Model

To enable the driver with driver model support, firstly, enable the driver model for the corresponding sub-system, i.e. enabling the symbol like CONFIG_DM_<subsys>.

Take the Atmel SPI driver for example to configure.

Enable the Atmel SPI driver with driver model by enabling the symbols, CONFIG_DM_SPI, CONFIG_ATMEL_SPI.

    Device Drivers  --->
        SPI Support  --->
            [*] Enable Driver Model for SPI drivers

            [*]   Atmel SPI driver

Build U-Boot

Building

After the configuration is done, built U-Boot with driver model and fdt supported in two ways,

1. Build with the default DTS which is defined from CONFIG_DEFAULT_DEVICE_TREE.

make ARCH=arm CROSS_COMPILE=<path_to_cross-compiler/cross-compiler-prefix->

2. Build with the user specified dts file.

make ARCH=arm CROSS_COMPILE=<path_to_cross-compiler/cross-compiler-prefix-> DEVICE_TREE=<dts-file-name>

path_to_cross-compiler is only needed if the path of the cross-compiler is not in your PATH.

cross-compiler-prefix- looks like arm-linux- , arm-elf- , arm-linux-gnueabihf- , or arm-none-linux-gnueabi- .

dts-file-name is the filename of the device tree source for the board, as at91-sama5d2_xplained

The Building Output files

After the built is done, you can see the generated files like,

$ ls -l u-boot*.bin
-rw-rw-r-- 1 wyang wyang 381857 Nov  3 15:45 u-boot.bin
-rw-rw-r-- 1 wyang wyang 381857 Nov  3 15:45 u-boot-dtb.bin
-rwxrwxr-x 1 wyang wyang 369264 Nov  3 15:45 u-boot-nodtb.bin

$ ls -l u-boot*.dtb
-rw-rw-r-- 1 wyang wyang 12593 Nov  3 15:45 u-boot.dtb

u-boot.dtb is the compact binary file produced by dtc tool from the device tree source file.

u-boot-nodtb.bin is the raw binary file of U-Boot without DT stuff.

u-boot-dtb.bin is the binary file generated by joining the above two file.

cat u-boot-nodtb.bin u-boot.dtb > u-boot-dtb.bin

u-boot.bin is identical to u-boot-dtb.bin.

u-boot.bin single file is pretty different as the one without the DM/DT but it's use is the same.

Nothing needs to change for the first bootloader.

U-Boot dm Command usage

Flash the u-boot.bin image to the target board.

After U-Boot boot up successfully, you can check the driver model tree using the dm command. It is very helpful for the developer to check the device binding.

=> dm help
dm - Driver model low level access

Usage:
dm tree         Dump driver model tree ('*' = activated)
dm uclass        Dump list of instances for each uclass
dm devres        Dump list of device resources for each device

=> dm tree
 Class       Probed   Name
----------------------------------------
 root        [ + ]    root_driver
 video       [ + ]    |-- hlcdc@f0000000
 vidconsole0 [ + ]    |   `-- hlcdc@f0000000.vidconsole0
 simple_bus  [ + ]    `-- ahb
 usb         [   ]        |-- ehci@00500000
 mmc         [ + ]        |-- sdio-host@a0000000
 mmc         [ + ]        |-- sdio-host@b0000000
 simple_bus  [ + ]        `-- apb
 clk         [ + ]            |-- pmc@f0014000
 clk         [ + ]            |   |-- mainck
 clk         [ + ]            |   |-- pllack
 clk         [ + ]            |   |-- utmick
 clk         [ + ]            |   |-- masterck
 clk         [ + ]            |   |-- h32mxck
 clk         [   ]            |   |-- systemck
 clk         [   ]            |   |   |-- ddrck
 clk         [   ]            |   |   |-- lcdck
 clk         [   ]            |   |   |-- uhpck
 clk         [   ]            |   |   |-- udpck
 clk         [   ]            |   |   |-- pck0
 clk         [   ]            |   |   |-- pck1
 clk         [   ]            |   |   |-- pck2
 clk         [   ]            |   |   `-- iscck
 clk         [ + ]            |   |-- periph32ck
 clk         [ + ]            |   |   |-- macb0_clk
 clk         [   ]            |   |   |-- tdes_clk
 clk         [   ]            |   |   |-- matrix1_clk
 clk         [   ]            |   |   |-- hsmc_clk
 clk         [ + ]            |   |   |-- pioA_clk
 clk         [   ]            |   |   |-- flx0_clk
 clk         [   ]            |   |   |-- flx1_clk
 clk         [   ]            |   |   |-- flx2_clk
 clk         [   ]            |   |   |-- flx3_clk
 clk         [   ]            |   |   |-- flx4_clk
 clk         [   ]            |   |   |-- uart0_clk
 clk         [   ]            |   |   |-- uart1_clk
 clk         [   ]            |   |   |-- uart2_clk
 clk         [   ]            |   |   |-- uart3_clk
 clk         [   ]            |   |   |-- uart4_clk
 clk         [   ]            |   |   |-- twi0_clk
 clk         [ + ]            |   |   |-- twi1_clk
 clk         [ + ]            |   |   |-- spi0_clk
 clk         [   ]            |   |   |-- spi1_clk
 clk         [   ]            |   |   |-- tcb0_clk
 clk         [   ]            |   |   |-- tcb1_clk
 clk         [   ]            |   |   |-- pwm_clk
 clk         [   ]            |   |   |-- adc_clk
 clk         [   ]            |   |   |-- uhphs_clk
 clk         [   ]            |   |   |-- udphs_clk
 clk         [   ]            |   |   |-- ssc0_clk
 clk         [   ]            |   |   |-- ssc1_clk
 clk         [   ]            |   |   |-- trng_clk
 clk         [   ]            |   |   |-- pdmic_clk
 clk         [   ]            |   |   |-- i2s0_clk
 clk         [   ]            |   |   |-- i2s1_clk
 clk         [   ]            |   |   |-- can0_clk
 clk         [   ]            |   |   |-- can1_clk
 clk         [   ]            |   |   `-- classd_clk
 clk         [ + ]            |   |-- periph64ck
 clk         [   ]            |   |   |-- dma0_clk
 clk         [   ]            |   |   |-- dma1_clk
 clk         [   ]            |   |   |-- aes_clk
 clk         [   ]            |   |   |-- aesb_clk
 clk         [   ]            |   |   |-- sha_clk
 clk         [   ]            |   |   |-- mpddr_clk
 clk         [   ]            |   |   |-- matrix0_clk
 clk         [ + ]            |   |   |-- sdmmc0_hclk
 clk         [ + ]            |   |   |-- sdmmc1_hclk
 clk         [ + ]            |   |   |-- lcdc_clk
 clk         [   ]            |   |   |-- isc_clk
 clk         [   ]            |   |   |-- qspi0_clk
 clk         [   ]            |   |   `-- qspi1_clk
 clk         [ + ]            |   `-- gck
 clk         [ + ]            |       |-- sdmmc0_gclk
 clk         [ + ]            |       |-- sdmmc1_gclk
 clk         [   ]            |       |-- tcb0_gclk
 clk         [   ]            |       |-- tcb1_gclk
 clk         [   ]            |       |-- pwm_gclk
 clk         [   ]            |       |-- pdmic_gclk
 clk         [   ]            |       |-- i2s0_gclk
 clk         [   ]            |       |-- i2s1_gclk
 clk         [   ]            |       |-- can0_gclk
 clk         [   ]            |       |-- can1_gclk
 clk         [   ]            |       `-- classd_gclk
 spi         [ + ]            |-- spi@f8000000
 spi_flash   [   ]            |   `-- spi_flash@0
 eth         [ + ]            |-- ethernet@f8008000
 serial      [ + ]            |-- serial@f8020000
 clk         [   ]            |-- sckc@f8048050
 clk         [   ]            |   `-- slowck
 i2c         [ + ]            |-- i2c@fc028000
 i2c_generic [ + ]            |   `-- generic_5c
 gpio        [ + ]            `-- gpio@fc038000
 pinctrl     [ + ]                `-- pinctrl
 pinconfig   [ + ]                    |-- i2c1_default
 pinconfig   [ + ]                    |-- pinctrl_lcd_base
 pinconfig   [ + ]                    |-- pinctrl_lcd_pwm
 pinconfig   [ + ]                    |-- pinctrl_lcd_rgb666
 pinconfig   [ + ]                    |-- macb0_phy_irq
 pinconfig   [ + ]                    |-- macb0_rmii
 pinconfig   [   ]                    |-- qspi0_default
 pinconfig   [ + ]                    |-- sdmmc0_cmd_dat_default
 pinconfig   [ + ]                    |-- sdmmc0_ck_cd_default
 pinconfig   [ + ]                    |-- sdmmc1_cmd_dat_default
 pinconfig   [ + ]                    |-- sdmmc1_ck_cd_default
 pinconfig   [ + ]                    |-- spi0_default
 pinconfig   [ + ]                    |-- uart1_default
 pinconfig   [   ]                    |-- usb_default
 pinconfig   [   ]                    `-- usba_vbus

=> dm uclass
uclass 0: root
- * root_driver @ 3f981028, seq 0, (req -1)

uclass 9: simple_bus
- * ahb @ 3f981138, seq 0, (req -1)
- * apb @ 3f981308, seq 1, (req -1)

uclass 11: clk
- * pmc@f0014000 @ 3f981390, seq 0, (req -1)
- * mainck @ 3f9813e8, seq 7, (req -1)
- * pllack @ 3f981450, seq 8, (req -1)
- * utmick @ 3f9814b8, seq 9, (req -1)
- * masterck @ 3f981520, seq 10, (req -1)
- * h32mxck @ 3f981578, seq 14, (req -1)
-   systemck @ 3f9815e0
-   ddrck @ 3f981648
-   lcdck @ 3f9816a0
-   uhpck @ 3f9816f8
-   udpck @ 3f981750
-   pck0 @ 3f9817a8
-   pck1 @ 3f981800
-   pck2 @ 3f981858
-   iscck @ 3f9818b0
- * periph32ck @ 3f981908, seq 1, (req -1)
- * macb0_clk @ 3f981970, seq 17, (req -1)
-   tdes_clk @ 3f9819c8
-   matrix1_clk @ 3f981a20
-   hsmc_clk @ 3f981a78
- * pioA_clk @ 3f981ad0, seq 2, (req -1)
-   flx0_clk @ 3f981b28
-   flx1_clk @ 3f981b80
-   flx2_clk @ 3f981bd8
-   flx3_clk @ 3f981c30
-   flx4_clk @ 3f981c88
-   uart0_clk @ 3f981ce0
-   uart1_clk @ 3f981d38
-   uart2_clk @ 3f981d90
-   uart3_clk @ 3f981de8
-   uart4_clk @ 3f981e40
-   twi0_clk @ 3f981e98
- * twi1_clk @ 3f981ef0, seq 16, (req -1)
- * spi0_clk @ 3f981f48, seq 13, (req -1)
-   spi1_clk @ 3f981fa0
-   tcb0_clk @ 3f981ff8
-   tcb1_clk @ 3f982050
-   pwm_clk @ 3f9820a8
-   adc_clk @ 3f982100
-   uhphs_clk @ 3f982158
-   udphs_clk @ 3f9821b0
-   ssc0_clk @ 3f982208
-   ssc1_clk @ 3f982260
-   trng_clk @ 3f9822b8
-   pdmic_clk @ 3f982310
-   i2s0_clk @ 3f982368
-   i2s1_clk @ 3f9823c0
-   can0_clk @ 3f982418
-   can1_clk @ 3f982470
-   classd_clk @ 3f9824c8
- * periph64ck @ 3f982520, seq 3, (req -1)
-   dma0_clk @ 3f982588
-   dma1_clk @ 3f9825e0
-   aes_clk @ 3f982638
-   aesb_clk @ 3f982690
-   sha_clk @ 3f9826e8
-   mpddr_clk @ 3f982740
-   matrix0_clk @ 3f982798
- * sdmmc0_hclk @ 3f9827f0, seq 4, (req -1)
- * sdmmc1_hclk @ 3f982848, seq 11, (req -1)
- * lcdc_clk @ 3f9828a0, seq 15, (req -1)
-   isc_clk @ 3f9828f8
-   qspi0_clk @ 3f982950
-   qspi1_clk @ 3f9829a8
- * gck @ 3f982a00, seq 5, (req -1)
- * sdmmc0_gclk @ 3f982a68, seq 6, (req -1)
- * sdmmc1_gclk @ 3f982ac0, seq 12, (req -1)
-   tcb0_gclk @ 3f982b18
-   tcb1_gclk @ 3f982b70
-   pwm_gclk @ 3f982bc8
-   pdmic_gclk @ 3f982c20
-   i2s0_gclk @ 3f982c78
-   i2s1_gclk @ 3f982cd0
-   can0_gclk @ 3f982d28
-   can1_gclk @ 3f982d80
-   classd_gclk @ 3f982dd8
-   sckc@f8048050 @ 3f983070
-   slowck @ 3f9830c8

uclass 14: disk
uclass 18: eth
- * ethernet@f8008000 @ 3f982f78, seq 0, (req -1)

uclass 19: gpio
- * gpio@fc038000 @ 3f9831b8, seq 0, (req -1)

uclass 20: i2c
- * i2c@fc028000 @ 3f983140, seq 1, (req 1)

uclass 22: i2c_generic
- * generic_5c @ 3f984350, seq 0, (req -1)

uclass 28: usb_mass_storage
uclass 30: mmc
- * sdio-host@a0000000 @ 3f981258, seq 0, (req -1)
- * sdio-host@b0000000 @ 3f9812b0, seq 1, (req -1)

uclass 34: panel
uclass 35: backlight
uclass 39: pinctrl
- * pinctrl @ 3f983240, seq 0, (req -1)

uclass 40: pinconfig
- * i2c1_default @ 3f9832c8, seq 9, (req -1)
- * pinctrl_lcd_base @ 3f983320, seq 6, (req -1)
- * pinctrl_lcd_pwm @ 3f983378, seq 7, (req -1)
- * pinctrl_lcd_rgb666 @ 3f9833d0, seq 8, (req -1)
- * macb0_phy_irq @ 3f983428, seq 11, (req -1)
- * macb0_rmii @ 3f983480, seq 10, (req -1)
-   qspi0_default @ 3f9834d8
- * sdmmc0_cmd_dat_default @ 3f983530, seq 1, (req -1)
- * sdmmc0_ck_cd_default @ 3f983588, seq 2, (req -1)
- * sdmmc1_cmd_dat_default @ 3f9835e0, seq 3, (req -1)
- * sdmmc1_ck_cd_default @ 3f983638, seq 4, (req -1)
- * spi0_default @ 3f983690, seq 5, (req -1)
- * uart1_default @ 3f9836e8, seq 0, (req -1)
-   usb_default @ 3f983740
-   usba_vbus @ 3f983798

uclass 44: regulator
uclass 48: serial
- * serial@f8020000 @ 3f983008, seq 0, (req -1)

uclass 49: spi
- * spi@f8000000 @ 3f982e50, seq 0, (req 0)

uclass 50: spi_flash
- * spi_flash@0 @ 3f982ed8, seq 0, (req -1)

uclass 51: spi_generic
uclass 56: usb
-   ehci@00500000 @ 3f9811d0

uclass 57: usb_dev_generic
uclass 58: usb_hub
uclass 59: video
- * hlcdc@f0000000 @ 3f9810b0, seq 0, (req -1)

uclass 61: vidconsole0
- * hlcdc@f0000000.vidconsole0 @ 3f984088, seq 0, (req -1)

Reference Documents

1. doc/driver-model/README
2. doc/README.fdt-control
3. U-Boot Driver Model

Other useful slides:

1. Order at Last, The New U-Boot Driver Model Architecture by Simon Glass, ELEC 2015, Dublin.
2. Driver Model in U-Boot by Simon Glass, U-Boot Mini-Summit 2014.