linux-kernel - [PATCH] staging: comedi: comedidev.h: Document usage of 'detach' handler

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-Id: <20161208135310.16295-1-abbotti@mev.co.uk>
Date:   Thu,  8 Dec 2016 13:53:10 +0000
From:   Ian Abbott <abbotti@....co.uk>
To:     devel@...verdev.osuosl.org
Cc:     Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Ian Abbott <abbotti@....co.uk>,
        H Hartley Sweeten <hsweeten@...ionengravers.com>,
        linux-kernel@...r.kernel.org
Subject: [PATCH] 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@....co.uk>
---
 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: */
-- 
2.10.2