Merge with 2.3.99-pre6.

5 files changed, 430 insertions, 171 deletions

diff --git a/drivers/parport/ChangeLog b/drivers/parport/ChangeLog
index b2f122af0..1e09974c9 100644
--- a/drivers/parport/ChangeLog
+++ b/drivers/parport/ChangeLog
@@ -1,3 +1,20 @@
+2000-04-04  Tim Waugh  <twaugh@redhat.com>
+
+	* parport_pc.c: Add support for another PCI card.
+
+2000-04-04  Tim Waugh  <twaugh@redhat.com>
+
+	* daisy.c: Documentation in kernel-doc format.
+
+	* ieee1284.c: Likewise.
+
+	* share.c: Likewise.
+
+2000-04-01  Tim Waugh  <twaugh@redhat.com>
+
+	* share.c (parport_register_device): Need to hold the module
+	reference counts before sleeping.
+
 2000-03-27  Tim Waugh  <twaugh@redhat.com>
 
 	* parport_pc.c (parport_pc_ecp_read_block_pio): Correct operation
diff --git a/drivers/parport/daisy.c b/drivers/parport/daisy.c
index 3b13ea71a..ead3443b4 100644
--- a/drivers/parport/daisy.c
+++ b/drivers/parport/daisy.c
@@ -174,7 +174,26 @@ void parport_daisy_fini (struct parport *port)
 	return;
 }
 
