dm: Expand and improve the device lifecycle docs

The lifecycle of a device is an important part of driver model. Add to the existing documentation and clarify it. Reported-by: Jon Loeliger <jdl@jdl.com> Signed-off-by: Simon Glass <sjg@chromium.org>

dm: Expand and improve the device lifecycle docs
The lifecycle of a device is an important part of driver model. Add to the existing documentation and clarify it. Reported-by: Jon Loeliger <jdl@jdl.com> Signed-off-by: Simon Glass <sjg@chromium.org>
Simon Glass
1 parent f2bc6fc331
Showing 1 changed file with 213 additions and 7 deletions Side-by-side Diff
doc/driver-model/README.txt
@@ -222,7 +222,44 @@
 Platform Data
 -------------
  
-Where does the platform data come from? See demo-pdata.c which
+Platform data is like Linux platform data, if you are familiar with that.
+It provides the board-specific information to start up a device.
+
+Why is this information not just stored in the device driver itself? The
+idea is that the device driver is generic, and can in principle operate on
+any board that has that type of device. For example, with modern
+highly-complex SoCs it is common for the IP to come from an IP vendor, and
+therefore (for example) the MMC controller may be the same on chips from
+different vendors. It makes no sense to write independent drivers for the
+MMC controller on each vendor's SoC, when they are all almost the same.
+Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same,
+but lie at different addresses in the address space.
+
+Using the UART example, we have a single driver and it is instantiated 6
+times by supplying 6 lots of platform data. Each lot of platform data
+gives the driver name and a pointer to a structure containing information
+about this instance - e.g. the address of the register space. It may be that
+one of the UARTS supports RS-485 operation - this can be added as a flag in
+the platform data, which is set for this one port and clear for the rest.
+
+Think of your driver as a generic piece of code which knows how to talk to
+a device, but needs to know where it is, any variant/option information and
+so on. Platform data provides this link between the generic piece of code
+and the specific way it is bound on a particular board.
+
+Examples of platform data include:
+
+   - The base address of the IP block's register space
+   - Configuration options, like:
+         - the SPI polarity and maximum speed for a SPI controller
+         - the I2C speed to use for an I2C device
+         - the number of GPIOs available in a GPIO device
+
+Where does the platform data come from? It is either held in a structure
+which is compiled into U-Boot, or it can be parsed from the Device Tree
+(see 'Device Tree' below).
+
+For an example of how it can be compiled in, see demo-pdata.c which
 sets up a table of driver names and their associated platform data.
 The data can be interpreted by the drivers however they like - it is
 basically a communication scheme between the board-specific code and
  
  
  
@@ -259,21 +296,30 @@
 		sides = <4>;
 	};
  
+This means that instead of having lots of U_BOOT_DEVICE() 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
+benefit is that the Linux device tree can be used, thus further simplifying
+the task of board-bring up either for U-Boot or Linux devs (whoever gets to
+the board first!).
  
 The easiest way to make this work it to add a few members to the driver:
  
 	.platdata_auto_alloc_size = sizeof(struct dm_test_pdata),
 	.ofdata_to_platdata = testfdt_ofdata_to_platdata,
-	.probe	= testfdt_drv_probe,
  
 The 'auto_alloc' feature allowed space for the platdata to be allocated
-and zeroed before the driver's ofdata_to_platdata method is called. This
-method reads the information out of the device tree and puts it in
-dev->platdata. Then the probe method is called to set up the device.
+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
+when the probe method is called later (to set up the device ready for use)
+the platform data will be present.
  
 Note that both methods are optional. If you provide an ofdata_to_platdata
-method then it will be called first (after bind). If you provide a probe
-method it will be called next.
+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_alloc_size. In this case you can use malloc
@@ -293,6 +339,166 @@
 It is also possible to specify special methods for probe, etc. The uclass
 numbering comes from include/dm/uclass.h. To add a new uclass, add to the
 end of the enum there, then declare your uclass as above.
