diff options
author | Alan Stern <stern@rowland.harvard.edu> | 2012-01-17 11:39:00 -0500 |
---|---|---|
committer | Greg Kroah-Hartman <gregkh@suse.de> | 2012-01-24 10:47:41 -0800 |
commit | b10d5efdf7892d18b3b7d899edce2c8d9b80aea9 (patch) | |
tree | e1e00c06b0c7e75350afb8713968243ae8c6a89c /drivers | |
parent | 4f4ffe52e1e5ddb9708fe075aaef4424f1fb744a (diff) | |
download | linux-b10d5efdf7892d18b3b7d899edce2c8d9b80aea9.tar.bz2 |
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>
Diffstat (limited to 'drivers')
-rw-r--r-- | drivers/base/core.c | 15 |
1 files changed, 15 insertions, 0 deletions
diff --git a/drivers/base/core.c b/drivers/base/core.c index 4a67cc0c8b37..ad29e928baaa 100644 --- a/drivers/base/core.c +++ b/drivers/base/core.c @@ -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 @@ name_error: * 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. |