From 3e0f9b2ca8e4839335e4d64ec0a75f4fd5111c4b Mon Sep 17 00:00:00 2001 From: Ian Abbott Date: Thu, 8 Dec 2016 13:53:10 +0000 Subject: 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 Signed-off-by: Greg Kroah-Hartman --- drivers/staging/comedi/comedidev.h | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/drivers/staging/comedi/comedidev.h b/drivers/staging/comedi/comedidev.h index dcb6376..0c7c37a 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: */ -- cgit v1.1