+
+
+Driver Lifecycle
+----------------
+
+Here are the stages that a device goes through in driver model. Note that all
+methods mentioned here are optional - e.g. if there is no probe() method for
+a device then it will not be called. A simple device may have very few
+methods actually defined.
+
+1. Bind stage
+
+A device and its driver are bound using one of these two methods:
+
+   - Scan the U_BOOT_DEVICE() definitions. U-Boot It looks up the
+name specified by each, to find the appropriate driver. It then calls
+device_bind() to create a new device and bind' it to its driver. This will
+call the device's bind() method.
+
+   - 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 part of the U_BOOT_DRIVER() structure to find the
+right driver for each node. It then calls device_bind() to bind the
+newly-created device to its driver (thereby creating a device structure).
+This will also call the device's bind() method.
+
+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
+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
+node that caused the device to be created. The uclass is set correctly for
+the device.
+
+The device's bind() method is permitted to perform simple actions, but
+should not scan the device tree node, not initialise hardware, nor set up
+structures or allocate memory. All of these tasks should be left for
+the probe() method.
+
+Note that compared to Linux, U-Boot's driver model has a separate step of
+probe/remove which is independent of bind/unbind. This is partly because in
+U-Boot it may be expensive to probe devices and we don't want to do it until
+they are needed, or perhaps until after relocation.
+
+2. Activation/probe
+
+When a device needs to be used, U-Boot activates it, by following these
+steps (see device_probe()):
+
+   a. If priv_auto_alloc_size is non-zero, then the device-private space
+   is allocated for the device and zeroed. It will be accessible as
+   dev->priv. The driver can put anything it likes in there, but should use
+   it for run-time information, not platform data (which should be static
+   and known before the device is probed).
+
+   b. If platdata_auto_alloc_size 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.
+
+   c. If the device's uclass specifies a non-zero per_device_auto_alloc_size,
+   then this space is allocated and zeroed also. It is allocated for and
+   stored in the device, but it is uclass data. owned by the uclass driver.
+   It is possible for the device to access it.
+
+   d. All parent devices are probed. It is not possible to activate a device
+   unless its predecessors (all the way up to the root device) are activated.
+   This means (for example) that an I2C driver will require that its bus
+   be activated.
+
+   e. 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 fdtdec_get_int(gd->fdt_blob, dev->of_offset, ...)
+   to access the node and store the resulting information into dev->platdata.
+   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_alloc_size 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 decoding in ofdata_to_platdata() rather than
+   in probe(). (Apart from the ugliness of mixing configuration and run-time
+   data, one day it is possible that U-Boot will cache platformat data for
+   devices which are regularly de/activated).
+
+   f. The device's probe() method is called. This should do anything that
+   is required by the device to get it going. This could include checking
+   that the hardware is actually present, setting up clocks for the
+   hardware and setting up hardware registers to initial values. The code
+   in probe() can access:
+
+      - platform data in dev->platdata (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_alloc_size then you will need to
+   allocate the priv space here yourself. The same applies also to
+   platdata_auto_alloc_size. Remember to free them in the remove() method.
+
+   g. The device is marked 'activated'
+
+   h. The uclass's post_probe() method is called, if one exists. This may
+   cause the uclass to do some housekeeping to record the device as
+   activated and 'known' by the uclass.
+
+3. Running stage
+
+The device is now activated and can be used. From now until it is removed
+all of the above structures are accessible. The device appears in the
+uclass's list of devices (so if the device is in UCLASS_GPIO it will appear
+as a device in the GPIO uclass). This is the 'running' state of the device.
+
+4. Removal stage
+
+When the device is no-longer required, you can call device_remove() to
+remove it. This performs the probe steps in reverse:
+
+   a. The uclass's pre_remove() method is called, if one exists. This may
+   cause the uclass to do some housekeeping to record the device as
+   deactivated and no-longer 'known' by the uclass.
+
+   b. All the device's children are removed. It is not permitted to have
+   an active child device with a non-active parent. This means that
+   device_remove() is called for all the children recursively at this point.
+
+   c. The device's remove() method is called. At this stage nothing has been
+   deallocated so platform data, private data and the uclass data will all
+   still be present. This is where the hardware can be shut down. It is
+   intended that the device be completely inactive at this point, For U-Boot
+   to be sure that no hardware is running, it should be enough to remove
+   all devices.
+
+   d. The device memory is freed (platform data, private data, uclass data).
+
+   Note: Because the platform data for a U_BOOT_DEVICE() 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
+   remove() method, either:
+
+      1. if the platdata_auto_alloc_size is non-zero, the deallocation
+      happens automatically within the driver model core; or
+
+      2. when platdata_auto_alloc_size is 0, both the allocation (in probe()
+      or preferably ofdata_to_platdata()) and the deallocation in remove()
+      are the responsibility of the driver author.
+
+   e. The device is marked inactive. Note that it is still bound, so the
+   device structure itself is not freed at this point. Should the device be
+   activated again, then the cycle starts again at step 2 above.
+
+5. Unbind stage
+
+The device is unbound. This is the step that actually destroys the device.
+If a parent has children these will be destroyed first. After this point
+the device does not exist and its memory has be deallocated.
  
  
 Data Structures
