Commit bccbe21e authored by Even Xu's avatar Even Xu Committed by Jiri Kosina
Browse files

HID: Intel-thc-hid: Intel-quicki2c: Refine code comments 



Align capitalization of the first characters for all code comments and
refine some descriptions.

Signed-off-by: default avatarEven Xu <even.xu@intel.com>
Reviewed-by: default avatarAndy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: default avatarJiri Kosina <jkosina@suse.com>
parent 22da60f0

drivers/hid/intel-thc-hid/intel-quicki2c/pci-quicki2c.c

+57 −68
Original line number Diff line number Diff line
@@ -29,17 +29,16 @@ static guid_t thc_platform_guid = 


/**

 * quicki2c_acpi_get_dsm_property - Query device ACPI DSM parameter

 *

 * @adev: point to ACPI device

 * @adev: Point to ACPI device

 * @guid: ACPI method's guid

 * @rev: ACPI method's revision

 * @func: ACPI method's function number

 * @type: ACPI parameter's data type

 * @prop_buf: point to return buffer

 * @prop_buf: Point to return buffer

 *

 * This is a helper function for device to query its ACPI DSM parameters.

 *

 * Return: 0 if success or ENODEV on failed.

 * Return: 0 if success or ENODEV on failure.

 */

static int quicki2c_acpi_get_dsm_property(struct acpi_device *adev, const guid_t *guid,

					  u64 rev, u64 func, acpi_object_type type, void *prop_buf)
@@ -67,11 +66,10 @@ static int quicki2c_acpi_get_dsm_property(struct acpi_device *adev, const guid_t 


/**

 * quicki2c_acpi_get_dsd_property - Query device ACPI DSD parameter

 *

 * @adev: point to ACPI device

 * @adev: Point to ACPI device

 * @dsd_method_name: ACPI method's property name

 * @type: ACPI parameter's data type

 * @prop_buf: point to return buffer

 * @prop_buf: Point to return buffer

 *

 * This is a helper function for device to query its ACPI DSD parameters.

 *
@@ -100,13 +98,12 @@ static int quicki2c_acpi_get_dsd_property(struct acpi_device *adev, acpi_string 
}



/**

 * quicki2c_get_acpi_resources - Query all quicki2c devices' ACPI parameters

 *

 * @qcdev: point to quicki2c device

 * quicki2c_get_acpi_resources - Query all QuickI2C devices' ACPI parameters

 * @qcdev: Point to quicki2c_device structure

 *

 * This function gets all quicki2c devices' ACPI resource.

 * This function gets all QuickI2C devices' ACPI resource.

 *

 * Return: 0 if success or error code on failed.

 * Return: 0 if success or error code on failure.

 */

static int quicki2c_get_acpi_resources(struct quicki2c_device *qcdev)

{
@@ -192,10 +189,9 @@ static int quicki2c_get_acpi_resources(struct quicki2c_device *qcdev) 
}



/**

 * quicki2c_irq_quick_handler - The ISR of the quicki2c driver

 *

 * quicki2c_irq_quick_handler - The ISR of the QuickI2C driver

 * @irq: The irq number

 * @dev_id: pointer to the device structure

 * @dev_id: Pointer to the quicki2c_device structure

 *

 * Return: IRQ_WAKE_THREAD if further process needed.

 */
@@ -214,13 +210,13 @@ static irqreturn_t quicki2c_irq_quick_handler(int irq, void *dev_id) 


/**

 * try_recover - Try to recovery THC and Device

 * @qcdev: pointer to quicki2c device

 * @qcdev: Pointer to quicki2c_device structure

 *

 * This function is a error handler, called when fatal error happens.

 * It try to reset Touch Device and re-configure THC to recovery

 * transferring between Device and THC.

 * This function is an error handler, called when fatal error happens.

 * It try to reset touch device and re-configure THC to recovery

 * communication between touch device and THC.

 *

 * Return: 0 if successful or error code on failed

 * Return: 0 if successful or error code on failure

 */

static int try_recover(struct quicki2c_device *qcdev)

{
@@ -264,7 +260,7 @@ static int handle_input_report(struct quicki2c_device *qcdev) 
			continue;

		}



		/* discard samples before driver probe complete */

		/* Discard samples before driver probe complete */

		if (qcdev->state != QUICKI2C_ENABLED)

			continue;
@@ -276,10 +272,9 @@ static int handle_input_report(struct quicki2c_device *qcdev) 
}



