TODO file has task: remove unnecessary comments. Driver uses some
custom comment format. Driver would be better if it used kernel doc
format.
Audit header file comments. Replace struct comments with kernel doc
format comments. Remove unnecessary comments.
Signed-off-by: Tobin C. Harding <me@xxxxxxxx>
---
drivers/staging/dgnc/dgnc_cls.h | 36 ++--
drivers/staging/dgnc/dgnc_driver.h | 335 ++++++++++++++++++++++---------------
drivers/staging/dgnc/dgnc_neo.h | 79 +++++----
drivers/staging/dgnc/dgnc_pci.h | 7 +-
drivers/staging/dgnc/digi.h | 127 +++++++++-----
5 files changed, 349 insertions(+), 235 deletions(-)
diff --git a/drivers/staging/dgnc/dgnc_cls.h b/drivers/staging/dgnc/dgnc_cls.h
index 463ad30..ee01473 100644
--- a/drivers/staging/dgnc/dgnc_cls.h
+++ b/drivers/staging/dgnc/dgnc_cls.h
@@ -16,24 +16,21 @@
#ifndef __DGNC_CLS_H
#define __DGNC_CLS_H
-/************************************************************************
- * Per channel/port Classic UART structure *
- ************************************************************************
- * Base Structure Entries Usage Meanings to Host *
- * *
- * W = read write R = read only *
- * U = Unused. *
- ************************************************************************/
-
-/*
- * txrx : WR RHR/THR - Holding reg
- * ier : WR IER - Interrupt Enable Reg
- * isr_fcr : WR ISR/FCR - Interrupt Status Reg/Fifo Control Reg
- * lcr : WR LCR - Line Control Reg
- * mcr : WR MCR - Modem Control Reg
- * lsr : WR LSR - Line Status Reg
- * msr : WR MSG - Modem Status Reg
- * spr : WR SPR - Scratch pad Reg
+/**
+ * struct cls_uart_struct - Per channel/port Classic UART.
+ *
+ * key - W = read write
+ * - R = read only
+ * - U = unused
+ *
+ * @txrx: (WR) Holding Register.
+ * @ier: (WR) Interrupt Enable Register.
+ * @isr_fcr: (WR) Interrupt Status Register/Fifo Control Register.
+ * @lcr: (WR) Line Control Register.
+ * @mcr: (WR) Modem Control Register.
+ * @lsr: (WR) Line Status Register.
+ * @msr: (WR) Modem Status Register.
+ * @spr: (WR) Scratch Pad Register.
*/
struct cls_uart_struct {
u8 txrx;
@@ -74,9 +71,6 @@ struct cls_uart_struct {
#define UART_EXAR654_IER_RTSDTR 0x40 /* Output Interrupt Enable */
#define UART_EXAR654_IER_CTSDSR 0x80 /* Input Interrupt Enable */
-/*
- * Our Global Variables
- */
extern struct board_ops dgnc_cls_ops;
#endif
diff --git a/drivers/staging/dgnc/dgnc_driver.h b/drivers/staging/dgnc/dgnc_driver.h
index c8119f2..65f3f53 100644
--- a/drivers/staging/dgnc/dgnc_driver.h
+++ b/drivers/staging/dgnc/dgnc_driver.h
@@ -11,8 +11,6 @@
* but WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED; without even the
* implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU General Public License for more details.
- *
- * Driver includes
*/
#ifndef __DGNC_DRIVER_H
@@ -24,8 +22,6 @@
#include "digi.h" /* Digi specific ioctl header */
-/* Driver defines */
-
/* Driver identification and error statements */
#define PROCSTR "dgnc" /* /proc entries */
#define DEVSTR "/dev/dg/dgnc" /* /dev entries */
@@ -53,10 +49,7 @@
#define PORT_NUM(dev) ((dev) & 0x7f)
#define IS_PRINT(dev) (((dev) & 0xff) >= 0x80)
-/*
- *MAX number of stop characters we will send
- * when our read queue is getting full
- */
+/* MAX number of stop characters sent when our read queue is getting full */
#define MAX_STOPS_SENT 5
/* 4 extra for alignment play space */
@@ -82,27 +75,24 @@
#endif
/* All the possible states the driver can be while being loaded. */
-
enum {
DRIVER_INITIALIZED = 0,
DRIVER_READY
};
/* All the possible states the board can be while booting up. */
-
enum {
BOARD_FAILED = 0,
BOARD_FOUND,
BOARD_READY
};
-/* Structures and closely related defines. */
-
struct dgnc_board;
struct channel_t;
-/* Per board operations structure */
-
+/**
+ * struct board_ops - Per board operations.
+ */
struct board_ops {
void (*tasklet)(unsigned long data);
irqreturn_t (*intr)(int irq, void *voidbrd);
@@ -128,77 +118,109 @@ struct board_ops {
#define BD_IS_PCI_EXPRESS 0x0001 /* Is a PCI Express board */
-/* Per-board information */
-
+/**
+ * struct dgnc_board - Per board information.
+ * @magic: Board magic number.
+ * @boardnum: Board number (0 - 32).
+ *
+ * @type: Type of board.
+ * @name: Product name.
+ * @pdev: Pointer to the pci_dev structure.
+ * @bd_flags: Board flags.
+ * @vendor: PCI vendor ID.
+ * @device: PCI device ID.
+ * @subvendor: PCI subsystem vendor ID.
+ * @subdevice: PCI subsystem device ID.
+ * @rev: PCI revision ID.
+ * @pci_bus: PCI bus value.
+ * @pci_slot: PCI slot value.
+ * @maxports: Maximum ports this board can handle.
+ * @dvid: Board specific device ID.
+ * @vpd: VPD of this board, if found.
+ * @serial_num: Serial number of this board, if found in VPD.
+ * @bd_lock: Used to protect board.
+ * @bd_intr_lock: Protect poller tasklet and interrupt routine from each other.
+ * @state: State of the card.
+ * @state_wait: Queue to sleep on for state change.
+ * @helper_tasklet: Poll helper tasklet.
+ * @nasync: Number of ports on card.
+ * @irq: Interrupt request number.
+ * @membase: Start of base memory of the card.
+ * @membase_end: End of base memory of the card.
+ * @iobase: Start of IO base of the card.
+ * @iobase_end: End of IO base of the card.
+ * @bd_uart_offset: Space between each UART.
+ * @channels: array of pointers to our channels.
+ * @serial_driver: Pointer to the serial driver.
+ * @serial_name: Serial driver name.
+ * @print_dirver: Pointer to the print driver.
+ * @print_name: Print driver name.
+ * @dpatype: Board type as defined by DPA.
+ * @dpastatus: Board status as defined by DPA.
+ * @bd_dividend: Board/UART's specific dividend.
+ * @bd_ops: Pointer to board operations structure.
+ * @proc_entry_pointer: Proc/<board> entry
+ * @dgnc_board_table: Proc/<board> entry
+ */
struct dgnc_board {
- int magic; /* Board Magic number. */
- int boardnum; /* Board number: 0-32 */
+ int magic;
+ int boardnum;
- int type; /* Type of board */
- char *name; /* Product Name */
- struct pci_dev *pdev; /* Pointer to the pci_dev struct */
- unsigned long bd_flags; /* Board flags */
- u16 vendor; /* PCI vendor ID */
- u16 device; /* PCI device ID */
- u16 subvendor; /* PCI subsystem vendor ID */
- u16 subdevice; /* PCI subsystem device ID */
- unsigned char rev; /* PCI revision ID */
- uint pci_bus; /* PCI bus value */
- uint pci_slot; /* PCI slot value */
- uint maxports; /* MAX ports this board can handle */
- unsigned char dvid; /* Board specific device id */
- unsigned char vpd[128]; /* VPD of board, if found */
- unsigned char serial_num[20]; /* Serial number of board,
- * if found in VPD
- */
+ int type;
+ char *name;
+ struct pci_dev *pdev;
+ unsigned long bd_flags;
+ u16 vendor;
+ u16 device;
+ u16 subvendor;
+ u16 subdevice;
+ unsigned char rev;
+ uint pci_bus;
+ uint pci_slot;
+ uint maxports;
+ unsigned char dvid;
+ unsigned char vpd[128];
+ unsigned char serial_num[20];
- spinlock_t bd_lock; /* Used to protect board */
+ /* used to protect the board */
+ spinlock_t bd_lock;
- spinlock_t bd_intr_lock; /* Used to protect the poller tasklet
- * and the interrupt routine from each
- * other.
- */
+ /* Protect poller tasklet and interrupt routine from each other. */
+ spinlock_t bd_intr_lock;
- uint state; /* State of card. */
- wait_queue_head_t state_wait; /* Place to sleep on for state change */
+ uint state;
+ wait_queue_head_t state_wait;
- struct tasklet_struct helper_tasklet; /* Poll helper tasklet */
+ struct tasklet_struct helper_tasklet;
- uint nasync; /* Number of ports on card */
+ uint nasync;
- uint irq; /* Interrupt request number */
+ uint irq;
- ulong membase; /* Start of base memory of the card */
- ulong membase_end; /* End of base memory of the card */
+ ulong membase;
+ ulong membase_end;
- u8 __iomem *re_map_membase; /* Remapped memory of the card */
+ u8 __iomem *re_map_membase;
- ulong iobase; /* Start of io base of the card */
- ulong iobase_end; /* End of io base of the card */
+ ulong iobase;
+ ulong iobase_end;
- uint bd_uart_offset; /* Space between each UART */
+ uint bd_uart_offset;
- struct channel_t *channels[MAXPORTS]; /* array of pointers
- * to our channels.
- */
+ struct channel_t *channels[MAXPORTS];
struct tty_driver *serial_driver;
char serial_name[200];
struct tty_driver *print_driver;
char print_name[200];
- u16 dpatype; /* The board "type",
- * as defined by DPA
- */
- u16 dpastatus; /* The board "status",
- * as defined by DPA
- */
+ u16 dpatype;
+ u16 dpastatus;
- uint bd_dividend; /* Board/UARTs specific dividend */
+ uint bd_dividend;
struct board_ops *bd_ops;
- /* /proc/<board> entries */
struct proc_dir_entry *proc_entry_pointer;
struct dgnc_proc_entry *dgnc_board_table;
@@ -221,17 +243,25 @@ struct dgnc_board {
struct device;
-/* Structure for terminal or printer unit. */
+/**
+ * struct un_t - terminal or printer unit
+ * @magic: Unit magic number.
+ * @un_open_count: Counter of opens to port.
+ * @un_tty: Pointer to unit tty structure.
+ * @un_flags: Unit flags.
+ * @un_flags_wait: Place to sleep to wait on unit.
+ * @un_dev: Minor device number.
+ */
struct un_t {
- int magic; /* Unit Magic Number. */
+ int magic;
struct channel_t *un_ch;
ulong un_time;
uint un_type;
- uint un_open_count; /* Counter of opens to port */
- struct tty_struct *un_tty; /* Pointer to unit tty structure */
- uint un_flags; /* Unit flags */
- wait_queue_head_t un_flags_wait; /* Place to sleep to wait on unit */
- uint un_dev; /* Minor device number */
+ uint un_open_count;
+ struct tty_struct *un_tty;
+ uint un_flags;
+ wait_queue_head_t un_flags_wait;
+ uint un_dev;
struct device *un_sysfs;
};
@@ -263,102 +293,139 @@ struct un_t {
#define EQUEUESIZE RQUEUESIZE
#define WQUEUESIZE (WQUEUEMASK + 1)
-/* Channel information structure. */
+/**
+ * struct channel_t - Channel information.
+ * @magic: Channel magic number.
+ * @dgnc_board: Pointer to board structure.
+ * @ch_bd: Transparent print structure.
+ * @ch_tun: Terminal unit information.
+ * @ch_pun: Printer unit information.
+ * @ch_lock: Provide for serialization.
+ * @ch_flags_wait: Channel flags wait queue.
+ * @ch_portnum: Port number, 0 offset.
+ * @ch_open_count: Open count.
+ * @ch_flags: Channel flags.
+ * @ch_close_delay: How long we should drop RTS/DTR for.
+ * @ch_cpstime: Time for CPS calculations.
+ * @ch_c_iflag: Channel iflags.
+ * @ch_c_cflag: Channel cflags.
+ * @ch_c_oflag: Channel oflags.
+ * @ch_c_lflag: Channel lflags.
+ * @ch_stopc: Stop character.
+ * @ch_startc: Start character.
+ * @ch_old_baud: Cache of the current baud rate.
+ * @ch_custom_speed: Custom baud rate, if set.
+ * @ch_wopen: Waiting for open process count.
+ * @ch_mostat: FEP output modem status.
+ * @ch_mistat: FEP input modem status.
+ * @chc_neo_uart: Pointer to the mapped neo UART struct
+ * @ch_cls_uart: Pointer to the mapped cls UART struct
+ * @ch_cached_lsr: Cached value of the LSR register.
+ * @ch_rqueue: Read queue buffer, malloc'ed.
+ * @ch_r_head: Head location of the read queue.
+ * @ch_r_tail: Tail location of the read queue.
+ * @ch_equeue: Error queue buffer, malloc'ed.
+ * @ch_e_head: Head location of the error queue.
+ * @ch_e_tail: Tail location of the error queue.
+ * @ch_wqueue: Write queue buffer, malloc'ed.
+ * @ch_w_head: Head location of the write queue.
+ * @ch_w_tail: Tail location of the write queue.
+ * @ch_rxcount: Total of data received so far.
+ * @ch_txcount: Total of data transmitted so far.
+ * @ch_r_tlevel: Receive trigger level.
+ * @ch_t_tlevel: Transmit trigger level.
+ * @ch_r_watermark: Receive water mark.
+ * @ch_stop_sending_break: Time we should STOP sending a break.
+ * @ch_stops_sent: How many times I have send a stop character to try
+ * to stop the other guy sending.
+ * @ch_err_parity: Count of parity
+ * @ch_err_frame: Count of framing errors on channel.
+ * @ch_err_break: Count of breaks on channel.
+ * @ch_err_overrun: Count of overruns on channel.
+ * @ch_xon_sends: Count of xons transmitted.
+ * @ch_xoff_sends: Count of xoffs transmitted.
+ * @proc_entry_pointer: Proc/<board>/<channel> entry.
+ * @dgnc_channel_table: Proc/<board>/<channel> entry.
+ */
struct channel_t {
- int magic; /* Channel Magic Number */
- struct dgnc_board *ch_bd; /* Board structure pointer */
- struct digi_t ch_digi; /* Transparent Print structure */
- struct un_t ch_tun; /* Terminal unit info */
- struct un_t ch_pun; /* Printer unit info */
+ int magic;
+ struct dgnc_board *ch_bd;
+ struct digi_t ch_digi;
+ struct un_t ch_tun;
+ struct un_t ch_pun;
- spinlock_t ch_lock; /* provide for serialization */
+ spinlock_t ch_lock; /* provide for serialization */
wait_queue_head_t ch_flags_wait;
- uint ch_portnum; /* Port number, 0 offset. */
- uint ch_open_count; /* open count */
- uint ch_flags; /* Channel flags */
+ uint ch_portnum;
+ uint ch_open_count;
+ uint ch_flags;
- ulong ch_close_delay; /* How long we should
- * drop RTS/DTR for
- */
+ ulong ch_close_delay;
- ulong ch_cpstime; /* Time for CPS calculations */
+ ulong ch_cpstime;
- tcflag_t ch_c_iflag; /* channel iflags */
- tcflag_t ch_c_cflag; /* channel cflags */
- tcflag_t ch_c_oflag; /* channel oflags */
- tcflag_t ch_c_lflag; /* channel lflags */
- unsigned char ch_stopc; /* Stop character */
- unsigned char ch_startc; /* Start character */
+ tcflag_t ch_c_iflag;
+ tcflag_t ch_c_cflag;
+ tcflag_t ch_c_oflag;
+ tcflag_t ch_c_lflag;
+ unsigned char ch_stopc;
+ unsigned char ch_startc;
- uint ch_old_baud; /* Cache of the current baud */
- uint ch_custom_speed;/* Custom baud, if set */
+ uint ch_old_baud;
+ uint ch_custom_speed;
- uint ch_wopen; /* Waiting for open process cnt */
+ uint ch_wopen;
- unsigned char ch_mostat; /* FEP output modem status */
- unsigned char ch_mistat; /* FEP input modem status */
+ unsigned char ch_mostat;
+ unsigned char ch_mistat;
- struct neo_uart_struct __iomem *ch_neo_uart; /* Pointer to the
- * "mapped" UART struct
- */
- struct cls_uart_struct __iomem *ch_cls_uart; /* Pointer to the
- * "mapped" UART struct
- */
+ struct neo_uart_struct __iomem *ch_neo_uart;
+ struct cls_uart_struct __iomem *ch_cls_uart;
- unsigned char ch_cached_lsr; /* Cached value of the LSR register */
+ unsigned char ch_cached_lsr;
- unsigned char *ch_rqueue; /* Our read queue buffer - malloc'ed */
- ushort ch_r_head; /* Head location of the read queue */
- ushort ch_r_tail; /* Tail location of the read queue */
+ unsigned char *ch_rqueue;
+ ushort ch_r_head;
+ ushort ch_r_tail;
- unsigned char *ch_equeue; /* Our error queue buffer - malloc'ed */
- ushort ch_e_head; /* Head location of the error queue */
- ushort ch_e_tail; /* Tail location of the error queue */
+ unsigned char *ch_equeue;
+ ushort ch_e_head;
+ ushort ch_e_tail;
- unsigned char *ch_wqueue; /* Our write queue buffer - malloc'ed */
- ushort ch_w_head; /* Head location of the write queue */
- ushort ch_w_tail; /* Tail location of the write queue */
+ unsigned char *ch_wqueue;
+ ushort ch_w_head;
+ ushort ch_w_tail;
- ulong ch_rxcount; /* total of data received so far */
- ulong ch_txcount; /* total of data transmitted so far */
+ ulong ch_rxcount;
+ ulong ch_txcount;
- unsigned char ch_r_tlevel; /* Receive Trigger level */
- unsigned char ch_t_tlevel; /* Transmit Trigger level */
+ unsigned char ch_r_tlevel;
+ unsigned char ch_t_tlevel;
- unsigned char ch_r_watermark; /* Receive Watermark */
+ unsigned char ch_r_watermark;
- ulong ch_stop_sending_break; /* Time we should STOP
- * sending a break
- */
+ ulong ch_stop_sending_break;
+ uint ch_stops_sent;
- uint ch_stops_sent; /* How many times I have sent a stop
- * character to try to stop the other
- * guy sending.
- */
- ulong ch_err_parity; /* Count of parity errors on channel */
- ulong ch_err_frame; /* Count of framing errors on channel */
- ulong ch_err_break; /* Count of breaks on channel */
- ulong ch_err_overrun; /* Count of overruns on channel */
+ ulong ch_err_parity;
+ ulong ch_err_frame;
+ ulong ch_err_break;
+ ulong ch_err_overrun;
- ulong ch_xon_sends; /* Count of xons transmitted */
- ulong ch_xoff_sends; /* Count of xoffs transmitted */
+ ulong ch_xon_sends;
+ ulong ch_xoff_sends;
- /* /proc/<board>/<channel> entries */
struct proc_dir_entry *proc_entry_pointer;
struct dgnc_proc_entry *dgnc_channel_table;
};
-/* Our Global Variables. */
-
extern uint dgnc_major; /* Our driver/mgmt major */
extern int dgnc_poll_tick; /* Poll interval - 20 ms */
extern spinlock_t dgnc_global_lock; /* Driver global spinlock */
extern spinlock_t dgnc_poll_lock; /* Poll scheduling lock */
extern uint dgnc_num_boards; /* Total number of boards */
-extern struct dgnc_board *dgnc_board[MAXBOARDS];/* Array of board
- * structs
- */
+extern struct dgnc_board *dgnc_board[MAXBOARDS];/* Array of boards */
#endif
diff --git a/drivers/staging/dgnc/dgnc_neo.h b/drivers/staging/dgnc/dgnc_neo.h
index 77ecd9b..6a6a83e 100644
--- a/drivers/staging/dgnc/dgnc_neo.h
+++ b/drivers/staging/dgnc/dgnc_neo.h
@@ -18,38 +18,57 @@
#include "dgnc_driver.h"
-/*
- * Per channel/port NEO UART structure
- * Base Structure Entries Usage Meanings to Host
+/**
+ * struct neo_uart_struct - Per channel/port NEO UART structure
+ *
+ * key - W = read write
+ * - R = read only
+ * - U = unused
*
- * W = read write R = read only
- * U = Unused.
+ * @txrx: (RW) Holding Register.
+ * @ier: (RW) Interrupt Enable Register.
+ * @isr_fcr: (RW) Interrupt Status Reg/Fifo Control Register.
+ * @lcr: (RW) Line Control Register.
+ * @mcr: (RW) Modem Control Register.
+ * @lsr: (RW) Line Status Register.
+ * @msr: (RW) Modem Status Register.
+ * @spr: (RW) Scratch Pad Register.
+ * @fctr: (RW) Feature Control Register.
+ * @efr: (RW) Enhanced Function Register.
+ * @tfifo: (RW) Transmit FIFO Register.
+ * @rfifo: (RW) Receive FIFO Register.
+ * @xoffchar1: (RW) XOff Character 1 Register.
+ * @xoffchar2: (RW) XOff Character 2 Register.
+ * @xonchar1: (RW) Xon Character 1 Register.
+ * @xonchar2: (RW) XOn Character 2 Register.
+ * @reserved1: (U) Reserved by Exar.
+ * @txrxburst: (RW) 64 bytes of RX/TX FIFO Data.
+ * @reserved2: (U) Reserved by Exar.
+ * @rxburst_with_errors: (R) bytes of RX FIFO Data + LSR.
*/
-
struct neo_uart_struct {
- u8 txrx; /* WR RHR/THR - Holding Reg */
- u8 ier; /* WR IER - Interrupt Enable Reg */
- u8 isr_fcr; /* WR ISR/FCR - Interrupt Status Reg/Fifo
- * Control Reg
- */
- u8 lcr; /* WR LCR - Line Control Reg */
- u8 mcr; /* WR MCR - Modem Control Reg */
- u8 lsr; /* WR LSR - Line Status Reg */
- u8 msr; /* WR MSR - Modem Status Reg */
- u8 spr; /* WR SPR - Scratch Pad Reg */
- u8 fctr; /* WR FCTR - Feature Control Reg */
- u8 efr; /* WR EFR - Enhanced Function Reg */
- u8 tfifo; /* WR TXCNT/TXTRG - Transmit FIFO Reg */
- u8 rfifo; /* WR RXCNT/RXTRG - Receive FIFO Reg */
- u8 xoffchar1; /* WR XOFF 1 - XOff Character 1 Reg */
- u8 xoffchar2; /* WR XOFF 2 - XOff Character 2 Reg */
- u8 xonchar1; /* WR XON 1 - Xon Character 1 Reg */
- u8 xonchar2; /* WR XON 2 - XOn Character 2 Reg */
-
- u8 reserved1[0x2ff - 0x200]; /* U Reserved by Exar */
- u8 txrxburst[64]; /* RW 64 bytes of RX/TX FIFO Data */
- u8 reserved2[0x37f - 0x340]; /* U Reserved by Exar */
- u8 rxburst_with_errors[64]; /* R 64 bytes of RX FIFO Data + LSR */
+ u8 txrx;
+ u8 ier;
+ u8 isr_fcr;
+
+ u8 lcr;
+ u8 mcr;
+ u8 lsr;
+ u8 msr;
+ u8 spr;
+ u8 fctr;
+ u8 efr;
+ u8 tfifo;
+ u8 rfifo;
+ u8 xoffchar1;
+ u8 xoffchar2;
+ u8 xonchar1;
+ u8 xonchar2;
+
+ u8 reserved1[0x2ff - 0x200];
+ u8 txrxburst[64];
+ u8 reserved2[0x37f - 0x340];
+ u8 rxburst_with_errors[64];
};
/* Where to read the extended interrupt register (32bits instead of 8bits) */
@@ -151,8 +170,6 @@ struct neo_uart_struct {
#define UART_17158_IER_RTSDTR 0x40 /* Output Interrupt Enable */
#define UART_17158_IER_CTSDSR 0x80 /* Input Interrupt Enable */
-/* Our Global Variables */
-
extern struct board_ops dgnc_neo_ops;
#endif
diff --git a/drivers/staging/dgnc/dgnc_pci.h b/drivers/staging/dgnc/dgnc_pci.h
index 4e170c4..4d6fc4a 100644
--- a/drivers/staging/dgnc/dgnc_pci.h
+++ b/drivers/staging/dgnc/dgnc_pci.h
@@ -16,7 +16,8 @@
#ifndef __DGNC_PCI_H
#define __DGNC_PCI_H
-#define PCIMAX 32 /* maximum number of PCI boards */
+/* Maximum number of PCI boards */
+#define PCIMAX 32
#define DIGI_VID 0x114F
@@ -59,10 +60,10 @@
#define PCI_DEVICE_NEO_EXPRESS_8RJ45_PCI_NAME "Neo 8 PCI Express RJ45"
#define PCI_DEVICE_NEO_EXPRESS_4_IBM_PCI_NAME "Neo 4 PCI Express IBM"
-/* Size of Memory and I/O for PCI (4 K) */
+/* Size of memory and I/O for PCI (4 K) */
#define PCI_RAM_SIZE 0x1000
-/* Size of Memory (2MB) */
+/* Size of memory (2MB) */
#define PCI_MEM_SIZE 0x1000
#endif
diff --git a/drivers/staging/dgnc/digi.h b/drivers/staging/dgnc/digi.h
index ec2e3dd..84a914e 100644
--- a/drivers/staging/dgnc/digi.h
+++ b/drivers/staging/dgnc/digi.h
@@ -45,8 +45,7 @@
#define DIGI_SETAW (('e' << 8) | 96) /* Drain & set params */
#define DIGI_SETAF (('e' << 8) | 97) /* Drain, flush & set params */
#define DIGI_GET_NI_INFO (('d' << 8) | 250) /* Non-intelligent state info */
-#define DIGI_LOOPBACK (('d' << 8) | 252) /*
- * Enable/disable UART
+#define DIGI_LOOPBACK (('d' << 8) | 252) /* Enable/disable UART
* internal loopback
*/
#define DIGI_FAST 0x0002 /* Fast baud rates */
@@ -64,50 +63,77 @@
/*
* Structure used with ioctl commands for DIGI parameters.
*/
+/**
+ * struct digi_t - Ioctl commands for DIGI parameters.
+ * @digi_flags: Flags.
+ * @digi_maxcps: Maximum printer CPS.
+ * @digi_maxchar: Maximum characters in the print queue.
+ * @digi_bufsize: Buffer size.
+ * @digi_onlen: Length of ON string.
+ * @digi_offlen: Length of OFF string.
+ * @digi_onstr: Printer ON string.
+ * @digi_offstr: Printer OFF string.
+ * @digi_term: Terminal string.
+ */
struct digi_t {
- unsigned short digi_flags; /* Flags (see above) */
- unsigned short digi_maxcps; /* Max printer CPS */
- unsigned short digi_maxchar; /* Max chars in print queue */
- unsigned short digi_bufsize; /* Buffer size */
- unsigned char digi_onlen; /* Length of ON string */
- unsigned char digi_offlen; /* Length of OFF string */
- char digi_onstr[DIGI_PLEN]; /* Printer on string */
- char digi_offstr[DIGI_PLEN]; /* Printer off string */
- char digi_term[DIGI_TSIZ]; /* terminal string */
+ unsigned short digi_flags;
+ unsigned short digi_maxcps;
+ unsigned short digi_maxchar;
+ unsigned short digi_bufsize;
+ unsigned char digi_onlen;
+ unsigned char digi_offlen;
+ char digi_onstr[DIGI_PLEN];
+ char digi_offstr[DIGI_PLEN];
+ char digi_term[DIGI_TSIZ];
};
-/* Structure to get driver status information */
-
+/**
+ * struct digi_dinfo - Driver status information.
+ * @dinfo_nboards: Number of boards configured.
+ * @dinfo_reserved: Not used, for future expansion.
+ * @dinfio_version: Driver version.
+ */
struct digi_dinfo {
- unsigned int dinfo_nboards; /* # boards configured */
- char dinfo_reserved[12]; /* for future expansion */
- char dinfo_version[16]; /* driver version */
+ unsigned int dinfo_nboards;
+ char dinfo_reserved[12];
+ char dinfo_version[16];
};
#define DIGI_GETDD (('d' << 8) | 248) /* get driver info */
-/*
- * Structure used with ioctl commands for per-board information
+/**
+ * struct digi_info - Ioctl commands for per board information.
*
- * physsize and memsize differ when board has "windowed" memory
+ * Physsize and memsize differ when board has "windowed" memory.
+ *
+ * @info_bdnum: Board number (0 based).
+ * @info_ioport: IO port address.
+ * @indo_physaddr: Memory address.
+ * @info_physize: Size of host memory window.
+ * @info_memsize: Amount of dual-port memory on board.
+ * @info_bdtype: Board type.
+ * @info_nports: Number of ports.
+ * @info_bdstate: Board state.
+ * @info_reserved: Not used, for future expansion.
*/
struct digi_info {
- unsigned int info_bdnum; /* Board number (0 based) */
- unsigned int info_ioport; /* io port address */
- unsigned int info_physaddr; /* memory address */
- unsigned int info_physsize; /* Size of host mem window */
- unsigned int info_memsize; /* Amount of dual-port mem */
- /* on board */
- unsigned short info_bdtype; /* Board type */
- unsigned short info_nports; /* number of ports */
- char info_bdstate; /* board state */
- char info_reserved[7]; /* for future expansion */
+ unsigned int info_bdnum;
+ unsigned int info_ioport;
+ unsigned int info_physaddr;
+ unsigned int info_physsize;
+ unsigned int info_memsize;
+ unsigned short info_bdtype;
+ unsigned short info_nports;
+ char info_bdstate;
+ char info_reserved[7];
};
#define DIGI_GETBD (('d' << 8) | 249) /* get board info */
-struct digi_getbuffer /* Struct for holding buffer use counts */
-{
+/**
+ * struct digi_getbuffer - Holds buffer use counts.
+ */
+struct digi_getbuffer {
unsigned long tx_in;
unsigned long tx_out;
unsigned long rxbuf;
@@ -115,14 +141,24 @@ struct digi_getbuffer /* Struct for holding buffer use counts */
unsigned long txdone;
};
+/**
+ * struct digi_getcounter
+ * @norun: Number of UART overrun errors.
+ * @noflow: Number of buffer overflow errors.
+ * @nframe: Number of framing errors.
+ * @nparity: Number of parity errors.
+ * @nbreak: Number of breaks received.
+ * @rbytes: Number of received bytes.
+ * @tbytes: Number of transmitted bytes.
+ */
struct digi_getcounter {
- unsigned long norun; /* number of UART overrun errors */
- unsigned long noflow; /* number of buffer overflow errors */
- unsigned long nframe; /* number of framing errors */
- unsigned long nparity; /* number of parity errors */
- unsigned long nbreak; /* number of breaks received */
- unsigned long rbytes; /* number of received bytes */
- unsigned long tbytes; /* number of bytes transmitted fully */
+ unsigned long norun;
+ unsigned long noflow;
+ unsigned long nframe;
+ unsigned long nparity;
+ unsigned long nbreak;
+ unsigned long rbytes;
+ unsigned long tbytes;
};
/* Board State Definitions */
@@ -137,15 +173,14 @@ struct digi_getcounter {
#define DIGI_REALPORT_GETCOUNTERS (('e' << 8) | 110)
#define DIGI_REALPORT_GETEVENTS (('e' << 8) | 111)
-#define EV_OPU 0x0001 /* !<Output paused by client */
-#define EV_OPS 0x0002 /* !<Output paused by regular sw flowctrl */
-#define EV_IPU 0x0010 /* !<Input paused unconditionally by user */
-#define EV_IPS 0x0020 /* !<Input paused by high/low water marks */
-#define EV_TXB 0x0040 /* !<Transmit break pending */
+#define EV_OPU 0x0001 /* Output paused by client */
+#define EV_OPS 0x0002 /* Output paused by regular sw flowctrl */
+#define EV_IPU 0x0010 /* Input paused unconditionally by user */
+#define EV_IPS 0x0020 /* Input paused by high/low water marks */
+#define EV_TXB 0x0040 /* Transmit break pending */
-/*
- * This structure holds data needed for the intelligent <--> nonintelligent
- * DPA translation
+/**
+ * struct ni_info - intelligent <--> non-intelligent DPA translation.
*/
struct ni_info {
int board;
--
2.7.4
_______________________________________________
devel mailing list
devel@xxxxxxxxxxxxxxxxxxxxxx
http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel
