|
@@ -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
|