/**

 * quicki2c_irq_thread_handler - IRQ thread handler of quicki2c driver

 *

 * quicki2c_irq_thread_handler - IRQ thread handler of QuickI2C driver

 * @irq: The IRQ number

 * @dev_id: pointer to the quicki2c device structure

 * @dev_id: Pointer to the quicki2c_device structure

 *

 * Return: IRQ_HANDLED to finish this handler.

 */
@@ -325,18 +320,17 @@ static irqreturn_t quicki2c_irq_thread_handler(int irq, void *dev_id) 
}



/**

 * quicki2c_dev_init - Initialize quicki2c device

 *

 * @pdev: pointer to the thc pci device

 * @mem_addr: The pointer of MMIO memory address

 * quicki2c_dev_init - Initialize QuickI2C device

 * @pdev: Pointer to the THC PCI device

 * @mem_addr: The Pointer of MMIO memory address

 *

 * Alloc quicki2c device structure and initialized THC device,

 * Alloc quicki2c_device structure and initialized THC device,

 * then configure THC to HIDI2C mode.

 *

 * If success, enable THC hardware interrupt.

 *

 * Return: pointer to the quicki2c device structure if success

 * or NULL on failed.

 * Return: Pointer to the quicki2c_device structure if success

 * or NULL on failure.

 */

static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __iomem *mem_addr)

{
@@ -355,7 +349,7 @@ static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __io 


	init_waitqueue_head(&qcdev->reset_ack_wq);



	/* thc hw init */

	/* THC hardware init */

	qcdev->thc_hw = thc_dev_init(qcdev->dev, qcdev->mem_addr);

	if (IS_ERR(qcdev->thc_hw)) {

		ret = PTR_ERR(qcdev->thc_hw);
@@ -398,9 +392,8 @@ static struct quicki2c_device *quicki2c_dev_init(struct pci_dev *pdev, void __io 
}



/**

 * quicki2c_dev_deinit - De-initialize quicki2c device

 *

 * @qcdev: pointer to the quicki2c device structure

 * quicki2c_dev_deinit - De-initialize QuickI2C device

 * @qcdev: Pointer to the quicki2c_device structure

 *

 * Disable THC interrupt and deinitilize THC.

 */
@@ -413,13 +406,13 @@ static void quicki2c_dev_deinit(struct quicki2c_device *qcdev) 
}



/**

 * quicki2c_dma_init - Configure THC DMA for quicki2c device

 * @qcdev: pointer to the quicki2c device structure

 * quicki2c_dma_init - Configure THC DMA for QuickI2C device

 * @qcdev: Pointer to the quicki2c_device structure

 *

 * This function uses TIC's parameters(such as max input length, max output

 * length) to allocate THC DMA buffers and configure THC DMA engines.

 *

 * Return: 0 if success or error code on failed.

 * Return: 0 if success or error code on failure.

 */

static int quicki2c_dma_init(struct quicki2c_device *qcdev)

{
@@ -451,12 +444,12 @@ static int quicki2c_dma_init(struct quicki2c_device *qcdev) 
		return ret;

	}



	return ret;

	return 0;

}



/**

 * quicki2c_dma_deinit - Release THC DMA for quicki2c device

 * @qcdev: pointer to the quicki2c device structure

 * quicki2c_dma_deinit - Release THC DMA for QuickI2C device

 * @qcdev: Pointer to the quicki2c_device structure

 *

 * Stop THC DMA engines and release all DMA buffers.

 *
@@ -469,7 +462,7 @@ static void quicki2c_dma_deinit(struct quicki2c_device *qcdev) 


/**

 * quicki2c_alloc_report_buf - Alloc report buffers

 * @qcdev: pointer to the quicki2c device structure

 * @qcdev: Pointer to the quicki2c_device structure

 *

 * Allocate report descriptor buffer, it will be used for restore TIC HID

 * report descriptor.
@@ -480,7 +473,7 @@ static void quicki2c_dma_deinit(struct quicki2c_device *qcdev) 
 * Allocate output report buffer, it will be used for store HID output report,

 * such as set feature.

 *

 * Return: 0 if success or error code on failed.

 * Return: 0 if success or error code on failure.

 */

static int quicki2c_alloc_report_buf(struct quicki2c_device *qcdev)

{
@@ -518,24 +511,23 @@ static int quicki2c_alloc_report_buf(struct quicki2c_device *qcdev) 
}