...	...	@@ -222,7 +222,44 @@
222	222	Platform Data
223	223	-------------
224	224
225		-Where does the platform data come from? See demo-pdata.c which
	225	+Platform data is like Linux platform data, if you are familiar with that.
	226	+It provides the board-specific information to start up a device.
	227	+
	228	+Why is this information not just stored in the device driver itself? The
	229	+idea is that the device driver is generic, and can in principle operate on
	230	+any board that has that type of device. For example, with modern
	231	+highly-complex SoCs it is common for the IP to come from an IP vendor, and
	232	+therefore (for example) the MMC controller may be the same on chips from
	233	+different vendors. It makes no sense to write independent drivers for the
	234	+MMC controller on each vendor's SoC, when they are all almost the same.
	235	+Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same,
	236	+but lie at different addresses in the address space.
	237	+
	238	+Using the UART example, we have a single driver and it is instantiated 6
	239	+times by supplying 6 lots of platform data. Each lot of platform data
	240	+gives the driver name and a pointer to a structure containing information
	241	+about this instance - e.g. the address of the register space. It may be that
	242	+one of the UARTS supports RS-485 operation - this can be added as a flag in
	243	+the platform data, which is set for this one port and clear for the rest.
	244	+
	245	+Think of your driver as a generic piece of code which knows how to talk to
	246	+a device, but needs to know where it is, any variant/option information and
	247	+so on. Platform data provides this link between the generic piece of code
	248	+and the specific way it is bound on a particular board.
	249	+
	250	+Examples of platform data include:
	251	+
	252	+ - The base address of the IP block's register space
	253	+ - Configuration options, like:
	254	+ - the SPI polarity and maximum speed for a SPI controller
	255	+ - the I2C speed to use for an I2C device
	256	+ - the number of GPIOs available in a GPIO device
	257	+
	258	+Where does the platform data come from? It is either held in a structure
	259	+which is compiled into U-Boot, or it can be parsed from the Device Tree
	260	+(see 'Device Tree' below).
	261	+
	262	+For an example of how it can be compiled in, see demo-pdata.c which
226	263	sets up a table of driver names and their associated platform data.
227	264	The data can be interpreted by the drivers however they like - it is
228	265	basically a communication scheme between the board-specific code and
229	266
230	267
231	268
...	...	@@ -259,21 +296,30 @@
259	296	sides = <4>;
260	297	};
261	298
	299	+This means that instead of having lots of U_BOOT_DEVICE() declarations in
	300	+the board file, we put these in the device tree. This approach allows a lot
	301	+more generality, since the same board file can support many types of boards
	302	+(e,g. with the same SoC) just by using different device trees. An added
	303	+benefit is that the Linux device tree can be used, thus further simplifying
	304	+the task of board-bring up either for U-Boot or Linux devs (whoever gets to
	305	+the board first!).
262	306
263	307	The easiest way to make this work it to add a few members to the driver:
264	308
265	309	.platdata_auto_alloc_size = sizeof(struct dm_test_pdata),
266	310	.ofdata_to_platdata = testfdt_ofdata_to_platdata,
267		- .probe = testfdt_drv_probe,
268	311
269	312	The 'auto_alloc' feature allowed space for the platdata to be allocated
270		-and zeroed before the driver's ofdata_to_platdata method is called. This
271		-method reads the information out of the device tree and puts it in
272		-dev->platdata. Then the probe method is called to set up the device.
	313	+and zeroed before the driver's ofdata_to_platdata() method is called. The
	314	+ofdata_to_platdata() method, which the driver write supplies, should parse
	315	+the device tree node for this device and place it in dev->platdata. Thus
	316	+when the probe method is called later (to set up the device ready for use)
	317	+the platform data will be present.
273	318
274	319	Note that both methods are optional. If you provide an ofdata_to_platdata
275		-method then it will be called first (after bind). If you provide a probe
276		-method it will be called next.
	320	+method then it will be called first (during activation). If you provide a
	321	+probe method it will be called next. See Driver Lifecycle below for more
	322	+details.
