staging: dgnc: remove unnecessary comments

TODO file lists task to remove unnecessary comments.

Make initial attempt at removing unnecessary comments. Choose not to
be to vicious in removal. We can remove more once the driver is
cleaned up/tested some more.

For functions with internal linkage, reduce the function comment where
possible. For functions with external linkage, migrate the function
comment to kernel doc format.

Signed-off-by: Tobin C. Harding <me@tobin.cc>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

drivers/staging/dgnc/dgnc_cls.c

@@ -14,15 +14,15 @@
  */
 
 #include <linux/kernel.h>
-#include <linux/sched.h>	/* For jiffies, task states */
-#include <linux/interrupt.h>	/* For tasklet and interrupt structs/defines */
-#include <linux/delay.h>	/* For udelay */
-#include <linux/io.h>		/* For read[bwl]/write[bwl] */
-#include <linux/serial.h>	/* For struct async_serial */
-#include <linux/serial_reg.h>	/* For the various UART offsets */
+#include <linux/sched.h>
+#include <linux/interrupt.h>
+#include <linux/delay.h>
+#include <linux/io.h>
+#include <linux/serial.h>
+#include <linux/serial_reg.h>
 #include <linux/pci.h>
 
-#include "dgnc_driver.h"	/* Driver main header file */
+#include "dgnc_driver.h"
 #include "dgnc_cls.h"
 #include "dgnc_tty.h"
 
@@ -273,7 +273,6 @@ static inline void cls_set_no_input_flow_control(struct channel_t *ch)
 }
 
 /*
- * cls_clear_break.
  * Determines whether its time to shut off break condition.
  *
  * No locks are assumed to be held when calling this function.
@@ -288,7 +287,6 @@ static inline void cls_clear_break(struct channel_t *ch, int force)
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* Bail if we aren't currently sending a break. */
 	if (!ch->ch_stop_sending_break) {
 		spin_unlock_irqrestore(&ch->ch_lock, flags);
 		return;
@@ -321,11 +319,9 @@ static void cls_copy_data_from_uart_to_queue(struct channel_t *ch)
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* cache head and tail of queue */
 	head = ch->ch_r_head;
 	tail = ch->ch_r_tail;
 
-	/* Store how much space we have left in the queue */
 	qleft = tail - head - 1;
 	if (qleft < 0)
 		qleft += RQUEUEMASK + 1;
@@ -343,9 +339,7 @@ static void cls_copy_data_from_uart_to_queue(struct channel_t *ch)
 		if (!(linestatus & (UART_LSR_DR)))
 			break;
 
-		/*
-		 * Discard character if we are ignoring the error mask.
-		 */
+		/* Discard character if we are ignoring the error mask. */
 		if (linestatus & error_mask)  {
 			linestatus = 0;
 			readb(&ch->ch_cls_uart->txrx);
@@ -356,9 +350,6 @@ static void cls_copy_data_from_uart_to_queue(struct channel_t *ch)
 		 * If our queue is full, we have no choice but to drop some
 		 * data. The assumption is that HWFLOW or SWFLOW should have
 		 * stopped things way way before we got to this point.
-		 *
-		 * I decided that I wanted to ditch the oldest data first,
-		 * I hope thats okay with everyone? Yes? Good.
 		 */
 		while (qleft < 1) {
 			tail = (tail + 1) & RQUEUEMASK;
@@ -380,13 +371,10 @@ static void cls_copy_data_from_uart_to_queue(struct channel_t *ch)
 		if (ch->ch_equeue[head] & UART_LSR_FE)
 			ch->ch_err_frame++;
 
-		/* Add to, and flip head if needed */
 		head = (head + 1) & RQUEUEMASK;
 		ch->ch_rxcount++;
 	}
 
-	/* Write new final heads to channel structure. */
-
 	ch->ch_r_head = head & RQUEUEMASK;
 	ch->ch_e_head = head & EQUEUEMASK;
 
@@ -426,7 +414,6 @@ static void cls_copy_data_from_queue_to_uart(struct channel_t *ch)
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* No data to write to the UART */
 	if (ch->ch_w_tail == ch->ch_w_head)
 		goto exit_unlock;
 
@@ -440,12 +427,10 @@ static void cls_copy_data_from_queue_to_uart(struct channel_t *ch)
 
 	n = 32;
 
-	/* cache head and tail of queue */
 	head = ch->ch_w_head & WQUEUEMASK;
 	tail = ch->ch_w_tail & WQUEUEMASK;
 	qlen = (head - tail) & WQUEUEMASK;
 
-	/* Find minimum of the FIFO space, versus queue length */
 	n = min(n, qlen);
 
 	while (n > 0) {
@@ -524,10 +509,7 @@ static void cls_parse_modem(struct channel_t *ch, unsigned char signals)
 	}
 	spin_unlock_irqrestore(&ch->ch_lock, flags);
 
-	/*
-	 * Scrub off lower bits. They signify delta's, which I don't
-	 * care about
-	 */
+	/* Scrub off lower bits. They signify delta's */
 	signals &= 0xf0;
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
@@ -576,27 +558,23 @@ static inline void cls_parse_isr(struct dgnc_board *brd, uint port)
 	while (1) {
 		isr = readb(&ch->ch_cls_uart->isr_fcr);
 
-		/* Bail if no pending interrupt on port */
 		if (isr & UART_IIR_NO_INT)
 			break;
 
 		/* Receive Interrupt pending */
 		if (isr & (UART_IIR_RDI | UART_IIR_RDI_TIMEOUT)) {
-			/* Read data from uart -> queue */
 			cls_copy_data_from_uart_to_queue(ch);
 			dgnc_check_queue_flow_control(ch);
 		}
 
 		/* Transmit Hold register empty pending */
 		if (isr & UART_IIR_THRI) {
-			/* Transfer data (if any) from Write Queue -> UART. */
 			spin_lock_irqsave(&ch->ch_lock, flags);
 			ch->ch_flags |= (CH_TX_FIFO_EMPTY | CH_TX_FIFO_LWM);
 			spin_unlock_irqrestore(&ch->ch_lock, flags);
 			cls_copy_data_from_queue_to_uart(ch);
 		}
 
-		/* Parse any modem signal changes */
 		cls_parse_modem(ch, readb(&ch->ch_cls_uart->msr));
 	}
 }
@@ -636,10 +614,7 @@ static void cls_flush_uart_read(struct channel_t *ch)
 	udelay(10);
 }
 
