Commit bb6beabf authored by Randy Dunlap's avatar Randy Dunlap Committed by Martin K. Petersen
Browse files

scsi: pm8001: Clean up kernel-doc and comments 

Fix kernel-doc warnings then test again, wash, rinse, find more, then
repeat more/again.

Also fix spellos, some grammar, and some punctuation.

../drivers/scsi/pm8001/pm8001_ctl.c:557: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 ** pm8001_ctl_fatal_log_show - fatal error logging
../drivers/scsi/pm8001/pm8001_ctl.c:577: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 ** non_fatal_log_show - non fatal error logging
../drivers/scsi/pm8001/pm8001_ctl.c:622: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 ** pm8001_ctl_gsm_log_show - gsm dump collection

Link: https://lore.kernel.org/r/20210708165723.8594-1-rdunlap@infradead.org


Cc: Jack Wang <jinpu.wang@cloud.ionos.com>
Cc: linux-scsi@vger.kernel.org
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Acked-by: default avatarJack Wang <jinpu.wang@ionos.com>
Signed-off-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarMartin K. Petersen <martin.petersen@oracle.com>
parent 8b3bdd99

drivers/scsi/pm8001/pm8001_ctl.c

+26 −22
Original line number Diff line number Diff line
@@ -77,7 +77,7 @@ DEVICE_ATTR(interface_rev, S_IRUGO, pm8001_ctl_mpi_interface_rev_show, NULL); 
 * @attr: device attribute (unused)

 * @buf: the buffer returned

 *

 * A sysfs 'read only' shost attribute.

 * A sysfs 'read-only' shost attribute.

 */

static ssize_t controller_fatal_error_show(struct device *cdev,

		struct device_attribute *attr, char *buf)
