[SCSI] megaraid: fix kernel-doc

/**

 * scb_t - scsi command control block

 * @param ccb		: command control block for individual driver

 * @param list		: list of control blocks

 * @param gp		: general purpose field for LLDs

 * @param sno		: all SCBs have a serial number

 * @param scp		: associated scsi command

 * @param state		: current state of scb

 * @param dma_dir	: direction of data transfer

 * @param dma_type	: transfer with sg list, buffer, or no data transfer

 * @param dev_channel	: actual channel on the device

 * @param dev_target	: actual target on the device

 * @param status	: completion status

 * @ccb			: command control block for individual driver

 * @list		: list of control blocks

 * @gp			: general purpose field for LLDs

 * @sno			: all SCBs have a serial number

 * @scp			: associated scsi command

 * @state		: current state of scb

 * @dma_dir		: direction of data transfer

 * @dma_type		: transfer with sg list, buffer, or no data transfer

 * @dev_channel		: actual channel on the device

 * @dev_target		: actual target on the device

 * @status		: completion status

 *

 * This is our central data structure to issue commands the each driver.

 * Driver specific data structures are maintained in the ccb field.

/**

 * struct adapter_t - driver's initialization structure

 * @param dpc_h			: tasklet handle

 * @param pdev			: pci configuration pointer for kernel

 * @param host			: pointer to host structure of mid-layer

 * @param lock			: synchronization lock for mid-layer and driver

 * @param quiescent		: driver is quiescent for now.

 * @param outstanding_cmds	: number of commands pending in the driver

 * @param kscb_list		: pointer to the bulk of SCBs pointers for IO

 * @param kscb_pool		: pool of free scbs for IO

 * @param kscb_pool_lock	: lock for pool of free scbs

 * @param pend_list		: pending commands list

 * @param pend_list_lock	: exlusion lock for pending commands list

 * @param completed_list	: list of completed commands

 * @param completed_list_lock	: exclusion lock for list of completed commands

 * @param sglen			: max sg elements supported

 * @param device_ids		: to convert kernel device addr to our devices.

 * @param raid_device		: raid adapter specific pointer

 * @param max_channel		: maximum channel number supported - inclusive

 * @param max_target		: max target supported - inclusive

 * @param max_lun		: max lun supported - inclusive

 * @param unique_id		: unique identifier for each adapter

 * @param irq			: IRQ for this adapter

 * @param ito			: internal timeout value, (-1) means no timeout

 * @param ibuf			: buffer to issue internal commands

 * @param ibuf_dma_h		: dma handle for the above buffer

 * @param uscb_list		: SCB pointers for user cmds, common mgmt module

 * @param uscb_pool		: pool of SCBs for user commands

 * @param uscb_pool_lock	: exclusion lock for these SCBs

 * @param max_cmds		: max outstanding commands

 * @param fw_version		: firmware version

 * @param bios_version		: bios version

 * @param max_cdb_sz		: biggest CDB size supported.

 * @param ha			: is high availability present - clustering

 * @param init_id		: initiator ID, the default value should be 7

 * @param max_sectors		: max sectors per request

 * @param cmd_per_lun		: max outstanding commands per LUN

 * @param being_detached	: set when unloading, no more mgmt calls

 * @aram dpc_h			: tasklet handle

 * @pdev			: pci configuration pointer for kernel

 * @host			: pointer to host structure of mid-layer

 * @lock			: synchronization lock for mid-layer and driver

 * @quiescent			: driver is quiescent for now.

 * @outstanding_cmds		: number of commands pending in the driver

 * @kscb_list			: pointer to the bulk of SCBs pointers for IO

 * @kscb_pool			: pool of free scbs for IO

 * @kscb_pool_lock		: lock for pool of free scbs

 * @pend_list			: pending commands list

 * @pend_list_lock		: exclusion lock for pending commands list

 * @completed_list		: list of completed commands

 * @completed_list_lock		: exclusion lock for list of completed commands

 * @sglen			: max sg elements supported

 * @device_ids			: to convert kernel device addr to our devices.

 * @raid_device			: raid adapter specific pointer

 * @max_channel			: maximum channel number supported - inclusive

 * @max_target			: max target supported - inclusive

 * @max_lun			: max lun supported - inclusive

 * @unique_id			: unique identifier for each adapter

 * @irq				: IRQ for this adapter

 * @ito				: internal timeout value, (-1) means no timeout

 * @ibuf			: buffer to issue internal commands

 * @ibuf_dma_h			: dma handle for the above buffer

 * @uscb_list			: SCB pointers for user cmds, common mgmt module

 * @uscb_pool			: pool of SCBs for user commands

 * @uscb_pool_lock		: exclusion lock for these SCBs

 * @max_cmds			: max outstanding commands

 * @fw_version			: firmware version

 * @bios_version		: bios version

 * @max_cdb_sz			: biggest CDB size supported.

 * @ha				: is high availability present - clustering

 * @init_id			: initiator ID, the default value should be 7

 * @max_sectors			: max sectors per request

 * @cmd_per_lun			: max outstanding commands per LUN

 * @being_detached		: set when unloading, no more mgmt calls

 *

 *

 * mraid_setup_device_map() can be called anytime after the device map is

#define SCP2ADAPTER(scp)	(adapter_t *)SCSIHOST2ADAP(SCP2HOST(scp))

/**

 * MRAID_GET_DEVICE_MAP - device ids

 * @param adp		- Adapter's soft state

 * @param scp		- mid-layer scsi command pointer

 * @param p_chan	- physical channel on the controller

 * @param target	- target id of the device or logical drive number

 * @param islogical	- set if the command is for the logical drive

 *

 * Macro to retrieve information about device class, logical or physical and

 * the corresponding physical channel and target or logical drive number

 **/