-/*
- * cls_param()
- * Send any/all changes to the line to the UART.
- */
+/* Send any/all changes to the line to the UART. */
 static void cls_param(struct tty_struct *tty)
 {
 	unsigned char lcr = 0;
@@ -668,7 +643,6 @@ static void cls_param(struct tty_struct *tty)
 		return;
 
 	/* If baud rate is zero, flush queues, and set mval to drop DTR. */
-
 	if ((ch->ch_c_cflag & (CBAUD)) == 0) {
 		ch->ch_r_head = 0;
 		ch->ch_r_tail = 0;
@@ -778,10 +752,6 @@ static void cls_param(struct tty_struct *tty)
 	if (!(ch->ch_c_cflag & PARODD))
 		lcr |= UART_LCR_EPAR;
 
-	/*
-	 * Not all platforms support mark/space parity,
-	 * so this will hide behind an ifdef.
-	 */
 #ifdef CMSPAR
 	if (ch->ch_c_cflag & CMSPAR)
 		lcr |= UART_LCR_SPAR;
@@ -852,10 +822,6 @@ static void cls_param(struct tty_struct *tty)
 	if (ch->ch_digi.digi_flags & CTSPACE || ch->ch_c_cflag & CRTSCTS) {
 		cls_set_cts_flow_control(ch);
 	} else if (ch->ch_c_iflag & IXON) {
-		/*
-		 * If start/stop is set to disable, then we should
-		 * disable flow control
-		 */
 		if ((ch->ch_startc == _POSIX_VDISABLE) ||
 		    (ch->ch_stopc == _POSIX_VDISABLE))
 			cls_set_no_output_flow_control(ch);
@@ -868,10 +834,6 @@ static void cls_param(struct tty_struct *tty)
 	if (ch->ch_digi.digi_flags & RTSPACE || ch->ch_c_cflag & CRTSCTS) {
 		cls_set_rts_flow_control(ch);
 	} else if (ch->ch_c_iflag & IXOFF) {
-		/*
-		 * If start/stop is set to disable, then we should disable
-		 * flow control
-		 */
 		if ((ch->ch_startc == _POSIX_VDISABLE) ||
 		    (ch->ch_stopc == _POSIX_VDISABLE))
 			cls_set_no_input_flow_control(ch);
@@ -883,12 +845,10 @@ static void cls_param(struct tty_struct *tty)
 
 	cls_assert_modem_signals(ch);
 
-	/* Get current status of the modem signals now */
 	cls_parse_modem(ch, readb(&ch->ch_cls_uart->msr));
 }
 
-/* Our board poller function. */
-
+/* Board poller function. */
 static void cls_tasklet(unsigned long data)
 {
 	struct dgnc_board *bd = (struct dgnc_board *)data;
@@ -901,7 +861,6 @@ static void cls_tasklet(unsigned long data)
 	if (!bd || bd->magic != DGNC_BOARD_MAGIC)
 		return;
 
-	/* Cache a couple board values */
 	spin_lock_irqsave(&bd->bd_lock, flags);
 	state = bd->state;
 	ports = bd->nasync;
@@ -913,10 +872,7 @@ static void cls_tasklet(unsigned long data)
 	 */
 	spin_lock_irqsave(&bd->bd_intr_lock, flags);
 
-	/* If board is ready, parse deeper to see if there is anything to do. */
-
 	if ((state == BOARD_READY) && (ports > 0)) {
-		/* Loop on each port */
 		for (i = 0; i < ports; i++) {
 			ch = bd->channels[i];
 
@@ -936,8 +892,6 @@ static void cls_tasklet(unsigned long data)
 			cls_copy_data_from_queue_to_uart(ch);
 			dgnc_wakeup_writes(ch);
 
-			/* Check carrier function. */
-
 			dgnc_carrier(ch);
 
 			/*
@@ -952,11 +906,7 @@ static void cls_tasklet(unsigned long data)
 	spin_unlock_irqrestore(&bd->bd_intr_lock, flags);
 }
 
-/*
- * cls_intr()
- *
- * Classic specific interrupt handler.
- */
+/* Classic specific interrupt handler. */
 static irqreturn_t cls_intr(int irq, void *voidbrd)
 {
 	struct dgnc_board *brd = voidbrd;
@@ -964,33 +914,20 @@ static irqreturn_t cls_intr(int irq, void *voidbrd)
 	unsigned char poll_reg;
 	unsigned long flags;
 
-	/*
-	 * Check to make sure it didn't receive interrupt with a null board
-	 * associated or a board pointer that wasn't ours.
-	 */
 	if (!brd || brd->magic != DGNC_BOARD_MAGIC)
 		return IRQ_NONE;
 
 	spin_lock_irqsave(&brd->bd_intr_lock, flags);
 
-	/*
-	 * Check the board's global interrupt offset to see if we
-	 * we actually do have an interrupt pending for us.
-	 */
 	poll_reg = readb(brd->re_map_membase + UART_CLASSIC_POLL_ADDR_OFFSET);
-
-	/* If 0, no interrupts pending */
 	if (!poll_reg) {
 		spin_unlock_irqrestore(&brd->bd_intr_lock, flags);
 		return IRQ_NONE;
 	}
 
-	/* Parse each port to find out what caused the interrupt */
 	for (i = 0; i < brd->nasync; i++)
 		cls_parse_isr(brd, i);
 
-	/* Schedule tasklet to more in-depth servicing at a better time. */
-
 	tasklet_schedule(&brd->helper_tasklet);
 
 	spin_unlock_irqrestore(&brd->bd_intr_lock, flags);
@@ -1015,7 +952,7 @@ static void cls_enable_receiver(struct channel_t *ch)
 }
 
 /*
- * This function basically goes to sleep for secs, or until
+ * This function basically goes to sleep for seconds, or until
  * it gets signalled that the port has fully drained.
  */
 static int cls_drain(struct tty_struct *tty, uint seconds)
@@ -1069,7 +1006,6 @@ static void cls_send_stop_character(struct channel_t *ch)
 	}
 }
 
-/* Inits UART */
 static void cls_uart_init(struct channel_t *ch)
 {
 	unsigned char lcrb = readb(&ch->ch_cls_uart->lcr);
@@ -1106,18 +1042,14 @@ static void cls_uart_init(struct channel_t *ch)
 	readb(&ch->ch_cls_uart->msr);
 }
 
-/* Turns off UART.  */
-
 static void cls_uart_off(struct channel_t *ch)
 {
 	writeb(0, &ch->ch_cls_uart->ier);
 }
 
 /*
- * cls_get_uarts_bytes_left.
- * Returns 0 is nothing left in the FIFO, returns 1 otherwise.
- *
  * The channel lock MUST be held by the calling function.
+ * Returns 0 is nothing left in the FIFO, returns 1 otherwise.
  */
 static uint cls_get_uart_bytes_left(struct channel_t *ch)
 {
@@ -1143,9 +1075,7 @@ static uint cls_get_uart_bytes_left(struct channel_t *ch)
 }
 
 /*
- * cls_send_break.
  * Starts sending a break thru the UART.
- *
  * The channel lock MUST be held by the calling function.
  */
 static void cls_send_break(struct channel_t *ch, int msecs)
@@ -1154,9 +1084,7 @@ static void cls_send_break(struct channel_t *ch, int msecs)
 		return;
 
 	/* If we receive a time of 0, this means turn off the break. */
-
 	if (msecs == 0) {
-		/* Turn break off, and unset some variables */
 		if (ch->ch_flags & CH_BREAK_SENDING) {
 			unsigned char temp = readb(&ch->ch_cls_uart->lcr);
 
@@ -1184,7 +1112,6 @@ static void cls_send_break(struct channel_t *ch, int msecs)
 }
 
 /*
- * cls_send_immediate_char.
  * Sends a specific character as soon as possible to the UART,
  * jumping over any bytes that might be in the write queue.
  *
@@ -1205,8 +1132,6 @@ static void cls_vpd(struct dgnc_board *brd)
 	int i = 0;
 
 	vpdbase = pci_resource_start(brd->pdev, 3);
-
-	/* No VPD */
 	if (!vpdbase)
 		return;
 
@@ -1215,7 +1140,6 @@ static void cls_vpd(struct dgnc_board *brd)
 	if (!re_map_vpdbase)
 		return;
 
-	/* Store the VPD into our buffer */
 	for (i = 0; i < 0x40; i++) {
 		brd->vpd[i] = readb(re_map_vpdbase + i);
 		pr_info("%x ", brd->vpd[i]);

drivers/staging/dgnc/dgnc_driver.c

@@ -30,8 +30,6 @@ MODULE_AUTHOR("Digi International, http://www.digi.com");
 MODULE_DESCRIPTION("Driver for the Digi International Neo and Classic PCI based product line");
 MODULE_SUPPORTED_DEVICE("dgnc");
 
-/* File operations permitted on Control/Management major. */
-
 static const struct file_operations dgnc_board_fops = {
 	.owner		=	THIS_MODULE,
 	.unlocked_ioctl =	dgnc_mgmt_ioctl,
@@ -39,8 +37,6 @@ static const struct file_operations dgnc_board_fops = {
 	.release	=	dgnc_mgmt_close
 };
 
-/* Globals */
-
 uint			dgnc_num_boards;
 struct dgnc_board		*dgnc_board[MAXBOARDS];
 DEFINE_SPINLOCK(dgnc_global_lock);
@@ -48,12 +44,8 @@ DEFINE_SPINLOCK(dgnc_poll_lock); /* Poll scheduling lock */
 uint			dgnc_major;
 int			dgnc_poll_tick = 20;	/* Poll interval - 20 ms */
 
-/* Static vars. */
-
 static struct class *dgnc_class;
 
-/* Poller stuff */
-
 static ulong		dgnc_poll_time; /* Time of next poll */
 static uint		dgnc_poll_stop; /* Used to tell poller to stop */
 static struct timer_list dgnc_poll_timer;
@@ -95,7 +87,6 @@ static const struct board_id dgnc_ids[] = {
 };
 
 /* Remap PCI memory. */
-
 static int dgnc_do_remap(struct dgnc_board *brd)
 {
 	brd->re_map_membase = ioremap(brd->membase, 0x1000);
@@ -105,11 +96,8 @@ static int dgnc_do_remap(struct dgnc_board *brd)
 	return 0;
 }
 
-/*
- * dgnc_found_board()
- *
- * A board has been found, init it.
- */
+
+/* A board has been found, initialize  it. */
 static struct dgnc_board *dgnc_found_board(struct pci_dev *pdev, int id)
 {
 	struct dgnc_board *brd;
@@ -117,7 +105,6 @@ static struct dgnc_board *dgnc_found_board(struct pci_dev *pdev, int id)
 	int i = 0;
 	int rc = 0;
 
-	/* get the board structure and prep it */
 	brd = kzalloc(sizeof(*brd), GFP_KERNEL);
 	if (!brd)
 		return ERR_PTR(-ENOMEM);
@@ -168,7 +155,6 @@ static struct dgnc_board *dgnc_found_board(struct pci_dev *pdev, int id)
 		 * 4	Memory Mapped UARTs and Status
 		 */
 
-		/* get the PCI Base Address Registers */
 		brd->membase = pci_resource_start(pdev, 4);
 
 		if (!brd->membase) {
@@ -189,7 +175,6 @@ static struct dgnc_board *dgnc_found_board(struct pci_dev *pdev, int id)
 		brd->iobase_end = pci_resource_end(pdev, 1);
 		brd->iobase	= ((unsigned int)(brd->iobase)) & 0xFFFE;
 
-		/* Assign the board_ops struct */
 		brd->bd_ops = &dgnc_cls_ops;
 
 		brd->bd_uart_offset = 0x8;
@@ -234,7 +219,6 @@ static struct dgnc_board *dgnc_found_board(struct pci_dev *pdev, int id)
 		else
 			brd->dpatype = T_NEO | T_PCIBUS;
 
-		/* get the PCI Base Address Registers */
 		brd->membase     = pci_resource_start(pdev, 0);
 		brd->membase_end = pci_resource_end(pdev, 0);
 
@@ -243,7 +227,6 @@ static struct dgnc_board *dgnc_found_board(struct pci_dev *pdev, int id)
 		else
 			brd->membase &= ~15;
 
-		/* Assign the board_ops struct */
 		brd->bd_ops = &dgnc_neo_ops;
 
 		brd->bd_uart_offset = 0x200;
@@ -269,7 +252,6 @@ static struct dgnc_board *dgnc_found_board(struct pci_dev *pdev, int id)
 		goto failed;
 	}
 
-	/* init our poll helper tasklet */
 	tasklet_init(&brd->helper_tasklet,
 		     brd->bd_ops->tasklet,
 		     (unsigned long)brd);
@@ -306,30 +288,12 @@ static void dgnc_free_irq(struct dgnc_board *brd)
 		free_irq(brd->irq, brd);
 }
 
-/*
- * Function:
- *
- *    dgnc_poll_handler
- *
- * Author:
- *
- *    Scott H Kilau
- *
- * Parameters:
- *
- *    dummy -- ignored
- *
- * Return Values:
- *
- *    none
- *
- * Description:
- *
- *    As each timer expires, it determines (a) whether the "transmit"
- *    waiter needs to be woken up, and (b) whether the poller needs to
- *    be rescheduled.
- */
 
+ /*
+  * As each timer expires, it determines (a) whether the "transmit"
+  * waiter needs to be woken up, and (b) whether the poller needs to
+  * be rescheduled.
+  */
 static void dgnc_poll_handler(ulong dummy)
 {
 	struct dgnc_board *brd;
@@ -337,19 +301,16 @@ static void dgnc_poll_handler(ulong dummy)
 	int i;
 	unsigned long new_time;
 
-	/* Go thru each board, kicking off a tasklet for each if needed */
 	for (i = 0; i < dgnc_num_boards; i++) {
 		brd = dgnc_board[i];
 
 		spin_lock_irqsave(&brd->bd_lock, flags);
 
-		/* If board is in a failed state don't schedule a tasklet */
 		if (brd->state == BOARD_FAILED) {
 			spin_unlock_irqrestore(&brd->bd_lock, flags);
 			continue;
 		}
 
-		/* Schedule a poll helper task */
 		tasklet_schedule(&brd->helper_tasklet);
 
 		spin_unlock_irqrestore(&brd->bd_lock, flags);
@@ -379,7 +340,6 @@ static int dgnc_init_one(struct pci_dev *pdev, const struct pci_device_id *ent)
 	int rc;
 	struct dgnc_board *brd;
 
-	/* wake up and enable device */
 	rc = pci_enable_device(pdev);
 	if (rc)
 		return -EIO;
@@ -388,8 +348,6 @@ static int dgnc_init_one(struct pci_dev *pdev, const struct pci_device_id *ent)
 	if (IS_ERR(brd))
 		return PTR_ERR(brd);
 
-	/* Do tty device initialization. */
-
 	rc = dgnc_tty_register(brd);
 	if (rc < 0) {
 		pr_err(DRVSTR ": Can't register tty devices (%d)\n", rc);
@@ -431,24 +389,14 @@ static struct pci_driver dgnc_driver = {
 	.id_table       = dgnc_pci_tbl,
 };
 
-/* Start of driver. */
-
 static int dgnc_start(void)
 {
 	int rc = 0;
 	unsigned long flags;
 	struct device *dev;
 
-	/* make sure timer is initialized before we do anything else */
 	init_timer(&dgnc_poll_timer);
 
-	/*
-	 * Register our base character device into the kernel.
-	 * This allows the download daemon to connect to the downld device
-	 * before any of the boards are init'ed.
-	 *
-	 * Register management/dpa devices
-	 */
 	rc = register_chrdev(0, "dgnc", &dgnc_board_fops);
 	if (rc < 0) {
 		pr_err(DRVSTR ": Can't register dgnc driver device (%d)\n", rc);
@@ -491,11 +439,7 @@ failed_class:
 	return rc;
 }
 
-/*
- * dgnc_cleanup_board()
- *
- * Free all the memory associated with a board
- */
+/* Free all the memory associated with a board */
 static void dgnc_cleanup_board(struct dgnc_board *brd)
 {
 	int i = 0;
@@ -527,7 +471,6 @@ static void dgnc_cleanup_board(struct dgnc_board *brd)
 		brd->re_map_membase = NULL;
 	}
 
-	/* Free all allocated channels structs */
 	for (i = 0; i < MAXPORTS ; i++) {
 		if (brd->channels[i]) {
 			kfree(brd->channels[i]->ch_rqueue);
@@ -567,34 +510,22 @@ static void cleanup(void)
 	}
 }
 
-/*
- * dgnc_cleanup_module()
- *
- * Module unload.  This is where it all ends.
- */
 static void __exit dgnc_cleanup_module(void)
 {
 	cleanup();
 	pci_unregister_driver(&dgnc_driver);
 }
 
-/*
- * init_module()
- *
- * Module load.  This is where it all starts.
- */
 static int __init dgnc_init_module(void)
 {
 	int rc;
 
 	/* Initialize global stuff */
-
 	rc = dgnc_start();
 	if (rc < 0)
 		return rc;
 
 	/* Find and configure all the cards */
-
 	rc = pci_register_driver(&dgnc_driver);
 	if (rc) {
 		pr_warn("WARNING: dgnc driver load failed.  No Digi Neo or Classic boards found.\n");

drivers/staging/dgnc/dgnc_mgmt.c

@@ -20,11 +20,11 @@
 
 #include <linux/kernel.h>
 #include <linux/ctype.h>
-#include <linux/sched.h>	/* For jiffies, task states */
-#include <linux/interrupt.h>	/* For tasklet and interrupt structs/defines */
+#include <linux/sched.h>
+#include <linux/interrupt.h>
 #include <linux/serial_reg.h>
 #include <linux/termios.h>
-#include <linux/uaccess.h>	/* For copy_from_user/copy_to_user */
+#include <linux/uaccess.h>
 
 #include "dgnc_driver.h"
 #include "dgnc_pci.h"
@@ -33,10 +33,8 @@
 /* Our "in use" variables, to enforce 1 open only */
 static int dgnc_mgmt_in_use[MAXMGMTDEVICES];
 
-/*
- * dgnc_mgmt_open()
- *
- * Open the mgmt/downld/dpa device
+/**
+ * dgnc_mgmt_open() - Open the mgmt/downld/dpa device.
  */
 int dgnc_mgmt_open(struct inode *inode, struct file *file)
 {
@@ -46,7 +44,6 @@ int dgnc_mgmt_open(struct inode *inode, struct file *file)
 
 	spin_lock_irqsave(&dgnc_global_lock, flags);
 
-	/* mgmt device */
 	if (minor >= MAXMGMTDEVICES) {
 		rc = -ENXIO;
 		goto out;
@@ -64,10 +61,8 @@ out:
 	return rc;
 }
 
-/*
- * dgnc_mgmt_close()
- *
- * Open the mgmt/dpa device
+/**
+ * dgnc_mgmt_close() - Close the mgmt/dpa device
  */
 int dgnc_mgmt_close(struct inode *inode, struct file *file)
 {
@@ -77,7 +72,6 @@ int dgnc_mgmt_close(struct inode *inode, struct file *file)
 
 	spin_lock_irqsave(&dgnc_global_lock, flags);
 
-	/* mgmt device */
 	if (minor >= MAXMGMTDEVICES) {
 		rc = -ENXIO;
 		goto out;
@@ -90,12 +84,9 @@ out:
 	return rc;
 }
 
-/*
- * dgnc_mgmt_ioctl()
- *
- * ioctl the mgmt/dpa device
+/**
+ * dgnc_mgmt_ioctl() - Ioctl the mgmt/dpa device.
  */
-
 long dgnc_mgmt_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
 {
 	unsigned long flags;
@@ -176,11 +167,9 @@ long dgnc_mgmt_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
 		board = ni.board;
 		channel = ni.channel;
 
-		/* Verify boundaries on board */
 		if (board >= dgnc_num_boards)
 			return -ENODEV;
 
-		/* Verify boundaries on channel */
 		if (channel >= dgnc_board[board]->nasync)
 			return -ENODEV;
 

drivers/staging/dgnc/dgnc_neo.c

@@ -14,15 +14,15 @@
  */
 
 #include <linux/kernel.h>
-#include <linux/sched.h>	/* For jiffies, task states */
-#include <linux/interrupt.h>    /* For tasklet and interrupt structs/defines */
-#include <linux/delay.h>	/* For udelay */
-#include <linux/io.h>		/* For read[bwl]/write[bwl] */
-#include <linux/serial.h>	/* For struct async_serial */
-#include <linux/serial_reg.h>	/* For the various UART offsets */
-
-#include "dgnc_driver.h"	/* Driver main header file */
-#include "dgnc_neo.h"		/* Our header file */
+#include <linux/sched.h>
+#include <linux/interrupt.h>
+#include <linux/delay.h>
+#include <linux/io.h>
+#include <linux/serial.h>
+#include <linux/serial_reg.h>
+
+#include "dgnc_driver.h"
+#include "dgnc_neo.h"
 #include "dgnc_tty.h"
 
 static inline void neo_parse_lsr(struct dgnc_board *brd, uint port);
@@ -358,20 +358,17 @@ static inline void neo_set_new_start_stop_chars(struct channel_t *ch)
 }
 
 /* No locks are assumed to be held when calling this function. */
-
 static inline void neo_clear_break(struct channel_t *ch, int force)
 {
 	unsigned long flags;
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* Bail if we aren't currently sending a break. */
 	if (!ch->ch_stop_sending_break) {
 		spin_unlock_irqrestore(&ch->ch_lock, flags);
 		return;
 	}
 
-	/* Turn break off, and unset some variables */
 	if (ch->ch_flags & CH_BREAK_SENDING) {
 		if (force ||
 		    time_after_eq(jiffies, ch->ch_stop_sending_break)) {
@@ -387,7 +384,6 @@ static inline void neo_clear_break(struct channel_t *ch, int force)
 }
 
 /* Parse the ISR register. */
-
 static inline void neo_parse_isr(struct dgnc_board *brd, uint port)
 {
 	struct channel_t *ch;
@@ -403,7 +399,6 @@ static inline void neo_parse_isr(struct dgnc_board *brd, uint port)
 	while (1) {
 		isr = readb(&ch->ch_neo_uart->isr_fcr);
 
-		/* Bail if no pending interrupt */
 		if (isr & UART_IIR_NO_INT)
 			break;
 
@@ -426,7 +421,6 @@ static inline void neo_parse_isr(struct dgnc_board *brd, uint port)
 		}
 
 		if (isr & UART_IIR_THRI) {
-			/* Transfer data (if any) from Write Queue -> UART. */
 			spin_lock_irqsave(&ch->ch_lock, flags);
 			ch->ch_flags |= (CH_TX_FIFO_EMPTY | CH_TX_FIFO_LWM);
 			spin_unlock_irqrestore(&ch->ch_lock, flags);
@@ -442,10 +436,7 @@ static inline void neo_parse_isr(struct dgnc_board *brd, uint port)
 			 * one it was, so we can suspend or resume data flow.
 			 */
 			if (cause == UART_17158_XON_DETECT) {
-				/*
-				 * Is output stopped right now, if so,
-				 * resume it
-				 */
+				/* resume output if stopped */
 				if (brd->channels[port]->ch_flags & CH_STOP) {
 					spin_lock_irqsave(&ch->ch_lock,
 							  flags);
@@ -504,7 +495,6 @@ static inline void neo_parse_isr(struct dgnc_board *brd, uint port)
 			}
 		}
 
-		/* Parse any modem signal changes */
 		neo_parse_modem(ch, readb(&ch->ch_neo_uart->msr));
 	}
 }
@@ -515,10 +505,6 @@ static inline void neo_parse_lsr(struct dgnc_board *brd, uint port)
 	int linestatus;
 	unsigned long flags;
 
-	/*
-	 * Check to make sure it didn't receive interrupt with a null board
-	 * associated or a board pointer that wasn't ours.
-	 */
 	if (!brd || brd->magic != DGNC_BOARD_MAGIC)
 		return;
 
@@ -534,7 +520,6 @@ static inline void neo_parse_lsr(struct dgnc_board *brd, uint port)
 	ch->ch_cached_lsr |= linestatus;
 
 	if (ch->ch_cached_lsr & UART_LSR_DR) {
-		/* Read data from uart -> queue */
 		neo_copy_data_from_uart_to_queue(ch);
 		spin_lock_irqsave(&ch->ch_lock, flags);
 		dgnc_check_queue_flow_control(ch);
@@ -571,22 +556,17 @@ static inline void neo_parse_lsr(struct dgnc_board *brd, uint port)
 		ch->ch_flags |= (CH_TX_FIFO_EMPTY | CH_TX_FIFO_LWM);
 		spin_unlock_irqrestore(&ch->ch_lock, flags);
 
-		/* Transfer data (if any) from Write Queue -> UART. */
 		neo_copy_data_from_queue_to_uart(ch);
 	} else if (linestatus & UART_17158_TX_AND_FIFO_CLR) {
 		spin_lock_irqsave(&ch->ch_lock, flags);
 		ch->ch_flags |= (CH_TX_FIFO_EMPTY | CH_TX_FIFO_LWM);
 		spin_unlock_irqrestore(&ch->ch_lock, flags);
 
-		/* Transfer data (if any) from Write Queue -> UART. */
 		neo_copy_data_from_queue_to_uart(ch);
 	}
 }
 
-/*
- * neo_param()
- * Send any/all changes to the line to the UART.
- */
+/* Send any/all changes to the line to the UART. */
 static void neo_param(struct tty_struct *tty)
 {
 	unsigned char lcr = 0;
@@ -615,7 +595,6 @@ static void neo_param(struct tty_struct *tty)
 		return;
 
 	/* If baud rate is zero, flush queues, and set mval to drop DTR. */
-
 	if ((ch->ch_c_cflag & (CBAUD)) == 0) {
 		ch->ch_r_head = 0;
 		ch->ch_r_tail = 0;
@@ -724,10 +703,6 @@ static void neo_param(struct tty_struct *tty)
 	if (!(ch->ch_c_cflag & PARODD))
 		lcr |= UART_LCR_EPAR;
 
-	/*
-	 * Not all platforms support mark/space parity,
-	 * so this will hide behind an ifdef.
-	 */
 #ifdef CMSPAR
 	if (ch->ch_c_cflag & CMSPAR)
 		lcr |= UART_LCR_SPAR;
@@ -796,16 +771,11 @@ static void neo_param(struct tty_struct *tty)
 	if (ier != uart_ier)
 		writeb(ier, &ch->ch_neo_uart->ier);
 
-	/* Set new start/stop chars */
 	neo_set_new_start_stop_chars(ch);
 
 	if (ch->ch_digi.digi_flags & CTSPACE || ch->ch_c_cflag & CRTSCTS) {
 		neo_set_cts_flow_control(ch);
 	} else if (ch->ch_c_iflag & IXON) {
-		/*
-		 * If start/stop is set to disable, then we should
-		 * disable flow control
-		 */
 		if ((ch->ch_startc == _POSIX_VDISABLE) ||
 		    (ch->ch_stopc == _POSIX_VDISABLE))
 			neo_set_no_output_flow_control(ch);
@@ -818,10 +788,6 @@ static void neo_param(struct tty_struct *tty)
 	if (ch->ch_digi.digi_flags & RTSPACE || ch->ch_c_cflag & CRTSCTS) {
 		neo_set_rts_flow_control(ch);
 	} else if (ch->ch_c_iflag & IXOFF) {
-		/*
-		 * If start/stop is set to disable, then we should
-		 * disable flow control
-		 */
 		if ((ch->ch_startc == _POSIX_VDISABLE) ||
 		    (ch->ch_stopc == _POSIX_VDISABLE))
 			neo_set_no_input_flow_control(ch);
@@ -843,12 +809,10 @@ static void neo_param(struct tty_struct *tty)
 
 	neo_assert_modem_signals(ch);
 
-	/* Get current status of the modem signals now */
 	neo_parse_modem(ch, readb(&ch->ch_neo_uart->msr));
 }
 
-/* Our board poller function. */
-
+/* Board poller function. */
 static void neo_tasklet(unsigned long data)
 {
 	struct dgnc_board *bd = (struct dgnc_board *)data;
@@ -861,7 +825,6 @@ static void neo_tasklet(unsigned long data)
 	if (!bd || bd->magic != DGNC_BOARD_MAGIC)
 		return;
 
-	/* Cache a couple board values */
 	spin_lock_irqsave(&bd->bd_lock, flags);
 	state = bd->state;
 	ports = bd->nasync;
@@ -873,10 +836,7 @@ static void neo_tasklet(unsigned long data)
 	 */
 	spin_lock_irqsave(&bd->bd_intr_lock, flags);
 
-	/* If board is ready, parse deeper to see if there is anything to do. */
-
 	if ((state == BOARD_READY) && (ports > 0)) {
-		/* Loop on each port */
 		for (i = 0; i < ports; i++) {
 			ch = bd->channels[i];
 
@@ -903,10 +863,6 @@ static void neo_tasklet(unsigned long data)
 			neo_copy_data_from_queue_to_uart(ch);
 			dgnc_wakeup_writes(ch);
 
-			/*
-			 * Call carrier carrier function, in case something
-			 * has changed.
-			 */
 			dgnc_carrier(ch);
 
 			/*
@@ -918,15 +874,10 @@ static void neo_tasklet(unsigned long data)
 		}
 	}
 
-	/* Allow interrupt routine to access the interrupt register again */
 	spin_unlock_irqrestore(&bd->bd_intr_lock, flags);
 }
 
-/*
- * dgnc_neo_intr()
- *
- * Neo specific interrupt handler.
- */
+/* Neo specific interrupt handler. */
 static irqreturn_t neo_intr(int irq, void *voidbrd)
 {
 	struct dgnc_board *brd = voidbrd;
@@ -937,10 +888,6 @@ static irqreturn_t neo_intr(int irq, void *voidbrd)
 	unsigned long flags;
 	unsigned long flags2;
 
-	/*
-	 * Check to make sure it didn't receive interrupt with a null board
-	 * associated or a board pointer that wasn't ours.
-	 */
 	if (!brd || brd->magic != DGNC_BOARD_MAGIC)
 		return IRQ_NONE;
 
@@ -964,19 +911,12 @@ static irqreturn_t neo_intr(int irq, void *voidbrd)
 		return IRQ_NONE;
 	}
 
-	/*
-	 * At this point, we have at least SOMETHING to service, dig
-	 * further...
-	 */
-
-	/* Loop on each port */
 	while ((uart_poll & 0xff) != 0) {
 		type = uart_poll >> (8 + (port * 3));
 		type &= 0x7;
 
 		uart_poll &= ~(0x01 << port);
 
-		/* Switch on type of interrupt we have */
 		switch (type) {
 		case UART_17158_RXRDY_TIMEOUT:
 			/*
@@ -984,7 +924,6 @@ static irqreturn_t neo_intr(int irq, void *voidbrd)
 			 * RX FIFO until it falls below the trigger level.
 			 */
 
-			/* Verify the port is in range. */
 			if (port >= brd->nasync)
 				break;
 
@@ -1027,27 +966,17 @@ static irqreturn_t neo_intr(int irq, void *voidbrd)
 			break;
 
 		case UART_17158_MSR:
-
 			/* MSR or flow control was seen. */
-
 			neo_parse_isr(brd, port);
 			break;
 
 		default:
-			/*
-			 * The UART triggered us with a bogus interrupt type.
-			 * It appears the Exar chip, when REALLY bogged down,
-			 * will throw these once and awhile.
-			 * Its harmless, just ignore it and move on.
-			 */
 			break;
 		}
 
 		port++;
 	}
 
-	/* Schedule tasklet to more in-depth servicing at a better time. */
-
 	tasklet_schedule(&brd->helper_tasklet);
 
 	spin_unlock_irqrestore(&brd->bd_intr_lock, flags);
@@ -1099,27 +1028,18 @@ static void neo_copy_data_from_uart_to_queue(struct channel_t *ch)
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* cache head and tail of queue */
 	head = ch->ch_r_head & RQUEUEMASK;
 	tail = ch->ch_r_tail & RQUEUEMASK;
 
-	/* Get our cached LSR */
 	linestatus = ch->ch_cached_lsr;
 	ch->ch_cached_lsr = 0;
 
-	/* Store how much space we have left in the queue */
 	qleft = tail - head - 1;
 	if (qleft < 0)
 		qleft += RQUEUEMASK + 1;
 
-	/*
-	 * If the UART is not in FIFO mode, force the FIFO copy to
-	 * NOT be run, by setting total to 0.
-	 *
-	 * On the other hand, if the UART IS in FIFO mode, then ask
-	 * the UART to give us an approximation of data it has RX'ed.
-	 */
 	if (!(ch->ch_flags & CH_FIFO_ENABLED)) {
+		/* force the FIFO copy to NOT be run */
 		total = 0;
 	} else {
 		total = readb(&ch->ch_neo_uart->rfifo);
@@ -1138,26 +1058,11 @@ static void neo_copy_data_from_uart_to_queue(struct channel_t *ch)
 			total -= 3;
 	}
 
-	/*
-	 * Finally, bound the copy to make sure we don't overflow
-	 * our own queue...
-	 * The byte by byte copy loop below this loop this will
-	 * deal with the queue overflow possibility.
-	 */
 	total = min(total, qleft);
 
 	while (total > 0) {
-		/*
-		 * Grab the linestatus register, we need to check
-		 * to see if there are any errors in the FIFO.
-		 */
 		linestatus = readb(&ch->ch_neo_uart->lsr);
 
-		/*
-		 * Break out if there is a FIFO error somewhere.
-		 * This will allow us to go byte by byte down below,
-		 * finding the exact location of the error.
-		 */
 		if (linestatus & UART_17158_RX_FIFO_DATA_ERROR)
 			break;
 
@@ -1182,7 +1087,6 @@ static void neo_copy_data_from_uart_to_queue(struct channel_t *ch)
 
 		linestatus = 0;
 
-		/* Copy data from uart to the queue */
 		memcpy_fromio(ch->ch_rqueue + head,
 			      &ch->ch_neo_uart->txrxburst, n);
 
@@ -1193,7 +1097,6 @@ static void neo_copy_data_from_uart_to_queue(struct channel_t *ch)
 		 */
 		memset(ch->ch_equeue + head, 0, n);
 
-		/* Add to and flip head if needed */
 		head = (head + n) & RQUEUEMASK;
 		total -= n;
 		qleft -= n;
@@ -1242,8 +1145,6 @@ static void neo_copy_data_from_uart_to_queue(struct channel_t *ch)
 			ch->ch_flags |= (CH_TX_FIFO_EMPTY | CH_TX_FIFO_LWM);
 		}
 
-		/* Discard character if we are ignoring the error mask. */
-
 		if (linestatus & error_mask)  {
 			unsigned char discard;
 
@@ -1253,13 +1154,10 @@ static void neo_copy_data_from_uart_to_queue(struct channel_t *ch)
 		}
 
 		/*
-		 * If our queue is full, we have no choice but to drop some
-		 * data.
-		 * The assumption is that HWFLOW or SWFLOW should have stopped
-		 * things way way before we got to this point.
-		 *
-		 * I decided that I wanted to ditch the oldest data first,
-		 * I hope thats okay with everyone? Yes? Good.
+		 * If our queue is full, we have no choice but to drop
+		 * some data. The assumption is that HWFLOW or SWFLOW
+		 * should have stopped things way way before we got to
+		 * this point.
 		 */
 		while (qleft < 1) {
 			tail = (tail + 1) & RQUEUEMASK;
@@ -1272,18 +1170,14 @@ static void neo_copy_data_from_uart_to_queue(struct channel_t *ch)
 			      &ch->ch_neo_uart->txrxburst, 1);
 		ch->ch_equeue[head] = (unsigned char)linestatus;
 
-		/* Ditch any remaining linestatus value. */
 		linestatus = 0;
 
-		/* Add to and flip head if needed */
 		head = (head + 1) & RQUEUEMASK;
 
 		qleft--;
 		ch->ch_rxcount++;
 	}
 
-	/* Write new final heads to channel structure. */
-
 	ch->ch_r_head = head & RQUEUEMASK;
 	ch->ch_e_head = head & EQUEUEMASK;
 
@@ -1316,10 +1210,6 @@ static int neo_drain(struct tty_struct *tty, uint seconds)
 	un->un_flags |= UN_EMPTY;
 	spin_unlock_irqrestore(&ch->ch_lock, flags);
 
-	/*
-	 * Go to sleep waiting for the tty layer to wake me back up when
-	 * the empty flag goes away.
-	 */
 	rc = wait_event_interruptible_timeout(un->un_flags_wait,
 					      ((un->un_flags & UN_EMPTY) == 0),
 					      msecs_to_jiffies(seconds * 1000));
@@ -1330,8 +1220,7 @@ static int neo_drain(struct tty_struct *tty, uint seconds)
 
 /*
  * Flush the WRITE FIFO on the Neo.
- *
- * NOTE: Channel lock MUST be held before calling this function!
+ * Channel lock MUST be held before calling this function!
  */
 static void neo_flush_uart_write(struct channel_t *ch)
 {
@@ -1347,7 +1236,7 @@ static void neo_flush_uart_write(struct channel_t *ch)
 
 	for (i = 0; i < 10; i++) {
 		/*
-		 * Check to see if the UART feels it completely flushed the
+		 * Check to see if the UART completely flushed the FIFO
 		 * FIFO.
 		 */
 		tmp = readb(&ch->ch_neo_uart->isr_fcr);
@@ -1362,8 +1251,7 @@ static void neo_flush_uart_write(struct channel_t *ch)
 
 /*
  * Flush the READ FIFO on the Neo.
- *
- * NOTE: Channel lock MUST be held before calling this function!
+ * Channel lock MUST be held before calling this function!
  */
 static void neo_flush_uart_read(struct channel_t *ch)
 {
@@ -1405,7 +1293,6 @@ static void neo_copy_data_from_queue_to_uart(struct channel_t *ch)
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* No data to write to the UART */
 	if (ch->ch_w_tail == ch->ch_w_head)
 		goto exit_unlock;
 
@@ -1414,12 +1301,10 @@ static void neo_copy_data_from_queue_to_uart(struct channel_t *ch)
 	    (ch->ch_flags & CH_BREAK_SENDING))
 		goto exit_unlock;
 
-	/* If FIFOs are disabled. Send data directly to txrx register */
-
 	if (!(ch->ch_flags & CH_FIFO_ENABLED)) {
+		/* Send data directly to txrx register */
 		unsigned char lsrbits = readb(&ch->ch_neo_uart->lsr);
 
-		/* Cache the LSR bits for later parsing */
 		ch->ch_cached_lsr |= lsrbits;
 		if (ch->ch_cached_lsr & UART_LSR_THRE) {
 			ch->ch_cached_lsr &= ~(UART_LSR_THRE);
@@ -1477,12 +1362,10 @@ static void neo_copy_data_from_queue_to_uart(struct channel_t *ch)
 		n = UART_17158_TX_FIFOSIZE - readb(&ch->ch_neo_uart->tfifo);
 	}
 
-	/* cache head and tail of queue */
 	head = ch->ch_w_head & WQUEUEMASK;
 	tail = ch->ch_w_tail & WQUEUEMASK;
 	qlen = (head - tail) & WQUEUEMASK;
 
-	/* Find minimum of the FIFO space, versus queue length */
 	n = min(n, qlen);
 
 	while (n > 0) {
@@ -1521,14 +1404,12 @@ static void neo_copy_data_from_queue_to_uart(struct channel_t *ch)
 		memcpy_toio(&ch->ch_neo_uart->txrxburst,
 			    ch->ch_wqueue + tail, s);
 
-		/* Add and flip queue if needed */
 		tail = (tail + s) & WQUEUEMASK;
 		n -= s;
 		ch->ch_txcount += s;
 		len_written += s;
 	}
 
-	/* Update the final tail */
 	ch->ch_w_tail = tail & WQUEUEMASK;
 
 	if (len_written > 0) {
@@ -1572,10 +1453,7 @@ static void neo_parse_modem(struct channel_t *ch, unsigned char signals)
 		}
 	}
 
-	/*
-	 * Scrub off lower bits. They signify delta's, which I don't care
-	 * about
-	 */
+	/* Scrub off lower bits. They signify delta's */
 	msignals &= 0xf0;
 
 	if (msignals & UART_MSR_DCD)
@@ -1668,7 +1546,6 @@ static void neo_uart_init(struct channel_t *ch)
 }
 
 /* Make the UART completely turn off. */
-
 static void neo_uart_off(struct channel_t *ch)
 {
 	/* Turn off UART enhanced bits */
@@ -1735,8 +1612,6 @@ static void neo_send_break(struct channel_t *ch, int msecs)
 }
 
 /*
- * neo_send_immediate_char.
- *
  * Sends a specific character as soon as possible to the UART,
  * jumping over any bytes that might be in the write queue.
  *

drivers/staging/dgnc/dgnc_tty.c

@@ -59,15 +59,14 @@ static const struct digi_t dgnc_digi_init = {
  * 1 stop bit.
  */
 static const struct ktermios default_termios = {
-	.c_iflag =	(DEFAULT_IFLAGS),	/* iflags */
-	.c_oflag =	(DEFAULT_OFLAGS),	/* oflags */
-	.c_cflag =	(DEFAULT_CFLAGS),	/* cflags */
-	.c_lflag =	(DEFAULT_LFLAGS),	/* lflags */
+	.c_iflag =	(DEFAULT_IFLAGS),
+	.c_oflag =	(DEFAULT_OFLAGS),
+	.c_cflag =	(DEFAULT_CFLAGS),
+	.c_lflag =	(DEFAULT_LFLAGS),
 	.c_cc =		INIT_C_CC,
 	.c_line =	0,
 };
 
-/* Our function prototypes */
 static int dgnc_tty_open(struct tty_struct *tty, struct file *file);
 static void dgnc_tty_close(struct tty_struct *tty, struct file *file);
 static int dgnc_block_til_ready(struct tty_struct *tty, struct file *file,
@@ -130,10 +129,8 @@ static const struct tty_operations dgnc_tty_ops = {
 
 /* TTY Initialization/Cleanup Functions */
 
-/*
- * dgnc_tty_register()
- *
- * Init the tty subsystem for this board.
+/**
+ * dgnc_tty_register() - Init the tty subsystem for this board.
  */
 int dgnc_tty_register(struct dgnc_board *brd)
 {
@@ -230,11 +227,10 @@ void dgnc_tty_unregister(struct dgnc_board *brd)
 	put_tty_driver(brd->serial_driver);
 }
 
-/*
- * dgnc_tty_init()
+/**
+ * dgnc_tty_init() - Initialize the tty subsystem.
  *
- * Init the tty subsystem.  Called once per board after board has been
- * downloaded and init'ed.
+ * Called once per board after board has been downloaded and initialized.
  */
 int dgnc_tty_init(struct dgnc_board *brd)
 {
@@ -253,10 +249,6 @@ int dgnc_tty_init(struct dgnc_board *brd)
 	brd->nasync = brd->maxports;
 
 	for (i = 0; i < brd->nasync; i++) {
-		/*
-		 * Okay to malloc with GFP_KERNEL, we are not at
-		 * interrupt context, and there are no locks held.
-		 */
 		brd->channels[i] = kzalloc(sizeof(*brd->channels[i]),
 					   GFP_KERNEL);
 		if (!brd->channels[i]) {
@@ -324,8 +316,8 @@ err_free_channels:
 	return rc;
 }
 
-/*
- * dgnc_cleanup_tty()
+/**
+ * dgnc_cleanup_tty() - Cleanup driver.
  *
  * Uninitialize the TTY portion of this driver.  Free all memory and
  * resources.
@@ -348,12 +340,11 @@ void dgnc_cleanup_tty(struct dgnc_board *brd)
 	put_tty_driver(brd->print_driver);
 }
 
-/*
- *	dgnc_wmove - Write data to transmit queue.
- *
- *		ch	- Pointer to channel structure.
- *		buf	- Pointer to characters to be moved.
- *		n	- Number of characters to move.
+/**
+ * dgnc_wmove() - Write data to transmit queue.
+ * @ch: Pointer to channel structure.
+ * @buf: Pointer to characters to be moved.
+ * @n: Number of characters to move.
  */
 static void dgnc_wmove(struct channel_t *ch, char *buf, uint n)
 {
@@ -390,10 +381,9 @@ static void dgnc_wmove(struct channel_t *ch, char *buf, uint n)
 	ch->ch_w_head = head;
 }
 
-/*
- *      dgnc_input - Process received data.
- *
- *	      ch      - Pointer to channel structure.
+/**
+ * dgnc_input() - Process received data.
+ * @ch: Pointer to channel structure.
  */
 void dgnc_input(struct channel_t *ch)
 {
@@ -422,10 +412,6 @@ void dgnc_input(struct channel_t *ch)
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/*
-	 *      Figure the number of characters in the buffer.
-	 *      Exit immediately if none.
-	 */
 	rmask = RQUEUEMASK;
 	head = ch->ch_r_head & rmask;
 	tail = ch->ch_r_tail & rmask;
@@ -450,32 +436,18 @@ void dgnc_input(struct channel_t *ch)
 		goto exit_unlock;
 	}
 
-	/* If we are throttled, simply don't read any data. */
-
 	if (ch->ch_flags & CH_FORCED_STOPI)
 		goto exit_unlock;
 
 	flip_len = TTY_FLIPBUF_SIZE;
 
-	/* Chop down the length, if needed */
 	len = min(data_len, flip_len);
 	len = min(len, (N_TTY_BUF_SIZE - 1));
 
 	ld = tty_ldisc_ref(tp);
-
-	/*
-	 * If we were unable to get a reference to the ld,
-	 * don't flush our buffer, and act like the ld doesn't
-	 * have any space to put the data right now.
-	 */
 	if (!ld) {
 		len = 0;
 	} else {
-		/*
-		 * If ld doesn't have a pointer to a receive_buf function,
-		 * flush the data, then act like the ld doesn't have any
-		 * space to put the data right now.
-		 */
 		if (!ld->ops->receive_buf) {
 			ch->ch_r_head = ch->ch_r_tail;
 			len = 0;
@@ -564,7 +536,9 @@ exit_unlock:
 		tty_ldisc_deref(ld);
 }
 
-/*
+/**
+ * dgnc_carrier()
+ *
  * Determines when CARRIER changes state and takes appropriate
  * action.
  */
@@ -654,7 +628,6 @@ void dgnc_carrier(struct channel_t *ch)
 }
 
 /*  Assign the custom baud rate to the channel structure */
-
 static void dgnc_set_custom_speed(struct channel_t *ch, uint newrate)
 {
 	int testdiv;
@@ -718,7 +691,6 @@ void dgnc_check_queue_flow_control(struct channel_t *ch)
 {
 	int qleft;
 
-	/* Store how much space we have left in the queue */
 	qleft = ch->ch_r_tail - ch->ch_r_head - 1;
 	if (qleft < 0)
 		qleft += RQUEUEMASK + 1;
@@ -885,8 +857,6 @@ static struct dgnc_board *find_board_by_major(unsigned int major)
 
 /* TTY Entry points and helper functions */
 
-/* dgnc_tty_open() */
-
 static int dgnc_tty_open(struct tty_struct *tty, struct file *file)
 {
 	struct dgnc_board	*brd;
@@ -905,15 +875,10 @@ static int dgnc_tty_open(struct tty_struct *tty, struct file *file)
 	if (major > 255)
 		return -ENXIO;
 
-	/* Get board pointer from our array of majors we have allocated */
 	brd = find_board_by_major(major);
 	if (!brd)
 		return -ENXIO;
 
-	/*
-	 * If board is not yet up to a state of READY, go to
-	 * sleep waiting for it to happen or they cancel the open.
-	 */
 	rc = wait_event_interruptible(brd->state_wait,
 				      (brd->state & BOARD_READY));
 	if (rc)
@@ -921,7 +886,6 @@ static int dgnc_tty_open(struct tty_struct *tty, struct file *file)
 
 	spin_lock_irqsave(&brd->bd_lock, flags);
 
-	/* If opened device is greater than our number of ports, bail. */
 	if (PORT_NUM(minor) >= brd->nasync) {
 		rc = -ENXIO;
 		goto err_brd_unlock;
@@ -933,10 +897,8 @@ static int dgnc_tty_open(struct tty_struct *tty, struct file *file)
 		goto err_brd_unlock;
 	}
 
-	/* Drop board lock */
 	spin_unlock_irqrestore(&brd->bd_lock, flags);
 
-	/* Grab channel lock */
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
 	/* Figure out our type */
@@ -981,14 +943,12 @@ static int dgnc_tty_open(struct tty_struct *tty, struct file *file)
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* Store our unit into driver_data, so we always have it available. */
 	tty->driver_data = un;
 
 	/* Initialize tty's */
 
 	if (!(un->un_flags & UN_ISOPEN)) {
-		/* Store important variables. */
-		un->un_tty     = tty;
+		un->un_tty = tty;
 
 		/* Maybe do something here to the TTY struct as well? */
 	}
@@ -999,7 +959,6 @@ static int dgnc_tty_open(struct tty_struct *tty, struct file *file)
 	 */
 	ch->ch_flags |= (CH_OPENING);
 
-	/* Drop locks, as malloc with GFP_KERNEL can sleep */
 	spin_unlock_irqrestore(&ch->ch_lock, flags);
 
 	if (!ch->ch_rqueue)
@@ -1060,19 +1019,14 @@ static int dgnc_tty_open(struct tty_struct *tty, struct file *file)
 		brd->bd_ops->uart_init(ch);
 	}
 
-	/* Run param in case we changed anything */
-
 	brd->bd_ops->param(tty);
 
 	dgnc_carrier(ch);
 
-	/* follow protocol for opening port */
-
 	spin_unlock_irqrestore(&ch->ch_lock, flags);
 
 	rc = dgnc_block_til_ready(tty, file, ch);
 
-	/* No going back now, increment our unit and channel counters */
 	spin_lock_irqsave(&ch->ch_lock, flags);
 	ch->ch_open_count++;
 	un->un_open_count++;
@@ -1091,11 +1045,7 @@ err_ch_unlock:
 	return rc;
 }
 
-/*
- * dgnc_block_til_ready()
- *
- * Wait for DCD, if needed.
- */
+/* Wait for DCD, if needed. */
 static int dgnc_block_til_ready(struct tty_struct *tty,
 				struct file *file,
 				struct channel_t *ch)
@@ -1113,20 +1063,14 @@ static int dgnc_block_til_ready(struct tty_struct *tty,
 
 	ch->ch_wopen++;
 
-	/* Loop forever */
 	while (1) {
 		sleep_on_un_flags = 0;
 
-		/*
-		 * If board has failed somehow during our sleep,
-		 * bail with error.
-		 */
 		if (ch->ch_bd->state == BOARD_FAILED) {
 			rc = -ENXIO;
 			break;
 		}
 
-		/* If tty was hung up, break out of loop and set error. */
 		if (tty_hung_up_p(file)) {
 			rc = -EAGAIN;
 			break;
@@ -1169,15 +1113,12 @@ static int dgnc_block_til_ready(struct tty_struct *tty,
 		/*
 		 * If there is a signal pending, the user probably
 		 * interrupted (ctrl-c) us.
-		 * Leave loop with error set.
 		 */
 		if (signal_pending(current)) {
 			rc = -ERESTARTSYS;
 			break;
 		}
 
-		/* Store the flags before we let go of channel lock */
-
 		if (sleep_on_un_flags)
 			old_flags = ch->ch_tun.un_flags | ch->ch_pun.un_flags;
 		else
@@ -1219,11 +1160,7 @@ static int dgnc_block_til_ready(struct tty_struct *tty,
 	return rc;
 }
 
-/*
- * dgnc_tty_hangup()
- *
- * Hangup the port.  Like a close, but don't wait for output to drain.
- */
+/* Hangup the port.  Like a close, but don't wait for output to drain. */
 static void dgnc_tty_hangup(struct tty_struct *tty)
 {
 	if (!tty || tty->magic != TTY_MAGIC)
@@ -1233,8 +1170,6 @@ static void dgnc_tty_hangup(struct tty_struct *tty)
 	dgnc_tty_flush_buffer(tty);
 }
 
-/* dgnc_tty_close() */
-
 static void dgnc_tty_close(struct tty_struct *tty, struct file *file)
 {
 	struct dgnc_board *bd;
@@ -1368,8 +1303,6 @@ static void dgnc_tty_close(struct tty_struct *tty, struct file *file)
 }
 
 /*
- * dgnc_tty_chars_in_buffer()
- *
  * Return number of characters that have not been transmitted yet.
  *
  * This routine is used by the line discipline to determine if there
@@ -1415,8 +1348,6 @@ static int dgnc_tty_chars_in_buffer(struct tty_struct *tty)
 }
 
 /*
- * dgnc_maxcps_room
- *
  * Reduces bytes_available to the max number of characters
  * that can be sent currently given the maxcps value, and
  * returns the new bytes_available.  This only affects printer
@@ -1452,11 +1383,7 @@ static int dgnc_maxcps_room(struct channel_t *ch, int bytes_available)
 	return rc;
 }
 
-/*
- * dgnc_tty_write_room()
- *
- * Return room available in Tx buffer
- */
+/* Return room available in Tx buffer */
 static int dgnc_tty_write_room(struct tty_struct *tty)
 {
 	struct channel_t *ch = NULL;
@@ -1513,23 +1440,16 @@ static int dgnc_tty_write_room(struct tty_struct *tty)
 }
 
 /*
- * dgnc_tty_put_char()
- *
  * Put a character into ch->ch_buf
- *
- *      - used by the line discipline for OPOST processing
+ * Used by the line discipline for OPOST processing
  */
 static int dgnc_tty_put_char(struct tty_struct *tty, unsigned char c)
 {
-	/* Simply call tty_write. */
-
 	dgnc_tty_write(tty, &c, 1);
 	return 1;
 }
 
 /*
- * dgnc_tty_write()
- *
  * Take data from the user or kernel and send it out to the FEP.
  * In here exists all the Transparent Print magic as well.
  */
@@ -1567,7 +1487,6 @@ static int dgnc_tty_write(struct tty_struct *tty,
 
 	spin_lock_irqsave(&ch->ch_lock, flags);
 
-	/* Get our space available for the channel from the board */
 	tmask = WQUEUEMASK;
 	head = (ch->ch_w_head) & tmask;
 	tail = (ch->ch_w_tail) & tmask;
@@ -1583,14 +1502,7 @@ static int dgnc_tty_write(struct tty_struct *tty,
 	if (un->un_type != DGNC_PRINT)
 		bufcount = dgnc_maxcps_room(ch, bufcount);
 
-	/*
-	 * Take minimum of what the user wants to send, and the
-	 * space available in the FEP buffer.
-	 */
 	count = min(count, bufcount);
-
-	/* Bail if no space left. */
-
 	if (count <= 0)
 		goto exit_retry;
 
@@ -1652,13 +1564,8 @@ static int dgnc_tty_write(struct tty_struct *tty,
 
 	spin_unlock_irqrestore(&ch->ch_lock, flags);
 
-	if (count) {
-		/*
-		 * Channel lock is grabbed and then released
-		 * inside this routine.
-		 */
+	if (count)
 		ch->ch_bd->bd_ops->copy_data_from_queue_to_uart(ch);
-	}
 
 	return count;
 
@@ -1669,7 +1576,6 @@ exit_retry:
 }
 
 /* Return modem signals to ld. */
-
 static int dgnc_tty_tiocmget(struct tty_struct *tty)
 {
 	struct channel_t *ch;
@@ -1713,12 +1619,7 @@ static int dgnc_tty_tiocmget(struct tty_struct *tty)
 	return rc;
 }
 
-/*
- * dgnc_tty_tiocmset()
- *
- * Set modem signals, called by ld.
- */
-
+/* Set modem signals, called by ld. */
 static int dgnc_tty_tiocmset(struct tty_struct *tty,
 			     unsigned int set, unsigned int clear)
 {
@@ -1763,11 +1664,7 @@ static int dgnc_tty_tiocmset(struct tty_struct *tty,
 	return 0;
 }
 
-/*
- * dgnc_tty_send_break()
- *
- * Send a Break, called by ld.
- */
+/* Send a Break, called by ld. */
 static int dgnc_tty_send_break(struct tty_struct *tty, int msec)
 {
 	struct dgnc_board *bd;
@@ -1802,11 +1699,7 @@ static int dgnc_tty_send_break(struct tty_struct *tty, int msec)
 	return 0;
 }
 
-/*
- * dgnc_tty_wait_until_sent()
- *
- * wait until data has been transmitted, called by ld.
- */
+/* wait until data has been transmitted, called by ld. */
 static void dgnc_tty_wait_until_sent(struct tty_struct *tty, int timeout)
 {
 	struct dgnc_board *bd;
@@ -1831,11 +1724,7 @@ static void dgnc_tty_wait_until_sent(struct tty_struct *tty, int timeout)
 	bd->bd_ops->drain(tty, 0);
 }
 
-/*
- * dgnc_send_xchar()
- *
- * send a high priority character, called by ld.
- */
+/* send a high priority character, called by ld. */
 static void dgnc_tty_send_xchar(struct tty_struct *tty, char c)
 {
 	struct dgnc_board *bd;
@@ -1864,7 +1753,6 @@ static void dgnc_tty_send_xchar(struct tty_struct *tty, char c)
 }
 
 /* Return modem signals to ld. */
-
 static inline int dgnc_get_mstat(struct channel_t *ch)
 {
 	unsigned char mstat;
@@ -1899,18 +1787,13 @@ static inline int dgnc_get_mstat(struct channel_t *ch)
 }
 
 /* Return modem signals to ld. */
-
 static int dgnc_get_modem_info(struct channel_t *ch,
 			       unsigned int  __user *value)
 {
 	return put_user(dgnc_get_mstat(ch), value);
 }
 
-/*
- * dgnc_set_modem_info()
- *
- * Set modem signals, called by ld.
- */
+/* Set modem signals, called by ld. */
 static int dgnc_set_modem_info(struct channel_t *ch,
 			       unsigned int command,
 			       unsigned int __user *value)
@@ -1969,11 +1852,7 @@ static int dgnc_set_modem_info(struct channel_t *ch,
 	return 0;
 }
 
-/*
- * dgnc_tty_digigeta()
- *
- * Ioctl to get the information for ditty.
- */
+/* Ioctl to get the information for ditty. */
 static int dgnc_tty_digigeta(struct tty_struct *tty,
 			     struct digi_t __user *retinfo)
 {
@@ -2008,11 +1887,7 @@ static int dgnc_tty_digigeta(struct tty_struct *tty,
 	return 0;
 }
 
-/*
- * dgnc_tty_digiseta()
- *
- * Ioctl to set the information for ditty.
- */
+/* Ioctl to set the information for ditty. */
 static int dgnc_tty_digiseta(struct tty_struct *tty,
 			     struct digi_t __user *new_info)
 {
@@ -2090,8 +1965,6 @@ static int dgnc_tty_digiseta(struct tty_struct *tty,
 	return 0;
 }
 
-/* dgnc_set_termios() */
-
 static void dgnc_tty_set_termios(struct tty_struct *tty,
 				 struct ktermios *old_termios)
 {
@@ -2237,8 +2110,6 @@ static void dgnc_tty_stop(struct tty_struct *tty)
 }
 
 /*
- * dgnc_tty_flush_chars()
- *
  * Flush the cook buffer
  *
  * Note to self, and any other poor souls who venture here:
@@ -2278,11 +2149,7 @@ static void dgnc_tty_flush_chars(struct tty_struct *tty)
 	spin_unlock_irqrestore(&ch->ch_lock, flags);
 }
 
-/*
- * dgnc_tty_flush_buffer()
- *
- * Flush Tx buffer (make in == out)
- */
+/* Flush Tx buffer (make in == out) */
 static void dgnc_tty_flush_buffer(struct tty_struct *tty)
 {
 	struct channel_t *ch;
@@ -2322,11 +2189,7 @@ static void dgnc_tty_flush_buffer(struct tty_struct *tty)
 	spin_unlock_irqrestore(&ch->ch_lock, flags);
 }
 
-/*
- * dgnc_wake_up_unit()
- *
- * Wakes up processes waiting in the unit's (teminal/printer) wait queue
- */
+/* Wakes up processes waiting in the unit's (teminal/printer) wait queue */
 static void dgnc_wake_up_unit(struct un_t *unit)
 {
 	unit->un_flags &= ~(UN_LOW | UN_EMPTY);
@@ -2335,11 +2198,7 @@ static void dgnc_wake_up_unit(struct un_t *unit)
 
 /* The IOCTL function and all of its helpers */
 
-/*
- * dgnc_tty_ioctl()
- *
- * The usual assortment of ioctl's
- */
+/* The usual assortment of ioctl's */
 static int dgnc_tty_ioctl(struct tty_struct *tty, unsigned int cmd,
 			  unsigned long arg)
 {
@@ -2624,7 +2483,7 @@ static int dgnc_tty_ioctl(struct tty_struct *tty, unsigned int cmd,
 	case DIGI_SETCUSTOMBAUD:
 	{
 		int new_rate;
-		/* Let go of locks when accessing user space, could sleep */
+
 		spin_unlock_irqrestore(&ch->ch_lock, flags);
 		rc = get_user(new_rate, (int __user *)arg);
 		if (rc)
@@ -2722,8 +2581,6 @@ static int dgnc_tty_ioctl(struct tty_struct *tty, unsigned int cmd,
 
 		spin_unlock_irqrestore(&ch->ch_lock, flags);
 
-		/* Get data from user first. */
-
 		if (copy_from_user(&buf, uarg, sizeof(buf)))
 			return -EFAULT;
 

drivers/staging/dgnc/dgnc_utils.c

@@ -2,12 +2,11 @@
 #include <linux/sched/signal.h>
 #include "dgnc_utils.h"
 
-/*
- * dgnc_ms_sleep()
+/**
+ * dgnc_ms_sleep - Put the driver to sleep
+ * @ms - milliseconds to sleep
  *
- * Put the driver to sleep for x ms's
- *
- * Returns 0 if timed out, !0 (showing signal) if interrupted by a signal.
+ * Return: 0 if timed out, if interrupted by a signal return signal.
  */
 int dgnc_ms_sleep(ulong ms)
 {