Skip to contentSkip to conversation

Fix a bunch more W=1 warnings in Misc

PATCH In review Lee Jones 3 participants 41 messages Jun 29, 2020 – Jun 30, 2020

Subsystems (3)
lore
Share & tools
lore

Lee Jones

author
#0 lore raw

cover Fix a bunch more W=1 warnings in Misc

Attempting to clean-up W=1 kernel builds, which are currently overwhelmingly riddled with niggly little warnings.

Lee Jones (20):
misc: pti: Repair kerneldoc formatting issues
misc: pti: Remove unparsable empty line in function header
misc: habanalabs: firmware_if: Add missing 'fw_name' and 'dst' entries
to function header
misc: habanalabs: pci: Fix a variety of kerneldoc issues
misc: habanalabs: irq: Repair kerneldoc formatting issues
misc: habanalabs: goya: Omit pointless check ensuring addr is >=0
misc: habanalabs: pci: Scrub documentation for non-present function
argument
misc: habanalabs: goya: goya_coresight: Remove set but unused variable

    'val'
  misc: habanalabs: gaudi: Remove ill placed asterisk from kerneldoc
    header
  misc: habanalabs: gaudi: gaudi_security: Repair incorrectly named
    function arg
  misc: enclosure: Fix some kerneldoc anomalies
  misc: lattice-ecp3-config: Remove set but clearly unused variable
    'ret'

misc: pch_phub: Provide descriptions for 'chip' argument
misc: pch_phub: Remove superfluous descriptions to non-existent args
'offset_address'
misc: enclosure: Update enclosure_remove_device() documentation to
match reality
misc: genwqe: card_base: Remove set but unused variable 'rc'
misc: genwqe: card_base: Do not pass unused argument 'fatal_err'
misc: genwqe: card_base: Whole host of kerneldoc fixes
misc: genwqe: card_dev: Whole host of kerneldoc fixes
misc: genwqe: card_utils: Whole a plethora of documentation issues

 drivers/misc/enclosure.c                      |  8 ++--
 drivers/misc/genwqe/card_base.c               | 46 ++++++++++---------
 drivers/misc/genwqe/card_dev.c                | 24 +++++++---
 drivers/misc/genwqe/card_utils.c              | 30 ++++++++++--
 drivers/misc/habanalabs/firmware_if.c         |  3 ++
 drivers/misc/habanalabs/gaudi/gaudi.c         |  2 +-
 .../misc/habanalabs/gaudi/gaudi_security.c    |  3 +-
 drivers/misc/habanalabs/goya/goya.c           | 16 +++----
 drivers/misc/habanalabs/goya/goya_coresight.c |  3 +-
 drivers/misc/habanalabs/irq.c                 | 22 ++++-----
 drivers/misc/habanalabs/pci.c                 | 13 ++++--
 drivers/misc/lattice-ecp3-config.c            | 19 ++++----
 drivers/misc/pch_phub.c                       |  9 +++-
 drivers/misc/pti.c                            | 11 ++---
 14 files changed, 126 insertions(+), 83 deletions(-)
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#1 lore raw

PATCH 1/20 misc: pti: Repair kerneldoc formatting issues

W=1 kernel builds report a lack of descriptions for various function arguments. In reality they are documented, but the formatting was not as expected '@.*:'. Instead, '-'s were used as separators.

This change fixes the following warnings:

drivers/misc/pti.c:748: warning: Function parameter or member 'port' not described in 'pti_port_activate' drivers/misc/pti.c:748: warning: Function parameter or member 'tty' not described in 'pti_port_activate' drivers/misc/pti.c:765: warning: Function parameter or member 'port' not described in 'pti_port_shutdown' drivers/misc/pti.c:793: warning: Function parameter or member 'pdev' not described in 'pti_pci_probe' drivers/misc/pti.c:793: warning: Function parameter or member 'ent' not described in 'pti_pci_probe'

---
 drivers/misc/pti.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
drivers/misc/pti.c +5 -5
index 07e9da7918ebd..e19988766aa69 100644
@@ -733,8 +733,8 @@ static struct console pti_console = {
  * pti_port_activate()- Used to start/initialize any items upon
  * first opening of tty_port().
  *
- * @port- The tty port number of the PTI device.
- * @tty-  The tty struct associated with this device.
+ * @port: The tty port number of the PTI device.
+ * @tty:  The tty struct associated with this device.
  *
  * Returns:
  *	always returns 0
@@ -754,7 +754,7 @@ static int pti_port_activate(struct tty_port *port, struct tty_struct *tty)
  * pti_port_shutdown()- Used to stop/shutdown any items upon the
  * last tty port close.
  *
- * @port- The tty port number of the PTI device.
+ * @port: The tty port number of the PTI device.
  *
  * Notes: The primary purpose of the PTI tty port 0 is to hook
  * the syslog daemon to it; thus this port will be open for a
@@ -780,8 +780,8 @@ static const struct tty_port_operations tty_port_ops = {
  * pti_pci_probe()- Used to detect pti on the pci bus and set
  *		    things up in the driver.
  *
- * @pdev- pci_dev struct values for pti.
- * @ent-  pci_device_id struct for pti driver.
+ * @pdev: pci_dev struct values for pti.
+ * @ent:  pci_device_id struct for pti driver.
  *
  * Returns:
  *	0 for success
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#2 lore raw

PATCH 2/20 misc: pti: Remove unparsable empty line in function header

In reply to Lee Jones

The kerneldoc tooling/parsers/validators get confused if non- standard formatting is used. The first line after the kerneldoc identifier '/**' must not be blank else the following warnings will be issued:

drivers/misc/pti.c:902: warning: Cannot understand * on line 902 - I thought it was a doc line

---
 drivers/misc/pti.c | 1 -
 1 file changed, 1 deletion(-)
drivers/misc/pti.c +0 -1
index e19988766aa69..7236ae527b19e 100644
@@ -898,7 +898,6 @@ static struct pci_driver pti_pci_driver = {
 };
 
 /**
- *
  * pti_init()- Overall entry/init call to the pti driver.
  *             It starts the registration process with the kernel.
  *
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#3 lore raw

PATCH 3/20 misc: habanalabs: firmware_if: Add missing 'fw_name' and 'dst' entries to function header

In reply to Lee Jones

Looks as though documentation for these function arguments have been missing since the driver's inception last year.

Fixes the following W=1 kernel build warnings:

drivers/misc/habanalabs/firmware_if.c:26: warning: Function parameter or member 'fw_name' not described in 'hl_fw_load_fw_to_device' drivers/misc/habanalabs/firmware_if.c:26: warning: Function parameter or member 'dst' not described in 'hl_fw_load_fw_to_device'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/firmware_if.c | 3 +++
 1 file changed, 3 insertions(+)
drivers/misc/habanalabs/firmware_if.c +3 -0
index baf790cf4b787..15e0793da6554 100644
@@ -15,7 +15,10 @@
 
 /**
  * hl_fw_load_fw_to_device() - Load F/W code to device's memory.
+ *
  * @hdev: pointer to hl_device structure.
+ * @fw_name: the firmware image name
+ * @dst: IO memory mapped address space to copy firmware to
  *
  * Copy fw code from firmware file to device memory.
  *
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 3/20
#4 lore raw

Re: [PATCH 03/20] misc: habanalabs: firmware_if: Add missing 'fw_name' and 'dst' entries to function header

Quoted 32 lines · Lee Jones

Looks as though documentation for these function arguments have been missing since the driver's inception last year.

Fixes the following W=1 kernel build warnings:

drivers/misc/habanalabs/firmware_if.c:26: warning: Function parameter or member 'fw_name' not described in 'hl_fw_load_fw_to_device' drivers/misc/habanalabs/firmware_if.c:26: warning: Function parameter or member 'dst' not described in 'hl_fw_load_fw_to_device'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/firmware_if.c | 3 +++
 1 file changed, 3 insertions(+)
drivers/misc/habanalabs/firmware_if.c +3 -1
index baf790cf4b787..15e0793da6554 100644
@@ -15,7 +15,10 @@
 
 /**
  * hl_fw_load_fw_to_device() - Load F/W code to device's memory.
+ *
  * @hdev: pointer to hl_device structure.
+ * @fw_name: the firmware image name
+ * @dst: IO memory mapped address space to copy firmware to
  *
  * Copy fw code from firmware file to device memory.
  *
--
Quoted 2 lines

2.25.1

This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#5 lore raw

PATCH 4/20 misc: habanalabs: pci: Fix a variety of kerneldoc issues

In reply to Lee Jones

hl_pci_bars_map() has a miss-typed argument name in the function description. hl_pci_elbi_write() was missing documented arguments. The headers for functions hl_pci_bars_unmap(), hl_pci_elbi_write() and hl_pci_reset_link_through_bridge() were written in kerneldoc format, but lack the kerneldoc identifier '/**'. Let's promote them so they can gain access to the checker.

These changes fix the following W=1 kernel build warnings:

drivers/misc/habanalabs/pci.c:27: warning: Function parameter or member 'name' not described in 'hl_pci_bars_map' drivers/misc/habanalabs/pci.c:27: warning: Excess function parameter 'bar_name' description in 'hl_pci_bars_map' drivers/misc/habanalabs/pci.c:147: warning: Function parameter or member 'addr' not described in 'hl_pci_iatu_write' drivers/misc/habanalabs/pci.c:147: warning: Function parameter or member 'data' not described in 'hl_pci_iatu_write' drivers/misc/habanalabs/pci.c:324: warning: Excess function parameter 'dma_mask' description in 'hl_pci_set_dma_mask'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/pci.c | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)
drivers/misc/habanalabs/pci.c +8 -4
index 9f634ef6f5b37..24073e8eb8df9 100644
@@ -15,7 +15,7 @@
 /**
  * hl_pci_bars_map() - Map PCI BARs.
  * @hdev: Pointer to hl_device structure.
- * @bar_name: Array of BAR names.
+ * @name: Array of BAR names.
  * @is_wc: Array with flag per BAR whether a write-combined mapping is needed.
  *
  * Request PCI regions and map them to kernel virtual addresses.
@@ -61,7 +61,7 @@ int hl_pci_bars_map(struct hl_device *hdev, const char * const name[3],
 	return rc;
 }
 
-/*
+/**
  * hl_pci_bars_unmap() - Unmap PCI BARS.
  * @hdev: Pointer to hl_device structure.
  *
@@ -80,9 +80,11 @@ static void hl_pci_bars_unmap(struct hl_device *hdev)
 	pci_release_regions(pdev);
 }
 
-/*
+/**
  * hl_pci_elbi_write() - Write through the ELBI interface.
  * @hdev: Pointer to hl_device structure.
+ * @addr: Address to write to
+ * @data: Data to write
  *
  * Return: 0 on success, negative value for failure.
  */
@@ -140,6 +142,8 @@ static int hl_pci_elbi_write(struct hl_device *hdev, u64 addr, u32 data)
 /**
  * hl_pci_iatu_write() - iatu write routine.
  * @hdev: Pointer to hl_device structure.
+ * @addr: Address to write to
+ * @data: Data to write
  *
  * Return: 0 on success, negative value for failure.
  */
@@ -161,7 +165,7 @@ int hl_pci_iatu_write(struct hl_device *hdev, u32 addr, u32 data)
 	return 0;
 }
 
-/*
+/**
  * hl_pci_reset_link_through_bridge() - Reset PCI link.
  * @hdev: Pointer to hl_device structure.
  */
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 4/20
#6 lore raw

Re: [PATCH 04/20] misc: habanalabs: pci: Fix a variety of kerneldoc issues

Quoted 77 lines · Lee Jones

hl_pci_bars_map() has a miss-typed argument name in the function description. hl_pci_elbi_write() was missing documented arguments. The headers for functions hl_pci_bars_unmap(), hl_pci_elbi_write() and hl_pci_reset_link_through_bridge() were written in kerneldoc format, but lack the kerneldoc identifier '/**'. Let's promote them so they can gain access to the checker.

These changes fix the following W=1 kernel build warnings:

drivers/misc/habanalabs/pci.c:27: warning: Function parameter or member 'name' not described in 'hl_pci_bars_map' drivers/misc/habanalabs/pci.c:27: warning: Excess function parameter 'bar_name' description in 'hl_pci_bars_map' drivers/misc/habanalabs/pci.c:147: warning: Function parameter or member 'addr' not described in 'hl_pci_iatu_write' drivers/misc/habanalabs/pci.c:147: warning: Function parameter or member 'data' not described in 'hl_pci_iatu_write' drivers/misc/habanalabs/pci.c:324: warning: Excess function parameter 'dma_mask' description in 'hl_pci_set_dma_mask'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/pci.c | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)
drivers/misc/habanalabs/pci.c +8 -5
index 9f634ef6f5b37..24073e8eb8df9 100644
@@ -15,7 +15,7 @@
 /**
  * hl_pci_bars_map() - Map PCI BARs.
  * @hdev: Pointer to hl_device structure.
- * @bar_name: Array of BAR names.
+ * @name: Array of BAR names.
  * @is_wc: Array with flag per BAR whether a write-combined mapping is needed.
  *
  * Request PCI regions and map them to kernel virtual addresses.
@@ -61,7 +61,7 @@ int hl_pci_bars_map(struct hl_device *hdev, const char * const name[3],
        return rc;
 }
 
-/*
+/**
  * hl_pci_bars_unmap() - Unmap PCI BARS.
  * @hdev: Pointer to hl_device structure.
  *
@@ -80,9 +80,11 @@ static void hl_pci_bars_unmap(struct hl_device *hdev)
        pci_release_regions(pdev);
 }
 
-/*
+/**
  * hl_pci_elbi_write() - Write through the ELBI interface.
  * @hdev: Pointer to hl_device structure.
+ * @addr: Address to write to
+ * @data: Data to write
  *
  * Return: 0 on success, negative value for failure.
  */
@@ -140,6 +142,8 @@ static int hl_pci_elbi_write(struct hl_device *hdev, u64 addr, u32 data)
 /**
  * hl_pci_iatu_write() - iatu write routine.
  * @hdev: Pointer to hl_device structure.
+ * @addr: Address to write to
+ * @data: Data to write
  *
  * Return: 0 on success, negative value for failure.
  */
@@ -161,7 +165,7 @@ int hl_pci_iatu_write(struct hl_device *hdev, u32 addr, u32 data)
        return 0;
 }
 
-/*
+/**
  * hl_pci_reset_link_through_bridge() - Reset PCI link.
  * @hdev: Pointer to hl_device structure.
  */
--
Quoted 2 lines

2.25.1

This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#7 lore raw

PATCH 5/20 misc: habanalabs: irq: Repair kerneldoc formatting issues

In reply to Lee Jones

W=1 kernel builds report a lack of descriptions for various function arguments. In reality they are documented, but the formatting was not as expected '@.*:'. Instead, '-'s were used as separators.

