diff options
author | Simon Glass <sjg@chromium.org> | 2020-12-29 06:34:54 +0300 |
---|---|---|
committer | Simon Glass <sjg@chromium.org> | 2021-01-05 22:26:35 +0300 |
commit | 20e442ab2df355450006574fff178c746d254a18 (patch) | |
tree | 7e4eae44adf14d155a5cb028a909cdcf8174eab3 /doc | |
parent | be3bd3bb177ec913050745131687089c1ff69c44 (diff) | |
download | u-boot-20e442ab2df355450006574fff178c746d254a18.tar.xz |
dm: Rename U_BOOT_DEVICE() to U_BOOT_DRVINFO()
The current macro is a misnomer since it does not declare a device
directly. Instead, it declares driver_info record which U-Boot uses at
runtime to create a device.
The distinction seems somewhat minor most of the time, but is becomes
quite confusing when we actually want to declare a device, with
of-platdata. We are left trying to distinguish between a device which
isn't actually device, and a device that is (perhaps an 'instance'?)
It seems better to rename this macro to describe what it actually is. The
macros is not widely used, since boards should use devicetree to declare
devices.
Rename it to U_BOOT_DRVINFO(), which indicates clearly that this is
declaring a new driver_info record, not a device.
Signed-off-by: Simon Glass <sjg@chromium.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/driver-model/design.rst | 18 | ||||
-rw-r--r-- | doc/driver-model/of-plat.rst | 12 | ||||
-rw-r--r-- | doc/driver-model/remoteproc-framework.rst | 2 | ||||
-rw-r--r-- | doc/driver-model/spi-howto.rst | 4 |
4 files changed, 18 insertions, 18 deletions
diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst index f26e4f14df..ffed7d5f79 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 afa27c211c..39e6295aa0 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,7 +155,7 @@ 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), @@ -178,7 +178,7 @@ 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 @@ -189,7 +189,7 @@ 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 +linker list (instantiated by the U_BOOT_DRVINFO() 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 @@ -339,7 +339,7 @@ prevents them being used inadvertently. All usage must be bracketed with 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 +information by adding references to U_BOOT_DRVINFO by using DM_GET_DEVICE 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 edb09cc105..566495a21c 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 f1c4167139..97fbf750cb 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, }; |