summaryrefslogtreecommitdiffstats
path: root/drivers/staging
diff options
context:
space:
mode:
authorIan Abbott <abbotti@mev.co.uk>2016-12-08 13:53:10 +0000
committerGreg Kroah-Hartman <gregkh@linuxfoundation.org>2016-12-08 21:01:23 +0100
commit3e0f9b2ca8e4839335e4d64ec0a75f4fd5111c4b (patch)
tree888fe093d6b8eab537059b032c8779f69dd90ced /drivers/staging
parent3c87f653af6f5a94d30786903fe79f5816ec08f3 (diff)
downloadlinux-3e0f9b2ca8e4839335e4d64ec0a75f4fd5111c4b.tar.bz2
staging: comedi: comedidev.h: Document usage of 'detach' handler
Document when the "detach" handler function pointed to by the `detach` member of a `struct comedi_driver` is called by the comedi core, and how the "attach" and "auto_attach" handlers can defer clean-up to it when they return an error to the comedi core. This is already mentioned as part of the documentation for `comedi_auto_config()`, but is useful to document it for `struct comedi_driver` as well, since `comedi_auto_config()` is not usually called directly by low-level comedi drivers, and it is not called at all for "legacy" comedi devices that are configured manually. Signed-off-by: Ian Abbott <abbotti@mev.co.uk> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Diffstat (limited to 'drivers/staging')
-rw-r--r--drivers/staging/comedi/comedidev.h12
1 files changed, 12 insertions, 0 deletions
diff --git a/drivers/staging/comedi/comedidev.h b/drivers/staging/comedi/comedidev.h
index dcb637665eb7..0c7c37a8ff33 100644
--- a/drivers/staging/comedi/comedidev.h
+++ b/drivers/staging/comedi/comedidev.h
@@ -426,6 +426,18 @@ enum comedi_cb {
* handler will be called with the COMEDI device structure's board_ptr member
* pointing to the matched pointer to a board name within the driver's private
* array of static, read-only board type information.
+ *
+ * The @detach handler has two roles. If a COMEDI device was successfully
+ * configured by the @attach or @auto_attach handler, it is called when the
+ * device is being deconfigured (by the %COMEDI_DEVCONFIG ioctl, or due to
+ * unloading of the driver, or due to device removal). It is also called when
+ * the @attach or @auto_attach handler returns an error. Therefore, the
+ * @attach or @auto_attach handlers can defer clean-up on error until the
+ * @detach handler is called. If the @attach or @auto_attach handlers free
+ * any resources themselves, they must prevent the @detach handler from
+ * freeing the same resources. The @detach handler must not assume that all
+ * resources requested by the @attach or @auto_attach handler were
+ * successfully allocated.
*/
struct comedi_driver {
/* private: */