diff options
Diffstat (limited to 'doc/driver-model')
| -rw-r--r-- | doc/driver-model/design.rst | 18 | ||||
| -rw-r--r-- | doc/driver-model/of-plat.rst | 32 | ||||
| -rw-r--r-- | doc/driver-model/remoteproc-framework.rst | 2 | ||||
| -rw-r--r-- | doc/driver-model/spi-howto.rst | 4 |
4 files changed, 26 insertions, 30 deletions
diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst index f26e4f1..ffed7d5 100644 --- a/doc/driver-model/design.rst +++ b/doc/driver-model/design.rst @@ -422,7 +422,7 @@ Device Tree While plat is useful, a more flexible way of providing device data is by using device tree. In U-Boot you should use this where possible. Avoid -sending patches which make use of the U_BOOT_DEVICE() macro unless strictly +sending patches which make use of the U_BOOT_DRVINFO() macro unless strictly necessary. With device tree we replace the above code with the following device tree @@ -436,7 +436,7 @@ fragment: sides = <4>; }; -This means that instead of having lots of U_BOOT_DEVICE() declarations in +This means that instead of having lots of U_BOOT_DRVINFO() declarations in the board file, we put these in the device tree. This approach allows a lot more generality, since the same board file can support many types of boards (e,g. with the same SoC) just by using different device trees. An added @@ -665,9 +665,9 @@ Bind stage U-Boot discovers devices using one of these two methods: -- Scan the U_BOOT_DEVICE() definitions. U-Boot looks up the name specified +- Scan the U_BOOT_DRVINFO() definitions. U-Boot looks up the name specified by each, to find the appropriate U_BOOT_DRIVER() definition. In this case, - there is no path by which driver_data may be provided, but the U_BOOT_DEVICE() + there is no path by which driver_data may be provided, but the U_BOOT_DRVINFO() may provide plat. - Scan through the device tree definitions. U-Boot looks at top-level @@ -685,7 +685,7 @@ driver's bind() method if one is defined. At this point all the devices are known, and bound to their drivers. There is a 'struct udevice' allocated for all devices. However, nothing has been activated (except for the root device). Each bound device that was created -from a U_BOOT_DEVICE() declaration will hold the plat pointer specified +from a U_BOOT_DRVINFO() declaration will hold the plat pointer specified in that declaration. For a bound device created from the device tree, plat will be NULL, but of_offset will be the offset of the device tree node that caused the device to be created. The uclass is set correctly for @@ -726,7 +726,7 @@ The steps are: 2. If plat_auto is non-zero, then the platform data space is allocated. This is only useful for device tree operation, since otherwise you would have to specific the platform data in the - U_BOOT_DEVICE() declaration. The space is allocated for the device and + U_BOOT_DRVINFO() declaration. The space is allocated for the device and zeroed. It will be accessible as dev->plat. 3. If the device's uclass specifies a non-zero per_device_auto, @@ -746,7 +746,7 @@ The steps are: do various calls like dev_read_u32(dev, ...) to access the node and store the resulting information into dev->plat. After this point, the device works the same way whether it was bound using a device tree node or - U_BOOT_DEVICE() structure. In either case, the platform data is now stored + U_BOOT_DRVINFO() structure. In either case, the platform data is now stored in the plat structure. Typically you will use the plat_auto feature to specify the size of the platform data structure, and U-Boot will automatically allocate and zero it for you before @@ -855,7 +855,7 @@ remove it. This performs the probe steps in reverse: 4. The device memory is freed (platform data, private data, uclass data, parent data). - Note: Because the platform data for a U_BOOT_DEVICE() is defined with a + Note: Because the platform data for a U_BOOT_DRVINFO() is defined with a static pointer, it is not de-allocated during the remove() method. For a device instantiated using the device tree data, the platform data will be dynamically allocated, and thus needs to be deallocated during the @@ -931,7 +931,7 @@ property can provide better control granularity on which device is bound before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all devices with the same driver are bound, which requires allocation a large amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the -only way for statically declared devices via U_BOOT_DEVICE() to be bound +only way for statically declared devices via U_BOOT_DRVINFO() to be bound prior to relocation. It is possible to limit this to specific relocation steps, by using diff --git a/doc/driver-model/of-plat.rst b/doc/driver-model/of-plat.rst index afa27c2..4ef2fe6 100644 --- a/doc/driver-model/of-plat.rst +++ b/doc/driver-model/of-plat.rst @@ -21,7 +21,7 @@ SoCs require a 16KB SPL image which must include a full MMC stack. In this case the overhead of device tree access may be too great. It is possible to create platform data manually by defining C structures -for it, and reference that data in a U_BOOT_DEVICE() declaration. This +for it, and reference that data in a U_BOOT_DRVINFO() declaration. This bypasses the use of device tree completely, effectively creating a parallel configuration mechanism. But it is an available option for SPL. @@ -79,7 +79,7 @@ SPL/TPL and should be tested with: A new tool called 'dtoc' converts a device tree file either into a set of struct declarations, one for each compatible node, and a set of -U_BOOT_DEVICE() declarations along with the actual platform data for each +U_BOOT_DRVINFO() declarations along with the actual platform data for each device. As an example, consider this MMC node: .. code-block:: none @@ -155,16 +155,13 @@ and the following device declarations: .card_detect_delay = 0xc8, }; - U_BOOT_DEVICE(dwmmc_at_ff0c0000) = { + U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = { .name = "rockchip_rk3288_dw_mshc", .plat = &dtv_dwmmc_at_ff0c0000, .plat_size = sizeof(dtv_dwmmc_at_ff0c0000), .parent_idx = -1, }; - void dm_populate_phandle_data(void) { - } - The device is then instantiated at run-time and the platform data can be accessed using: @@ -178,24 +175,21 @@ platform data in the driver. The of_to_plat() method should therefore do nothing in such a driver. Note that for the platform data to be matched with a driver, the 'name' -property of the U_BOOT_DEVICE() declaration has to match a driver declared +property of the U_BOOT_DRVINFO() declaration has to match a driver declared via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a 'name' corresponding to the devicetree 'compatible' string (after converting it to a valid name for C) is needed, so a dedicated driver is required for each 'compatible' string. -In order to make this a bit more flexible U_BOOT_DRIVER_ALIAS macro can be +In order to make this a bit more flexible DM_DRIVER_ALIAS macro can be used to declare an alias for a driver name, typically a 'compatible' string. This macro produces no code, but it is by dtoc tool. The parent_idx is the index of the parent driver_info structure within its -linker list (instantiated by the U_BOOT_DEVICE() macro). This is used to support -dev_get_parent(). The dm_populate_phandle_data() is included to allow for -fix-ups required by dtoc. It is not currently used. The values in 'clocks' are -the index of the driver_info for the target device followed by any phandle -arguments. This is used to support device_get_by_driver_info_idx(). +linker list (instantiated by the U_BOOT_DRVINFO() macro). This is used to support +dev_get_parent(). -During the build process dtoc parses both U_BOOT_DRIVER and U_BOOT_DRIVER_ALIAS +During the build process dtoc parses both U_BOOT_DRIVER and DM_DRIVER_ALIAS to build a list of valid driver names and driver aliases. If the 'compatible' string used for a device does not not match a valid driver name, it will be checked against the list of driver aliases in order to get the right driver @@ -297,7 +291,7 @@ For example: .plat_auto = sizeof(struct mmc_plat), }; - U_BOOT_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */ + DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */ Note that struct mmc_plat is defined in the C file, not in a header. This is to avoid needing to include dt-structs.h in a header file. The idea is to @@ -337,9 +331,11 @@ prevents them being used inadvertently. All usage must be bracketed with #if CONFIG_IS_ENABLED(OF_PLATDATA). The dt-plat.c file contains the device declarations and is is built in -spl/dt-plat.c. It additionally contains the definition of -dm_populate_phandle_data() which is responsible of filling the phandle -information by adding references to U_BOOT_DEVICE by using DM_GET_DEVICE +spl/dt-plat.c. + +The dm_populate_phandle_data() function that was previous needed has now been +removed, since dtoc can address the drivers directly from dt-plat.c and does +not need to fix up things at runtime. The pylibfdt Python module is used to access the devicetree. diff --git a/doc/driver-model/remoteproc-framework.rst b/doc/driver-model/remoteproc-framework.rst index edb09cc..566495a 100644 --- a/doc/driver-model/remoteproc-framework.rst +++ b/doc/driver-model/remoteproc-framework.rst @@ -125,7 +125,7 @@ a simplified definition of a device is as follows: .driver_plat_data = &mydriver_data; }; - U_BOOT_DEVICE(proc_3_demo) = { + U_BOOT_DRVINFO(proc_3_demo) = { .name = "sandbox_test_proc", .plat = &proc_3_test, }; diff --git a/doc/driver-model/spi-howto.rst b/doc/driver-model/spi-howto.rst index f1c4167..97fbf75 100644 --- a/doc/driver-model/spi-howto.rst +++ b/doc/driver-model/spi-howto.rst @@ -270,7 +270,7 @@ fills in the fields from device tree. Add the platform data [non-device-tree only] -------------------------------------------- -Specify this data in a U_BOOT_DEVICE() declaration in your board file: +Specify this data in a U_BOOT_DRVINFO() declaration in your board file: .. code-block:: c @@ -281,7 +281,7 @@ Specify this data in a U_BOOT_DEVICE() declaration in your board file: .deactivate_delay_us = ... }; - U_BOOT_DEVICE(board_spi0) = { + U_BOOT_DRVINFO(board_spi0) = { .name = "exynos_spi", .plat = &platdata_spi0, }; |