@@ -149,7 +149,7 @@ static ssize_t pm8001_ctl_ila_version_show(struct device *cdev, 
static DEVICE_ATTR(ila_version, 0444, pm8001_ctl_ila_version_show, NULL);



/**

 * pm8001_ctl_inactive_fw_version_show - Inacative firmware version number

 * pm8001_ctl_inactive_fw_version_show - Inactive firmware version number

 * @cdev: pointer to embedded class device

 * @attr: device attribute (unused)

 * @buf: the buffer returned
@@ -396,6 +396,7 @@ static DEVICE_ATTR(aap_log, S_IRUGO, pm8001_ctl_aap_log_show, NULL); 
 * @cdev:pointer to embedded class device

 * @attr: device attribute (unused)

 * @buf: the buffer returned

 *

 * A sysfs 'read-only' shost attribute.

 */

static ssize_t pm8001_ctl_ib_queue_log_show(struct device *cdev,
@@ -430,6 +431,7 @@ static DEVICE_ATTR(ib_log, S_IRUGO, pm8001_ctl_ib_queue_log_show, NULL); 
 * @cdev:pointer to embedded class device

 * @attr: device attribute (unused)

 * @buf: the buffer returned

 *

 * A sysfs 'read-only' shost attribute.

 */
@@ -464,6 +466,7 @@ static DEVICE_ATTR(ob_log, S_IRUGO, pm8001_ctl_ob_queue_log_show, NULL); 
 * @cdev:pointer to embedded class device

 * @attr: device attribute (unused)

 * @buf:the buffer returned

 *

 * A sysfs 'read-only' shost attribute.

 */

static ssize_t pm8001_ctl_bios_version_show(struct device *cdev,
@@ -555,13 +558,13 @@ static ssize_t pm8001_ctl_iop_log_show(struct device *cdev, 
static DEVICE_ATTR(iop_log, S_IRUGO, pm8001_ctl_iop_log_show, NULL);



/**

 ** pm8001_ctl_fatal_log_show - fatal error logging

 ** @cdev:pointer to embedded class device

 ** @attr: device attribute

 ** @buf: the buffer returned

 **

 ** A sysfs 'read-only' shost attribute.

 **/

 * pm8001_ctl_fatal_log_show - fatal error logging

 * @cdev:pointer to embedded class device

 * @attr: device attribute

 * @buf: the buffer returned

 *

 * A sysfs 'read-only' shost attribute.

 */



static ssize_t pm8001_ctl_fatal_log_show(struct device *cdev,

	struct device_attribute *attr, char *buf)
@@ -575,13 +578,13 @@ static ssize_t pm8001_ctl_fatal_log_show(struct device *cdev, 
static DEVICE_ATTR(fatal_log, S_IRUGO, pm8001_ctl_fatal_log_show, NULL);



/**

 ** non_fatal_log_show - non fatal error logging

 ** @cdev:pointer to embedded class device

 ** @attr: device attribute

 ** @buf: the buffer returned

 **

 ** A sysfs 'read-only' shost attribute.

 **/

 * non_fatal_log_show - non fatal error logging

 * @cdev:pointer to embedded class device

 * @attr: device attribute

 * @buf: the buffer returned

 *

 * A sysfs 'read-only' shost attribute.

 */

static ssize_t non_fatal_log_show(struct device *cdev,

	struct device_attribute *attr, char *buf)

{
@@ -620,12 +623,13 @@ static ssize_t non_fatal_count_store(struct device *cdev, 
static DEVICE_ATTR_RW(non_fatal_count);



/**

 ** pm8001_ctl_gsm_log_show - gsm dump collection

 ** @cdev:pointer to embedded class device

 ** @attr: device attribute (unused)

 ** @buf: the buffer returned

 ** A sysfs 'read-only' shost attribute.

 **/

 * pm8001_ctl_gsm_log_show - gsm dump collection

 * @cdev:pointer to embedded class device

 * @attr: device attribute (unused)

 * @buf: the buffer returned

 *

 * A sysfs 'read-only' shost attribute.

 */

static ssize_t pm8001_ctl_gsm_log_show(struct device *cdev,

	struct device_attribute *attr, char *buf)

{

drivers/scsi/pm8001/pm8001_hwi.c

+9 −9
Original line number Diff line number Diff line
@@ -384,7 +384,7 @@ static void update_outbnd_queue_table(struct pm8001_hba_info *pm8001_ha, 


/**

 * pm8001_bar4_shift - function is called to shift BAR base address

 * @pm8001_ha : our hba card infomation

 * @pm8001_ha : our hba card information

 * @shiftValue : shifting value in memory bar.

 */

int pm8001_bar4_shift(struct pm8001_hba_info *pm8001_ha, u32 shiftValue)
@@ -1151,7 +1151,7 @@ static void pm8001_hw_chip_rst(struct pm8001_hba_info *pm8001_ha) 
}



/**

 * pm8001_chip_iounmap - which maped when initialized.

 * pm8001_chip_iounmap - which mapped when initialized.

 * @pm8001_ha: our hba card information

 */

void pm8001_chip_iounmap(struct pm8001_hba_info *pm8001_ha)
@@ -1876,8 +1876,8 @@ static void pm8001_send_read_log(struct pm8001_hba_info *pm8001_ha, 
 * @piomb: the message contents of this outbound message.

 *

 * When FW has completed a ssp request for example a IO request, after it has

 * filled the SG data with the data, it will trigger this event represent

 * that he has finished the job,please check the coresponding buffer.

 * filled the SG data with the data, it will trigger this event representing

 * that he has finished the job; please check the corresponding buffer.

 * So we will tell the caller who maybe waiting the result to tell upper layer

 * that the task has been finished.

 */

drivers/scsi/pm8001/pm8001_init.c

+15 −14
Original line number Diff line number Diff line
@@ -233,7 +233,7 @@ static irqreturn_t pm8001_interrupt_handler_msix(int irq, void *opaque) 
/**

 * pm8001_interrupt_handler_intx - main INTx interrupt handler.

 * @irq: interrupt number

 * @dev_id: sas_ha structure. The HBA is retrieved from sas_has structure.

 * @dev_id: sas_ha structure. The HBA is retrieved from sas_ha structure.

 */



static irqreturn_t pm8001_interrupt_handler_intx(int irq, void *dev_id)
@@ -439,7 +439,7 @@ static int pm8001_alloc(struct pm8001_hba_info *pm8001_ha, 
}



/**

 * pm8001_ioremap - remap the pci high physical address to kernal virtual

 * pm8001_ioremap - remap the pci high physical address to kernel virtual

 * address so that we can access them.

 * @pm8001_ha: our hba structure.

 */
@@ -790,7 +790,7 @@ struct pm8001_mpi3_phy_pg_trx_config { 
};



/**

 * pm8001_get_internal_phy_settings : Retrieves the internal PHY settings

 * pm8001_get_internal_phy_settings - Retrieves the internal PHY settings

 * @pm8001_ha : our adapter

 * @phycfg : PHY config page to populate

 */
@@ -810,7 +810,7 @@ void pm8001_get_internal_phy_settings(struct pm8001_hba_info *pm8001_ha, 
}



/**

 * pm8001_get_external_phy_settings : Retrieves the external PHY settings

 * pm8001_get_external_phy_settings - Retrieves the external PHY settings

 * @pm8001_ha : our adapter

 * @phycfg : PHY config page to populate

 */
@@ -830,7 +830,7 @@ void pm8001_get_external_phy_settings(struct pm8001_hba_info *pm8001_ha, 
}



/**

 * pm8001_get_phy_mask : Retrieves the mask that denotes if a PHY is int/ext

 * pm8001_get_phy_mask - Retrieves the mask that denotes if a PHY is int/ext

 * @pm8001_ha : our adapter

 * @phymask : The PHY mask

 */
@@ -868,7 +868,7 @@ void pm8001_get_phy_mask(struct pm8001_hba_info *pm8001_ha, int *phymask) 
}



/**

 * pm8001_set_phy_settings_ven_117c_12G() : Configure ATTO 12Gb PHY settings

 * pm8001_set_phy_settings_ven_117c_12G() - Configure ATTO 12Gb PHY settings

 * @pm8001_ha : our adapter

 */

static
@@ -903,7 +903,7 @@ int pm8001_set_phy_settings_ven_117c_12G(struct pm8001_hba_info *pm8001_ha) 
}



/**

 * pm8001_configure_phy_settings : Configures PHY settings based on vendor ID.

 * pm8001_configure_phy_settings - Configures PHY settings based on vendor ID.

 * @pm8001_ha : our hba.

 */

static int pm8001_configure_phy_settings(struct pm8001_hba_info *pm8001_ha)
@@ -1053,8 +1053,8 @@ static u32 pm8001_request_irq(struct pm8001_hba_info *pm8001_ha) 
 * @ent: pci device id

 *

 * This function is the main initialization function, when register a new

 * pci driver it is invoked, all struct an hardware initilization should be done

 * here, also, register interrupt

 * pci driver it is invoked, all struct and hardware initialization should be

 * done here, also, register interrupt.

 */

static int pm8001_pci_probe(struct pci_dev *pdev,

			    const struct pci_device_id *ent)
@@ -1172,10 +1172,11 @@ static int pm8001_pci_probe(struct pci_dev *pdev, 
	return rc;

}



/*

/**

 * pm8001_init_ccb_tag - allocate memory to CCB and tag.

 * @pm8001_ha: our hba card information.

 * @shost: scsi host which has been allocated outside.

 * @pdev: pci device.

 */

static int

pm8001_init_ccb_tag(struct pm8001_hba_info *pm8001_ha, struct Scsi_Host *shost,
@@ -1270,7 +1271,7 @@ static void pm8001_pci_remove(struct pci_dev *pdev) 
 * pm8001_pci_suspend - power management suspend main entry point

 * @dev: Device struct

 *

 * Returns 0 success, anything else error.

 * Return: 0 on success, anything else on error.

 */

static int __maybe_unused pm8001_pci_suspend(struct device *dev)

{
@@ -1315,7 +1316,7 @@ static int __maybe_unused pm8001_pci_suspend(struct device *dev) 
 * pm8001_pci_resume - power management resume main entry point

 * @dev: Device struct

 *

 * Returns 0 success, anything else error.

 * Return: 0 on success, anything else on error.

 */

static int __maybe_unused pm8001_pci_resume(struct device *dev)

{

drivers/scsi/pm8001/pm8001_sas.c

+22 −19
Original line number Diff line number Diff line
@@ -102,9 +102,11 @@ void pm8001_tag_init(struct pm8001_hba_info *pm8001_ha) 
 * pm8001_mem_alloc - allocate memory for pm8001.

 * @pdev: pci device.

 * @virt_addr: the allocated virtual address

 * @pphys_addr: DMA address for this device

 * @pphys_addr_hi: the physical address high byte address.

 * @pphys_addr_lo: the physical address low byte address.

 * @mem_size: memory size.

 * @align: requested byte alignment

 */

int pm8001_mem_alloc(struct pci_dev *pdev, void **virt_addr,

	dma_addr_t *pphys_addr, u32 *pphys_addr_hi,
@@ -705,7 +707,7 @@ static void pm8001_tmf_timedout(struct timer_list *t) 
  * @parameter: ssp task parameter.

  *

  * when errors or exception happened, we may want to do something, for example

  * abort the issued task which result in this execption, it is done by calling

  * abort the issued task which result in this exception, it is done by calling

  * this function, note it is also with the task execute interface.

  */

static int pm8001_exec_internal_tmf_task(struct domain_device *dev,
@@ -984,10 +986,11 @@ void pm8001_open_reject_retry( 
}



/**

 * pm8001_I_T_nexus_reset()

 * pm8001_I_T_nexus_reset() - reset the initiator/target connection

 * @dev: the device structure for the device to reset.

 *

 * Standard mandates link reset for ATA (type 0) and hard reset for

 * SSP (type 1), only for RECOVERY

  * @dev: the device structure for the device to reset.

 */

int pm8001_I_T_nexus_reset(struct domain_device *dev)

{

drivers/scsi/pm8001/pm80xx_hwi.c

+25 −25
Original line number Diff line number Diff line
@@ -140,7 +140,7 @@ ssize_t pm80xx_get_fatal_dump(struct device *cdev, 
		pm8001_ha->fatal_bar_loc = 0;

	}



	/* Read until accum_len is retrived */

	/* Read until accum_len is retrieved */

	accum_len = pm8001_mr32(fatal_table_address,

				MPI_FATAL_EDUMP_TABLE_ACCUM_LEN);

	/* Determine length of data between previously stored transfer length
@@ -1093,7 +1093,7 @@ static int init_pci_device_addresses(struct pm8001_hba_info *pm8001_ha) 


	value = pm8001_cr32(pm8001_ha, 0, MSGU_SCRATCH_PAD_0);



	/**

	/*

	 * lower 26 bits of SCRATCHPAD0 register describes offset within the

	 * PCIe BAR where the MPI configuration table is present

	 */
@@ -1101,7 +1101,7 @@ static int init_pci_device_addresses(struct pm8001_hba_info *pm8001_ha) 


	pm8001_dbg(pm8001_ha, DEV, "Scratchpad 0 Offset: 0x%x value 0x%x\n",

		   offset, value);

	/**

	/*

	 * Upper 6 bits describe the offset within PCI config space where BAR

	 * is located.

	 */
@@ -1109,7 +1109,7 @@ static int init_pci_device_addresses(struct pm8001_hba_info *pm8001_ha) 
	pcibar = get_pci_bar_index(pcilogic);

	pm8001_dbg(pm8001_ha, INIT, "Scratchpad 0 PCI BAR: %d\n", pcibar);



	/**

	/*

	 * Make sure the offset falls inside the ioremapped PCI BAR

	 */

	if (offset > pm8001_ha->io_mem[pcibar].memsize) {
@@ -1121,7 +1121,7 @@ static int init_pci_device_addresses(struct pm8001_hba_info *pm8001_ha) 
	pm8001_ha->main_cfg_tbl_addr = base_addr =

		pm8001_ha->io_mem[pcibar].memvirtaddr + offset;



	/**

	/*

	 * Validate main configuration table address: first DWord should read

	 * "PMCS"

	 */
@@ -1385,7 +1385,7 @@ pm80xx_get_encrypt_info(struct pm8001_hba_info *pm8001_ha) 
}



/**

 * pm80xx_encrypt_update - update flash with encryption informtion

 * pm80xx_encrypt_update - update flash with encryption information

 * @pm8001_ha: our hba card information.

 */

static int pm80xx_encrypt_update(struct pm8001_hba_info *pm8001_ha)
@@ -1422,7 +1422,7 @@ static int pm80xx_encrypt_update(struct pm8001_hba_info *pm8001_ha) 
}



/**

 * pm80xx_chip_init - the main init function that initialize whole PM8001 chip.

 * pm80xx_chip_init - the main init function that initializes whole PM8001 chip.

 * @pm8001_ha: our hba card information

 */

static int pm80xx_chip_init(struct pm8001_hba_info *pm8001_ha)
@@ -1541,7 +1541,7 @@ static int mpi_uninit_check(struct pm8001_hba_info *pm8001_ha) 
}



/**

 * pm80xx_fatal_errors - returns non zero *ONLY* when fatal errors

 * pm80xx_fatal_errors - returns non-zero *ONLY* when fatal errors

 * @pm8001_ha: our hba card information

 *

 * Fatal errors are recoverable only after a host reboot.
@@ -1576,8 +1576,8 @@ pm80xx_fatal_errors(struct pm8001_hba_info *pm8001_ha) 
}



/**

 * pm80xx_chip_soft_rst - soft reset the PM8001 chip, so that the clear all

 * the FW register status to the originated status.

 * pm80xx_chip_soft_rst - soft reset the PM8001 chip, so that all

 * FW register status are reset to the originated status.

 * @pm8001_ha: our hba card information

 */
@@ -1900,8 +1900,8 @@ static void pm80xx_send_read_log(struct pm8001_hba_info *pm8001_ha, 
 * @piomb: the message contents of this outbound message.

 *

 * When FW has completed a ssp request for example a IO request, after it has

 * filled the SG data with the data, it will trigger this event represent

 * that he has finished the job,please check the coresponding buffer.

 * filled the SG data with the data, it will trigger this event representing

 * that he has finished the job; please check the corresponding buffer.

 * So we will tell the caller who maybe waiting the result to tell upper layer

 * that the task has been finished.

 */
@@ -3217,7 +3217,7 @@ mpi_smp_completion(struct pm8001_hba_info *pm8001_ha, void *piomb) 
}



/**

 * pm80xx_hw_event_ack_req- For PM8001,some events need to acknowage to FW.

 * pm80xx_hw_event_ack_req- For PM8001, some events need to acknowledge to FW.

 * @pm8001_ha: our hba card information

 * @Qnum: the outbound queue message number.

 * @SEA: source of event to ack
@@ -3500,7 +3500,7 @@ static int mpi_phy_start_resp(struct pm8001_hba_info *pm8001_ha, void *piomb) 
}



/**

 * mpi_thermal_hw_event -The hw event has come.

 * mpi_thermal_hw_event - a thermal hw event has come.

 * @pm8001_ha: our hba card information

 * @piomb: IO message buffer

 */
@@ -4025,7 +4025,7 @@ static void process_one_iomb(struct pm8001_hba_info *pm8001_ha, void *piomb) 
	case OPC_OUB_SET_DEV_INFO:

		pm8001_dbg(pm8001_ha, MSG, "OPC_OUB_SET_DEV_INFO\n");

		break;

	/* spcv specifc commands */

	/* spcv specific commands */

	case OPC_OUB_PHY_START_RESP:

		pm8001_dbg(pm8001_ha, MSG,

			   "OPC_OUB_PHY_START_RESP opcode:%x\n", opc);
@@ -4186,7 +4186,7 @@ static void build_smp_cmd(u32 deviceID, __le32 hTag, 
}



/**

 * pm80xx_chip_smp_req - send a SMP task to FW

 * pm80xx_chip_smp_req - send an SMP task to FW

 * @pm8001_ha: our hba card information.

 * @ccb: the ccb information this request used.

 */
@@ -4346,7 +4346,7 @@ static int check_enc_sat_cmd(struct sas_task *task) 
}



/**

 * pm80xx_chip_ssp_io_req - send a SSP task to FW

 * pm80xx_chip_ssp_io_req - send an SSP task to FW

 * @pm8001_ha: our hba card information.

 * @ccb: the ccb information this request used.

 */
@@ -4750,13 +4750,13 @@ pm80xx_chip_phy_start_req(struct pm8001_hba_info *pm8001_ha, u8 phy_id) 
	payload.ase_sh_lm_slr_phyid = cpu_to_le32(SPINHOLD_DISABLE |

			LINKMODE_AUTO | pm8001_ha->link_rate | phy_id);

	/* SSC Disable and SAS Analog ST configuration */

	/**

	/*

	payload.ase_sh_lm_slr_phyid =

		cpu_to_le32(SSC_DISABLE_30 | SAS_ASE | SPINHOLD_DISABLE |

		LINKMODE_AUTO | LINKRATE_15 | LINKRATE_30 | LINKRATE_60 |

		phy_id);

	Have to add "SAS PHY Analog Setup SPASTI 1 Byte" Based on need

	**/

	*/



	payload.sas_identify.dev_type = SAS_END_DEVICE;

	payload.sas_identify.initiator_bits = SAS_PROTOCOL_ALL;