Documentation update for the driver model core

This patch (as1509) documents two important points regarding the use
of device structures in the driver model:

	Structures must be initialized to all 0's before they are
	passed to device_initialize().

	Structures must not be passed to device_add() or
	device_register() more than once.

Although these restrictions have applied ever since the driver model
was first created, they have not been mentioned anywhere.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
This commit is contained in:
Alan Stern 2012-01-17 11:39:00 -05:00 committed by Greg Kroah-Hartman
parent 4f4ffe52e1
commit b10d5efdf7

View file

@ -632,6 +632,11 @@ static void klist_children_put(struct klist_node *n)
* may be used for reference counting of @dev after calling this
* function.
*
* All fields in @dev must be initialized by the caller to 0, except
* for those explicitly set to some other value. The simplest
* approach is to use kzalloc() to allocate the structure containing
* @dev.
*
* NOTE: Use put_device() to give up your reference instead of freeing
* @dev directly once you have called this function.
*/
@ -930,6 +935,13 @@ int device_private_init(struct device *dev)
* to the global and sibling lists for the device, then
* adds it to the other relevant subsystems of the driver model.
*
* Do not call this routine or device_register() more than once for
* any device structure. The driver model core is not designed to work
* with devices that get unregistered and then spring back to life.
* (Among other things, it's very hard to guarantee that all references
* to the previous incarnation of @dev have been dropped.) Allocate
* and register a fresh new struct device instead.
*
* NOTE: _Never_ directly free @dev after calling this function, even
* if it returned an error! Always use put_device() to give up your
* reference instead.
@ -1090,6 +1102,9 @@ int device_add(struct device *dev)
* have a clearly defined need to use and refcount the device
* before it is added to the hierarchy.
*
* For more information, see the kerneldoc for device_initialize()
* and device_add().
*
* NOTE: _Never_ directly free @dev after calling this function, even
* if it returned an error! Always use put_device() to give up the
* reference initialized in this function instead.