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:
parent
4f4ffe52e1
commit
b10d5efdf7
1 changed files with 15 additions and 0 deletions
|
@ -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.
|
||||||
|
|
Loading…
Reference in a new issue