While we're here, the headers for functions various functions were written in kerneldoc format, but lack the kerneldoc identifier '/**'. Let's promote them so they can gain access to the checker.

This change fixes the following W=1 warnings:

drivers/misc/habanalabs/irq.c:24: warning: Function parameter or member 'eq_work' not described in 'hl_eqe_work' drivers/misc/habanalabs/irq.c:24: warning: Function parameter or member 'hdev' not described in 'hl_eqe_work' drivers/misc/habanalabs/irq.c:24: warning: Function parameter or member 'eq_entry' not described in 'hl_eqe_work'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/irq.c | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
drivers/misc/habanalabs/irq.c +11 -11
index 4e77a73857793..6981d67153b11 100644
@@ -13,9 +13,9 @@
  * struct hl_eqe_work - This structure is used to schedule work of EQ
  *                      entry and armcp_reset event
  *
- * @eq_work          - workqueue object to run when EQ entry is received
- * @hdev             - pointer to device structure
- * @eq_entry         - copy of the EQ entry
+ * @eq_work:          workqueue object to run when EQ entry is received
+ * @hdev:             pointer to device structure
+ * @eq_entry:         copy of the EQ entry
  */
 struct hl_eqe_work {
 	struct work_struct	eq_work;
@@ -23,7 +23,7 @@ struct hl_eqe_work {
 	struct hl_eq_entry	eq_entry;
 };
 
-/*
+/**
  * hl_cq_inc_ptr - increment ci or pi of cq
  *
  * @ptr: the current ci or pi value of the completion queue
@@ -39,7 +39,7 @@ inline u32 hl_cq_inc_ptr(u32 ptr)
 	return ptr;
 }
 
-/*
+/**
  * hl_eq_inc_ptr - increment ci of eq
  *
  * @ptr: the current ci value of the event queue
@@ -66,7 +66,7 @@ static void irq_handle_eqe(struct work_struct *work)
 	kfree(eqe_work);
 }
 
-/*
+/**
  * hl_irq_handler_cq - irq handler for completion queue
  *
  * @irq: irq number
@@ -142,7 +142,7 @@ irqreturn_t hl_irq_handler_cq(int irq, void *arg)
 	return IRQ_HANDLED;
 }
 
-/*
+/**
  * hl_irq_handler_eq - irq handler for event queue
  *
  * @irq: irq number
@@ -206,7 +206,7 @@ irqreturn_t hl_irq_handler_eq(int irq, void *arg)
 	return IRQ_HANDLED;
 }
 
-/*
+/**
  * hl_cq_init - main initialization function for an cq object
  *
  * @hdev: pointer to device structure
@@ -238,7 +238,7 @@ int hl_cq_init(struct hl_device *hdev, struct hl_cq *q, u32 hw_queue_id)
 	return 0;
 }
 
-/*
+/**
  * hl_cq_fini - destroy completion queue
  *
  * @hdev: pointer to device structure
@@ -269,7 +269,7 @@ void hl_cq_reset(struct hl_device *hdev, struct hl_cq *q)
 	memset((void *) (uintptr_t) q->kernel_address, 0, HL_CQ_SIZE_IN_BYTES);
 }
 
-/*
+/**
  * hl_eq_init - main initialization function for an event queue object
  *
  * @hdev: pointer to device structure
@@ -297,7 +297,7 @@ int hl_eq_init(struct hl_device *hdev, struct hl_eq *q)
 	return 0;
 }
 
-/*
+/**
  * hl_eq_fini - destroy event queue
  *
  * @hdev: pointer to device structure
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 5/20
#8 lore raw

Re: [PATCH 05/20] misc: habanalabs: irq: Repair kerneldoc formatting issues

Quoted 114 lines · Lee Jones

W=1 kernel builds report a lack of descriptions for various function arguments. In reality they are documented, but the formatting was not as expected '@.*:'. Instead, '-'s were used as separators.

While we're here, the headers for functions various functions were written in kerneldoc format, but lack the kerneldoc identifier '/**'. Let's promote them so they can gain access to the checker.

This change fixes the following W=1 warnings:

drivers/misc/habanalabs/irq.c:24: warning: Function parameter or member 'eq_work' not described in 'hl_eqe_work' drivers/misc/habanalabs/irq.c:24: warning: Function parameter or member 'hdev' not described in 'hl_eqe_work' drivers/misc/habanalabs/irq.c:24: warning: Function parameter or member 'eq_entry' not described in 'hl_eqe_work'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/irq.c | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
drivers/misc/habanalabs/irq.c +11 -12
index 4e77a73857793..6981d67153b11 100644
@@ -13,9 +13,9 @@
  * struct hl_eqe_work - This structure is used to schedule work of EQ
  *                      entry and armcp_reset event
  *
- * @eq_work          - workqueue object to run when EQ entry is received
- * @hdev             - pointer to device structure
- * @eq_entry         - copy of the EQ entry
+ * @eq_work:          workqueue object to run when EQ entry is received
+ * @hdev:             pointer to device structure
+ * @eq_entry:         copy of the EQ entry
  */
 struct hl_eqe_work {
        struct work_struct      eq_work;
@@ -23,7 +23,7 @@ struct hl_eqe_work {
        struct hl_eq_entry      eq_entry;
 };
 
-/*
+/**
  * hl_cq_inc_ptr - increment ci or pi of cq
  *
  * @ptr: the current ci or pi value of the completion queue
@@ -39,7 +39,7 @@ inline u32 hl_cq_inc_ptr(u32 ptr)
        return ptr;
 }
 
-/*
+/**
  * hl_eq_inc_ptr - increment ci of eq
  *
  * @ptr: the current ci value of the event queue
@@ -66,7 +66,7 @@ static void irq_handle_eqe(struct work_struct *work)
        kfree(eqe_work);
 }
 
-/*
+/**
  * hl_irq_handler_cq - irq handler for completion queue
  *
  * @irq: irq number
@@ -142,7 +142,7 @@ irqreturn_t hl_irq_handler_cq(int irq, void *arg)
        return IRQ_HANDLED;
 }
 
-/*
+/**
  * hl_irq_handler_eq - irq handler for event queue
  *
  * @irq: irq number
@@ -206,7 +206,7 @@ irqreturn_t hl_irq_handler_eq(int irq, void *arg)
        return IRQ_HANDLED;
 }
 
-/*
+/**
  * hl_cq_init - main initialization function for an cq object
  *
  * @hdev: pointer to device structure
@@ -238,7 +238,7 @@ int hl_cq_init(struct hl_device *hdev, struct hl_cq *q, u32 hw_queue_id)
        return 0;
 }
 
-/*
+/**
  * hl_cq_fini - destroy completion queue
  *
  * @hdev: pointer to device structure
@@ -269,7 +269,7 @@ void hl_cq_reset(struct hl_device *hdev, struct hl_cq *q)
        memset((void *) (uintptr_t) q->kernel_address, 0, HL_CQ_SIZE_IN_BYTES);
 }
 
-/*
+/**
  * hl_eq_init - main initialization function for an event queue object
  *
  * @hdev: pointer to device structure
@@ -297,7 +297,7 @@ int hl_eq_init(struct hl_device *hdev, struct hl_eq *q)
        return 0;
 }
 
-/*
+/**
  * hl_eq_fini - destroy event queue
  *
  * @hdev: pointer to device structure
--
Quoted 2 lines

2.25.1

This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#9 lore raw

PATCH 6/20 misc: habanalabs: goya: Omit pointless check ensuring addr is >=0

In reply to Lee Jones

Seeing as 'addr' is unsigned, it would be impossible for the assigned value to be anything other than zero or positive.

Squashes the following W=1 warnings:

drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_read32’:
drivers/misc/habanalabs/goya/goya.c:3945:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 3945 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_write32’:
drivers/misc/habanalabs/goya/goya.c:4002:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 4002 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_read64’:
drivers/misc/habanalabs/goya/goya.c:4047:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 4047 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_write64’:
drivers/misc/habanalabs/goya/goya.c:4091:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 4091 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/pci.c:328: warning: Excess function parameter 'dma_mask' description in 'hl_pci_set_dma_mask' drivers/misc/habanalabs/goya/goya_coresight.c: In function ‘goya_debug_coresight’:
drivers/misc/habanalabs/goya/goya_coresight.c:643:6: warning: variable ‘val’ set but not used [-Wunused-but-set-variable] 643 | u32 val;
| ^~~

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/goya/goya.c | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)
drivers/misc/habanalabs/goya/goya.c +6 -10
index 0d2952bb58dfb..a4a20e27ed3b4 100644
@@ -3942,8 +3942,7 @@ static int goya_debugfs_read32(struct hl_device *hdev, u64 addr, u32 *val)
 		*val = readl(hdev->pcie_bar[SRAM_CFG_BAR_ID] +
 				(addr - SRAM_BASE_ADDR));
 
-	} else if ((addr >= DRAM_PHYS_BASE) &&
-			(addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size)) {
+	} else if (addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size) {
 
 		u64 bar_base_addr = DRAM_PHYS_BASE +
 				(addr & ~(prop->dram_pci_bar_size - 0x1ull));
@@ -3999,8 +3998,7 @@ static int goya_debugfs_write32(struct hl_device *hdev, u64 addr, u32 val)
 		writel(val, hdev->pcie_bar[SRAM_CFG_BAR_ID] +
 					(addr - SRAM_BASE_ADDR));
 
-	} else if ((addr >= DRAM_PHYS_BASE) &&
-			(addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size)) {
+	} else if (addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size) {
 
 		u64 bar_base_addr = DRAM_PHYS_BASE +
 				(addr & ~(prop->dram_pci_bar_size - 0x1ull));
@@ -4044,9 +4042,8 @@ static int goya_debugfs_read64(struct hl_device *hdev, u64 addr, u64 *val)
 		*val = readq(hdev->pcie_bar[SRAM_CFG_BAR_ID] +
 				(addr - SRAM_BASE_ADDR));
 
-	} else if ((addr >= DRAM_PHYS_BASE) &&
-		   (addr <=
-		    DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64))) {
+	} else if (addr <=
+		   DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64)) {
 
 		u64 bar_base_addr = DRAM_PHYS_BASE +
 				(addr & ~(prop->dram_pci_bar_size - 0x1ull));
@@ -4088,9 +4085,8 @@ static int goya_debugfs_write64(struct hl_device *hdev, u64 addr, u64 val)
 		writeq(val, hdev->pcie_bar[SRAM_CFG_BAR_ID] +
 					(addr - SRAM_BASE_ADDR));
 
-	} else if ((addr >= DRAM_PHYS_BASE) &&
-		   (addr <=
-		    DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64))) {
+	} else if (addr <=
+		   DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64)) {
 
 		u64 bar_base_addr = DRAM_PHYS_BASE +
 				(addr & ~(prop->dram_pci_bar_size - 0x1ull));
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 6/20
#10 lore raw

Re: [PATCH 06/20] misc: habanalabs: goya: Omit pointless check ensuring addr is >=0

Quoted 84 lines · Lee Jones

Seeing as 'addr' is unsigned, it would be impossible for the assigned value to be anything other than zero or positive.

Squashes the following W=1 warnings:

drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_read32’:
drivers/misc/habanalabs/goya/goya.c:3945:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 3945 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_write32’:
drivers/misc/habanalabs/goya/goya.c:4002:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 4002 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_read64’:
drivers/misc/habanalabs/goya/goya.c:4047:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 4047 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/goya/goya.c: In function ‘goya_debugfs_write64’:
drivers/misc/habanalabs/goya/goya.c:4091:19: warning: comparison of unsigned expression >= 0 is always true [-Wtype-limits] 4091 | } else if ((addr >= DRAM_PHYS_BASE) &&
| ^~
drivers/misc/habanalabs/pci.c:328: warning: Excess function parameter 'dma_mask' description in 'hl_pci_set_dma_mask' drivers/misc/habanalabs/goya/goya_coresight.c: In function ‘goya_debug_coresight’:
drivers/misc/habanalabs/goya/goya_coresight.c:643:6: warning: variable ‘val’ set but not used [-Wunused-but-set-variable] 643 | u32 val;
| ^~~

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/goya/goya.c | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)
drivers/misc/habanalabs/goya/goya.c +6 -11
index 0d2952bb58dfb..a4a20e27ed3b4 100644
@@ -3942,8 +3942,7 @@ static int goya_debugfs_read32(struct hl_device *hdev, u64 addr, u32 *val)
                *val = readl(hdev->pcie_bar[SRAM_CFG_BAR_ID] +
                                (addr - SRAM_BASE_ADDR));
 
-       } else if ((addr >= DRAM_PHYS_BASE) &&
-                       (addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size)) {
+       } else if (addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size) {
 
                u64 bar_base_addr = DRAM_PHYS_BASE +
                                (addr & ~(prop->dram_pci_bar_size - 0x1ull));
@@ -3999,8 +3998,7 @@ static int goya_debugfs_write32(struct hl_device *hdev, u64 addr, u32 val)
                writel(val, hdev->pcie_bar[SRAM_CFG_BAR_ID] +
                                        (addr - SRAM_BASE_ADDR));
 
-       } else if ((addr >= DRAM_PHYS_BASE) &&
-                       (addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size)) {
+       } else if (addr < DRAM_PHYS_BASE + hdev->asic_prop.dram_size) {
 
                u64 bar_base_addr = DRAM_PHYS_BASE +
                                (addr & ~(prop->dram_pci_bar_size - 0x1ull));
@@ -4044,9 +4042,8 @@ static int goya_debugfs_read64(struct hl_device *hdev, u64 addr, u64 *val)
                *val = readq(hdev->pcie_bar[SRAM_CFG_BAR_ID] +
                                (addr - SRAM_BASE_ADDR));
 
-       } else if ((addr >= DRAM_PHYS_BASE) &&
-                  (addr <=
-                   DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64))) {
+       } else if (addr <=
+                  DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64)) {
 
                u64 bar_base_addr = DRAM_PHYS_BASE +
                                (addr & ~(prop->dram_pci_bar_size - 0x1ull));
@@ -4088,9 +4085,8 @@ static int goya_debugfs_write64(struct hl_device *hdev, u64 addr, u64 val)
                writeq(val, hdev->pcie_bar[SRAM_CFG_BAR_ID] +
                                        (addr - SRAM_BASE_ADDR));
 
-       } else if ((addr >= DRAM_PHYS_BASE) &&
-                  (addr <=
-                   DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64))) {
+       } else if (addr <=
+                  DRAM_PHYS_BASE + hdev->asic_prop.dram_size - sizeof(u64)) {
 
                u64 bar_base_addr = DRAM_PHYS_BASE +
                                (addr & ~(prop->dram_pci_bar_size - 0x1ull));
--
Quoted 2 lines

2.25.1

This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#11 lore raw

PATCH 7/20 misc: habanalabs: pci: Scrub documentation for non-present function argument

In reply to Lee Jones

'dma_mask' is not passed directly into hl_pci_set_dma_mask() as an argument. Instead, it is pulled from struct hl_device *hdev.

Fixed the following W=1 warning:

drivers/misc/habanalabs/pci.c:328: warning: Excess function parameter 'dma_mask' description in 'hl_pci_set_dma_mask

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/pci.c | 1 -
 1 file changed, 1 deletion(-)
drivers/misc/habanalabs/pci.c +0 -1
index 24073e8eb8df9..61a8bb07262cf 100644
@@ -317,7 +317,6 @@ int hl_pci_init_iatu(struct hl_device *hdev, u64 sram_base_address,
 /**
  * hl_pci_set_dma_mask() - Set DMA masks for the device.
  * @hdev: Pointer to hl_device structure.
- * @dma_mask: number of bits for the requested dma mask.
  *
  * This function sets the DMA masks (regular and consistent) for a specified
  * value. If it doesn't succeed, it tries to set it to a fall-back value
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 7/20
#12 lore raw

Re: [PATCH 07/20] misc: habanalabs: pci: Scrub documentation for non-present function argument

Quoted 28 lines · Lee Jones

'dma_mask' is not passed directly into hl_pci_set_dma_mask() as an argument. Instead, it is pulled from struct hl_device *hdev.

Fixed the following W=1 warning:

drivers/misc/habanalabs/pci.c:328: warning: Excess function parameter 'dma_mask' description in 'hl_pci_set_dma_mask

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/pci.c | 1 -
 1 file changed, 1 deletion(-)
drivers/misc/habanalabs/pci.c +0 -2
index 24073e8eb8df9..61a8bb07262cf 100644
@@ -317,7 +317,6 @@ int hl_pci_init_iatu(struct hl_device *hdev, u64 sram_base_address,
 /**
  * hl_pci_set_dma_mask() - Set DMA masks for the device.
  * @hdev: Pointer to hl_device structure.
- * @dma_mask: number of bits for the requested dma mask.
  *
  * This function sets the DMA masks (regular and consistent) for a specified
  * value. If it doesn't succeed, it tries to set it to a fall-back value
--
Quoted 2 lines

2.25.1

This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#13 lore raw

PATCH 8/20 misc: habanalabs: goya: goya_coresight: Remove set but unused variable 'val'

In reply to Lee Jones

No attempt to check the return value of RREG32() has been made since the call was introduced a year ago.

Fixes W=1 kernel build warning:

drivers/misc/habanalabs/goya/goya_coresight.c: In function ‘goya_debug_coresight’:
drivers/misc/habanalabs/goya/goya_coresight.c:643:6: warning: variable ‘val’ set but not used [-Wunused-but-set-variable] 643 | u32 val;
| ^~~

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/goya/goya_coresight.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
drivers/misc/habanalabs/goya/goya_coresight.c +1 -2
index 1258724ea5106..aa51fc71f0a1f 100644
@@ -640,7 +640,6 @@ static int goya_config_spmu(struct hl_device *hdev,
 int goya_debug_coresight(struct hl_device *hdev, void *data)
 {
 	struct hl_debug_params *params = data;
-	u32 val;
 	int rc = 0;
 
 	switch (params->op) {
@@ -672,7 +671,7 @@ int goya_debug_coresight(struct hl_device *hdev, void *data)
 	}
 
 	/* Perform read from the device to flush all configuration */
-	val = RREG32(mmPCIE_DBI_DEVICE_ID_VENDOR_ID_REG);
+	RREG32(mmPCIE_DBI_DEVICE_ID_VENDOR_ID_REG);
 
 	return rc;
 }
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 8/20
#14 lore raw

Re: [PATCH 08/20] misc: habanalabs: goya: goya_coresight: Remove set but unused variable 'val'

Quoted 40 lines · Lee Jones

No attempt to check the return value of RREG32() has been made since the call was introduced a year ago.

Fixes W=1 kernel build warning:

drivers/misc/habanalabs/goya/goya_coresight.c: In function ‘goya_debug_coresight’:
drivers/misc/habanalabs/goya/goya_coresight.c:643:6: warning: variable ‘val’ set but not used [-Wunused-but-set-variable] 643 | u32 val;
| ^~~

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/goya/goya_coresight.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
drivers/misc/habanalabs/goya/goya_coresight.c +1 -3
index 1258724ea5106..aa51fc71f0a1f 100644
@@ -640,7 +640,6 @@ static int goya_config_spmu(struct hl_device *hdev,
 int goya_debug_coresight(struct hl_device *hdev, void *data)
 {
        struct hl_debug_params *params = data;
-       u32 val;
        int rc = 0;
 
        switch (params->op) {
@@ -672,7 +671,7 @@ int goya_debug_coresight(struct hl_device *hdev, void *data)
        }
 
        /* Perform read from the device to flush all configuration */
-       val = RREG32(mmPCIE_DBI_DEVICE_ID_VENDOR_ID_REG);
+       RREG32(mmPCIE_DBI_DEVICE_ID_VENDOR_ID_REG);
 
        return rc;
 }
--
Quoted 2 lines

2.25.1

This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#15 lore raw

PATCH 9/20 misc: habanalabs: gaudi: Remove ill placed asterisk from kerneldoc header

In reply to Lee Jones

W=1 kernel builds report a lack of description of gaudi_set_asic_funcs()'s 'hdev' argument. In reality it is documented, but the formatting was not as expected '@.*:'. Instead, there was a misplaced asterisk which was confusing the kerneldoc validator.

Squashes the following W=1 warning:

drivers/misc/habanalabs/gaudi/gaudi.c:6746: warning: Function parameter or member 'hdev' not described in 'gaudi_set_asic_funcs'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/gaudi/gaudi.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/misc/habanalabs/gaudi/gaudi.c +1 -1
index 61f88e9884ce9..bdb9c0080c464 100644
@@ -6739,7 +6739,7 @@ static const struct hl_asic_funcs gaudi_funcs = {
 /**
  * gaudi_set_asic_funcs - set GAUDI function pointers
  *
- * @*hdev: pointer to hl_device structure
+ * @hdev: pointer to hl_device structure
  *
  */
 void gaudi_set_asic_funcs(struct hl_device *hdev)
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 9/20
#16 lore raw

Re: [PATCH 09/20] misc: habanalabs: gaudi: Remove ill placed asterisk from kerneldoc header

Quoted 31 lines · Lee Jones

W=1 kernel builds report a lack of description of gaudi_set_asic_funcs()'s 'hdev' argument. In reality it is documented, but the formatting was not as expected '@.*:'. Instead, there was a misplaced asterisk which was confusing the kerneldoc validator.

Squashes the following W=1 warning:

drivers/misc/habanalabs/gaudi/gaudi.c:6746: warning: Function parameter or member 'hdev' not described in 'gaudi_set_asic_funcs'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/gaudi/gaudi.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/misc/habanalabs/gaudi/gaudi.c +1 -2
index 61f88e9884ce9..bdb9c0080c464 100644
@@ -6739,7 +6739,7 @@ static const struct hl_asic_funcs gaudi_funcs = {
 /**
  * gaudi_set_asic_funcs - set GAUDI function pointers
  *
- * @*hdev: pointer to hl_device structure
+ * @hdev: pointer to hl_device structure
  *
  */
 void gaudi_set_asic_funcs(struct hl_device *hdev)
--
Quoted 2 lines

2.25.1

This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#17 lore raw

PATCH 10/20 misc: habanalabs: gaudi: gaudi_security: Repair incorrectly named function arg

In reply to Lee Jones

audi_pb_set_block()'s argument 'base' was incorrectly named 'block' in its function header.

Fixes the following W=1 kernel build warning(s):

drivers/misc/habanalabs/gaudi/gaudi_security.c:454: warning: Function parameter or member 'base' not described in 'gaudi_pb_set_block' drivers/misc/habanalabs/gaudi/gaudi_security.c:454: warning: Excess function parameter 'block' description in 'gaudi_pb_set_block'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/gaudi/gaudi_security.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
drivers/misc/habanalabs/gaudi/gaudi_security.c +1 -2
index 6a351e31fa6af..abdd5ed8f2cf6 100644
@@ -447,8 +447,7 @@ static u64 gaudi_rr_hbw_mask_high_ar_regs[GAUDI_NUMBER_OF_RR_REGS] = {
  * gaudi_set_block_as_protected - set the given block as protected
  *
  * @hdev: pointer to hl_device structure
- * @block: block base address
- *
+ * @base: block base address
  */
 static void gaudi_pb_set_block(struct hl_device *hdev, u64 base)
 {
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
Reviewed-by on v1 10/20
#18 lore raw

Re: [PATCH 10/20] misc: habanalabs: gaudi: gaudi_security: Repair incorrectly named function arg

Quoted 2 lines · Lee Jones

audi_pb_set_block()'s argument 'base' was incorrectly named 'block' in

gaudi_pb_set_block()'s

Quoted 29 lines

its function header.

Fixes the following W=1 kernel build warning(s):

drivers/misc/habanalabs/gaudi/gaudi_security.c:454: warning: Function parameter or member 'base' not described in 'gaudi_pb_set_block' drivers/misc/habanalabs/gaudi/gaudi_security.c:454: warning: Excess function parameter 'block' description in 'gaudi_pb_set_block'

Cc Oded Gabbay <[email protected]>
Cc Tomer Tayar <[email protected]>
---
 drivers/misc/habanalabs/gaudi/gaudi_security.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
drivers/misc/habanalabs/gaudi/gaudi_security.c +1 -3
index 6a351e31fa6af..abdd5ed8f2cf6 100644
@@ -447,8 +447,7 @@ static u64 gaudi_rr_hbw_mask_high_ar_regs[GAUDI_NUMBER_OF_RR_REGS] = {
  * gaudi_set_block_as_protected - set the given block as protected
  *
  * @hdev: pointer to hl_device structure
- * @block: block base address
- *
+ * @base: block base address
  */
 static void gaudi_pb_set_block(struct hl_device *hdev, u64 base)
 {
--
Quoted 2 lines

2.25.1

With the above fix, This patch is:

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#19 lore raw

PATCH v2 10/20 misc: habanalabs: gaudi: gaudi_security: Repair incorrectly named function arg

In reply to Lee Jones

misc: habanalabs: gaudi: gaudi_security: Repair incorrectly named function arg

gaudi_pb_set_block()'s argument 'base' was incorrectly named 'block' in its function header.

Fixes the following W=1 kernel build warning(s):

drivers/misc/habanalabs/gaudi/gaudi_security.c:454: warning: Function parameter or member 'base' not described in 'gaudi_pb_set_block' drivers/misc/habanalabs/gaudi/gaudi_security.c:454: warning: Excess function parameter 'block' description in 'gaudi_pb_set_block'

drivers/misc/habanalabs/gaudi/gaudi_security.c +1 -2
index 6a351e31fa6af..abdd5ed8f2cf6 100644
@@ -447,8 +447,7 @@ static u64 gaudi_rr_hbw_mask_high_ar_regs[GAUDI_NUMBER_OF_RR_REGS] = {
  * gaudi_set_block_as_protected - set the given block as protected
  *
  * @hdev: pointer to hl_device structure
- * @block: block base address
- *
+ * @base: block base address
  */
 static void gaudi_pb_set_block(struct hl_device *hdev, u64 base)
 {

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

author
#20 lore raw

PATCH 11/20 misc: enclosure: Fix some kerneldoc anomalies

In reply to Lee Jones

Firstly some missing function argument documentation, then some whch are present, but are incorrectly named.

Fixes the following W=1 kernel build warnings:

drivers/misc/enclosure.c:115: warning: Function parameter or member 'name' not described in 'enclosure_register' drivers/misc/enclosure.c:115: warning: Function parameter or member 'cb' not described in 'enclosure_register' drivers/misc/enclosure.c:283: warning: Function parameter or member 'number' not described in 'enclosure_component_alloc' drivers/misc/enclosure.c:283: warning: Excess function parameter 'num' description in 'enclosure_component_alloc' drivers/misc/enclosure.c:363: warning: Function parameter or member 'component' not described in 'enclosure_add_device' drivers/misc/enclosure.c:363: warning: Excess function parameter 'num' description in 'enclosure_add_device' drivers/misc/enclosure.c:398: warning: Function parameter or member 'dev' not described in 'enclosure_remove_device' drivers/misc/enclosure.c:398: warning: Excess function parameter 'num' description in 'enclosure_remove_device'

Cc James Bottomley <[email protected]>
---
 drivers/misc/enclosure.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
drivers/misc/enclosure.c +4 -2
index 3c2d405bc79b9..e8eba52750b34 100644
@@ -103,7 +103,9 @@ EXPORT_SYMBOL_GPL(enclosure_for_each_device);
  * enclosure_register - register device as an enclosure
  *
  * @dev:	device containing the enclosure
+ * @name:	chosen device name
  * @components:	number of components in the enclosure
+ * @cb:         platform call-backs
  *
  * This sets up the device for being an enclosure.  Note that @dev does
  * not have to be a dedicated enclosure device.  It may be some other type
@@ -266,7 +268,7 @@ static const struct attribute_group *enclosure_component_groups[];
 /**
  * enclosure_component_alloc - prepare a new enclosure component
  * @edev:	the enclosure to add the component
- * @num:	the device number
+ * @number:	the device number
  * @type:	the type of component being added
  * @name:	an optional name to appear in sysfs (leave NULL if none)
  *
@@ -347,7 +349,7 @@ EXPORT_SYMBOL_GPL(enclosure_component_register);
 /**
  * enclosure_add_device - add a device as being part of an enclosure
  * @edev:	the enclosure device being added to.
- * @num:	the number of the component
+ * @component:	the number of the component
  * @dev:	the device being added
  *
  * Declares a real device to reside in slot (or identifier) @num of an
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#21 lore raw

PATCH 12/20 misc: lattice-ecp3-config: Remove set but clearly unused variable 'ret'

In reply to Lee Jones

It's odd for the return value to be assigned to a variable so many times, but never actually checked, but this has been the case since the driver's inception in 2012. If it hasn't caused any issues by now, it's probably unlikely to. Let's take it out, at least until someone finds a reason to start using it.

Fixes the following W=1 kernel build warning:

drivers/misc/lattice-ecp3-config.c: In function ‘firmware_load’:
drivers/misc/lattice-ecp3-config.c:70:6: warning: variable ‘ret’ set but not used [-Wunused-but-set-variable] 70 | int ret;
| ^~~

Cc Stefan Roese <[email protected]>
---
 drivers/misc/lattice-ecp3-config.c | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)
drivers/misc/lattice-ecp3-config.c +9 -10
index 884485c3f7232..5eaf74447ca1e 100644
@@ -67,7 +67,6 @@ static void firmware_load(const struct firmware *fw, void *context)
 	struct spi_device *spi = (struct spi_device *)context;
 	struct fpga_data *data = spi_get_drvdata(spi);
 	u8 *buffer;
-	int ret;
 	u8 txbuf[8];
 	u8 rxbuf[8];
 	int rx_len = 8;
@@ -92,7 +91,7 @@ static void firmware_load(const struct firmware *fw, void *context)
 
 	/* Trying to speak with the FPGA via SPI... */
 	txbuf[0] = FPGA_CMD_READ_ID;
-	ret = spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
+	spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
 	jedec_id = get_unaligned_be32(&rxbuf[4]);
 	dev_dbg(&spi->dev, "FPGA JTAG ID=%08x\n", jedec_id);
 
@@ -110,7 +109,7 @@ static void firmware_load(const struct firmware *fw, void *context)
 	dev_info(&spi->dev, "FPGA %s detected\n", ecp3_dev[i].name);
 
 	txbuf[0] = FPGA_CMD_READ_STATUS;
-	ret = spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
+	spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
 	status = get_unaligned_be32(&rxbuf[4]);
 	dev_dbg(&spi->dev, "FPGA Status=%08x\n", status);
 
@@ -130,20 +129,20 @@ static void firmware_load(const struct firmware *fw, void *context)
 	memcpy(buffer + 4, fw->data, fw->size);
 
 	txbuf[0] = FPGA_CMD_REFRESH;
-	ret = spi_write(spi, txbuf, 4);
+	spi_write(spi, txbuf, 4);
 
 	txbuf[0] = FPGA_CMD_WRITE_EN;
-	ret = spi_write(spi, txbuf, 4);
+	spi_write(spi, txbuf, 4);
 
 	txbuf[0] = FPGA_CMD_CLEAR;
-	ret = spi_write(spi, txbuf, 4);
+	spi_write(spi, txbuf, 4);
 
 	/*
 	 * Wait for FPGA memory to become cleared
 	 */
 	for (i = 0; i < FPGA_CLEAR_LOOP_COUNT; i++) {
 		txbuf[0] = FPGA_CMD_READ_STATUS;
-		ret = spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
+		spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
 		status = get_unaligned_be32(&rxbuf[4]);
 		if (status == FPGA_STATUS_CLEARED)
 			break;
@@ -160,13 +159,13 @@ static void firmware_load(const struct firmware *fw, void *context)
 	}
 
 	dev_info(&spi->dev, "Configuring the FPGA...\n");
-	ret = spi_write(spi, buffer, fw->size + 8);
+	spi_write(spi, buffer, fw->size + 8);
 
 	txbuf[0] = FPGA_CMD_WRITE_DIS;
-	ret = spi_write(spi, txbuf, 4);
+	spi_write(spi, txbuf, 4);
 
 	txbuf[0] = FPGA_CMD_READ_STATUS;
-	ret = spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
+	spi_write_then_read(spi, txbuf, 8, rxbuf, rx_len);
 	status = get_unaligned_be32(&rxbuf[4]);
 	dev_dbg(&spi->dev, "FPGA Status=%08x\n", status);
 
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#22 lore raw

PATCH 13/20 misc: pch_phub: Provide descriptions for 'chip' argument

In reply to Lee Jones

For some reason (probably copy 'n' paste) kerneldoc descriptions were missing for all instances of 'chip'. Providing them squashes the following W=1 kernel build warnings:

drivers/misc/pch_phub.c:145: warning: Function parameter or member 'chip' not described in 'pch_phub_read_modify_write_reg' drivers/misc/pch_phub.c:282: warning: Function parameter or member 'chip' not described in 'pch_phub_read_serial_rom' drivers/misc/pch_phub.c:296: warning: Function parameter or member 'chip' not described in 'pch_phub_write_serial_rom' drivers/misc/pch_phub.c:334: warning: Function parameter or member 'chip' not described in 'pch_phub_read_serial_rom_val' drivers/misc/pch_phub.c:350: warning: Function parameter or member 'chip' not described in 'pch_phub_write_serial_rom_val' drivers/misc/pch_phub.c:450: warning: Function parameter or member 'chip' not described in 'pch_phub_read_gbe_mac_addr' drivers/misc/pch_phub.c:462: warning: Function parameter or member 'chip' not described in 'pch_phub_write_gbe_mac_addr'

Cc Masayuki Ohtak <[email protected]>
Cc Tomoya MORINAGA <[email protected]>
---
 drivers/misc/pch_phub.c | 7 +++++++
 1 file changed, 7 insertions(+)
drivers/misc/pch_phub.c +7 -0
index 60828af7506a3..95ba82a8625b0 100644
@@ -135,6 +135,7 @@ static DEFINE_MUTEX(pch_phub_mutex);
 
 /**
  * pch_phub_read_modify_write_reg() - Reading modifying and writing register
+ * @chip:		Pointer to the PHUB register structure
  * @reg_addr_offset:	Register offset address value.
  * @data:		Writing value.
  * @mask:		Mask value.
@@ -274,6 +275,7 @@ static void pch_phub_restore_reg_conf(struct pci_dev *pdev)
 
 /**
  * pch_phub_read_serial_rom() - Reading Serial ROM
+ * @chip:		Pointer to the PHUB register structure
  * @offset_address:	Serial ROM offset address to read.
  * @data:		Read buffer for specified Serial ROM value.
  */
@@ -288,6 +290,7 @@ static void pch_phub_read_serial_rom(struct pch_phub_reg *chip,
 
 /**
  * pch_phub_write_serial_rom() - Writing Serial ROM
+ * @chip:		Pointer to the PHUB register structure
  * @offset_address:	Serial ROM offset address.
  * @data:		Serial ROM value to write.
  */
@@ -326,6 +329,7 @@ static int pch_phub_write_serial_rom(struct pch_phub_reg *chip,
 
 /**
  * pch_phub_read_serial_rom_val() - Read Serial ROM value
+ * @chip:		Pointer to the PHUB register structure
  * @offset_address:	Serial ROM address offset value.
  * @data:		Serial ROM value to read.
  */
@@ -342,6 +346,7 @@ static void pch_phub_read_serial_rom_val(struct pch_phub_reg *chip,
 
 /**
  * pch_phub_write_serial_rom_val() - writing Serial ROM value
+ * @chip:		Pointer to the PHUB register structure
  * @offset_address:	Serial ROM address offset value.
  * @data:		Serial ROM value.
  */
@@ -444,6 +449,7 @@ static int pch_phub_gbe_serial_rom_conf_mp(struct pch_phub_reg *chip)
 /**
  * pch_phub_read_gbe_mac_addr() - Read Gigabit Ethernet MAC address
  * @offset_address:	Gigabit Ethernet MAC address offset value.
+ * @chip:		Pointer to the PHUB register structure
  * @data:		Buffer of the Gigabit Ethernet MAC address value.
  */
 static void pch_phub_read_gbe_mac_addr(struct pch_phub_reg *chip, u8 *data)
@@ -456,6 +462,7 @@ static void pch_phub_read_gbe_mac_addr(struct pch_phub_reg *chip, u8 *data)
 /**
  * pch_phub_write_gbe_mac_addr() - Write MAC address
  * @offset_address:	Gigabit Ethernet MAC address offset value.
+ * @chip:		Pointer to the PHUB register structure
  * @data:		Gigabit Ethernet MAC address value.
  */
 static int pch_phub_write_gbe_mac_addr(struct pch_phub_reg *chip, u8 *data)
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#23 lore raw

PATCH 14/20 misc: pch_phub: Remove superfluous descriptions to non-existent args 'offset_address'

In reply to Lee Jones

Probably a copy 'n' paste error, 'offset_address' has never been part of the pch_phub_{read,write}_gbe_mac_addr() functions.

Squashes the following W=1 warnings:

drivers/misc/pch_phub.c:450: warning: Excess function parameter 'offset_address' description in 'pch_phub_read_gbe_mac_addr' drivers/misc/pch_phub.c:462: warning: Excess function parameter 'offset_address' description in 'pch_phub_write_gbe_mac_addr'

Cc Masayuki Ohtak <[email protected]>
Cc Tomoya MORINAGA <[email protected]>
---
 drivers/misc/pch_phub.c | 2 --
 1 file changed, 2 deletions(-)
drivers/misc/pch_phub.c +0 -2
index 95ba82a8625b0..b27d826132915 100644
@@ -448,7 +448,6 @@ static int pch_phub_gbe_serial_rom_conf_mp(struct pch_phub_reg *chip)
 
 /**
  * pch_phub_read_gbe_mac_addr() - Read Gigabit Ethernet MAC address
- * @offset_address:	Gigabit Ethernet MAC address offset value.
  * @chip:		Pointer to the PHUB register structure
  * @data:		Buffer of the Gigabit Ethernet MAC address value.
  */
@@ -461,7 +460,6 @@ static void pch_phub_read_gbe_mac_addr(struct pch_phub_reg *chip, u8 *data)
 
 /**
  * pch_phub_write_gbe_mac_addr() - Write MAC address
- * @offset_address:	Gigabit Ethernet MAC address offset value.
  * @chip:		Pointer to the PHUB register structure
  * @data:		Gigabit Ethernet MAC address value.
  */
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#24 lore raw

PATCH 15/20 misc: enclosure: Update enclosure_remove_device() documentation to match reality

In reply to Lee Jones

enclosure_remove_device() hasn't taken an 'int component for over a decade. Instead use kerneldoc to describe the 'struct device' actually passed in.

Fixes the following W=1 kernel build warning(s):

drivers/misc/enclosure.c:400: warning: Function parameter or member 'dev' not described in 'enclosure_remove_device' drivers/misc/enclosure.c:400: warning: Excess function parameter 'num' description in 'enclosure_remove_device'

Cc James Bottomley <[email protected]>
---
 drivers/misc/enclosure.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/misc/enclosure.c +1 -1
index e8eba52750b34..f950d0155876a 100644
@@ -391,7 +391,7 @@ EXPORT_SYMBOL_GPL(enclosure_add_device);
 /**
  * enclosure_remove_device - remove a device from an enclosure
  * @edev:	the enclosure device
- * @num:	the number of the component to remove
+ * @dev:	device to remove/put
  *
  * Returns zero on success or an error.
  *
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
author
#25 lore raw

PATCH 16/20 misc: genwqe: card_base: Remove set but unused variable 'rc'

In reply to Lee Jones

Variable 'rc' hasn't been checked since the driver's inception in 2013. If it hasn't caused any issues since then, it's unlikely to in the future. Let's take it out for now.

Fixes the following W=1 kernel build warning(s):

drivers/misc/genwqe/card_base.c: In function ‘genwqe_health_check_stop’:
/home/lee/projects/linux/kernel/drivers/misc/genwqe/card_base.c:1046:6: warning: variable ‘rc’ set but not used [-Wunused-but-set-variable] 1046 | int rc;
| ^~

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
drivers/misc/genwqe/card_base.c +1 -3
index 1dc6c7c5cbce9..bceebf49de2d5 100644
@@ -1043,12 +1043,10 @@ static int genwqe_health_thread_running(struct genwqe_dev *cd)
 
 static int genwqe_health_check_stop(struct genwqe_dev *cd)
 {
-	int rc;
-
 	if (!genwqe_health_thread_running(cd))
 		return -EIO;
 
-	rc = kthread_stop(cd->health_thread);
+	kthread_stop(cd->health_thread);
 	cd->health_thread = NULL;
 	return 0;
 }
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
#26 lore raw

Re: [PATCH 16/20] misc: genwqe: card_base: Remove set but unused variable 'rc'

Quoted 42 lines · Lee Jones

Variable 'rc' hasn't been checked since the driver's inception in 2013. If it hasn't caused any issues since then, it's unlikely to in the future. Let's take it out for now.

Fixes the following W=1 kernel build warning(s):

drivers/misc/genwqe/card_base.c: In function
‘genwqe_health_check_stop’:

/home/lee/projects/linux/kernel/drivers/misc/genwqe/card_base.c:1046:6:
warning: variable ‘rc’ set but not used [-Wunused-but-set-variable]
1046 | int rc;
| ^~

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
drivers/misc/genwqe/card_base.c +1 -3
index 1dc6c7c5cbce9..bceebf49de2d5 100644
@@ -1043,12 +1043,10 @@ static int genwqe_health_thread_running(struct
 genwqe_dev *cd)
 
 static int genwqe_health_check_stop(struct genwqe_dev *cd)
 {
-	int rc;
-
 	if (!genwqe_health_thread_running(cd))
 		return -EIO;
 
-	rc = kthread_stop(cd->health_thread);
+	kthread_stop(cd->health_thread);
 	cd->health_thread = NULL;
 	return 0;
Quoted 1 line

}

Good idea. Let's remove it Thanks for the contribution.

author
#27 lore raw

Re: [PATCH 16/20] misc: genwqe: card_base: Remove set but unused variable 'rc'

Quoted 40 lines · haver
Quoted 39 lines · Lee Jones

Variable 'rc' hasn't been checked since the driver's inception in 2013. If it hasn't caused any issues since then, it's unlikely to in the future. Let's take it out for now.

Fixes the following W=1 kernel build warning(s):

drivers/misc/genwqe/card_base.c: In function
‘genwqe_health_check_stop’:

/home/lee/projects/linux/kernel/drivers/misc/genwqe/card_base.c:1046:6:
warning: variable ‘rc’ set but not used [-Wunused-but-set-variable]
1046 | int rc;
| ^~

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
drivers/misc/genwqe/card_base.c +0 -2
index 1dc6c7c5cbce9..bceebf49de2d5 100644
@@ -1043,12 +1043,10 @@ static int genwqe_health_thread_running(struct
 genwqe_dev *cd)
 
 static int genwqe_health_check_stop(struct genwqe_dev *cd)
 {
-	int rc;
-
 	if (!genwqe_health_thread_running(cd))
 		return -EIO;
 
Quoted 7 lines
Quoted 5 lines
drivers/misc/genwqe/card_base.c +1 -1
-	rc = kthread_stop(cd->health_thread);
+	kthread_stop(cd->health_thread);
 	cd->health_thread = NULL;
 	return 0;

}

Good idea. Let's remove it Thanks for the contribution.

No problem, and you are welcome.

Quoted 1 line

Just as an aside, this should be Acked-by, unless you either contributed to the patch directly or are in the delivery path i.e. you plan to pick the patch and send it to, say Linus, via a pull-request.

Signature · 4 lines
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
Acked-by Frank Haverkamp
#28 lore raw

Re: [PATCH 16/20] misc: genwqe: card_base: Remove set but unused variable 'rc'

Quoted 50 lines · Lee Jones
Quoted 40 lines · haver
Quoted 39 lines · Lee Jones

Variable 'rc' hasn't been checked since the driver's inception in 2013. If it hasn't caused any issues since then, it's unlikely to in the future. Let's take it out for now.

Fixes the following W=1 kernel build warning(s):

drivers/misc/genwqe/card_base.c: In function
‘genwqe_health_check_stop’:

/home/lee/projects/linux/kernel/drivers/misc/genwqe/card_base.c:1046:6:
warning: variable ‘rc’ set but not used [-Wunused-but-set-variable]
1046 | int rc;
| ^~

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
drivers/misc/genwqe/card_base.c +0 -2
index 1dc6c7c5cbce9..bceebf49de2d5 100644
@@ -1043,12 +1043,10 @@ static int genwqe_health_thread_running(struct
 genwqe_dev *cd)
 
 static int genwqe_health_check_stop(struct genwqe_dev *cd)
 {
-	int rc;
-
 	if (!genwqe_health_thread_running(cd))
 		return -EIO;
 
Quoted 7 lines
Quoted 5 lines
drivers/misc/genwqe/card_base.c +1 -1
-	rc = kthread_stop(cd->health_thread);
+	kthread_stop(cd->health_thread);
 	cd->health_thread = NULL;
 	return 0;

}

Good idea. Let's remove it Thanks for the contribution.

Quoted 7 lines

No problem, and you are welcome.

Quoted 1 line

Just as an aside, this should be Acked-by, unless you either contributed to the patch directly or are in the delivery path i.e. you plan to pick the patch and send it to, say Linus, via a pull-request.

Right. Thanks for reminding me. Feel free to send it yourself. When was the documentation checking introduced? At the time we contributed the code there was no such checking.

author
#29 lore raw

Re: [PATCH 16/20] misc: genwqe: card_base: Remove set but unused variable 'rc'

Quoted 55 lines · haver
Quoted 54 lines · Lee Jones
Quoted 40 lines · haver
Quoted 39 lines · Lee Jones

Variable 'rc' hasn't been checked since the driver's inception in 2013. If it hasn't caused any issues since then, it's unlikely to in the future. Let's take it out for now.

Fixes the following W=1 kernel build warning(s):

drivers/misc/genwqe/card_base.c: In function
‘genwqe_health_check_stop’:

/home/lee/projects/linux/kernel/drivers/misc/genwqe/card_base.c:1046:6:
warning: variable ‘rc’ set but not used [-Wunused-but-set-variable]
1046 | int rc;
| ^~

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
drivers/misc/genwqe/card_base.c +0 -2
index 1dc6c7c5cbce9..bceebf49de2d5 100644
@@ -1043,12 +1043,10 @@ static int genwqe_health_thread_running(struct
 genwqe_dev *cd)
 
 static int genwqe_health_check_stop(struct genwqe_dev *cd)
 {
-	int rc;
-
 	if (!genwqe_health_thread_running(cd))
 		return -EIO;
 
Quoted 7 lines
Quoted 5 lines
drivers/misc/genwqe/card_base.c +1 -1
-	rc = kthread_stop(cd->health_thread);
+	kthread_stop(cd->health_thread);
 	cd->health_thread = NULL;
 	return 0;

}

Good idea. Let's remove it Thanks for the contribution.

No problem, and you are welcome.

Quoted 1 line
Quoted 7 lines
Quoted 3 lines

Just as an aside, this should be Acked-by, unless you either contributed to the patch directly or are in the delivery path i.e. you plan to pick the patch and send it to, say Linus, via a pull-request.

Right. Thanks for reminding me. Feel free to send it yourself. When was the documentation checking introduced? At the time we contributed the code there was no such checking.

The checking scripts have been in place for many years, but it looks like doc checking became part of EXTRA_GCC_CHECKS builds in 2017:

Quoted 1 line

commit 3a025e1d1c2ea42fa497c9c6b21c284e0f69e28b

Author: Matthew Wilcox <[email protected]>
Date:   Mon Nov 20 10:40:40 2017 -0800

Add optional check for bad kernel-doc comments

Implement a '-none' output mode for kernel-doc which will only output warning messages, and suppresses the warning message about there being no kernel-doc in the file.

If the build has requested additional warnings, automatically check all .c files. This patch does not check .h files. Enabling the warning by default would add about 1300 warnings, so it's default off for now. People who care can use this to check they didn't break the docs and maybe we'll get all the warnings fixed and be able to enable this check by default in the future.

scripts/Makefile.build +5 -0
index 2e3a10e79ca9e..aceac0ba07451 100644
@@ -108,6 +108,10 @@ ifneq ($(KBUILD_CHECKSRC),0)
   endif
 endif
 
+ifneq ($(KBUILD_ENABLE_EXTRA_GCC_CHECKS),)
+  cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $< ;
+endif
+
 # Do section mismatch analysis for each module/built-in.o
 ifdef CONFIG_DEBUG_SECTION_MISMATCH
   cmd_secanalysis = ; scripts/mod/modpost $@
@@ -289,6 +293,7 @@ define rule_cc_o_c
        $(call echo-cmd,checksrc) $(cmd_checksrc)                         \
        $(call cmd_and_fixdep,cc_o_c)                                     \
        $(cmd_modversions_c)                                              \
+       $(cmd_checkdoc)                                                   \
        $(call echo-cmd,objtool) $(cmd_objtool)                           \
        $(call echo-cmd,record_mcount) $(cmd_record_mcount)
 endef
Signature · 4 lines
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
author
#30 lore raw

PATCH 17/20 misc: genwqe: card_base: Do not pass unused argument 'fatal_err'

In reply to Lee Jones

'fatal_err' is taken as an argument to a static function which is only invoked once. During this invocation 'fatal_err' is not set. There doesn't appear to be a good reason to keep it around.

Also fixes the following W=1 kernel build warning:

drivers/misc/genwqe/card_base.c:588: warning: Function parameter or member 'fatal_err' not described in 'genwqe_recover_card'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 18 +++---------------
 1 file changed, 3 insertions(+), 15 deletions(-)
drivers/misc/genwqe/card_base.c +3 -15
index bceebf49de2d5..809a6f46f6de3 100644
@@ -569,30 +569,18 @@ static int genwqe_stop(struct genwqe_dev *cd)
 
 /**
  * genwqe_recover_card() - Try to recover the card if it is possible
- *
- * If fatal_err is set no register access is possible anymore. It is
- * likely that genwqe_start fails in that situation. Proper error
- * handling is required in this case.
+ * @cd: GenWQE device information
  *
  * genwqe_bus_reset() will cause the pci code to call genwqe_remove()
  * and later genwqe_probe() for all virtual functions.
  */
-static int genwqe_recover_card(struct genwqe_dev *cd, int fatal_err)
+static int genwqe_recover_card(struct genwqe_dev *cd)
 {
 	int rc;
 	struct pci_dev *pci_dev = cd->pci_dev;
 
 	genwqe_stop(cd);
 
-	/*
-	 * Make sure chip is not reloaded to maintain FFDC. Write SLU
-	 * Reset Register, CPLDReset field to 0.
-	 */
-	if (!fatal_err) {
-		cd->softreset = 0x70ull;
-		__genwqe_writeq(cd, IO_SLC_CFGREG_SOFTRESET, cd->softreset);
-	}
-
 	rc = genwqe_bus_reset(cd);
 	if (rc != 0) {
 		dev_err(&pci_dev->dev,
@@ -958,7 +946,7 @@ static int genwqe_health_thread(void *data)
 
 			cd->card_state = GENWQE_CARD_FATAL_ERROR;
 
-			rc = genwqe_recover_card(cd, 0);
+			rc = genwqe_recover_card(cd);
 			if (rc < 0) {
 				/* FIXME Card is unusable and needs unbind! */
 				goto fatal_error;
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
#31 lore raw

Re: [PATCH 17/20] misc: genwqe: card_base: Do not pass unused argument 'fatal_err'

Quoted 56 lines · Lee Jones

'fatal_err' is taken as an argument to a static function which is only invoked once. During this invocation 'fatal_err' is not set. There doesn't appear to be a good reason to keep it around.

Also fixes the following W=1 kernel build warning:

drivers/misc/genwqe/card_base.c:588: warning: Function parameter or
member 'fatal_err' not described in 'genwqe_recover_card'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 18 +++---------------
 1 file changed, 3 insertions(+), 15 deletions(-)
drivers/misc/genwqe/card_base.c +2 -14
index bceebf49de2d5..809a6f46f6de3 100644
@@ -569,30 +569,18 @@ static int genwqe_stop(struct genwqe_dev *cd)
 
 /**
  * genwqe_recover_card() - Try to recover the card if it is possible
- *
- * If fatal_err is set no register access is possible anymore. It is
- * likely that genwqe_start fails in that situation. Proper error
- * handling is required in this case.
+ * @cd: GenWQE device information
  *
  * genwqe_bus_reset() will cause the pci code to call genwqe_remove()
  * and later genwqe_probe() for all virtual functions.
  */
-static int genwqe_recover_card(struct genwqe_dev *cd, int fatal_err)
+static int genwqe_recover_card(struct genwqe_dev *cd)
 {
 	int rc;
 	struct pci_dev *pci_dev = cd->pci_dev;
 
 	genwqe_stop(cd);
 
-	/*
-	 * Make sure chip is not reloaded to maintain FFDC. Write SLU
-	 * Reset Register, CPLDReset field to 0.
-	 */
-	if (!fatal_err) {
-		cd->softreset = 0x70ull;
-		__genwqe_writeq(cd, IO_SLC_CFGREG_SOFTRESET, cd->softreset);
-	}
-
 	rc = genwqe_bus_reset(cd);
 	if (rc != 0) {
 		dev_err(&pci_dev->dev,

drivers/misc/genwqe/card_base.c static int genwqe_health_thread(void *data) · line 952

Quoted 8 lines
drivers/misc/genwqe/card_base.c +1 -1
@@ -958,7 +946,7 @@ static int genwqe_health_thread(void *data)
 
 			cd->card_state = GENWQE_CARD_FATAL_ERROR;
 
-			rc = genwqe_recover_card(cd, 0);
+			rc = genwqe_recover_card(cd);
 			if (rc < 0) {
 				/* FIXME Card is unusable and needs unbind! */
 				goto fatal_error;

I think this one I want to keep. Since fatal_err is 0, !fatal_error is 1 and the register write is actually executed.
I also want to keep the parameter even though it is only used with 0. The register bit causes a less drastic recovery, but if we would discover that that is not working ok, we rather discard the debug data we get in this case instead of letting the recovery fail. I think it does not hurt to keep it. Maybe you can add a comment?

Thanks

Frank

author
#32 lore raw

Re: [PATCH 17/20] misc: genwqe: card_base: Do not pass unused argument 'fatal_err'

Quoted 61 lines · haver
Quoted 60 lines · Lee Jones

'fatal_err' is taken as an argument to a static function which is only invoked once. During this invocation 'fatal_err' is not set. There doesn't appear to be a good reason to keep it around.

Also fixes the following W=1 kernel build warning:

drivers/misc/genwqe/card_base.c:588: warning: Function parameter or
member 'fatal_err' not described in 'genwqe_recover_card'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 18 +++---------------
 1 file changed, 3 insertions(+), 15 deletions(-)
drivers/misc/genwqe/card_base.c +2 -14
index bceebf49de2d5..809a6f46f6de3 100644
@@ -569,30 +569,18 @@ static int genwqe_stop(struct genwqe_dev *cd)
 
 /**
  * genwqe_recover_card() - Try to recover the card if it is possible
- *
- * If fatal_err is set no register access is possible anymore. It is
- * likely that genwqe_start fails in that situation. Proper error
- * handling is required in this case.
+ * @cd: GenWQE device information
  *
  * genwqe_bus_reset() will cause the pci code to call genwqe_remove()
  * and later genwqe_probe() for all virtual functions.
  */
-static int genwqe_recover_card(struct genwqe_dev *cd, int fatal_err)
+static int genwqe_recover_card(struct genwqe_dev *cd)
 {
 	int rc;
 	struct pci_dev *pci_dev = cd->pci_dev;
 
 	genwqe_stop(cd);
 
-	/*
-	 * Make sure chip is not reloaded to maintain FFDC. Write SLU
-	 * Reset Register, CPLDReset field to 0.
-	 */
-	if (!fatal_err) {
-		cd->softreset = 0x70ull;
-		__genwqe_writeq(cd, IO_SLC_CFGREG_SOFTRESET, cd->softreset);
-	}
-
 	rc = genwqe_bus_reset(cd);
 	if (rc != 0) {
 		dev_err(&pci_dev->dev,
@@ -958,7 +946,7 @@ static int genwqe_health_thread(void *data)
 
 			cd->card_state = GENWQE_CARD_FATAL_ERROR;
 
Quoted 8 lines

drivers/misc/genwqe/card_base.c static int genwqe_health_thread(void *data) · line 952

Quoted 5 lines
drivers/misc/genwqe/card_base.c +1 -1
-			rc = genwqe_recover_card(cd, 0);
+			rc = genwqe_recover_card(cd);
 			if (rc < 0) {
 				/* FIXME Card is unusable and needs unbind! */
 				goto fatal_error;

I think this one I want to keep. Since fatal_err is 0, !fatal_error is 1 and the register write is actually executed.

Ah yes, good catch.

What if we *always* did instead then?

Quoted 4 lines

I also want to keep the parameter even though it is only used with 0. The register bit causes a less drastic recovery, but if we would discover that that is not working ok, we rather discard the debug data we get in this case instead of letting the recovery fail. I think it does not hurt to keep it.

I'm not 100% against it, but it is dead code.

Quoted 1 line

Maybe you can add a comment?

If you really want to keep it, I can just update the kerneldoc instead.

Signature · 4 lines
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
#33 lore raw

Re: [PATCH 17/20] misc: genwqe: card_base: Do not pass unused argument 'fatal_err'

Quoted 72 lines · Lee Jones
Quoted 61 lines · haver
Quoted 60 lines · Lee Jones

'fatal_err' is taken as an argument to a static function which is only invoked once. During this invocation 'fatal_err' is not set. There doesn't appear to be a good reason to keep it around.

Also fixes the following W=1 kernel build warning:

drivers/misc/genwqe/card_base.c:588: warning: Function parameter or
member 'fatal_err' not described in 'genwqe_recover_card'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 18 +++---------------
 1 file changed, 3 insertions(+), 15 deletions(-)
drivers/misc/genwqe/card_base.c +2 -14
index bceebf49de2d5..809a6f46f6de3 100644
@@ -569,30 +569,18 @@ static int genwqe_stop(struct genwqe_dev *cd)
 
 /**
  * genwqe_recover_card() - Try to recover the card if it is possible
- *
- * If fatal_err is set no register access is possible anymore. It is
- * likely that genwqe_start fails in that situation. Proper error
- * handling is required in this case.
+ * @cd: GenWQE device information
  *
  * genwqe_bus_reset() will cause the pci code to call genwqe_remove()
  * and later genwqe_probe() for all virtual functions.
  */
-static int genwqe_recover_card(struct genwqe_dev *cd, int fatal_err)
+static int genwqe_recover_card(struct genwqe_dev *cd)
 {
 	int rc;
 	struct pci_dev *pci_dev = cd->pci_dev;
 
 	genwqe_stop(cd);
 
-	/*
-	 * Make sure chip is not reloaded to maintain FFDC. Write SLU
-	 * Reset Register, CPLDReset field to 0.
-	 */
-	if (!fatal_err) {
-		cd->softreset = 0x70ull;
-		__genwqe_writeq(cd, IO_SLC_CFGREG_SOFTRESET, cd->softreset);
-	}
-
 	rc = genwqe_bus_reset(cd);
 	if (rc != 0) {
 		dev_err(&pci_dev->dev,
@@ -958,7 +946,7 @@ static int genwqe_health_thread(void *data)
 
 			cd->card_state = GENWQE_CARD_FATAL_ERROR;
 
Quoted 8 lines

drivers/misc/genwqe/card_base.c static int genwqe_health_thread(void *data) · line 952

Quoted 5 lines
drivers/misc/genwqe/card_base.c +1 -1
-			rc = genwqe_recover_card(cd, 0);
+			rc = genwqe_recover_card(cd);
 			if (rc < 0) {
 				/* FIXME Card is unusable and needs unbind! */
 				goto fatal_error;

I think this one I want to keep. Since fatal_err is 0, !fatal_error is 1 and the register write is actually executed.

Quoted 3 lines

Ah yes, good catch.

What if we *always* did instead then?

I knew you would ask that ;-).

Quoted 6 lines
Quoted 5 lines

I also want to keep the parameter even though it is only used with 0. The register bit causes a less drastic recovery, but if we would discover that that is not working ok, we rather discard the debug data we get in this case instead of letting the recovery fail. I think it does not hurt to keep it.

Quoted 6 lines

I'm not 100% against it, but it is dead code.

Quoted 1 line

Maybe you can add a comment?

If you really want to keep it, I can just update the kerneldoc instead.

I prefer that option. I want to indicate that there are two possible ways to recover on a problem. If we delete the currently not exploited parameter, this information gets lost.

Regards

Frank

author
#34 lore raw

Re: [PATCH 17/20] misc: genwqe: card_base: Do not pass unused argument 'fatal_err'

Quoted 92 lines · haver
Quoted 73 lines · Lee Jones
Quoted 61 lines · haver
Quoted 60 lines · Lee Jones

'fatal_err' is taken as an argument to a static function which is only invoked once. During this invocation 'fatal_err' is not set. There doesn't appear to be a good reason to keep it around.

Also fixes the following W=1 kernel build warning:

drivers/misc/genwqe/card_base.c:588: warning: Function parameter or
member 'fatal_err' not described in 'genwqe_recover_card'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 18 +++---------------
 1 file changed, 3 insertions(+), 15 deletions(-)
drivers/misc/genwqe/card_base.c +2 -14
index bceebf49de2d5..809a6f46f6de3 100644
@@ -569,30 +569,18 @@ static int genwqe_stop(struct genwqe_dev *cd)
 
 /**
  * genwqe_recover_card() - Try to recover the card if it is possible
- *
- * If fatal_err is set no register access is possible anymore. It is
- * likely that genwqe_start fails in that situation. Proper error
- * handling is required in this case.
+ * @cd: GenWQE device information
  *
  * genwqe_bus_reset() will cause the pci code to call genwqe_remove()
  * and later genwqe_probe() for all virtual functions.
  */
-static int genwqe_recover_card(struct genwqe_dev *cd, int fatal_err)
+static int genwqe_recover_card(struct genwqe_dev *cd)
 {
 	int rc;
 	struct pci_dev *pci_dev = cd->pci_dev;
 
 	genwqe_stop(cd);
 
-	/*
-	 * Make sure chip is not reloaded to maintain FFDC. Write SLU
-	 * Reset Register, CPLDReset field to 0.
-	 */
-	if (!fatal_err) {
-		cd->softreset = 0x70ull;
-		__genwqe_writeq(cd, IO_SLC_CFGREG_SOFTRESET, cd->softreset);
-	}
-
 	rc = genwqe_bus_reset(cd);
 	if (rc != 0) {
 		dev_err(&pci_dev->dev,
@@ -958,7 +946,7 @@ static int genwqe_health_thread(void *data)
 
 			cd->card_state = GENWQE_CARD_FATAL_ERROR;
 
Quoted 9 lines

drivers/misc/genwqe/card_base.c static int genwqe_health_thread(void *data) · line 952

Quoted 5 lines
drivers/misc/genwqe/card_base.c +1 -1
-			rc = genwqe_recover_card(cd, 0);
+			rc = genwqe_recover_card(cd);
 			if (rc < 0) {
 				/* FIXME Card is unusable and needs unbind! */
 				goto fatal_error;

I think this one I want to keep. Since fatal_err is 0, !fatal_error is 1 and
the register write is actually executed.

Quoted 3 lines

Ah yes, good catch.

What if we *always* did instead then?

I knew you would ask that ;-).

Quoted 12 lines
Quoted 9 lines

I also want to keep the parameter even though it is only used with
0. The
register bit causes a less drastic recovery, but if we would discover that
that is not working ok, we rather discard the debug data we get in this case
instead of letting the recovery fail. I think it does not hurt to keep it.

I'm not 100% against it, but it is dead code.

Quoted 8 lines
Quoted 4 lines
Quoted 1 line

Maybe you can add a comment?

If you really want to keep it, I can just update the kerneldoc instead.

I prefer that option. I want to indicate that there are two possible ways to recover on a problem. If we delete the currently not exploited parameter, this information gets lost.

That's fine. Will fix.

Signature · 4 lines
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
author
#35 lore raw

PATCH 18/20 misc: genwqe: card_base: Whole host of kerneldoc fixes

In reply to Lee Jones

From missing documentation for function arguments, to promotion obvious kerneldoc headers and incorrectly named arguments.

Fixes the following W=1 warnings:

drivers/misc/genwqe/card_base.c:175: warning: Function parameter or member 'cd' not described in 'genwqe_bus_reset' drivers/misc/genwqe/card_base.c:272: warning: Function parameter or member 'cd' not described in 'genwqe_recovery_on_fatal_gfir_required' drivers/misc/genwqe/card_base.c:293: warning: Function parameter or member 'cd' not described in 'genwqe_T_psec' drivers/misc/genwqe/card_base.c:314: warning: Function parameter or member 'cd' not described in 'genwqe_setup_pf_jtimer' drivers/misc/genwqe/card_base.c:334: warning: Function parameter or member 'cd' not described in 'genwqe_setup_vf_jtimer' drivers/misc/genwqe/card_base.c:557: warning: Function parameter or member 'cd' not described in 'genwqe_stop' drivers/misc/genwqe/card_base.c:617: warning: Function parameter or member 'cd' not described in 'genwqe_fir_checking' drivers/misc/genwqe/card_base.c:760: warning: Function parameter or member 'pci_dev' not described in 'genwqe_pci_fundamental_reset' drivers/misc/genwqe/card_base.c:889: warning: Function parameter or member 'data' not described in 'genwqe_health_thread' drivers/misc/genwqe/card_base.c:1046: warning: Function parameter or member 'cd' not described in 'genwqe_pci_setup' drivers/misc/genwqe/card_base.c:1131: warning: Function parameter or member 'cd' not described in 'genwqe_pci_remove' drivers/misc/genwqe/card_base.c:1151: warning: Function parameter or member 'pci_dev' not described in 'genwqe_probe' drivers/misc/genwqe/card_base.c:1151: warning: Function parameter or member 'id' not described in 'genwqe_probe' drivers/misc/genwqe/card_base.c:1151: warning: Excess function parameter 'pdev' description in 'genwqe_probe' drivers/misc/genwqe/card_base.c:1207: warning: Function parameter or member 'pci_dev' not described in 'genwqe_remove' drivers/misc/genwqe/card_base.c:1336: warning: Function parameter or member 'dev' not described in 'genwqe_devnode' drivers/misc/genwqe/card_base.c:1336: warning: Function parameter or member 'mode' not described in 'genwqe_devnode'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)
drivers/misc/genwqe/card_base.c +21 -3
index 809a6f46f6de3..93d2ed91c85b2 100644
@@ -165,6 +165,7 @@ static void genwqe_dev_free(struct genwqe_dev *cd)
 
 /**
  * genwqe_bus_reset() - Card recovery
+ * @cd: GenWQE device information
  *
  * pci_reset_function() will recover the device and ensure that the
  * registers are accessible again when it completes with success. If
@@ -262,6 +263,7 @@ static void genwqe_tweak_hardware(struct genwqe_dev *cd)
 
 /**
  * genwqe_recovery_on_fatal_gfir_required() - Version depended actions
+ * @cd: GenWQE device information
  *
  * Bitstreams older than 2013-02-17 have a bug where fatal GFIRs must
  * be ignored. This is e.g. true for the bitstream we gave to the card
@@ -280,6 +282,7 @@ int genwqe_flash_readback_fails(struct genwqe_dev *cd)
 
 /**
  * genwqe_T_psec() - Calculate PF/VF timeout register content
+ * @cd: GenWQE device information
  *
  * Note: From a design perspective it turned out to be a bad idea to
  * use codes here to specifiy the frequency/speed values. An old
@@ -303,6 +306,7 @@ static int genwqe_T_psec(struct genwqe_dev *cd)
 
 /**
  * genwqe_setup_pf_jtimer() - Setup PF hardware timeouts for DDCB execution
+ * @cd: GenWQE device information
  *
  * Do this _after_ card_reset() is called. Otherwise the values will
  * vanish. The settings need to be done when the queues are inactive.
@@ -329,6 +333,7 @@ static bool genwqe_setup_pf_jtimer(struct genwqe_dev *cd)
 
 /**
  * genwqe_setup_vf_jtimer() - Setup VF hardware timeouts for DDCB execution
+ * @cd: GenWQE device information
  */
 static bool genwqe_setup_vf_jtimer(struct genwqe_dev *cd)
 {
@@ -543,6 +548,7 @@ static int genwqe_start(struct genwqe_dev *cd)
 
 /**
  * genwqe_stop() - Stop card operation
+ * @cd: GenWQE device information
  *
  * Recovery notes:
  *   As long as genwqe_thread runs we might access registers during
@@ -606,6 +612,7 @@ static int genwqe_health_check_cond(struct genwqe_dev *cd, u64 *gfir)
 
 /**
  * genwqe_fir_checking() - Check the fault isolation registers of the card
+ * @cd: GenWQE device information
  *
  * If this code works ok, can be tried out with help of the genwqe_poke tool:
  *   sudo ./tools/genwqe_poke 0x8 0xfefefefefef
@@ -750,6 +757,7 @@ static u64 genwqe_fir_checking(struct genwqe_dev *cd)
 
 /**
  * genwqe_pci_fundamental_reset() - trigger a PCIe fundamental reset on the slot
+ * @pci_dev:	PCI device information struct
  *
  * Note: pci_set_pcie_reset_state() is not implemented on all archs, so this
  * reset method will not work in all cases.
@@ -814,8 +822,9 @@ static int genwqe_platform_recovery(struct genwqe_dev *cd)
 	return rc;
 }
 
-/*
+/**
  * genwqe_reload_bistream() - reload card bitstream
+ * @cd: GenWQE device information
  *
  * Set the appropriate register and call fundamental reset to reaload the card
  * bitstream.
@@ -868,6 +877,7 @@ static int genwqe_reload_bistream(struct genwqe_dev *cd)
 
 /**
  * genwqe_health_thread() - Health checking thread
+ * @data: GenWQE device information
  *
  * This thread is only started for the PF of the card.
  *
@@ -1041,6 +1051,7 @@ static int genwqe_health_check_stop(struct genwqe_dev *cd)
 
 /**
  * genwqe_pci_setup() - Allocate PCIe related resources for our card
+ * @cd: GenWQE device information
  */
 static int genwqe_pci_setup(struct genwqe_dev *cd)
 {
@@ -1126,6 +1137,7 @@ static int genwqe_pci_setup(struct genwqe_dev *cd)
 
 /**
  * genwqe_pci_remove() - Free PCIe related resources for our card
+ * @cd: GenWQE device information
  */
 static void genwqe_pci_remove(struct genwqe_dev *cd)
 {
@@ -1140,7 +1152,8 @@ static void genwqe_pci_remove(struct genwqe_dev *cd)
 
 /**
  * genwqe_probe() - Device initialization
- * @pdev:	PCI device information struct
+ * @pci_dev:	PCI device information struct
+ * @id:		PCI device ID
  *
  * Callable for multiple cards. This function is called on bind.
  *
@@ -1200,6 +1213,7 @@ static int genwqe_probe(struct pci_dev *pci_dev,
 
 /**
  * genwqe_remove() - Called when device is removed (hot-plugable)
+ * @pci_dev:	PCI device information struct
  *
  * Or when driver is unloaded respecitively when unbind is done.
  */
@@ -1219,8 +1233,10 @@ static void genwqe_remove(struct pci_dev *pci_dev)
 	genwqe_dev_free(cd);
 }
 
-/*
+/**
  * genwqe_err_error_detected() - Error detection callback
+ * @pci_dev:	PCI device information struct
+ * @state:	PCI channel state
  *
  * This callback is called by the PCI subsystem whenever a PCI bus
  * error is detected.
@@ -1328,6 +1344,8 @@ static struct pci_driver genwqe_driver = {
 
 /**
  * genwqe_devnode() - Set default access mode for genwqe devices.
+ * @dev:	Pointer to device (unused)
+ * @mode:	Carrier to pass-back given mode (permissions)
  *
  * Default mode should be rw for everybody. Do not change default
  * device name.
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
#36 lore raw

Re: [PATCH 18/20] misc: genwqe: card_base: Whole host of kerneldoc fixes

Quoted 201 lines · Lee Jones

From missing documentation for function arguments, to promotion obvious kerneldoc headers and incorrectly named arguments.

Fixes the following W=1 warnings:

drivers/misc/genwqe/card_base.c:175: warning: Function parameter or
member 'cd' not described in 'genwqe_bus_reset'
drivers/misc/genwqe/card_base.c:272: warning: Function parameter or
member 'cd' not described in 'genwqe_recovery_on_fatal_gfir_required'
drivers/misc/genwqe/card_base.c:293: warning: Function parameter or
member 'cd' not described in 'genwqe_T_psec'
drivers/misc/genwqe/card_base.c:314: warning: Function parameter or
member 'cd' not described in 'genwqe_setup_pf_jtimer'
drivers/misc/genwqe/card_base.c:334: warning: Function parameter or
member 'cd' not described in 'genwqe_setup_vf_jtimer'
drivers/misc/genwqe/card_base.c:557: warning: Function parameter or
member 'cd' not described in 'genwqe_stop'
drivers/misc/genwqe/card_base.c:617: warning: Function parameter or
member 'cd' not described in 'genwqe_fir_checking'
drivers/misc/genwqe/card_base.c:760: warning: Function parameter or
member 'pci_dev' not described in 'genwqe_pci_fundamental_reset'
drivers/misc/genwqe/card_base.c:889: warning: Function parameter or
member 'data' not described in 'genwqe_health_thread'
drivers/misc/genwqe/card_base.c:1046: warning: Function parameter or
member 'cd' not described in 'genwqe_pci_setup'
drivers/misc/genwqe/card_base.c:1131: warning: Function parameter or
member 'cd' not described in 'genwqe_pci_remove'
drivers/misc/genwqe/card_base.c:1151: warning: Function parameter or
member 'pci_dev' not described in 'genwqe_probe'
drivers/misc/genwqe/card_base.c:1151: warning: Function parameter or
member 'id' not described in 'genwqe_probe'
drivers/misc/genwqe/card_base.c:1151: warning: Excess function
parameter 'pdev' description in 'genwqe_probe'
drivers/misc/genwqe/card_base.c:1207: warning: Function parameter or
member 'pci_dev' not described in 'genwqe_remove'
drivers/misc/genwqe/card_base.c:1336: warning: Function parameter or
member 'dev' not described in 'genwqe_devnode'
drivers/misc/genwqe/card_base.c:1336: warning: Function parameter or
member 'mode' not described in 'genwqe_devnode'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_base.c | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)
drivers/misc/genwqe/card_base.c +2 -0
index 809a6f46f6de3..93d2ed91c85b2 100644
@@ -165,6 +165,7 @@ static void genwqe_dev_free(struct genwqe_dev *cd)
 
 /**
  * genwqe_bus_reset() - Card recovery
+ * @cd: GenWQE device information
  *
  * pci_reset_function() will recover the device and ensure that the
  * registers are accessible again when it completes with success. If
@@ -262,6 +263,7 @@ static void genwqe_tweak_hardware(struct genwqe_dev 
 *cd)
 
 /**
  * genwqe_recovery_on_fatal_gfir_required() - Version depended actions
+ * @cd: GenWQE device information
  *
  * Bitstreams older than 2013-02-17 have a bug where fatal GFIRs must

* be ignored. This is e.g. true for the bitstream we gave to the card

drivers/misc/genwqe/card_base.c +1 -0
@@ -280,6 +282,7 @@ int genwqe_flash_readback_fails(struct genwqe_dev 
 *cd)
 
 /**
  * genwqe_T_psec() - Calculate PF/VF timeout register content
+ * @cd: GenWQE device information
  *
  * Note: From a design perspective it turned out to be a bad idea to

* use codes here to specifiy the frequency/speed values. An old

drivers/misc/genwqe/card_base.c +0 -0
@@ -303,6 +306,7 @@ static int genwqe_T_psec(struct genwqe_dev *cd)
 
 /**
  * genwqe_setup_pf_jtimer() - Setup PF hardware timeouts for DDCB 

execution
+ * @cd: GenWQE device information
*
* Do this _after_ card_reset() is called. Otherwise the values will
* vanish. The settings need to be done when the queues are inactive.

drivers/misc/genwqe/card_base.c +0 -0
@@ -329,6 +333,7 @@ static bool genwqe_setup_pf_jtimer(struct 
 genwqe_dev *cd)
 
 /**
  * genwqe_setup_vf_jtimer() - Setup VF hardware timeouts for DDCB 

execution
+ * @cd: GenWQE device information
*/
static bool genwqe_setup_vf_jtimer(struct genwqe_dev *cd) {

drivers/misc/genwqe/card_base.c +1 -0
@@ -543,6 +548,7 @@ static int genwqe_start(struct genwqe_dev *cd)
 
 /**
  * genwqe_stop() - Stop card operation
+ * @cd: GenWQE device information
  *
  * Recovery notes:
  *   As long as genwqe_thread runs we might access registers during
@@ -606,6 +612,7 @@ static int genwqe_health_check_cond(struct
 genwqe_dev *cd, u64 *gfir)
 
 /**
  * genwqe_fir_checking() - Check the fault isolation registers of the 

card
+ * @cd: GenWQE device information
*
* If this code works ok, can be tried out with help of the
genwqe_poke tool:
* sudo ./tools/genwqe_poke 0x8 0xfefefefefef

drivers/misc/genwqe/card_base.c +0 -0
@@ -750,6 +757,7 @@ static u64 genwqe_fir_checking(struct genwqe_dev 
 *cd)
 
 /**
  * genwqe_pci_fundamental_reset() - trigger a PCIe fundamental reset

on the slot
+ * @pci_dev: PCI device information struct
*
* Note: pci_set_pcie_reset_state() is not implemented on all archs,
so this
* reset method will not work in all cases.

drivers/misc/genwqe/card_base.c +2 -1
@@ -814,8 +822,9 @@ static int genwqe_platform_recovery(struct 
 genwqe_dev *cd)
 	return rc;
 }
 
-/*
+/**
  * genwqe_reload_bistream() - reload card bitstream
+ * @cd: GenWQE device information
  *
  * Set the appropriate register and call fundamental reset to reaload 

the card
* bitstream.

drivers/misc/genwqe/card_base.c +1 -0
@@ -868,6 +877,7 @@ static int genwqe_reload_bistream(struct genwqe_dev 
 *cd)
 
 /**
  * genwqe_health_thread() - Health checking thread
+ * @data: GenWQE device information
  *
  * This thread is only started for the PF of the card.

*

drivers/misc/genwqe/card_base.c +1 -0
@@ -1041,6 +1051,7 @@ static int genwqe_health_check_stop(struct 
 genwqe_dev *cd)
 
 /**
  * genwqe_pci_setup() - Allocate PCIe related resources for our card
+ * @cd: GenWQE device information
  */
 static int genwqe_pci_setup(struct genwqe_dev *cd)

{

drivers/misc/genwqe/card_base.c +1 -0
@@ -1126,6 +1137,7 @@ static int genwqe_pci_setup(struct genwqe_dev 
 *cd)
 
 /**
  * genwqe_pci_remove() - Free PCIe related resources for our card
+ * @cd: GenWQE device information
  */
 static void genwqe_pci_remove(struct genwqe_dev *cd)

{

drivers/misc/genwqe/card_base.c +2 -1
@@ -1140,7 +1152,8 @@ static void genwqe_pci_remove(struct genwqe_dev 
 *cd)
 
 /**
  * genwqe_probe() - Device initialization
- * @pdev:	PCI device information struct
+ * @pci_dev:	PCI device information struct
+ * @id:		PCI device ID
  *
  * Callable for multiple cards. This function is called on bind.

*

drivers/misc/genwqe/card_base.c +4 -1
@@ -1200,6 +1213,7 @@ static int genwqe_probe(struct pci_dev *pci_dev,
 
 /**
  * genwqe_remove() - Called when device is removed (hot-plugable)
+ * @pci_dev:	PCI device information struct
  *
  * Or when driver is unloaded respecitively when unbind is done.
  */
@@ -1219,8 +1233,10 @@ static void genwqe_remove(struct pci_dev 
 *pci_dev)
 	genwqe_dev_free(cd);
 }
 
-/*
+/**
  * genwqe_err_error_detected() - Error detection callback
+ * @pci_dev:	PCI device information struct
+ * @state:	PCI channel state
  *
  * This callback is called by the PCI subsystem whenever a PCI bus

* error is detected.

drivers/misc/genwqe/card_base.c static struct pci_driver genwqe_driver = { · line 1351

Quoted 8 lines
drivers/misc/genwqe/card_base.c +2 -0
@@ -1328,6 +1344,8 @@ static struct pci_driver genwqe_driver = {
 
 /**
  * genwqe_devnode() - Set default access mode for genwqe devices.
+ * @dev:	Pointer to device (unused)
+ * @mode:	Carrier to pass-back given mode (permissions)
  *
  * Default mode should be rw for everybody. Do not change default
  * device name.

Thanks for adding the documentation.

author
#37 lore raw

PATCH 19/20 misc: genwqe: card_dev: Whole host of kerneldoc fixes

In reply to Lee Jones

Including; add missing documentation for function arguments, re-ordering of #defines i.e. not placed between kerneldoc headers and the functions they are documenting, demotion of file header/comment from kerneldoc format and removal of documentation for non-existent args.

Fixes the following W=1 kernel build warnings:

drivers/misc/genwqe/card_dev.c:33: warning: Function parameter or member 'cd' not described in 'genwqe_open_files' drivers/misc/genwqe/card_dev.c:98: warning: Function parameter or member 'virt_addr' not described in 'genwqe_search_pin' drivers/misc/genwqe/card_dev.c:98: warning: Excess function parameter 'dma_addr' description in 'genwqe_search_pin' drivers/misc/genwqe/card_dev.c:154: warning: Function parameter or member 'virt_addr' not described in '__genwqe_search_mapping' drivers/misc/genwqe/card_dev.c:256: warning: Function parameter or member 'cd' not described in 'genwqe_kill_fasync' drivers/misc/genwqe/card_dev.c:256: warning: Function parameter or member 'sig' not described in 'genwqe_kill_fasync' drivers/misc/genwqe/card_dev.c:387: warning: Function parameter or member 'vma' not described in 'genwqe_vma_close' drivers/misc/genwqe/card_dev.c:430: warning: Function parameter or member 'filp' not described in 'genwqe_mmap' drivers/misc/genwqe/card_dev.c:430: warning: Function parameter or member 'vma' not described in 'genwqe_mmap' drivers/misc/genwqe/card_dev.c:495: warning: Excess function parameter 'cd' description in 'FLASH_BLOCK' drivers/misc/genwqe/card_dev.c:495: warning: Excess function parameter 'load' description in 'FLASH_BLOCK' drivers/misc/genwqe/card_dev.c:827: warning: Function parameter or member 'cfile' not described in 'ddcb_cmd_cleanup' drivers/misc/genwqe/card_dev.c:827: warning: Function parameter or member 'req' not described in 'ddcb_cmd_cleanup' drivers/misc/genwqe/card_dev.c:854: warning: Function parameter or member 'cfile' not described in 'ddcb_cmd_fixups' drivers/misc/genwqe/card_dev.c:854: warning: Function parameter or member 'req' not described in 'ddcb_cmd_fixups' drivers/misc/genwqe/card_dev.c:984: warning: Function parameter or member 'cfile' not described in 'genwqe_execute_ddcb' drivers/misc/genwqe/card_dev.c:984: warning: Function parameter or member 'cmd' not described in 'genwqe_execute_ddcb' drivers/misc/genwqe/card_dev.c:1350: warning: Function parameter or member 'cd' not described in 'genwqe_device_remove'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_dev.c | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)
drivers/misc/genwqe/card_dev.c +18 -6
index 040a0bda31254..55fc5b80e649f 100644
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0-only
-/**
+/*
  * IBM Accelerator Family 'GenWQE'
  *
  * (C) Copyright IBM Corp. 2013
@@ -87,7 +87,7 @@ static int genwqe_del_pin(struct genwqe_file *cfile, struct dma_mapping *m)
  * @cfile:	Descriptor of opened file
  * @u_addr:	User virtual address
  * @size:	Size of buffer
- * @dma_addr:	DMA address to be updated
+ * @virt_addr:	Virtual address to be updated
  *
  * Return: Pointer to the corresponding mapping	NULL if not found
  */
@@ -144,6 +144,7 @@ static void __genwqe_del_mapping(struct genwqe_file *cfile,
  * @u_addr:	user virtual address
  * @size:	size of buffer
  * @dma_addr:	DMA address to be updated
+ * @virt_addr:	Virtual address to be updated
  * Return: Pointer to the corresponding mapping	NULL if not found
  */
 static struct dma_mapping *__genwqe_search_mapping(struct genwqe_file *cfile,
@@ -249,6 +250,8 @@ static void genwqe_remove_pinnings(struct genwqe_file *cfile)
 
 /**
  * genwqe_kill_fasync() - Send signal to all processes with open GenWQE files
+ * @cd: GenWQE device information
+ * @sig: Signal to send out
  *
  * E.g. genwqe_send_signal(cd, SIGIO);
  */
@@ -380,6 +383,7 @@ static void genwqe_vma_open(struct vm_area_struct *vma)
 
 /**
  * genwqe_vma_close() - Called each time when vma is unmapped
+ * @vma: VMA area to close
  *
  * Free memory which got allocated by GenWQE mmap().
  */
@@ -416,6 +420,8 @@ static const struct vm_operations_struct genwqe_vma_ops = {
 
 /**
  * genwqe_mmap() - Provide contignous buffers to userspace
+ * @filp:	File pointer (unused)
+ * @vma:	VMA area to map
  *
  * We use mmap() to allocate contignous buffers used for DMA
  * transfers. After the buffer is allocated we remap it to user-space
@@ -484,16 +490,15 @@ static int genwqe_mmap(struct file *filp, struct vm_area_struct *vma)
 	return rc;
 }
 
+#define	FLASH_BLOCK	0x40000	/* we use 256k blocks */
+
 /**
  * do_flash_update() - Excute flash update (write image or CVPD)
- * @cd:        genwqe device
+ * @cfile:	Descriptor of opened file
  * @load:      details about image load
  *
  * Return: 0 if successful
  */
-
-#define	FLASH_BLOCK	0x40000	/* we use 256k blocks */
-
 static int do_flash_update(struct genwqe_file *cfile,
 			   struct genwqe_bitstream *load)
 {
@@ -820,6 +825,8 @@ static int genwqe_unpin_mem(struct genwqe_file *cfile, struct genwqe_mem *m)
 
 /**
  * ddcb_cmd_cleanup() - Remove dynamically created fixup entries
+ * @cfile:	Descriptor of opened file
+ * @req:	DDCB work request
  *
  * Only if there are any. Pinnings are not removed.
  */
@@ -844,6 +851,8 @@ static int ddcb_cmd_cleanup(struct genwqe_file *cfile, struct ddcb_requ *req)
 
 /**
  * ddcb_cmd_fixups() - Establish DMA fixups/sglists for user memory references
+ * @cfile:	Descriptor of opened file
+ * @req:	DDCB work request
  *
  * Before the DDCB gets executed we need to handle the fixups. We
  * replace the user-space addresses with DMA addresses or do
@@ -974,6 +983,8 @@ static int ddcb_cmd_fixups(struct genwqe_file *cfile, struct ddcb_requ *req)
 
 /**
  * genwqe_execute_ddcb() - Execute DDCB using userspace address fixups
+ * @cfile:	Descriptor of opened file
+ * @cmd:        Command identifier (passed from user)
  *
  * The code will build up the translation tables or lookup the
  * contignous memory allocation table to find the right translations
@@ -1339,6 +1350,7 @@ static int genwqe_inform_and_stop_processes(struct genwqe_dev *cd)
 
 /**
  * genwqe_device_remove() - Remove genwqe's char device
+ * @cd: GenWQE device information
  *
  * This function must be called after the client devices are removed
  * because it will free the major/minor number range for the genwqe
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
#38 lore raw

Re: [PATCH 19/20] misc: genwqe: card_dev: Whole host of kerneldoc fixes

Quoted 174 lines · Lee Jones

Including; add missing documentation for function arguments, re-ordering of #defines i.e. not placed between kerneldoc headers and the functions they are documenting, demotion of file header/comment from kerneldoc format and removal of documentation for non-existent args.

Fixes the following W=1 kernel build warnings:

drivers/misc/genwqe/card_dev.c:33: warning: Function parameter or
member 'cd' not described in 'genwqe_open_files'
drivers/misc/genwqe/card_dev.c:98: warning: Function parameter or
member 'virt_addr' not described in 'genwqe_search_pin'
drivers/misc/genwqe/card_dev.c:98: warning: Excess function parameter
'dma_addr' description in 'genwqe_search_pin'
drivers/misc/genwqe/card_dev.c:154: warning: Function parameter or
member 'virt_addr' not described in '__genwqe_search_mapping'
drivers/misc/genwqe/card_dev.c:256: warning: Function parameter or
member 'cd' not described in 'genwqe_kill_fasync'
drivers/misc/genwqe/card_dev.c:256: warning: Function parameter or
member 'sig' not described in 'genwqe_kill_fasync'
drivers/misc/genwqe/card_dev.c:387: warning: Function parameter or
member 'vma' not described in 'genwqe_vma_close'
drivers/misc/genwqe/card_dev.c:430: warning: Function parameter or
member 'filp' not described in 'genwqe_mmap'
drivers/misc/genwqe/card_dev.c:430: warning: Function parameter or
member 'vma' not described in 'genwqe_mmap'
drivers/misc/genwqe/card_dev.c:495: warning: Excess function
parameter 'cd' description in 'FLASH_BLOCK'
drivers/misc/genwqe/card_dev.c:495: warning: Excess function
parameter 'load' description in 'FLASH_BLOCK'
drivers/misc/genwqe/card_dev.c:827: warning: Function parameter or
member 'cfile' not described in 'ddcb_cmd_cleanup'
drivers/misc/genwqe/card_dev.c:827: warning: Function parameter or
member 'req' not described in 'ddcb_cmd_cleanup'
drivers/misc/genwqe/card_dev.c:854: warning: Function parameter or
member 'cfile' not described in 'ddcb_cmd_fixups'
drivers/misc/genwqe/card_dev.c:854: warning: Function parameter or
member 'req' not described in 'ddcb_cmd_fixups'
drivers/misc/genwqe/card_dev.c:984: warning: Function parameter or
member 'cfile' not described in 'genwqe_execute_ddcb'
drivers/misc/genwqe/card_dev.c:984: warning: Function parameter or
member 'cmd' not described in 'genwqe_execute_ddcb'
drivers/misc/genwqe/card_dev.c:1350: warning: Function parameter or
member 'cd' not described in 'genwqe_device_remove'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>
---
 drivers/misc/genwqe/card_dev.c | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)
drivers/misc/genwqe/card_dev.c +2 -2
index 040a0bda31254..55fc5b80e649f 100644
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0-only
-/**
+/*
  * IBM Accelerator Family 'GenWQE'
  *
  * (C) Copyright IBM Corp. 2013
@@ -87,7 +87,7 @@ static int genwqe_del_pin(struct genwqe_file *cfile,
 struct dma_mapping *m)
  * @cfile:	Descriptor of opened file
  * @u_addr:	User virtual address
  * @size:	Size of buffer
- * @dma_addr:	DMA address to be updated
+ * @virt_addr:	Virtual address to be updated
  *
  * Return: Pointer to the corresponding mapping	NULL if not found

*/

drivers/misc/genwqe/card_dev.c +1 -0
@@ -144,6 +144,7 @@ static void __genwqe_del_mapping(struct genwqe_file 
 *cfile,
  * @u_addr:	user virtual address
  * @size:	size of buffer
  * @dma_addr:	DMA address to be updated
+ * @virt_addr:	Virtual address to be updated
  * Return: Pointer to the corresponding mapping	NULL if not found
  */

static struct dma_mapping *__genwqe_search_mapping(struct genwqe_file
*cfile,

drivers/misc/genwqe/card_dev.c +0 -0
@@ -249,6 +250,8 @@ static void genwqe_remove_pinnings(struct
 genwqe_file *cfile)
 
 /**
  * genwqe_kill_fasync() - Send signal to all processes with open 

GenWQE files
+ * @cd: GenWQE device information
+ * @sig: Signal to send out
*
* E.g. genwqe_send_signal(cd, SIGIO);
*/

drivers/misc/genwqe/card_dev.c +1 -0
@@ -380,6 +383,7 @@ static void genwqe_vma_open(struct vm_area_struct 
 *vma)
 
 /**
  * genwqe_vma_close() - Called each time when vma is unmapped
+ * @vma: VMA area to close
  *
  * Free memory which got allocated by GenWQE mmap().

*/

drivers/misc/genwqe/card_dev.c +2 -0
@@ -416,6 +420,8 @@ static const struct vm_operations_struct 
 genwqe_vma_ops = {
 
 /**
  * genwqe_mmap() - Provide contignous buffers to userspace
+ * @filp:	File pointer (unused)
+ * @vma:	VMA area to map
  *
  * We use mmap() to allocate contignous buffers used for DMA

* transfers. After the buffer is allocated we remap it to user-space

drivers/misc/genwqe/card_dev.c +3 -4
@@ -484,16 +490,15 @@ static int genwqe_mmap(struct file *filp, struct
 vm_area_struct *vma)
 	return rc;
 }
 
+#define	FLASH_BLOCK	0x40000	/* we use 256k blocks */
+
 /**
  * do_flash_update() - Excute flash update (write image or CVPD)
- * @cd:        genwqe device
+ * @cfile:	Descriptor of opened file
  * @load:      details about image load
  *
  * Return: 0 if successful
  */
-
-#define	FLASH_BLOCK	0x40000	/* we use 256k blocks */
-
 static int do_flash_update(struct genwqe_file *cfile,
 			   struct genwqe_bitstream *load)

{

drivers/misc/genwqe/card_dev.c +2 -0
@@ -820,6 +825,8 @@ static int genwqe_unpin_mem(struct genwqe_file
 *cfile, struct genwqe_mem *m)
 
 /**
  * ddcb_cmd_cleanup() - Remove dynamically created fixup entries
+ * @cfile:	Descriptor of opened file
+ * @req:	DDCB work request
  *
  * Only if there are any. Pinnings are not removed.

*/

drivers/misc/genwqe/card_dev.c +0 -0
@@ -844,6 +851,8 @@ static int ddcb_cmd_cleanup(struct genwqe_file
 *cfile, struct ddcb_requ *req)
 
 /**
  * ddcb_cmd_fixups() - Establish DMA fixups/sglists for user memory 

references
+ * @cfile: Descriptor of opened file
+ * @req: DDCB work request
*
* Before the DDCB gets executed we need to handle the fixups. We
* replace the user-space addresses with DMA addresses or do

drivers/misc/genwqe/card_dev.c +2 -0
@@ -974,6 +983,8 @@ static int ddcb_cmd_fixups(struct genwqe_file
 *cfile, struct ddcb_requ *req)
 
 /**
  * genwqe_execute_ddcb() - Execute DDCB using userspace address fixups
+ * @cfile:	Descriptor of opened file
+ * @cmd:        Command identifier (passed from user)
  *
  * The code will build up the translation tables or lookup the

* contignous memory allocation table to find the right translations

drivers/misc/genwqe/card_dev.c +1 -0
@@ -1339,6 +1350,7 @@ static int
 genwqe_inform_and_stop_processes(struct genwqe_dev *cd)
 
 /**
  * genwqe_device_remove() - Remove genwqe's char device
+ * @cd: GenWQE device information
  *
  * This function must be called after the client devices are removed
Quoted 1 line

* because it will free the major/minor number range for the genwqe

Ok.

author
#39 lore raw

PATCH 20/20 misc: genwqe: card_utils: Whole a plethora of documentation issues

In reply to Lee Jones

Including; demoting file header from kerneldoc to standard comment/ header, adding a variety of missing function argument documentation, repairing formatting (kerneldoc does not like blank lines) and the demotion of a kerneldoc header which shows no interest in providing documentation for any of its arguments.

Fixes this the following W=1 issues:

drivers/misc/genwqe/card_utils.c:37: warning: Incorrect use of kernel-doc format: * __genwqe_writeq() - Write 64-bit register drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or member 'cd' not described in '__genwqe_writeq' drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or member 'byte_offs' not described in '__genwqe_writeq' drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or member 'val' not described in '__genwqe_writeq' drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or member 'cd' not described in 'genwqe_read_app_id' drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or member 'app_name' not described in 'genwqe_read_app_id' drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or member 'len' not described in 'genwqe_read_app_id' drivers/misc/genwqe/card_utils.c:186: warning: bad line:
drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or member 'cd' not described in 'genwqe_alloc_sync_sgl' drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or member 'sgl' not described in 'genwqe_alloc_sync_sgl' drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or member 'user_addr' not described in 'genwqe_alloc_sync_sgl' drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or member 'user_size' not described in 'genwqe_alloc_sync_sgl' drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or member 'write' not described in 'genwqe_alloc_sync_sgl' drivers/misc/genwqe/card_utils.c:469: warning: Function parameter or member 'cd' not described in 'genwqe_free_sync_sgl' drivers/misc/genwqe/card_utils.c:469: warning: Function parameter or member 'sgl' not described in 'genwqe_free_sync_sgl' drivers/misc/genwqe/card_utils.c:716: warning: Function parameter or member 'count' not described in 'genwqe_set_interrupt_capability' drivers/misc/genwqe/card_utils.c:747: warning: Function parameter or member 'idx' not described in 'set_reg_idx' drivers/misc/genwqe/card_utils.c:747: warning: Excess function parameter 'index' description in 'set_reg_idx' drivers/misc/genwqe/card_utils.c:823: warning: Function parameter or member 'cd' not described in 'genwqe_ffdc_buff_size' drivers/misc/genwqe/card_utils.c:823: warning: Function parameter or member 'uid' not described in 'genwqe_ffdc_buff_size' drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or member 'cd' not described in 'genwqe_ffdc_buff_read' drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or member 'uid' not described in 'genwqe_ffdc_buff_read' drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or member 'regs' not described in 'genwqe_ffdc_buff_read' drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or member 'max_regs' not described in 'genwqe_ffdc_buff_read' drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or member 'cd' not described in 'genwqe_write_vreg' drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or member 'reg' not described in 'genwqe_write_vreg' drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or member 'val' not described in 'genwqe_write_vreg' drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or member 'func' not described in 'genwqe_write_vreg' drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or member 'cd' not described in 'genwqe_read_vreg' drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or member 'reg' not described in 'genwqe_read_vreg' drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or member 'func' not described in 'genwqe_read_vreg' drivers/misc/genwqe/card_utils.c:995: warning: Function parameter or member 'cd' not described in 'genwqe_base_clock_frequency' drivers/misc/genwqe/card_utils.c:1012: warning: Function parameter or member 'cd' not described in 'genwqe_stop_traps' drivers/misc/genwqe/card_utils.c:1022: warning: Function parameter or member 'cd' not described in 'genwqe_start_traps'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>

# Please enter the commit message for your changes. Lines starting

 # with '#' will be ignored, and an empty message aborts the commit.
 #
 # Date:      Mon Jun 29 10:30:56 2020 +0100
 #
 # On branch tb-mfd-fix-warnings
 # Changes to be committed:
 #	modified:   drivers/misc/genwqe/card_utils.c
 #
 # Untracked files:
 #	qemu-i2c-devs.txt
 #
---
 drivers/misc/genwqe/card_utils.c | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)
drivers/misc/genwqe/card_utils.c +26 -4
index 77c21caf2acd1..039b923d1d60a 100644
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0-only
-/**
+/*
  * IBM Accelerator Family 'GenWQE'
  *
  * (C) Copyright IBM Corp. 2013
@@ -129,6 +129,9 @@ u32 __genwqe_readl(struct genwqe_dev *cd, u64 byte_offs)
 
 /**
  * genwqe_read_app_id() - Extract app_id
+ * @cd:	        genwqe device descriptor
+ * @app_name:   carrier used to pass-back name
+ * @len:        length of data for name
  *
  * app_unitcfg need to be filled with valid data first
  */
@@ -183,7 +186,7 @@ void genwqe_init_crc32(void)
  * @init:       initial crc (0xffffffff at start)
  *
  * polynomial = x^32 * + x^29 + x^18 + x^14 + x^3 + 1 (0x20044009)
-
+ *
  * Example: 4 bytes 0x01 0x02 0x03 0x04 with init=0xffffffff should
  * result in a crc32 of 0xf33cb7d3.
  *
@@ -277,7 +280,7 @@ static int genwqe_sgl_size(int num_pages)
 	return roundup(len, PAGE_SIZE);
 }
 
-/**
+/*
  * genwqe_alloc_sync_sgl() - Allocate memory for sgl and overlapping pages
  *
  * Allocates memory for sgl and overlapping pages. Pages which might
@@ -460,6 +463,8 @@ int genwqe_setup_sgl(struct genwqe_dev *cd, struct genwqe_sgl *sgl,
 
 /**
  * genwqe_free_sync_sgl() - Free memory for sgl and overlapping pages
+ * @cd:	        genwqe device descriptor
+ * @sgl:        scatter gather list describing user-space memory
  *
  * After the DMA transfer has been completed we free the memory for
  * the sgl and the cached pages. Data is being transferred from cached
@@ -710,6 +715,7 @@ int genwqe_read_softreset(struct genwqe_dev *cd)
 /**
  * genwqe_set_interrupt_capability() - Configure MSI capability structure
  * @cd:         pointer to the device
+ * @count:      number of vectors to allocate
  * Return: 0 if no error
  */
 int genwqe_set_interrupt_capability(struct genwqe_dev *cd, int count)
@@ -738,7 +744,7 @@ void genwqe_reset_interrupt_capability(struct genwqe_dev *cd)
  * @i:          index to desired entry
  * @m:          maximum possible entries
  * @addr:       addr which is read
- * @index:      index in debug array
+ * @idx:        index in debug array
  * @val:        read value
  */
 static int set_reg_idx(struct genwqe_dev *cd, struct genwqe_reg *r,
@@ -818,6 +824,8 @@ int genwqe_read_ffdc_regs(struct genwqe_dev *cd, struct genwqe_reg *regs,
 
 /**
  * genwqe_ffdc_buff_size() - Calculates the number of dump registers
+ * @cd:	        genwqe device descriptor
+ * @uid:	unit ID
  */
 int genwqe_ffdc_buff_size(struct genwqe_dev *cd, int uid)
 {
@@ -871,6 +879,10 @@ int genwqe_ffdc_buff_size(struct genwqe_dev *cd, int uid)
 
 /**
  * genwqe_ffdc_buff_read() - Implements LogoutExtendedErrorRegisters procedure
+ * @cd:	        genwqe device descriptor
+ * @uid:	unit ID
+ * @regs:       register information
+ * @max_regs:   number of register entries
  */
 int genwqe_ffdc_buff_read(struct genwqe_dev *cd, int uid,
 			  struct genwqe_reg *regs, unsigned int max_regs)
@@ -956,6 +968,10 @@ int genwqe_ffdc_buff_read(struct genwqe_dev *cd, int uid,
 
 /**
  * genwqe_write_vreg() - Write register in virtual window
+ * @cd:	        genwqe device descriptor
+ * @reg:	register (byte) offset within BAR
+ * @val:	value to write
+ * @func:	PCI virtual function
  *
  * Note, these registers are only accessible to the PF through the
  * VF-window. It is not intended for the VF to access.
@@ -969,6 +985,9 @@ int genwqe_write_vreg(struct genwqe_dev *cd, u32 reg, u64 val, int func)
 
 /**
  * genwqe_read_vreg() - Read register in virtual window
+ * @cd:	        genwqe device descriptor
+ * @reg:	register (byte) offset within BAR
+ * @func:	PCI virtual function
  *
  * Note, these registers are only accessible to the PF through the
  * VF-window. It is not intended for the VF to access.
@@ -981,6 +1000,7 @@ u64 genwqe_read_vreg(struct genwqe_dev *cd, u32 reg, int func)
 
 /**
  * genwqe_base_clock_frequency() - Deteremine base clock frequency of the card
+ * @cd:	        genwqe device descriptor
  *
  * Note: From a design perspective it turned out to be a bad idea to
  * use codes here to specifiy the frequency/speed values. An old
@@ -1005,6 +1025,7 @@ int genwqe_base_clock_frequency(struct genwqe_dev *cd)
 
 /**
  * genwqe_stop_traps() - Stop traps
+ * @cd:	        genwqe device descriptor
  *
  * Before reading out the analysis data, we need to stop the traps.
  */
@@ -1015,6 +1036,7 @@ void genwqe_stop_traps(struct genwqe_dev *cd)
 
 /**
  * genwqe_start_traps() - Start traps
+ * @cd:	        genwqe device descriptor
  *
  * After having read the data, we can/must enable the traps again.
  */
Signature · 7 lines
2.25.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
#40 lore raw

Re: [PATCH 20/20] misc: genwqe: card_utils: Whole a plethora of documentation issues

Quoted 234 lines · Lee Jones

Including; demoting file header from kerneldoc to standard comment/ header, adding a variety of missing function argument documentation, repairing formatting (kerneldoc does not like blank lines) and the demotion of a kerneldoc header which shows no interest in providing documentation for any of its arguments.

Fixes this the following W=1 issues:

drivers/misc/genwqe/card_utils.c:37: warning: Incorrect use of
kernel-doc format: * __genwqe_writeq() - Write 64-bit register
drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or
member 'cd' not described in '__genwqe_writeq'
drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or
member 'byte_offs' not described in '__genwqe_writeq'
drivers/misc/genwqe/card_utils.c:45: warning: Function parameter or
member 'val' not described in '__genwqe_writeq'
drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or
member 'cd' not described in 'genwqe_read_app_id'
drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or
member 'app_name' not described in 'genwqe_read_app_id'
drivers/misc/genwqe/card_utils.c:136: warning: Function parameter or
member 'len' not described in 'genwqe_read_app_id'
drivers/misc/genwqe/card_utils.c:186: warning: bad line:
drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
member 'cd' not described in 'genwqe_alloc_sync_sgl'
drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
member 'sgl' not described in 'genwqe_alloc_sync_sgl'
drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
member 'user_addr' not described in 'genwqe_alloc_sync_sgl'
drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
member 'user_size' not described in 'genwqe_alloc_sync_sgl'
drivers/misc/genwqe/card_utils.c:290: warning: Function parameter or
member 'write' not described in 'genwqe_alloc_sync_sgl'
drivers/misc/genwqe/card_utils.c:469: warning: Function parameter or
member 'cd' not described in 'genwqe_free_sync_sgl'
drivers/misc/genwqe/card_utils.c:469: warning: Function parameter or
member 'sgl' not described in 'genwqe_free_sync_sgl'
drivers/misc/genwqe/card_utils.c:716: warning: Function parameter or
member 'count' not described in 'genwqe_set_interrupt_capability'
drivers/misc/genwqe/card_utils.c:747: warning: Function parameter or
member 'idx' not described in 'set_reg_idx'
drivers/misc/genwqe/card_utils.c:747: warning: Excess function
parameter 'index' description in 'set_reg_idx'
drivers/misc/genwqe/card_utils.c:823: warning: Function parameter or
member 'cd' not described in 'genwqe_ffdc_buff_size'
drivers/misc/genwqe/card_utils.c:823: warning: Function parameter or
member 'uid' not described in 'genwqe_ffdc_buff_size'
drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
member 'cd' not described in 'genwqe_ffdc_buff_read'
drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
member 'uid' not described in 'genwqe_ffdc_buff_read'
drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
member 'regs' not described in 'genwqe_ffdc_buff_read'
drivers/misc/genwqe/card_utils.c:877: warning: Function parameter or
member 'max_regs' not described in 'genwqe_ffdc_buff_read'
drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
member 'cd' not described in 'genwqe_write_vreg'
drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
member 'reg' not described in 'genwqe_write_vreg'
drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
member 'val' not described in 'genwqe_write_vreg'
drivers/misc/genwqe/card_utils.c:964: warning: Function parameter or
member 'func' not described in 'genwqe_write_vreg'
drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or
member 'cd' not described in 'genwqe_read_vreg'
drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or
member 'reg' not described in 'genwqe_read_vreg'
drivers/misc/genwqe/card_utils.c:977: warning: Function parameter or
member 'func' not described in 'genwqe_read_vreg'
drivers/misc/genwqe/card_utils.c:995: warning: Function parameter or
member 'cd' not described in 'genwqe_base_clock_frequency'
drivers/misc/genwqe/card_utils.c:1012: warning: Function parameter or
member 'cd' not described in 'genwqe_stop_traps'
drivers/misc/genwqe/card_utils.c:1022: warning: Function parameter or
member 'cd' not described in 'genwqe_start_traps'

Cc Michael Jung <[email protected]>
Cc Michael Ruettger <[email protected]>
Cc Frank Haverkamp <[email protected]>
Cc Joerg-Stephan Vogt <[email protected]>

# Please enter the commit message for your changes. Lines starting

 # with '#' will be ignored, and an empty message aborts the commit.
 #
 # Date:      Mon Jun 29 10:30:56 2020 +0100
 #
 # On branch tb-mfd-fix-warnings
 # Changes to be committed:
 #	modified:   drivers/misc/genwqe/card_utils.c
 #
 # Untracked files:
 #	qemu-i2c-devs.txt
 #
---
 drivers/misc/genwqe/card_utils.c | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)
drivers/misc/genwqe/card_utils.c +4 -1
index 77c21caf2acd1..039b923d1d60a 100644
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0-only
-/**
+/*
  * IBM Accelerator Family 'GenWQE'
  *
  * (C) Copyright IBM Corp. 2013
@@ -129,6 +129,9 @@ u32 __genwqe_readl(struct genwqe_dev *cd, u64 
 byte_offs)
 
 /**
  * genwqe_read_app_id() - Extract app_id
+ * @cd:	        genwqe device descriptor
+ * @app_name:   carrier used to pass-back name
+ * @len:        length of data for name
  *
  * app_unitcfg need to be filled with valid data first

*/

drivers/misc/genwqe/card_utils.c +2 -2
@@ -183,7 +186,7 @@ void genwqe_init_crc32(void)
  * @init:       initial crc (0xffffffff at start)
  *
  * polynomial = x^32 * + x^29 + x^18 + x^14 + x^3 + 1 (0x20044009)
-
+ *
  * Example: 4 bytes 0x01 0x02 0x03 0x04 with init=0xffffffff should
  * result in a crc32 of 0xf33cb7d3.
  *
@@ -277,7 +280,7 @@ static int genwqe_sgl_size(int num_pages)
 	return roundup(len, PAGE_SIZE);
 }
 
-/**
+/*
  * genwqe_alloc_sync_sgl() - Allocate memory for sgl and overlapping 

pages
*
* Allocates memory for sgl and overlapping pages. Pages which might

drivers/misc/genwqe/card_utils.c +2 -0
@@ -460,6 +463,8 @@ int genwqe_setup_sgl(struct genwqe_dev *cd, struct
 genwqe_sgl *sgl,
 
 /**
  * genwqe_free_sync_sgl() - Free memory for sgl and overlapping pages
+ * @cd:	        genwqe device descriptor
+ * @sgl:        scatter gather list describing user-space memory
  *
  * After the DMA transfer has been completed we free the memory for

* the sgl and the cached pages. Data is being transferred from cached

drivers/misc/genwqe/card_utils.c +0 -0
@@ -710,6 +715,7 @@ int genwqe_read_softreset(struct genwqe_dev *cd)
 /**
  * genwqe_set_interrupt_capability() - Configure MSI capability 

structure
* @cd: pointer to the device
+ * @count: number of vectors to allocate
* Return: 0 if no error
*/
int genwqe_set_interrupt_capability(struct genwqe_dev *cd, int count)

drivers/misc/genwqe/card_utils.c +1 -1
@@ -738,7 +744,7 @@ void genwqe_reset_interrupt_capability(struct
 genwqe_dev *cd)
  * @i:          index to desired entry
  * @m:          maximum possible entries
  * @addr:       addr which is read
- * @index:      index in debug array
+ * @idx:        index in debug array
  * @val:        read value
  */

static int set_reg_idx(struct genwqe_dev *cd, struct genwqe_reg *r,

drivers/misc/genwqe/card_utils.c +2 -0
@@ -818,6 +824,8 @@ int genwqe_read_ffdc_regs(struct genwqe_dev *cd,
 struct genwqe_reg *regs,
 
 /**
  * genwqe_ffdc_buff_size() - Calculates the number of dump registers
+ * @cd:	        genwqe device descriptor
+ * @uid:	unit ID
  */
 int genwqe_ffdc_buff_size(struct genwqe_dev *cd, int uid)

{

drivers/misc/genwqe/card_utils.c +0 -0
@@ -871,6 +879,10 @@ int genwqe_ffdc_buff_size(struct genwqe_dev *cd, 
 int uid)
 
 /**
  * genwqe_ffdc_buff_read() - Implements LogoutExtendedErrorRegisters 

procedure
+ * @cd: genwqe device descriptor
+ * @uid: unit ID
+ * @regs: register information
+ * @max_regs: number of register entries
*/
int genwqe_ffdc_buff_read(struct genwqe_dev *cd, int uid,

drivers/misc/genwqe/card_utils.c +4 -0
 			  struct genwqe_reg *regs, unsigned int max_regs)
@@ -956,6 +968,10 @@ int genwqe_ffdc_buff_read(struct genwqe_dev *cd, 
 int uid,
 
 /**
  * genwqe_write_vreg() - Write register in virtual window
+ * @cd:	        genwqe device descriptor
+ * @reg:	register (byte) offset within BAR
+ * @val:	value to write
+ * @func:	PCI virtual function
  *
  * Note, these registers are only accessible to the PF through the

* VF-window. It is not intended for the VF to access.

drivers/misc/genwqe/card_utils.c +3 -0
@@ -969,6 +985,9 @@ int genwqe_write_vreg(struct genwqe_dev *cd, u32
 reg, u64 val, int func)
 
 /**
  * genwqe_read_vreg() - Read register in virtual window
+ * @cd:	        genwqe device descriptor
+ * @reg:	register (byte) offset within BAR
+ * @func:	PCI virtual function
  *
  * Note, these registers are only accessible to the PF through the

* VF-window. It is not intended for the VF to access.

drivers/misc/genwqe/card_utils.c +0 -0
@@ -981,6 +1000,7 @@ u64 genwqe_read_vreg(struct genwqe_dev *cd, u32
 reg, int func)
 
 /**
  * genwqe_base_clock_frequency() - Deteremine base clock frequency of 

the card
+ * @cd: genwqe device descriptor
*
* Note: From a design perspective it turned out to be a bad idea to
* use codes here to specifiy the frequency/speed values. An old

drivers/misc/genwqe/card_utils.c +1 -0
@@ -1005,6 +1025,7 @@ int genwqe_base_clock_frequency(struct genwqe_dev 
 *cd)
 
 /**
  * genwqe_stop_traps() - Stop traps
+ * @cd:	        genwqe device descriptor
  *
  * Before reading out the analysis data, we need to stop the traps.

*/

drivers/misc/genwqe/card_utils.c void genwqe_stop_traps(struct genwqe_dev *cd) · line 1042

Quoted 7 lines
drivers/misc/genwqe/card_utils.c +1 -0
@@ -1015,6 +1036,7 @@ void genwqe_stop_traps(struct genwqe_dev *cd)
 
 /**
  * genwqe_start_traps() - Start traps
+ * @cd:	        genwqe device descriptor
  *
  * After having read the data, we can/must enable the traps again.
  */

Thanks for adding proper documentation to our driver.