#define MRAID_IS_LOGICAL(adp, scp)	\

	(SCP2CHANNEL(scp) == (adp)->max_channel) ? 1 : 0

#define MRAID_IS_LOGICAL_SDEV(adp, sdev)	\

	(sdev->channel == (adp)->max_channel) ? 1 : 0

/**

 * MRAID_GET_DEVICE_MAP - device ids

 * @adp			: adapter's soft state

 * @scp			: mid-layer scsi command pointer

 * @p_chan		: physical channel on the controller

 * @target		: target id of the device or logical drive number

 * @islogical		: set if the command is for the logical drive

 *

 * Macro to retrieve information about device class, logical or physical and

 * the corresponding physical channel and target or logical drive number

 */

#define MRAID_GET_DEVICE_MAP(adp, scp, p_chan, target, islogical)	\

	/*								\

	 * Is the request coming for the virtual channel		\

/*

 * struct mraid_pci_blk - structure holds DMA memory block info

 * @param vaddr		: virtual address to a memory block

 * @param dma_addr	: DMA handle to a memory block

 * @vaddr		: virtual address to a memory block

 * @dma_addr		: DMA handle to a memory block

 *

 * This structure is filled up for the caller. It is the responsibilty of the

 * caller to allocate this array big enough to store addresses for all

#include "mbox_defs.h"

/*

 * console messages debug levels

 */

#define	CL_ANN		0	/* print unconditionally, announcements */

#define CL_DLEVEL1	1	/* debug level 1, informative */

#define CL_DLEVEL2	2	/* debug level 2, verbose */

#define CL_DLEVEL3	3	/* debug level 3, very verbose */

/**

 * con_log() - console log routine

 * @param level		: indicates the severity of the message.

 * @fparam mt		: format string

 * @level		: indicates the severity of the message.

 * @fmt			: format string

 *

 * con_log displays the error messages on the console based on the current

 * debug level. Also it attaches the appropriate kernel severity level with

 * the message.

 *

 *

 * consolge messages debug levels

 */

#define	CL_ANN		0	/* print unconditionally, announcements */

#define CL_DLEVEL1	1	/* debug level 1, informative */

#define CL_DLEVEL2	2	/* debug level 2, verbose */

#define CL_DLEVEL3	3	/* debug level 3, very verbose */

#define	con_log(level, fmt) if (LSI_DBGLVL >= level) printk fmt;

