Skip to content

Commit

Permalink
[SCSI] megaraid: fix kernel-doc
Browse files Browse the repository at this point in the history 
kernel-doc modifications:
- change "@param var" notation to @var;
- change function/description separator from ':' to '-';
- change var/description separator from '-' to ':';
- fix a few doc. typos;
- don't use kernel-doc /** lead-in when the doc. block is not kernel-doc;
- use Linux common */ ending comment format instead of **/;
- use correct function parameter names;
- place function parameters immediately after the function short description;
- place kernel-doc immediately before its function or macro;

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Sumant Patro <sumantp@lsil.com>
Signed-off-by: James Bottomley <James.Bottomley@SteelEye.com>
  • Loading branch information
Randy Dunlap authored and James Bottomley committed Jan 13, 2007
1 parent cd96d96 commit a69b74d
Show file tree
Hide file tree
Showing 6 changed files with 275 additions and 287 deletions.
120 changes: 60 additions & 60 deletions drivers/scsi/megaraid/mega_common.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,17 +46,17 @@

/**
* 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.
Expand Down Expand Up @@ -99,42 +99,42 @@ typedef struct {

/**
* 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
Expand Down Expand Up @@ -211,23 +211,23 @@ typedef struct {
#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 \
Expand Down Expand Up @@ -273,8 +273,8 @@ typedef struct {

/*
* 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
Expand Down
36 changes: 18 additions & 18 deletions drivers/scsi/megaraid/megaraid_ioctl.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,23 +22,23 @@

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

/*
Expand Down Expand Up @@ -157,14 +157,14 @@ typedef struct uioc {
/**
* 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
Expand Down
Loading

0 comments on commit a69b74d

Please sign in to comment.