staging: comedi: 8255: document callback parameters better

Several Comedi driver modules call `subdev_8255_init()` or
`subdev_8255_mm_init()` to set up a digital I/O subdevice based on the
"8255" chip.  One of the parameters to these functions is an optional
pointer to an I/O callback function to perform the actual register
accesses (an internal default callback function is used if NULL).

The kerneldoc for `subdev_8255_init()` and `subdev_8255_mm_init()`
describe the prototype of the optional I/O callback function
incorrectly (my fault), adding a non-existent parameter of type `struct
comedi_subdevice *`.  Fix the kerneldoc.  Also add parameter names to
the callback function pointer type wherever it occurs to make the usage
clearer.

Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
Reviewed-by: H Hartley Sweeten <hsweeten@visionengravers.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/drivers/staging/comedi/drivers/8255.c b/drivers/staging/comedi/drivers/8255.c
index 0fdf8342c995d11549712b9e2d63a19e5480d303..f87a27e540b13dfc3d1afa894862331993e9b049 100644 (file)
--- a/drivers/staging/comedi/drivers/8255.c
+++ b/drivers/staging/comedi/drivers/8255.c
@@ -55,7 +55,8 @@
 
 struct subdev_8255_private {
        unsigned long regbase;
-       int (*io)(struct comedi_device *, int, int, int, unsigned long);
+       int (*io)(struct comedi_device *dev, int dir, int port, int data,
+                 unsigned long regbase);
 };
 
 static int subdev_8255_io(struct comedi_device *dev,
@@ -160,8 +161,9 @@ static int subdev_8255_insn_config(struct comedi_device *dev,
 
 static int __subdev_8255_init(struct comedi_device *dev,
                              struct comedi_subdevice *s,
-                             int (*io)(struct comedi_device *,
-                                       int, int, int, unsigned long),
+                             int (*io)(struct comedi_device *dev,
+                                       int dir, int port, int data,
+                                       unsigned long regbase),
                              unsigned long regbase,
                              bool is_mmio)
 {
@@ -204,11 +206,10 @@ static int __subdev_8255_init(struct comedi_device *dev,
  * If the optional I/O call-back function is provided, its prototype is of
  * the following form:
  *
- *   int my_8255_callback(struct comedi_device *dev,
- *                        struct comedi_subdevice *s, int dir, int port,
+ *   int my_8255_callback(struct comedi_device *dev, int dir, int port,
  *                        int data, unsigned long regbase);
  *
- * where 'dev', 's', and 'regbase' match the values passed to this function,
+ * where 'dev', and 'regbase' match the values passed to this function,
  * 'port' is the 8255 port number 0 to 3 (including the control port), 'dir'
  * is the direction (0 for read, 1 for write) and 'data' is the value to be
  * written.  It should return 0 if writing or the value read if reading.
@@ -220,8 +221,8 @@ static int __subdev_8255_init(struct comedi_device *dev,
  * Return: -ENOMEM if failed to allocate memory, zero on success.
  */
 int subdev_8255_init(struct comedi_device *dev, struct comedi_subdevice *s,
-                    int (*io)(struct comedi_device *,
-                              int, int, int, unsigned long),
+                    int (*io)(struct comedi_device *dev, int dir, int port,
+                              int data, unsigned long regbase),
                     unsigned long regbase)
 {
        return __subdev_8255_init(dev, s, io, regbase, false);
@@ -240,11 +241,10 @@ EXPORT_SYMBOL_GPL(subdev_8255_init);
  * If the optional I/O call-back function is provided, its prototype is of
  * the following form:
  *
- *   int my_8255_callback(struct comedi_device *dev,
- *                        struct comedi_subdevice *s, int dir, int port,
+ *   int my_8255_callback(struct comedi_device *dev, int dir, int port,
  *                        int data, unsigned long regbase);
  *
- * where 'dev', 's', and 'regbase' match the values passed to this function,
+ * where 'dev', and 'regbase' match the values passed to this function,
  * 'port' is the 8255 port number 0 to 3 (including the control port), 'dir'
  * is the direction (0 for read, 1 for write) and 'data' is the value to be
  * written.  It should return 0 if writing or the value read if reading.
@@ -256,8 +256,8 @@ EXPORT_SYMBOL_GPL(subdev_8255_init);
  * Return: -ENOMEM if failed to allocate memory, zero on success.
  */
 int subdev_8255_mm_init(struct comedi_device *dev, struct comedi_subdevice *s,
-                       int (*io)(struct comedi_device *,
-                                 int, int, int, unsigned long),
+                       int (*io)(struct comedi_device *dev, int dir, int port,
+                                 int data, unsigned long regbase),
                        unsigned long regbase)
 {
        return __subdev_8255_init(dev, s, io, regbase, true);

diff --git a/drivers/staging/comedi/drivers/8255.h b/drivers/staging/comedi/drivers/8255.h
index 977cfe4da002fd790e887294defc4576e60998ad..21856d669288b0614d3d45f9b74c1b365999ab3d 100644 (file)
--- a/drivers/staging/comedi/drivers/8255.h
+++ b/drivers/staging/comedi/drivers/8255.h
@@ -36,14 +36,14 @@
 struct comedi_device;
 struct comedi_subdevice;
 
-int subdev_8255_init(struct comedi_device *, struct comedi_subdevice *,
-                    int (*io)(struct comedi_device *,
-                              int, int, int, unsigned long),
+int subdev_8255_init(struct comedi_device *dev, struct comedi_subdevice *s,
+                    int (*io)(struct comedi_device *dev, int dir, int port,
+                              int data, unsigned long regbase),
                     unsigned long regbase);
 
-int subdev_8255_mm_init(struct comedi_device *, struct comedi_subdevice *,
-                       int (*io)(struct comedi_device *,
-                                 int, int, int, unsigned long),
+int subdev_8255_mm_init(struct comedi_device *dev, struct comedi_subdevice *s,
+                       int (*io)(struct comedi_device *dev, int dir, int port,
+                                 int data, unsigned long regbase),
                        unsigned long regbase);
 
 #endif