/*

/**

 * struct mraid_hba_info - information about the controller

 *

 * @param pci_vendor_id		: PCI vendor id

 * @param pci_device_id		: PCI device id

 * @param subsystem_vendor_id	: PCI subsystem vendor id

 * @param subsystem_device_id	: PCI subsystem device id

 * @param baseport		: base port of hba memory

 * @param pci_bus		: PCI bus

 * @param pci_dev_fn		: PCI device/function values

 * @param irq			: interrupt vector for the device

 * @pci_vendor_id		: PCI vendor id

 * @pci_device_id		: PCI device id

 * @subsystem_vendor_id		: PCI subsystem vendor id

 * @subsystem_device_id		: PCI subsystem device id

 * @baseport			: base port of hba memory

 * @pci_bus			: PCI bus

 * @pci_dev_fn			: PCI device/function values

 * @irq				: interrupt vector for the device

 *

 * Extended information of 256 bytes about the controller. Align on the single

 * byte boundary so that 32-bit applications can be run on 64-bit platform

/**

 * mraid_device_t - adapter soft state structure for mailbox controllers

 * @param una_mbox64		: 64-bit mbox - unaligned

 * @param una_mbox64_dma	: mbox dma addr - unaligned

 * @param mbox			: 32-bit mbox - aligned

 * @param mbox64		: 64-bit mbox - aligned

 * @param mbox_dma		: mbox dma addr - aligned

 * @param mailbox_lock		: exclusion lock for the mailbox

 * @param baseport		: base port of hba memory

 * @param baseaddr		: mapped addr of hba memory

 * @param mbox_pool		: pool of mailboxes

 * @param mbox_pool_handle	: handle for the mailbox pool memory

 * @param epthru_pool		: a pool for extended passthru commands

 * @param epthru_pool_handle	: handle to the pool above

 * @param sg_pool		: pool of scatter-gather lists for this driver

 * @param sg_pool_handle	: handle to the pool above

 * @param ccb_list		: list of our command control blocks

 * @param uccb_list		: list of cmd control blocks for mgmt module

 * @param umbox64		: array of mailbox for user commands (cmm)

 * @param pdrv_state		: array for state of each physical drive.

 * @param last_disp		: flag used to show device scanning

 * @param hw_error		: set if FW not responding

 * @param fast_load		: If set, skip physical device scanning

 * @una_mbox64			: 64-bit mbox - unaligned

 * @una_mbox64_dma		: mbox dma addr - unaligned

 * @mbox			: 32-bit mbox - aligned

 * @mbox64			: 64-bit mbox - aligned

 * @mbox_dma			: mbox dma addr - aligned

 * @mailbox_lock		: exclusion lock for the mailbox

 * @baseport			: base port of hba memory

 * @baseaddr			: mapped addr of hba memory

 * @mbox_pool			: pool of mailboxes

 * @mbox_pool_handle		: handle for the mailbox pool memory

 * @epthru_pool			: a pool for extended passthru commands

 * @epthru_pool_handle		: handle to the pool above

 * @sg_pool			: pool of scatter-gather lists for this driver

 * @sg_pool_handle		: handle to the pool above

 * @ccb_list			: list of our command control blocks

 * @uccb_list			: list of cmd control blocks for mgmt module

 * @umbox64			: array of mailbox for user commands (cmm)

 * @pdrv_state			: array for state of each physical drive.

 * @last_disp			: flag used to show device scanning

 * @hw_error			: set if FW not responding

 * @fast_load			: If set, skip physical device scanning

 * @channel_class		: channel class, RAID or SCSI

 * @sysfs_sem			: semaphore to serialize access to sysfs res.

 * @sysfs_uioc			: management packet to issue FW calls from sysfs

/**

 * mraid_mm_open - open routine for char node interface

 * @inod	: unused

 * @inode	: unused

 * @filep	: unused

 *

 * allow ioctl operations by apps only if they superuser privilege

 * Allow ioctl operations by apps only if they have superuser privilege.

 */

static int

mraid_mm_open(struct inode *inode, struct file *filep)

/**

 * mraid_mm_get_adapter - Returns corresponding adapters for the mimd packet

 * @umimd	: User space mimd_t ioctl packet

 * @adapter	: pointer to the adapter (OUT)

 * @rval	: returned success/error status

 *

 * The function return value is a pointer to the located @adapter.

 */

static mraid_mmadp_t *

mraid_mm_get_adapter(mimd_t __user *umimd, int *rval)

	return adapter;

}

/*

 * handle_drvrcmd - This routine checks if the opcode is a driver

 * 			  cmd and if it is, handles it.

/**

 * handle_drvrcmd - Checks if the opcode is a driver cmd and if it is, handles it.

 * @arg		: packet sent by the user app

 * @old_ioctl	: mimd if 1; uioc otherwise

 * @rval	: pointer for command's returned value (not function status)

 */

static int

handle_drvrcmd(void __user *arg, uint8_t old_ioctl, int *rval)