/*

 * quicki2c_probe: Quicki2c driver probe function

 *

 * @pdev: point to pci device

 * @id: point to pci_device_id structure

 * quicki2c_probe: QuickI2C driver probe function

 * @pdev: Point to PCI device

 * @id: Point to pci_device_id structure

 *

 * This function initializes THC and HIDI2C device, the flow is:

 * - do THC pci device initialization

 * - query HIDI2C ACPI parameters

 * - configure THC to HIDI2C mode

 * - go through HIDI2C enumeration flow

 *   |- read device descriptor

 *   |- reset HIDI2C device

 * - enable THC interrupt and DMA

 * - read report descriptor

 * - register HID device

 * - enable runtime power management

 *

 * Return 0 if success or error code on failed.

 * - Do THC pci device initialization

 * - Query HIDI2C ACPI parameters

 * - Configure THC to HIDI2C mode

 * - Go through HIDI2C enumeration flow

 *   |- Read device descriptor

 *   |- Reset HIDI2C device

 * - Enable THC interrupt and DMA

 * - Read report descriptor

 * - Register HID device

 * - Enable runtime power management

 *

 * Return 0 if success or error code on failure.

 */

static int quicki2c_probe(struct pci_dev *pdev,

			  const struct pci_device_id *id)
@@ -668,11 +660,10 @@ static int quicki2c_probe(struct pci_dev *pdev, 


/**

 * quicki2c_remove - Device Removal Routine

 * @pdev: Point to PCI device structure

 *

 * @pdev: PCI device structure

 *

 * This is called by the PCI subsystem to alert the driver

 * that it should release a PCI device.

 * This is called by the PCI subsystem to alert the driver that it should

 * release a PCI device.

 */

static void quicki2c_remove(struct pci_dev *pdev)

{
@@ -694,12 +685,10 @@ static void quicki2c_remove(struct pci_dev *pdev) 


/**

 * quicki2c_shutdown - Device Shutdown Routine

 * @pdev: Point to PCI device structure

 *

 * @pdev: PCI device structure

 *

 * This is called from the reboot notifier

 * it's a simplified version of remove so we go down

 * faster.

 * This is called from the reboot notifier, it's a simplified version of remove

 * so we go down faster.

 */

static void quicki2c_shutdown(struct pci_dev *pdev)

{

drivers/hid/intel-thc-hid/intel-quicki2c/quicki2c-dev.h

+12 −13
Original line number Diff line number Diff line
@@ -130,15 +130,14 @@ struct acpi_device; 


/**

 * struct quicki2c_device -  THC QuickI2C device struct

 * @dev: point to kernel device

 * @pdev: point to PCI device

 * @thc_hw: point to THC device

 * @hid_dev: point to hid device

 * @acpi_dev: point to ACPI device

 * @driver_data: point to quicki2c specific driver data

 * @dev: Point to kernel device

 * @pdev: Point to PCI device

 * @thc_hw: Point to THC device

 * @hid_dev: Point to HID device

 * @acpi_dev: Point to ACPI device

 * @state: THC I2C device state

 * @mem_addr: MMIO memory address

 * @dev_desc: device descriptor for HIDI2C protocol

 * @dev_desc: Device descriptor for HIDI2C protocol

 * @i2c_slave_addr: HIDI2C device slave address

 * @hid_desc_addr: Register address for retrieve HID device descriptor

 * @active_ltr_val: THC active LTR value
@@ -146,12 +145,12 @@ struct acpi_device; 
 * @i2c_speed_mode: 0 - standard mode, 1 - fast mode, 2 - fast mode plus

 * @i2c_clock_hcnt: I2C CLK high period time (unit in cycle count)

 * @i2c_clock_lcnt: I2C CLK low period time (unit in cycle count)

 * @report_descriptor: store a copy of device report descriptor

 * @input_buf: store a copy of latest input report data

 * @report_buf: store a copy of latest input/output report packet from set/get feature

 * @report_len: the length of input/output report packet

 * @reset_ack_wq: workqueue for waiting reset response from device

 * @reset_ack: indicate reset response received or not

 * @report_descriptor: Store a copy of device report descriptor

 * @input_buf: Store a copy of latest input report data

 * @report_buf: Store a copy of latest input/output report packet from set/get feature

 * @report_len: The length of input/output report packet

 * @reset_ack_wq: Workqueue for waiting reset response from device

 * @reset_ack: Indicate reset response received or not

 */

struct quicki2c_device {

	struct device *dev;