Commit b10d5efd authored by Alan Stern's avatar Alan Stern Committed by Greg Kroah-Hartman
Browse files

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: default avatarAlan Stern <stern@rowland.harvard.edu>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@suse.de>
parent 4f4ffe52

drivers/base/core.c

+15 −0
Original line number Original line Diff line number Diff line
@@ -632,6 +632,11 @@ static void klist_children_put(struct klist_node *n) 
 * may be used for reference counting of @dev after calling this

 * may be used for reference counting of @dev after calling this

 * function.

 * 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

 * NOTE: Use put_device() to give up your reference instead of freeing

 * @dev directly once you have called this function.

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

 * to the global and sibling lists for the device, then

 * adds it to the other relevant subsystems of the driver model.

 * 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

 * NOTE: _Never_ directly free @dev after calling this function, even

 * if it returned an error! Always use put_device() to give up your

 * if it returned an error! Always use put_device() to give up your

 * reference instead.

 * reference instead.
@@ -1090,6 +1102,9 @@ name_error: 
 * have a clearly defined need to use and refcount the device

 * have a clearly defined need to use and refcount the device

 * before it is added to the hierarchy.

 * 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

 * NOTE: _Never_ directly free @dev after calling this function, even

 * if it returned an error! Always use put_device() to give up the

 * if it returned an error! Always use put_device() to give up the

 * reference initialized in this function instead.

 * reference initialized in this function instead.

CRA Git | Maintained and supported by SUSTech CRA and CCSE