-/* Find a device by canonical device number. */
+/**
+ *	parport_open - find a device by canonical device number
+ *	@devnum: canonical device number
+ *	@name: name to associate with the device
+ *	@pf: preemption callback
+ *	@kf: kick callback
+ *	@irqf: interrupt handler
+ *	@flags: registration flags
+ *	@handle: driver data
+ *
+ *	This function is similar to parport_register_device(), except
+ *	that it locates a device by its number rather than by the port
+ *	it is attached to.  See parport_find_device() and
+ *	parport_find_class().
+ *
+ *	All parameters except for @devnum are the same as for
+ *	parport_register_device().  The return value is the same as
+ *	for parport_register_device().
+ **/
+
 struct pardevice *parport_open (int devnum, const char *name,
 				int (*pf) (void *), void (*kf) (void *),
 				void (*irqf) (int, void *, struct pt_regs *),
@@ -219,13 +238,32 @@ struct pardevice *parport_open (int devnum, const char *name,
 	return dev;
 }
 
-/* The converse of parport_open. */
+/**
+ *	parport_close - close a device opened with parport_open()
+ *	@dev: device to close
+ *
+ *	This is to parport_open() as parport_unregister_device() is to
+ *	parport_register_device().
+ **/
+
 void parport_close (struct pardevice *dev)
 {
 	parport_unregister_device (dev);
 }
 
-/* Convert device coordinates into a canonical device number. */
+/**
+ *	parport_device_num - convert device coordinates into a
+ *			     canonical device number
+ *	@parport: parallel port number
+ *	@mux: multiplexor port number (-1 for no multiplexor)
+ *	@daisy: daisy chain address (-1 for no daisy chain address)
+ *
+ *	This tries to locate a device on the given parallel port,
+ *	multiplexor port and daisy chain address, and returns its
+ *	device number or -NXIO if no device with those coordinates
+ *	exists.
+ **/
+
 int parport_device_num (int parport, int mux, int daisy)
 {
 	struct daisydev *dev = topology;
@@ -240,7 +278,32 @@ int parport_device_num (int parport, int mux, int daisy)
 	return dev->devnum;
 }
 
-/* Convert a canonical device number into device coordinates. */
+/**
+ *	parport_device_coords - convert a canonical device number into
+ *				device coordinates
+ *	@devnum: device number
+ *	@parport: pointer to storage for parallel port number
+ *	@mux: pointer to storage for multiplexor port number
+ *	@daisy: pointer to storage for daisy chain address
+ *
+ *	This function converts a device number into its coordinates in
+ *	terms of which parallel port in the system it is attached to,
+ *	which multiplexor port it is attached to if there is a
+ *	multiplexor on that port, and which daisy chain address it has
+ *	if it is in a daisy chain.
+ *
+ *	The caller must allocate storage for @parport, @mux, and
+ *	@daisy.
+ *
+ *	If there is no device with the specified device number, -ENXIO
+ *	is returned.  Otherwise, the values pointed to by @parport,
+ *	@mux, and @daisy are set to the coordinates of the device,
+ *	with -1 for coordinates with no value.
+ *
+ *	This function is not actually very useful, but this interface
+ *	was suggested by IEEE 1284.3.
+ **/
+
 int parport_device_coords (int devnum, int *parport, int *mux, int *daisy)
 {
 	struct daisydev *dev = topology;
@@ -437,6 +500,28 @@ static int assign_addrs (struct parport *port)
 /* Find a device with a particular manufacturer and model string,
    starting from a given device number.  Like the PCI equivalent,
    'from' itself is skipped. */
+
+/**
+ *	parport_find_device - find a device with a specified
+ *			      manufacturer and model string
+ *	@mfg: required manufacturer string
+ *	@mdl: required model string
+ *	@from: previous device number found in search, or %NULL for
+ *	       new search
+ *
+ *	This walks through the list of parallel port devices looking
+ *	for a device whose 'MFG' string matches @mfg and whose 'MDL'
+ *	string matches @mdl in their IEEE 1284 Device ID.
+ *
+ *	When a device is found matching those requirements, its device
+ *	number is returned; if there is no matching device, a negative
+ *	value is returned.
+ *
+ *	A new search it initiated by passing %NULL as the @from
+ *	argument.  If @from is not %NULL, the search continues from
+ *	that device.
+ **/
+
 int parport_find_device (const char *mfg, const char *mdl, int from)
 {
 	struct daisydev *d = topology; /* sorted by devnum */
@@ -462,8 +547,25 @@ int parport_find_device (const char *mfg, const char *mdl, int from)
 	return -1;
 }
 
-/* Find a device in a particular class.  Like the PCI equivalent,
-   'from' itself is skipped. */
+/**
+ *	parport_find_class - find a device in a specified class
+ *	@cls: required class
+ *	@from: previous device number found in search, or %NULL for
+ *	       new search
+ *
+ *	This walks through the list of parallel port devices looking
+ *	for a device whose 'CLS' string matches @cls in their IEEE
+ *	1284 Device ID.
+ *
+ *	When a device is found matching those requirements, its device
+ *	number is returned; if there is no matching device, a negative
+ *	value is returned.
+ *
+ *	A new search it initiated by passing %NULL as the @from
+ *	argument.  If @from is not %NULL, the search continues from
+ *	that device.
+ **/
+
 int parport_find_class (parport_device_class cls, int from)
 {
 	struct daisydev *d = topology; /* sorted by devnum */
diff --git a/drivers/parport/ieee1284.c b/drivers/parport/ieee1284.c
index 6b9c9e47f..f25c50abd 100644
--- a/drivers/parport/ieee1284.c
+++ b/drivers/parport/ieee1284.c
@@ -42,11 +42,22 @@ static void timeout_waiting_on_port (unsigned long cookie)
 	parport_ieee1284_wakeup (port_from_cookie[cookie % PARPORT_MAX]);
 }
 
-/* Wait for a parport_ieee1284_wakeup.
- * 0:      success
- * <0:     error (exit as soon as possible)
- * >0:     timed out
+/**
+ *	parport_wait_event - wait for an event on a parallel port
+ *	@port: port to wait on
+ *	@timeout: time to wait (in jiffies)
+ *
+ *	This function waits for up to @timeout jiffies for an
+ *	interrupt to occur on a parallel port.  If the port timeout is
+ *	set to zero, it returns immediately.
+ *
+ *	If an interrupt occurs before the timeout period elapses, this
+ *	function returns one immediately.  If it times out, it returns
+ *	a value greater than zero.  An error code less than zero
+ *	indicates an error (most likely a pending signal), and the
+ *	calling code should finish what it's doing as soon as it can.
  */
+
 int parport_wait_event (struct parport *port, signed long timeout)
 {
 	int ret;
@@ -72,13 +83,29 @@ int parport_wait_event (struct parport *port, signed long timeout)
 	return ret;
 }
 
-/* Wait for Status line(s) to change in 35 ms - see IEEE1284-1994 page 24 to
- * 25 for this. After this time we can create a timeout because the
- * peripheral doesn't conform to IEEE1284.  We want to save CPU time: we are
- * waiting a maximum time of 500 us busy (this is for speed).  If there is
- * not the right answer in this time, we call schedule and other processes
- * are able to eat the time up to 40ms.
- */ 
+/**
+ *	parport_poll_peripheral - poll status lines
+ *	@port: port to watch
+ *	@mask: status lines to watch
+ *	@result: desired values of chosen status lines
+ *	@usec: timeout
+ *
+ *	This function busy-waits until the masked status lines have
+ *	the desired values, or until the timeout period elapses.  The
+ *	@mask and @result parameters are bitmasks, with the bits
+ *	defined by the constants in parport.h: %PARPORT_STATUS_BUSY,
+ *	and so on.
+ *
+ *	This function does not call schedule(); instead it busy-waits
+ *	using udelay().  It currently has a resolution of 5usec.
+ *
+ *	If the status lines take on the desired values before the
+ *	timeout period elapses, parport_poll_peripheral() returns zero
+ *	immediately.  A zero return value greater than zero indicates
+ *	a timeout.  An error code (less than zero) indicates an error,
+ *	most likely a signal that arrived, and the caller should
+ *	finish what it is doing as soon as possible.
+*/
 
 int parport_poll_peripheral(struct parport *port,
 			    unsigned char mask,
@@ -102,6 +129,31 @@ int parport_poll_peripheral(struct parport *port,
 	return 1;
 }
 
+/**
+ *	parport_wait_peripheral - wait for status lines to change in 35ms
+ *	@port: port to watch
+ *	@mask: status lines to watch
+ *	@result: desired values of chosen status lines
+ *
+ *	This function waits until the masked status lines have the
+ *	desired values, or until 35ms have elapsed (see IEEE 1284-1994
+ *	page 24 to 25 for why this value in particular is hardcoded).
+ *	The @mask and @result parameters are bitmasks, with the bits
+ *	defined by the constants in parport.h: %PARPORT_STATUS_BUSY,
+ *	and so on.
+ *
+ *	The port is polled quickly to start off with, in anticipation
+ *	of a fast response from the peripheral.  This fast polling
+ *	time is configurable (using /proc), and defaults to 500usec.
+ *	If the timeout for this port (see parport_set_timeout()) is
+ *	zero, the fast polling time is 35ms, and this function does
+ *	not call schedule().
+ *
+ *	If the timeout for this port is non-zero, after the fast
+ *	polling fails it uses parport_wait_event() to wait for up to
+ *	10ms, waking up if an interrupt occurs.
+ */
+
 int parport_wait_peripheral(struct parport *port,
 			    unsigned char mask, 
 			    unsigned char result)
@@ -255,12 +307,21 @@ static void parport_ieee1284_terminate (struct parport *port)
 }		
 #endif /* IEEE1284 support */
 
-/* Negotiate an IEEE 1284 mode.
- * return values are:
- *   0 - handshake OK; IEEE1284 peripheral and mode available
- *  -1 - handshake failed; peripheral is not compliant (or none present)
- *   1 - handshake OK; IEEE1284 peripheral present but mode not available
+/**
+ *	parport_negotiate - negotiate an IEEE 1284 mode
+ *	@port: port to use
+ *	@mode: mode to negotiate to
+ *
+ *	Use this to negotiate to a particular IEEE 1284 transfer mode.
+ *	The @mode parameter should be one of the constants in
+ *	parport.h starting %IEEE1284_MODE_xxx.
+ *
+ *	The return value is 0 if the peripheral has accepted the
+ *	negotiation to the mode specified, -1 if the peripheral is not
+ *	IEEE 1284 compliant (or not present), or 1 if the peripheral
+ *	has rejected the negotiation.
  */
+
 int parport_negotiate (struct parport *port, int mode)
 {
 #ifndef CONFIG_PARPORT_1284
@@ -513,7 +574,24 @@ void parport_ieee1284_interrupt (int which, void *handle, struct pt_regs *regs)
 #endif /* IEEE1284 support */
 }
 
-/* Write a block of data. */
+/**
+ *	parport_write - write a block of data to a parallel port
+ *	@port: port to write to
+ *	@buffer: data buffer (in kernel space)
+ *	@len: number of bytes of data to transfer
+ *
+ *	This will write up to @len bytes of @buffer to the port
+ *	specified, using the IEEE 1284 transfer mode most recently
+ *	negotiated to (using parport_negotiate()), as long as that
+ *	mode supports forward transfers (host to peripheral).
+ *
+ *	It is the caller's responsibility to ensure that the first
+ *	@len bytes of @buffer are valid.
+ *
+ *	This function returns the number of bytes transferred (if zero
+ *	or positive), or else an error code.
+ */
+
 ssize_t parport_write (struct parport *port, const void *buffer, size_t len)
 {
 #ifndef CONFIG_PARPORT_1284
@@ -578,7 +656,24 @@ ssize_t parport_write (struct parport *port, const void *buffer, size_t len)
 #endif /* IEEE1284 support */
 }
 
-/* Read a block of data. */
+/**
+ *	parport_read - read a block of data from a parallel port
+ *	@port: port to read from
+ *	@buffer: data buffer (in kernel space)
+ *	@len: number of bytes of data to transfer
+ *
+ *	This will read up to @len bytes of @buffer to the port
+ *	specified, using the IEEE 1284 transfer mode most recently
+ *	negotiated to (using parport_negotiate()), as long as that
+ *	mode supports reverse transfers (peripheral to host).
+ *
+ *	It is the caller's responsibility to ensure that the first
+ *	@len bytes of @buffer are available to write to.
+ *
+ *	This function returns the number of bytes transferred (if zero
+ *	or positive), or else an error code.
+ */
+
 ssize_t parport_read (struct parport *port, void *buffer, size_t len)
 {
 #ifndef CONFIG_PARPORT_1284
@@ -637,7 +732,23 @@ ssize_t parport_read (struct parport *port, void *buffer, size_t len)
 #endif /* IEEE1284 support */
 }
 
-/* Set the amount of time we wait while nothing's happening. */
+/**
+ *	parport_set_timeout - set the inactivity timeout for a device
+ *	                      on a port
+ *	@dev: device on a port
+ *	@inactivity: inactivity timeout (in jiffies)
+ *
+ *	This sets the inactivity timeout for a particular device on a
+ *	port.  This affects functions like parport_wait_peripheral().
+ *	The special value 0 means not to call schedule() while dealing
+ *	with this device.
+ *
+ *	The return value is the previous inactivity timeout.
+ *
+ *	Any callers of parport_wait_event() for this device are woken
+ *	up.
+ */
+
 long parport_set_timeout (struct pardevice *dev, long inactivity)
 {
 	long int old = dev->timeout;
diff --git a/drivers/parport/parport_pc.c b/drivers/parport/parport_pc.c
index 5b912d3ef..09255a3c1 100644
--- a/drivers/parport/parport_pc.c
+++ b/drivers/parport/parport_pc.c
@@ -427,6 +427,8 @@ static size_t parport_pc_ecpepp_read_data (struct parport *port, void *buf,
 	size_t got;
 
 	frob_econtrol (port, 0xe0, ECR_EPP << 5);
+	parport_pc_data_reverse (port);
+	parport_pc_write_control (port, 0x4);
 	got = parport_pc_epp_read_data (port, buf, length, flags);
 	frob_econtrol (port, 0xe0, ECR_PS2 << 5);
 
@@ -440,6 +442,8 @@ static size_t parport_pc_ecpepp_write_data (struct parport *port,
 	size_t written;
 
 	frob_econtrol (port, 0xe0, ECR_EPP << 5);
+	parport_pc_write_control (port, 0x4);
+	parport_pc_data_forward (port);
 	written = parport_pc_epp_write_data (port, buf, length, flags);
 	frob_econtrol (port, 0xe0, ECR_PS2 << 5);
 
@@ -452,6 +456,8 @@ static size_t parport_pc_ecpepp_read_addr (struct parport *port, void *buf,
 	size_t got;
 
 	frob_econtrol (port, 0xe0, ECR_EPP << 5);
+	parport_pc_data_reverse (port);
+	parport_pc_write_control (port, 0x4);
 	got = parport_pc_epp_read_addr (port, buf, length, flags);
 	frob_econtrol (port, 0xe0, ECR_PS2 << 5);
 
@@ -465,6 +471,8 @@ static size_t parport_pc_ecpepp_write_addr (struct parport *port,
 	size_t written;
 
 	frob_econtrol (port, 0xe0, ECR_EPP << 5);
+	parport_pc_write_control (port, 0x4);
+	parport_pc_data_forward (port);
 	written = parport_pc_epp_write_addr (port, buf, length, flags);
 	frob_econtrol (port, 0xe0, ECR_PS2 << 5);
 
@@ -582,7 +590,7 @@ static size_t parport_pc_fifo_write_block_dma (struct parport *port,
 	if (end < MAX_DMA_ADDRESS) {
 		/* If it would cross a 64k boundary, cap it at the end. */
 		if ((start ^ end) & ~0xffffUL)
-			maxlen = (0x10000 - start) & 0xffff;
+			maxlen = 0x10000 - (start & 0xffff);
 
 		dma_addr = dma_handle = pci_map_single(priv->dev, (void *)buf, length,
 						       PCI_DMA_TODEVICE);
@@ -1733,7 +1741,7 @@ static int __devinit parport_ECPEPP_supported(struct parport *pb)
 	oecr = inb (ECONTROL (pb));
 	/* Search for SMC style EPP+ECP mode */
 	outb (0x80, ECONTROL (pb));
-	
+	outb (0x04, CONTROL (pb));
 	result = parport_EPP_supported(pb);
 
 	outb (oecr, ECONTROL (pb));
@@ -2254,6 +2262,7 @@ enum parport_pc_pci_cards {
 	boca_ioppar,
 	plx_9050,
 	afavlab_tk9902,
+	timedia_1889,
 };
 
 
@@ -2291,6 +2300,7 @@ static struct parport_pc_pci {
 	/* boca_ioppar */		{ 1, { { 0, -1 }, } },
 	/* plx_9050 */			{ 2, { { 4, -1 }, { 5, -1 }, } },
 	/* afavlab_tk9902 */		{ 1, { { 0, 1 }, } },
+	/* timedia_1889 */		{ 1, { { 2, -1 }, } },
 };
 
 static struct pci_device_id parport_pc_pci_tbl[] __devinitdata = {
@@ -2348,6 +2358,8 @@ static struct pci_device_id parport_pc_pci_tbl[] __devinitdata = {
 	  PCI_SUBVENDOR_ID_EXSYS, PCI_SUBDEVICE_ID_EXSYS_4014, 0,0, plx_9050 },
 	{ PCI_VENDOR_ID_AFAVLAB, PCI_DEVICE_ID_AFAVLAB_TK9902,
 	  PCI_ANY_ID, PCI_ANY_ID, 0, 0, afavlab_tk9902 },
+	{ PCI_VENDOR_ID_TIMEDIA, PCI_DEVICE_ID_TIMEDIA_1889,
+	  PCI_ANY_ID, PCI_ANY_ID, 0, 0, timedia_1889 },
 	{ 0, }, /* terminate list */
 };
 MODULE_DEVICE_TABLE(pci,parport_pc_pci_tbl);
diff --git a/drivers/parport/share.c b/drivers/parport/share.c
index 27cd907e1..63a185029 100644
--- a/drivers/parport/share.c
+++ b/drivers/parport/share.c
@@ -104,18 +104,19 @@ static void get_lowlevel_driver (void)
 }
 
 /**
- * parport_register_driver - register a parallel port device driver
- * @drv: structure describing the driver
+ *	parport_register_driver - register a parallel port device driver
+ *	@drv: structure describing the driver
  *
- * This can be called by a parallel port device driver in order to
- * receive notifications about ports being found in the system, as
- * well as ports no longer available.
+ *	This can be called by a parallel port device driver in order
+ *	to receive notifications about ports being found in the
+ *	system, as well as ports no longer available.
  *
- * The @drv structure is allocated by the caller and must not be
- * deallocated until after calling parport_unregister_driver().
+ *	The @drv structure is allocated by the caller and must not be
+ *	deallocated until after calling parport_unregister_driver().
  *
- * Returns 0 on success.  Currently it always succeeds.
+ *	Returns 0 on success.  Currently it always succeeds.
  **/
+
 int parport_register_driver (struct parport_driver *drv)
 {
 	struct parport *port;
@@ -135,22 +136,23 @@ int parport_register_driver (struct parport_driver *drv)
 }
 
 /**
- * parport_unregister_driver - deregister a parallel port device driver
- * @arg: structure describing the driver that was given to
- *       parport_register_driver()
+ *	parport_unregister_driver - deregister a parallel port device driver
+ *	@arg: structure describing the driver that was given to
+ *	      parport_register_driver()
  *
- * This should be called by a parallel port device driver that has
- * registered itself using parport_register_driver() when it is about
- * to be unloaded.
+ *	This should be called by a parallel port device driver that
+ *	has registered itself using parport_register_driver() when it
+ *	is about to be unloaded.
  *
- * When it returns, the driver's attach() routine will no longer be
- * called, and for each port that attach() was called for, the
- * detach() routine will hae been called.
+ *	When it returns, the driver's attach() routine will no longer
+ *	be called, and for each port that attach() was called for, the
+ *	detach() routine will have been called.
  *
- * If the caller's attach() function can block, it is their
- * responsibility to make sure to wait for it to exit before
- * unloading.
+ *	If the caller's attach() function can block, it is their
+ *	responsibility to make sure to wait for it to exit before
+ *	unloading.
  **/
+
 void parport_unregister_driver (struct parport_driver *arg)
 {
 	struct parport_driver *drv = driver_chain, *olddrv = NULL;
@@ -180,16 +182,17 @@ void parport_unregister_driver (struct parport_driver *arg)
 }
 
 /**
- * parport_enumerate - return a list of the system's parallel ports
+ *	parport_enumerate - return a list of the system's parallel ports
  *
- * This returns the head of the list of parallel ports in the system.
- * The structure that is returned describes the first port in the
- * list, and its 'next' member points to the next port, or %NULL if
- * it's the last port.
+ *	This returns the head of the list of parallel ports in the
+ *	system, as a &struct parport.  The structure that is returned
+ *	describes the first port in the list, and its 'next' member
+ *	points to the next port, or %NULL if it's the last port.
  *
- * If there are no parallel ports in the system, parport_enumerate()
- * will return %NULL.
+ *	If there are no parallel ports in the system,
+ *	parport_enumerate() will return %NULL.
  **/
+
 struct parport *parport_enumerate(void)
 {
 	if (!portlist)
@@ -199,32 +202,34 @@ struct parport *parport_enumerate(void)
 }
 
 /**
- * parport_register_port - register a parallel port
- * @base: base I/O address
- * @irq: IRQ line
- * @dma: DMA channel
- * @ops: pointer to the port driver's port operations structure
+ *	parport_register_port - register a parallel port
+ *	@base: base I/O address
+ *	@irq: IRQ line
+ *	@dma: DMA channel
+ *	@ops: pointer to the port driver's port operations structure
  *
- * When a parallel port (lowlevel) driver finds a port that should be
- * made available to parallel port device drivers, it should call
- * parport_register_port().  The @base, @irq, and @dma parameters are
- * for the convenience of port drivers, and for ports where they
- * aren't meaningful needn't be set to anything special.  They can be
- * altered afterwards by adjusting the relevant members of the parport
- * structure that is returned and represents the port.  They should
- * not be tampered with after calling parport_announce_port, however.
+ *	When a parallel port (lowlevel) driver finds a port that
+ *	should be made available to parallel port device drivers, it
+ *	should call parport_register_port().  The @base, @irq, and
+ *	@dma parameters are for the convenience of port drivers, and
+ *	for ports where they aren't meaningful needn't be set to
+ *	anything special.  They can be altered afterwards by adjusting
+ *	the relevant members of the parport structure that is returned
+ *	and represents the port.  They should not be tampered with
+ *	after calling parport_announce_port, however.
  *
- * If there are parallel port device drivers in the system that have
- * registered themselves using parport_register_driver(), they are not
- * told about the port at this time; that is done by
- * parport_announce_port().
+ *	If there are parallel port device drivers in the system that
+ *	have registered themselves using parport_register_driver(),
+ *	they are not told about the port at this time; that is done by
+ *	parport_announce_port().
  *
- * The @ops structure is allocated by the caller, and must not be
- * deallocated before calling parport_unregister_port().
+ *	The @ops structure is allocated by the caller, and must not be
+ *	deallocated before calling parport_unregister_port().
  *
- * If there is no memory to allocate a new parport structure, this
- * function will return %NULL.
+ *	If there is no memory to allocate a new parport structure,
+ *	this function will return %NULL.
  **/
+
 struct parport *parport_register_port(unsigned long base, int irq, int dma,
 				      struct parport_operations *ops)
 {
@@ -310,16 +315,17 @@ struct parport *parport_register_port(unsigned long base, int irq, int dma,
 }
 
 /**
- * parport_announce_port - tell device drivers about a parallel port
- * @port: parallel port to announce
+ *	parport_announce_port - tell device drivers about a parallel port
+ *	@port: parallel port to announce
  *
- * After a port driver has registered a parallel port with
- * parport_register_port, and performed any necessary initialisation
- * or adjustments, it should call parport_announce_port() in order to
- * notify all device drivers that have called
- * parport_register_driver().  Their attach() functions will be
- * called, with @port as the parameter.
+ *	After a port driver has registered a parallel port with
+ *	parport_register_port, and performed any necessary
+ *	initialisation or adjustments, it should call
+ *	parport_announce_port() in order to notify all device drivers
+ *	that have called parport_register_driver().  Their attach()
+ *	functions will be called, with @port as the parameter.
  **/
+
 void parport_announce_port (struct parport *port)
 {
 #ifdef CONFIG_PARPORT_1284
@@ -364,22 +370,24 @@ static void free_port (struct parport *port)
 }
 
 /**
- * parport_unregister_port - deregister a parallel port
- * @port: parallel port to deregister
+ *	parport_unregister_port - deregister a parallel port
+ *	@port: parallel port to deregister
  *
- * When a parallel port driver is forcibly unloaded, or a parallel
- * port becomes inaccessible, the port driver must call this function
- * in order to deal with device drivers that still want to use it.
+ *	When a parallel port driver is forcibly unloaded, or a
+ *	parallel port becomes inaccessible, the port driver must call
+ *	this function in order to deal with device drivers that still
+ *	want to use it.
  *
- * The parport structure associated with the port has its operations
- * structure replaced with one containing 'null' operations that
- * return errors or just don't do anything.
+ *	The parport structure associated with the port has its
+ *	operations structure replaced with one containing 'null'
+ *	operations that return errors or just don't do anything.
  *
- * Any drivers that have registered themselves using
- * parport_register_driver() are notified that the port is no longer
- * accessible by having their detach() routines called with @port as
- * the parameter.
+ *	Any drivers that have registered themselves using
+ *	parport_register_driver() are notified that the port is no
+ *	longer accessible by having their detach() routines called
+ *	with @port as the parameter.
  **/
+
 void parport_unregister_port(struct parport *port)
 {
 	struct parport *p;
@@ -415,70 +423,74 @@ void parport_unregister_port(struct parport *port)
 }
 
 /**
- * parport_register_device - register a device on a parallel port
- * @port: port to which the device is attached
- * @name: a name to refer to the device
- * @pf: preemption callback
- * @kf: kick callback (wake-up)
- * @irq_func: interrupt handler
- * @flags: registration flags
- * @handle: data for callback functions
+ *	parport_register_device - register a device on a parallel port
+ *	@port: port to which the device is attached
+ *	@name: a name to refer to the device
+ *	@pf: preemption callback
+ *	@kf: kick callback (wake-up)
+ *	@irq_func: interrupt handler
+ *	@flags: registration flags
+ *	@handle: data for callback functions
  *
- * This function, called by parallel port device drivers, declares
- * that a device is connected to a port, and tells the system all it
- * needs to know.
+ *	This function, called by parallel port device drivers,
+ *	declares that a device is connected to a port, and tells the
+ *	system all it needs to know.
  *
- * The @name is allocated by the caller and must not be deallocated
- * until the caller calls @parport_unregister_device for that device.
+ *	The @name is allocated by the caller and must not be
+ *	deallocated until the caller calls @parport_unregister_device
+ *	for that device.
  *
- * The preemption callback function, @pf, is called when this device
- * driver has claimed access to the port but another device driver
- * wants to use it.  It is given @handle as its parameter, and should
- * return zero if it is willing for the system to release the port to
- * another driver on its behalf.  If it wants to keep control of the
- * port it should return non-zero, and no action will be taken.  It is
- * good manners for the driver to try to release the port at the
- * earliest opportunity after its preemption callback rejects a
- * preemption attempt.  Note that if a preemption callback is happy
- * for preemption to go ahead, there is no need to release the port;
- * it is done automatically.  This function may not block, as it may
- * be called from interrupt context.  If the device driver does not
- * support preemption, @pf can be %NULL.
+ *	The preemption callback function, @pf, is called when this
+ *	device driver has claimed access to the port but another
+ *	device driver wants to use it.  It is given @handle as its
+ *	parameter, and should return zero if it is willing for the
+ *	system to release the port to another driver on its behalf.
+ *	If it wants to keep control of the port it should return
+ *	non-zero, and no action will be taken.  It is good manners for
+ *	the driver to try to release the port at the earliest
+ *	opportunity after its preemption callback rejects a preemption
+ *	attempt.  Note that if a preemption callback is happy for
+ *	preemption to go ahead, there is no need to release the port;
+ *	it is done automatically.  This function may not block, as it
+ *	may be called from interrupt context.  If the device driver
+ *	does not support preemption, @pf can be %NULL.
  *
- * The wake-up ("kick") callback function, @kf, is called when the
- * port is available to be claimed for exclusive access; that is,
- * parport_claim() is guaranteed to succeed when called from inside
- * the wake-up callback function.  If the driver wants to claim the
- * port it should do so; otherwise, it need not take any action.  This
- * function may not block, as it may be called from interrupt context.
- * If the device driver does not want to be explicitly invited to
- * claim the port in this way, @kf can be %NULL.
+ *	The wake-up ("kick") callback function, @kf, is called when
+ *	the port is available to be claimed for exclusive access; that
+ *	is, parport_claim() is guaranteed to succeed when called from
+ *	inside the wake-up callback function.  If the driver wants to
+ *	claim the port it should do so; otherwise, it need not take
+ *	any action.  This function may not block, as it may be called
+ *	from interrupt context.  If the device driver does not want to
+ *	be explicitly invited to claim the port in this way, @kf can
+ *	be %NULL.
  *
- * The interrupt handler, @irq_func, is called when an interrupt
- * arrives from the parallel port.  Note that if a device driver wants
- * to use interrupts it should use parport_enable_irq(), and can also
- * check the irq member of the parport structure representing the
- * port.
+ *	The interrupt handler, @irq_func, is called when an interrupt
+ *	arrives from the parallel port.  Note that if a device driver
+ *	wants to use interrupts it should use parport_enable_irq(),
+ *	and can also check the irq member of the parport structure
+ *	representing the port.
  *
- * The parallel port (lowlevel) driver is the one that has called
- * request_irq() and whose interrupt handler is called first.  This
- * handler does whatever needs to be done to the hardware to
- * acknowledge the interrupt (for PC-style ports there is nothing
- * special to be done).  It then tells the IEEE 1284 code about the
- * interrupt, which may involve reacting to an IEEE 1284 event
- * depending on the current IEEE 1284 phase.  After this, it calls
- * @irq_func.  Needless to say, @irq_func will be called from
- * interrupt context, and may not block.
+ *	The parallel port (lowlevel) driver is the one that has called
+ *	request_irq() and whose interrupt handler is called first.
+ *	This handler does whatever needs to be done to the hardware to
+ *	acknowledge the interrupt (for PC-style ports there is nothing
+ *	special to be done).  It then tells the IEEE 1284 code about
+ *	the interrupt, which may involve reacting to an IEEE 1284
+ *	event depending on the current IEEE 1284 phase.  After this,
+ *	it calls @irq_func.  Needless to say, @irq_func will be called
+ *	from interrupt context, and may not block.
  *
- * The %PARPORT_DEV_EXCL flag is for preventing port sharing, and so
- * should only be used when sharing the port with other device drivers
- * is impossible and would lead to incorrect behaviour.  Use it
- * sparingly!  Normally, @flags will be zero.
+ *	The %PARPORT_DEV_EXCL flag is for preventing port sharing, and
+ *	so should only be used when sharing the port with other device
+ *	drivers is impossible and would lead to incorrect behaviour.
+ *	Use it sparingly!  Normally, @flags will be zero.
  *
- * This function returns a pointer to a structure that represents the
- * device on the port, or %NULL if there is not enough memory to
- * allocate space for that structure.
+ *	This function returns a pointer to a structure that represents
+ *	the device on the port, or %NULL if there is not enough memory
+ *	to allocate space for that structure.
  **/
+
 struct pardevice *
 parport_register_device(struct parport *port, const char *name,
 			int (*pf)(void *), void (*kf)(void *),
@@ -581,11 +593,12 @@ parport_register_device(struct parport *port, const char *name,
 }
 
 /**
- * parport_unregister_device - deregister a device on a parallel port
- * @dev: pointer to structure representing device
+ *	parport_unregister_device - deregister a device on a parallel port
+ *	@dev: pointer to structure representing device
  *
- * This undoes the effect of parport_register_device().
+ *	This undoes the effect of parport_register_device().
  **/
+
 void parport_unregister_device(struct pardevice *dev)
 {
 	struct parport *port;
@@ -633,15 +646,17 @@ void parport_unregister_device(struct pardevice *dev)
 }
 
 /**
- * parport_claim - claim access to a parallel port device
- * @dev: pointer to structure representing a device on the port
+ *	parport_claim - claim access to a parallel port device
+ *	@dev: pointer to structure representing a device on the port
  *
- * This function will not block and so can be used from interrupt
- * context.  If parport_claim() succeeds in claiming access to the
- * port it returns zero and the port is available to use.  It may fail
- * (returning non-zero) if the port is in use by another driver and
- * that driver is not willing to relinquish control of the port.
+ *	This function will not block and so can be used from interrupt
+ *	context.  If parport_claim() succeeds in claiming access to
+ *	the port it returns zero and the port is available to use.  It
+ *	may fail (returning non-zero) if the port is in use by another
+ *	driver and that driver is not willing to relinquish control of
+ *	the port.
  **/
+
 int parport_claim(struct pardevice *dev)
 {
 	struct pardevice *oldcad;
@@ -744,14 +759,15 @@ blocked:
 }
 
 /**
- * parport_claim_or_block - claim access to a parallel port device
- * @dev: pointer to structure representing a device on the port
+ *	parport_claim_or_block - claim access to a parallel port device
+ *	@dev: pointer to structure representing a device on the port
  *
- * This behaves like parport_claim(), but will block if necessary to
- * wait for the port to be free.  A return value of 1 indicates that
- * it slept; 0 means that it succeeded without needing to sleep.  A
- * negative error code indicates failure.
+ *	This behaves like parport_claim(), but will block if necessary
+ *	to wait for the port to be free.  A return value of 1
+ *	indicates that it slept; 0 means that it succeeded without
+ *	needing to sleep.  A negative error code indicates failure.
  **/
+
 int parport_claim_or_block(struct pardevice *dev)
 {
 	int r;
@@ -795,13 +811,14 @@ int parport_claim_or_block(struct pardevice *dev)
 }
 
 /**
- * parport_release - give up access to a parallel port device
- * @dev: pointer to structure representing parallel port device
+ *	parport_release - give up access to a parallel port device
+ *	@dev: pointer to structure representing parallel port device
  *
- * This function cannot fail, but it should not be called without the
- * port claimed.  Similarly, if the port is already claimed you should
- * not try claiming it again.
+ *	This function cannot fail, but it should not be called without
+ *	the port claimed.  Similarly, if the port is already claimed
+ *	you should not try claiming it again.
  **/
+
 void parport_release(struct pardevice *dev)
 {
 	struct parport *port = dev->port->physport;