277	323
278	324	If you don't want to have the platdata automatically allocated then you
279	325	can leave out platdata_auto_alloc_size. In this case you can use malloc
...	...	@@ -293,6 +339,166 @@
293	339	It is also possible to specify special methods for probe, etc. The uclass
294	340	numbering comes from include/dm/uclass.h. To add a new uclass, add to the
295	341	end of the enum there, then declare your uclass as above.
	342	+
	343	+
	344	+Driver Lifecycle
	345	+----------------
	346	+
	347	+Here are the stages that a device goes through in driver model. Note that all
	348	+methods mentioned here are optional - e.g. if there is no probe() method for
	349	+a device then it will not be called. A simple device may have very few
	350	+methods actually defined.
	351	+
	352	+1. Bind stage
	353	+
	354	+A device and its driver are bound using one of these two methods:
	355	+
	356	+ - Scan the U_BOOT_DEVICE() definitions. U-Boot It looks up the
	357	+name specified by each, to find the appropriate driver. It then calls
	358	+device_bind() to create a new device and bind' it to its driver. This will
	359	+call the device's bind() method.
	360	+
	361	+ - Scan through the device tree definitions. U-Boot looks at top-level
	362	+nodes in the the device tree. It looks at the compatible string in each node
	363	+and uses the of_match part of the U_BOOT_DRIVER() structure to find the
	364	+right driver for each node. It then calls device_bind() to bind the
	365	+newly-created device to its driver (thereby creating a device structure).
	366	+This will also call the device's bind() method.
	367	+
	368	+At this point all the devices are known, and bound to their drivers. There
	369	+is a 'struct udevice' allocated for all devices. However, nothing has been
	370	+activated (except for the root device). Each bound device that was created
	371	+from a U_BOOT_DEVICE() declaration will hold the platdata pointer specified
	372	+in that declaration. For a bound device created from the device tree,
	373	+platdata will be NULL, but of_offset will be the offset of the device tree
	374	+node that caused the device to be created. The uclass is set correctly for
	375	+the device.
	376	+
	377	+The device's bind() method is permitted to perform simple actions, but
	378	+should not scan the device tree node, not initialise hardware, nor set up
	379	+structures or allocate memory. All of these tasks should be left for
	380	+the probe() method.
	381	+
	382	+Note that compared to Linux, U-Boot's driver model has a separate step of
	383	+probe/remove which is independent of bind/unbind. This is partly because in
	384	+U-Boot it may be expensive to probe devices and we don't want to do it until
	385	+they are needed, or perhaps until after relocation.
	386	+
	387	+2. Activation/probe
	388	+
	389	+When a device needs to be used, U-Boot activates it, by following these
	390	+steps (see device_probe()):
	391	+
	392	+ a. If priv_auto_alloc_size is non-zero, then the device-private space
	393	+ is allocated for the device and zeroed. It will be accessible as
	394	+ dev->priv. The driver can put anything it likes in there, but should use
	395	+ it for run-time information, not platform data (which should be static
	396	+ and known before the device is probed).
	397	+
	398	+ b. If platdata_auto_alloc_size is non-zero, then the platform data space
	399	+ is allocated. This is only useful for device tree operation, since
	400	+ otherwise you would have to specific the platform data in the
	401	+ U_BOOT_DEVICE() declaration. The space is allocated for the device and
	402	+ zeroed. It will be accessible as dev->platdata.
	403	+
	404	+ c. If the device's uclass specifies a non-zero per_device_auto_alloc_size,
	405	+ then this space is allocated and zeroed also. It is allocated for and
	406	+ stored in the device, but it is uclass data. owned by the uclass driver.
	407	+ It is possible for the device to access it.
	408	+
	409	+ d. All parent devices are probed. It is not possible to activate a device
	410	+ unless its predecessors (all the way up to the root device) are activated.
	411	+ This means (for example) that an I2C driver will require that its bus
	412	+ be activated.
	413	+
	414	+ e. If the driver provides an ofdata_to_platdata() method, then this is
	415	+ called to convert the device tree data into platform data. This should
	416	+ do various calls like fdtdec_get_int(gd->fdt_blob, dev->of_offset, ...)
	417	+ to access the node and store the resulting information into dev->platdata.
	418	+ After this point, the device works the same way whether it was bound
	419	+ using a device tree node or U_BOOT_DEVICE() structure. In either case,
	420	+ the platform data is now stored in the platdata structure. Typically you
	421	+ will use the platdata_auto_alloc_size feature to specify the size of the
	422	+ platform data structure, and U-Boot will automatically allocate and zero
	423	+ it for you before entry to ofdata_to_platdata(). But if not, you can
	424	+ allocate it yourself in ofdata_to_platdata(). Note that it is preferable
	425	+ to do all the device tree decoding in ofdata_to_platdata() rather than
	426	+ in probe(). (Apart from the ugliness of mixing configuration and run-time
	427	+ data, one day it is possible that U-Boot will cache platformat data for
	428	+ devices which are regularly de/activated).
	429	+
	430	+ f. The device's probe() method is called. This should do anything that
	431	+ is required by the device to get it going. This could include checking
	432	+ that the hardware is actually present, setting up clocks for the
	433	+ hardware and setting up hardware registers to initial values. The code
	434	+ in probe() can access:
	435	+
	436	+ - platform data in dev->platdata (for configuration)
	437	+ - private data in dev->priv (for run-time state)
	438	+ - uclass data in dev->uclass_priv (for things the uclass stores
	439	+ about this device)
	440	+
	441	+ Note: If you don't use priv_auto_alloc_size then you will need to
	442	+ allocate the priv space here yourself. The same applies also to
	443	+ platdata_auto_alloc_size. Remember to free them in the remove() method.
	444	+
	445	+ g. The device is marked 'activated'
	446	+
	447	+ h. The uclass's post_probe() method is called, if one exists. This may
	448	+ cause the uclass to do some housekeeping to record the device as
	449	+ activated and 'known' by the uclass.
	450	+
	451	+3. Running stage
	452	+
	453	+The device is now activated and can be used. From now until it is removed
	454	+all of the above structures are accessible. The device appears in the
	455	+uclass's list of devices (so if the device is in UCLASS_GPIO it will appear
	456	+as a device in the GPIO uclass). This is the 'running' state of the device.
	457	+
	458	+4. Removal stage
	459	+
	460	+When the device is no-longer required, you can call device_remove() to
	461	+remove it. This performs the probe steps in reverse:
	462	+
	463	+ a. The uclass's pre_remove() method is called, if one exists. This may
	464	+ cause the uclass to do some housekeeping to record the device as
	465	+ deactivated and no-longer 'known' by the uclass.
	466	+
	467	+ b. All the device's children are removed. It is not permitted to have
	468	+ an active child device with a non-active parent. This means that
	469	+ device_remove() is called for all the children recursively at this point.
	470	+
	471	+ c. The device's remove() method is called. At this stage nothing has been
	472	+ deallocated so platform data, private data and the uclass data will all
	473	+ still be present. This is where the hardware can be shut down. It is
	474	+ intended that the device be completely inactive at this point, For U-Boot
	475	+ to be sure that no hardware is running, it should be enough to remove
	476	+ all devices.
	477	+
	478	+ d. The device memory is freed (platform data, private data, uclass data).
	479	+
	480	+ Note: Because the platform data for a U_BOOT_DEVICE() is defined with a
	481	+ static pointer, it is not de-allocated during the remove() method. For
	482	+ a device instantiated using the device tree data, the platform data will
	483	+ be dynamically allocated, and thus needs to be deallocated during the
	484	+ remove() method, either:
	485	+
	486	+ 1. if the platdata_auto_alloc_size is non-zero, the deallocation
	487	+ happens automatically within the driver model core; or
	488	+
	489	+ 2. when platdata_auto_alloc_size is 0, both the allocation (in probe()
	490	+ or preferably ofdata_to_platdata()) and the deallocation in remove()
	491	+ are the responsibility of the driver author.
	492	+
	493	+ e. The device is marked inactive. Note that it is still bound, so the
	494	+ device structure itself is not freed at this point. Should the device be
	495	+ activated again, then the cycle starts again at step 2 above.
	496	+
	497	+5. Unbind stage
	498	+
	499	+The device is unbound. This is the step that actually destroys the device.
	500	+If a parent has children these will be destroyed first. After this point
	501	+the device does not exist and its memory has be deallocated.
296	502
297	503
298	504	Data Structures