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>

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);

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