/**

 * mimd_to_kioc	- Converter from old to new ioctl format

 *

 * @umimd	: user space old MIMD IOCTL

 * @adp		: adapter softstate

 * @kioc	: kernel space new format IOCTL

 *

 * Routine to convert MIMD interface IOCTL to new interface IOCTL packet. The

/**

 * mraid_mm_attch_buf - Attach a free dma buffer for required size

 *

 * @adp		: Adapter softstate

 * @kioc	: kioc that the buffer needs to be attached to

 * @xferlen	: required length for buffer

/**

 * mraid_mm_dealloc_kioc - Return kioc to free pool

 *

 * @adp		: Adapter softstate

 * @kioc	: uioc_t node to be returned to free pool

 */

/**

 * lld_ioctl - Routine to issue ioctl to low level drvr

 *

 * @adp		: The adapter handle

 * @kioc	: The ioctl packet with kernel addresses

 */

/**

 * ioctl_done - callback from the low level driver

 *

 * @kioc	: completed ioctl packet

 */

static void

}

/*

 * lld_timedout	: callback from the expired timer

 *

/**

 * lld_timedout	- callback from the expired timer

 * @ptr		: ioctl packet that timed out

 */

static void

/**

 * kioc_to_mimd	: Converter from new back to old format

 *

 * kioc_to_mimd	- Converter from new back to old format

 * @kioc	: Kernel space IOCTL packet (successfully issued)

 * @mimd	: User space MIMD packet

 */

/**

 * hinfo_to_cinfo - Convert new format hba info into old format

 *

 * @hinfo	: New format, more comprehensive adapter info

 * @cinfo	: Old format adapter info to support mimd_t apps

 */

}

/*

 * mraid_mm_register_adp - Registration routine for low level drvrs

 *

 * @adp	: Adapter objejct

/**

 * mraid_mm_register_adp - Registration routine for low level drivers

 * @lld_adp	: Adapter objejct

 */

int

mraid_mm_register_adp(mraid_mmadp_t *lld_adp)

/**

 * mraid_mm_adapter_app_handle - return the application handle for this adapter

 * @unique_id	: adapter unique identifier

 *

 * For the given driver data, locate the adadpter in our global list and

 * For the given driver data, locate the adapter in our global list and

 * return the corresponding handle, which is also used by applications to

 * uniquely identify an adapter.

 *

 * @param unique_id : adapter unique identifier

 *

 * @return adapter handle if found in the list

 * @return 0 if adapter could not be located, should never happen though

 * Return adapter handle if found in the list.

 * Return 0 if adapter could not be located, should never happen though.

 */

uint32_t

mraid_mm_adapter_app_handle(uint32_t unique_id)

/**

 * mraid_mm_setup_dma_pools - Set up dma buffer pools per adapter

 *

 * @adp	: Adapter softstate

 *

 * We maintain a pool of dma buffers per each adapter. Each pool has one

}

/*

/**

 * mraid_mm_unregister_adp - Unregister routine for low level drivers

 *				  Assume no outstanding ioctls to llds.

 *

 * @unique_id	: UID of the adpater

 *

 * Assumes no outstanding ioctls to llds.

 */

int

mraid_mm_unregister_adp(uint32_t unique_id)

/**

 * mraid_mm_free_adp_resources - Free adapter softstate

 *

 * @adp	: Adapter softstate

 */

static void

/**

 * mraid_mm_teardown_dma_pools - Free all per adapter dma buffers

 *

 * @adp	: Adapter softstate

 */

static void

}

/**

 * mraid_mm_init	: Module entry point

 * mraid_mm_init	- Module entry point

 */

static int __init

mraid_mm_init(void)

}

#ifdef CONFIG_COMPAT

/**

 * mraid_mm_compat_ioctl	: 32bit to 64bit ioctl conversion routine

 * mraid_mm_compat_ioctl	- 32bit to 64bit ioctl conversion routine

 * @filep	: file operations pointer (ignored)

 * @cmd		: ioctl command

 * @arg		: user ioctl packet

 */

#ifdef CONFIG_COMPAT

static long

mraid_mm_compat_ioctl(struct file *filep, unsigned int cmd,

		      unsigned long arg)

#endif

/**

 * mraid_mm_exit	: Module exit point

 * mraid_mm_exit	- Module exit point

 */

static void __exit

mraid_mm_exit(void)