aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSimon Glass <sjg@chromium.org>2020-12-03 16:55:18 -0700
committerSimon Glass <sjg@chromium.org>2020-12-13 16:51:08 -0700
commitcaa4daa2ae3dc0a3e516addea5772c9af76abcb0 (patch)
tree0abbc5b538894532f4db28d56e4645d3be230d27 /doc
parent41575d8e4c334df148c4cdd7c40cc825dc0fcaa1 (diff)
downloadu-boot-caa4daa2ae3dc0a3e516addea5772c9af76abcb0.zip
u-boot-caa4daa2ae3dc0a3e516addea5772c9af76abcb0.tar.gz
u-boot-caa4daa2ae3dc0a3e516addea5772c9af76abcb0.tar.bz2
dm: treewide: Rename 'platdata' variables to just 'plat'
We use 'priv' for private data but often use 'platdata' for platform data. We can't really use 'pdata' since that is ambiguous (it could mean private or platform data). Rename some of the latter variables to end with 'plat' for consistency. Signed-off-by: Simon Glass <sjg@chromium.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/driver-model/design.rst60
-rw-r--r--doc/driver-model/ethernet.rst6
-rw-r--r--doc/driver-model/of-plat.rst14
-rw-r--r--doc/driver-model/remoteproc-framework.rst2
-rw-r--r--doc/driver-model/spi-howto.rst10
-rw-r--r--doc/driver-model/usb-info.rst4
6 files changed, 48 insertions, 48 deletions
diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst
index 92d1304..2cdea1c 100644
--- a/doc/driver-model/design.rst
+++ b/doc/driver-model/design.rst
@@ -59,7 +59,7 @@ uclass:
The demo class is pretty simple, but not trivial. The intention is that it
can be used for testing, so it will implement all driver model features and
provide good code coverage of them. It does have multiple drivers, it
-handles parameter data and platdata (data which tells the driver how
+handles parameter data and plat (data which tells the driver how
to operate on a particular platform) and it uses private driver data.
To try it, see the example session below::
@@ -333,7 +333,7 @@ Briefly, they are:
* bind - make the driver model aware of a device (bind it to its driver)
* unbind - make the driver model forget the device
- * ofdata_to_platdata - convert device tree data to platdata - see later
+ * ofdata_to_platdata - convert device tree data to plat - see later
* probe - make a device ready for use
* remove - remove a device so it cannot be used until probed again
@@ -396,7 +396,7 @@ The data can be interpreted by the drivers however they like - it is
basically a communication scheme between the board-specific code and
the generic drivers, which are intended to work on any board.
-Drivers can access their data via dev->info->platdata. Here is
+Drivers can access their data via dev->info->plat. Here is
the declaration for the platform data, which would normally appear
in the board file.
@@ -410,7 +410,7 @@ in the board file.
static const struct driver_info info[] = {
{
.name = "demo_shape_drv",
- .platdata = &red_square,
+ .plat = &red_square,
},
};
@@ -420,7 +420,7 @@ in the board file.
Device Tree
-----------
-While platdata is useful, a more flexible way of providing device data is
+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
necessary.
@@ -448,13 +448,13 @@ The easiest way to make this work it to add a few members to the driver:
.. code-block:: c
- .platdata_auto = sizeof(struct dm_test_pdata),
+ .plat_auto = sizeof(struct dm_test_pdata),
.ofdata_to_platdata = testfdt_ofdata_to_platdata,
-The 'auto' feature allowed space for the platdata to be allocated
+The 'auto' feature allowed space for the plat to be allocated
and zeroed before the driver's ofdata_to_platdata() method is called. The
ofdata_to_platdata() method, which the driver write supplies, should parse
-the device tree node for this device and place it in dev->platdata. Thus
+the device tree node for this device and place it in dev->plat. Thus
when the probe method is called later (to set up the device ready for use)
the platform data will be present.
@@ -463,8 +463,8 @@ method then it will be called first (during activation). If you provide a
probe method it will be called next. See Driver Lifecycle below for more
details.
-If you don't want to have the platdata automatically allocated then you
-can leave out platdata_auto. In this case you can use malloc
+If you don't want to have the plat automatically allocated then you
+can leave out plat_auto. In this case you can use malloc
in your ofdata_to_platdata (or probe) method to allocate the required memory,
and you should free it in the remove method.
@@ -587,9 +587,9 @@ Each of the devices is connected to a different address on the USB bus.
The bus device wants to store this address and some other information such
as the bus speed for each device.
-To achieve this, the bus device can use dev->parent_platdata in each of its
+To achieve this, the bus device can use dev->parent_plat in each of its
three children. This can be auto-allocated if the bus driver (or bus uclass)
-has a non-zero value for per_child_platdata_auto. If not, then
+has a non-zero value for per_child_plat_auto. If not, then
the bus device or uclass can allocate the space itself before the child
device is probed.
@@ -650,26 +650,26 @@ U-Boot discovers devices using one of these two methods:
- Scan the U_BOOT_DEVICE() 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()
- may provide platdata.
+ may provide plat.
- Scan through the device tree definitions. U-Boot looks at top-level
nodes in the the device tree. It looks at the compatible string in each node
and uses the of_match table of the U_BOOT_DRIVER() structure to find the
right driver for each node. In this case, the of_match table may provide a
- driver_data value, but platdata cannot be provided until later.
+ driver_data value, but plat cannot be provided until later.
For each device that is discovered, U-Boot then calls device_bind() to create a
new device, initializes various core fields of the device object such as name,
uclass & driver, initializes any optional fields of the device object that are
-applicable such as of_offset, driver_data & platdata, and finally calls the
+applicable such as of_offset, driver_data & plat, and finally calls the
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 platdata pointer specified
+from a U_BOOT_DEVICE() declaration will hold the plat pointer specified
in that declaration. For a bound device created from the device tree,
-platdata will be NULL, but of_offset will be the offset of 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
the device.
@@ -691,7 +691,7 @@ base address of hardware registers and parameters relating to driver
operation. This is called 'ofdata' (Open-Firmware data).
The device's_ofdata_to_platdata() implemnents allocation and reading of
-platdata. A parent's ofdata is always read before a child.
+plat. A parent's ofdata is always read before a child.
The steps are:
@@ -701,11 +701,11 @@ The steps are:
it for run-time information, not platform data (which should be static
and known before the device is probed).
- 2. If platdata_auto is non-zero, then the platform data space
+ 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
- zeroed. It will be accessible as dev->platdata.
+ zeroed. It will be accessible as dev->plat.
3. If the device's uclass specifies a non-zero per_device_auto,
then this space is allocated and zeroed also. It is allocated for and
@@ -722,11 +722,11 @@ The steps are:
5. If the driver provides an ofdata_to_platdata() method, then this is
called to convert the device tree data into platform data. This should
do various calls like dev_read_u32(dev, ...) to access the node and store
- the resulting information into dev->platdata. After this point, the device
+ 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
- in the platdata structure. Typically you will use the
- platdata_auto feature to specify the size of the platform data
+ 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
entry to ofdata_to_platdata(). But if not, you can allocate it yourself in
ofdata_to_platdata(). Note that it is preferable to do all the device tree
@@ -735,7 +735,7 @@ The steps are:
that U-Boot will cache platform data for devices which are regularly
de/activated).
- 5. The device is marked 'platdata valid'.
+ 6. The device is marked 'plat valid'.
Note that ofdata reading is always done (for a child and all its parents)
before probing starts. Thus devices go through two distinct states when
@@ -790,14 +790,14 @@ as above and then following these steps (see device_probe()):
hardware and setting up hardware registers to initial values. The code
in probe() can access:
- - platform data in dev->platdata (for configuration)
+ - platform data in dev->plat (for configuration)
- private data in dev->priv (for run-time state)
- uclass data in dev->uclass_priv (for things the uclass stores
about this device)
Note: If you don't use priv_auto then you will need to
allocate the priv space here yourself. The same applies also to
- platdata_auto. Remember to free them in the remove() method.
+ plat_auto. Remember to free them in the remove() method.
5. The device is marked 'activated'
@@ -843,10 +843,10 @@ remove it. This performs the probe steps in reverse:
be dynamically allocated, and thus needs to be deallocated during the
remove() method, either:
- - if the platdata_auto is non-zero, the deallocation
+ - if the plat_auto is non-zero, the deallocation
happens automatically within the driver model core; or
- - when platdata_auto is 0, both the allocation (in probe()
+ - when plat_auto is 0, both the allocation (in probe()
or preferably ofdata_to_platdata()) and the deallocation in remove()
are the responsibility of the driver author.
@@ -890,14 +890,14 @@ original patches, but makes at least the following changes:
the driver operations structure in the driver, rather than passing it
to the driver bind function.
- Rename some structures to make them more similar to Linux (struct udevice
- instead of struct instance, struct platdata, etc.)
+ instead of struct instance, struct plat, etc.)
- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that
this concept relates to a class of drivers (or a subsystem). We shouldn't
use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems
better than 'core'.
- Remove 'struct driver_instance' and just use a single 'struct udevice'.
This removes a level of indirection that doesn't seem necessary.
-- Built in device tree support, to avoid the need for platdata
+- Built in device tree support, to avoid the need for plat
- Removed the concept of driver relocation, and just make it possible for
the new driver (created after relocation) to access the old driver data.
I feel that relocation is a very special case and will only apply to a few
diff --git a/doc/driver-model/ethernet.rst b/doc/driver-model/ethernet.rst
index 781644d..2444c5c 100644
--- a/doc/driver-model/ethernet.rst
+++ b/doc/driver-model/ethernet.rst
@@ -29,7 +29,7 @@ the UCLASS_ETH .id field in the U-Boot driver struct:
.probe = eth_ape_probe,
.ops = &eth_ape_ops,
.priv_auto = sizeof(struct eth_ape_priv),
- .platdata_auto = sizeof(struct eth_ape_pdata),
+ .plat_auto = sizeof(struct eth_ape_pdata),
.flags = DM_FLAG_ALLOC_PRIV_DMA,
};
@@ -43,7 +43,7 @@ struct eth_ape_pdata contains static platform data, like the MMIO base address,
a hardware variant, the MAC address. ``struct eth_pdata eth_pdata``
as the first member of this struct helps to avoid duplicated code.
If you don't need any more platform data beside the standard member,
-just use sizeof(struct eth_pdata) for the platdata_auto.
+just use sizeof(struct eth_pdata) for the plat_auto.
PCI devices add a line pointing to supported vendor/device ID pairs:
@@ -96,7 +96,7 @@ operations. You often do things here such as resetting the MAC
and/or PHY, and waiting for the link to autonegotiate. You should also take
the opportunity to program the device's MAC address with the enetaddr member
of the generic struct eth_pdata (which would be the first member of your
-own platdata struct). This allows the rest of U-Boot to dynamically change
+own plat struct). This allows the rest of U-Boot to dynamically change
the MAC address and have the new settings be respected.
The **send** function does what you think -- transmit the specified packet
diff --git a/doc/driver-model/of-plat.rst b/doc/driver-model/of-plat.rst
index 2df59ed..a05faf7 100644
--- a/doc/driver-model/of-plat.rst
+++ b/doc/driver-model/of-plat.rst
@@ -157,8 +157,8 @@ and the following device declarations:
U_BOOT_DEVICE(dwmmc_at_ff0c0000) = {
.name = "rockchip_rk3288_dw_mshc",
- .platdata = &dtv_dwmmc_at_ff0c0000,
- .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000),
+ .plat = &dtv_dwmmc_at_ff0c0000,
+ .plat_size = sizeof(dtv_dwmmc_at_ff0c0000),
.parent_idx = -1,
};
@@ -232,7 +232,7 @@ How to structure your driver
Drivers should always support device tree as an option. The of-platdata
feature is intended as a add-on to existing drivers.
-Your driver should convert the platdata struct in its probe() method. The
+Your driver should convert the plat struct in its probe() method. The
existing device tree decoding logic should be kept in the
ofdata_to_platdata() method and wrapped with #if.
@@ -294,7 +294,7 @@ For example:
.ofdata_to_platdata = mmc_ofdata_to_platdata,
.probe = mmc_probe,
.priv_auto = sizeof(struct mmc_priv),
- .platdata_auto = sizeof(struct mmc_platdata),
+ .plat_auto = sizeof(struct mmc_platdata),
};
U_BOOT_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */
@@ -305,7 +305,7 @@ keep the use of each of-platdata struct to the smallest possible code area.
There is just one driver C file for each struct, that can convert from the
of-platdata struct to the standard one used by the driver.
-In the case where SPL_OF_PLATDATA is enabled, platdata_auto is
+In the case where SPL_OF_PLATDATA is enabled, plat_auto is
still used to allocate space for the platform data. This is different from
the normal behaviour and is triggered by the use of of-platdata (strictly
speaking it is a non-zero platdata_size which triggers this).
@@ -336,8 +336,8 @@ Otherwise (such as in U-Boot proper) these structs are not available. This
prevents them being used inadvertently. All usage must be bracketed with
#if CONFIG_IS_ENABLED(OF_PLATDATA).
-The dt-platdata.c file contains the device declarations and is is built in
-spl/dt-platdata.c. It additionally contains the definition of
+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
diff --git a/doc/driver-model/remoteproc-framework.rst b/doc/driver-model/remoteproc-framework.rst
index f21de0a..edb09cc 100644
--- a/doc/driver-model/remoteproc-framework.rst
+++ b/doc/driver-model/remoteproc-framework.rst
@@ -127,7 +127,7 @@ a simplified definition of a device is as follows:
U_BOOT_DEVICE(proc_3_demo) = {
.name = "sandbox_test_proc",
- .platdata = &proc_3_test,
+ .plat = &proc_3_test,
};
There can be additional data that may be desired depending on the
diff --git a/doc/driver-model/spi-howto.rst b/doc/driver-model/spi-howto.rst
index a12d692..6a1aace 100644
--- a/doc/driver-model/spi-howto.rst
+++ b/doc/driver-model/spi-howto.rst
@@ -231,7 +231,7 @@ tree, but we need to tell it the size:
U_BOOT_DRIVER(spi_exynos) = {
...
- .platdata_auto = sizeof(struct exynos_spi_platdata),
+ .plat_auto = sizeof(struct exynos_spi_platdata),
Here is a sample function. It gets a pointer to the platform data and
@@ -241,7 +241,7 @@ fills in the fields from device tree.
static int exynos_spi_ofdata_to_platdata(struct udevice *bus)
{
- struct exynos_spi_platdata *plat = bus->platdata;
+ struct exynos_spi_platdata *plat = bus->plat;
const void *blob = gd->fdt_blob;
int node = dev_of_offset(bus);
@@ -283,7 +283,7 @@ Specify this data in a U_BOOT_DEVICE() declaration in your board file:
U_BOOT_DEVICE(board_spi0) = {
.name = "exynos_spi",
- .platdata = &platdata_spi0,
+ .plat = &platdata_spi0,
};
You will unfortunately need to put the struct definition into a header file
@@ -437,7 +437,7 @@ Here is an example for the speed part:
static int exynos_spi_set_speed(struct udevice *bus, uint speed)
{
- struct exynos_spi_platdata *plat = bus->platdata;
+ struct exynos_spi_platdata *plat = bus->plat;
struct exynos_spi_priv *priv = dev_get_priv(bus);
int ret;
@@ -658,7 +658,7 @@ A little note about SPI uclass features
The SPI uclass keeps some information about each device 'dev' on the bus:
struct dm_spi_slave_platdata:
- This is device_get_parent_platdata(dev).
+ This is device_get_parent_plat(dev).
This is where the chip select number is stored, along with
the default bus speed and mode. It is automatically read
from the device tree in spi_child_post_bind(). It must not
diff --git a/doc/driver-model/usb-info.rst b/doc/driver-model/usb-info.rst
index 5f7cbfc..ec8f317 100644
--- a/doc/driver-model/usb-info.rst
+++ b/doc/driver-model/usb-info.rst
@@ -43,7 +43,7 @@ as drivers in the USB uclass. For example:
.probe = tegra_ehci_usb_probe,
.remove = tegra_ehci_usb_remove,
.ops = &ehci_usb_ops,
- .platdata_auto = sizeof(struct usb_platdata),
+ .plat_auto = sizeof(struct usb_platdata),
.priv_auto = sizeof(struct fdt_usb),
.flags = DM_FLAG_ALLOC_PRIV_DMA,
};
@@ -100,7 +100,7 @@ The following primary data structures are in use:
- struct usb_dev_platdata:
This holds platform data for a device. You can access it for a
- device 'dev' with dev_get_parent_platdata(dev). It holds the device
+ device 'dev' with dev_get_parent_plat(dev). It holds the device
address and speed - anything that can be determined before the device
driver is actually set up. When probing the bus this structure is
used to provide essential information to the device driver.