[PATCH 03/10] misc: ti-st: st_kim: Tidy-up bespoke commentry

From: Lee Jones
Date: Fri Jun 26 2020 - 09:05:50 EST

Next message: Lee Jones: "[PATCH 09/10] misc: habanalabs: irq: Add missing struct identifier for 'struct hl_eqe_work'"
Previous message: Lee Jones: "[PATCH 07/10] misc: mic: vop: vop_main: Remove set but unused variable 'ret'"
In reply to: Arnd Bergmann: "Re: [PATCH 07/10] misc: mic: vop: vop_main: Remove set but unused variable 'ret'"
Next in thread: Arnd Bergmann: "Re: [PATCH 03/10] misc: ti-st: st_kim: Tidy-up bespoke commentry"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

If it's still in use and worth the effort, it sure looks like
this driver could do with a good scrub (clean).

This patch conserns itself with the non-standard comments located
thoughout the file.

It also fixes the following W=1 warnings by demoting the kerneldoc
function headers to standard comments, since there doesn't appear
to be a requirement for the function args to be documented:

/drivers/misc/ti-st/st_kim.c:42: warning: Function parameter or member 'id' not described in 'st_get_plat_device'
/drivers/misc/ti-st/st_kim.c:53: warning: Function parameter or member 'kim_gdata' not described in 'validate_firmware_response'
/drivers/misc/ti-st/st_kim.c:126: warning: Function parameter or member 'kim_gdata' not described in 'kim_int_recv'
/drivers/misc/ti-st/st_kim.c:126: warning: Function parameter or member 'data' not described in 'kim_int_recv'
/drivers/misc/ti-st/st_kim.c:126: warning: Function parameter or member 'count' not described in 'kim_int_recv'
/drivers/misc/ti-st/st_kim.c:272: warning: Function parameter or member 'kim_gdata' not described in 'download_firmware'
/drivers/misc/ti-st/st_kim.c:445: warning: Function parameter or member 'kim_data' not described in 'st_kim_start'
/drivers/misc/ti-st/st_kim.c:509: warning: Function parameter or member 'kim_data' not described in 'st_kim_stop'
/drivers/misc/ti-st/st_kim.c:661: warning: Function parameter or member 'core_data' not described in 'st_kim_ref'
/drivers/misc/ti-st/st_kim.c:661: warning: Function parameter or member 'id' not described in 'st_kim_ref'

Cc: Pavan Savoy <pavan_savoy@xxxxxx>
Signed-off-by: Lee Jones <lee.jones@xxxxxxxxxx>
---
drivers/misc/ti-st/st_kim.c | 71 +++++++++++++++++++++++--------------
1 file changed, 44 insertions(+), 27 deletions(-)

diff --git a/drivers/misc/ti-st/st_kim.c b/drivers/misc/ti-st/st_kim.c
index a36ed1ff5967f..f2f6cab97c086 100644
--- a/drivers/misc/ti-st/st_kim.c
+++ b/drivers/misc/ti-st/st_kim.c
@@ -30,7 +30,7 @@ static struct platform_device *st_kim_devices[MAX_ST_DEVICES];
/**********************************************************************/
/* internal functions */

-/**
+/*
* st_get_plat_device -
* function which returns the reference to the platform device
* requested by id. As of now only 1 such device exists (id=0)
@@ -43,7 +43,7 @@ static struct platform_device *st_get_plat_device(int id)
return st_kim_devices[id];
}

-/**
+/*
* validate_firmware_response -
* function to return whether the firmware response was proper
* in case of error don't complete so that waiting for proper
@@ -55,7 +55,8 @@ static void validate_firmware_response(struct kim_data_s *kim_gdata)
if (!skb)
return;

- /* these magic numbers are the position in the response buffer which
+ /*
+ * these magic numbers are the position in the response buffer which
* allows us to distinguish whether the response is for the read
* version info. command
*/
@@ -79,7 +80,8 @@ static void validate_firmware_response(struct kim_data_s *kim_gdata)
kfree_skb(skb);
}

-/* check for data len received inside kim_int_recv
+/*
+ * check for data len received inside kim_int_recv
* most often hit the last case to update state to waiting for data
*/
static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len)
@@ -91,14 +93,16 @@ static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len)
if (!len) {
validate_firmware_response(kim_gdata);
} else if (len > room) {
- /* Received packet's payload length is larger.
+ /*
+ * Received packet's payload length is larger.
* We can't accommodate it in created skb.
*/
pr_err("Data length is too large len %d room %d", len,
room);
kfree_skb(kim_gdata->rx_skb);
} else {
- /* Packet header has non-zero payload length and
+ /*
+ * Packet header has non-zero payload length and
* we have enough space in created skb. Lets read
* payload data */
kim_gdata->rx_state = ST_W4_DATA;
@@ -106,8 +110,10 @@ static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len)
return len;
}

- /* Change ST LL state to continue to process next
- * packet */
+ /*
+ * Change ST LL state to continue to process next
+ * packet
+ */
kim_gdata->rx_state = ST_W4_PACKET_TYPE;
kim_gdata->rx_skb = NULL;
kim_gdata->rx_count = 0;
@@ -115,7 +121,7 @@ static inline int kim_check_data_len(struct kim_data_s *kim_gdata, int len)
return 0;
}

-/**
+/*
* kim_int_recv - receive function called during firmware download
* firmware download responses on different UART drivers
* have been observed to come in bursts of different
@@ -216,7 +222,8 @@ static long read_local_version(struct kim_data_s *kim_gdata, char *bts_scr_name)
return timeout ? -ERESTARTSYS : -ETIMEDOUT;
}
reinit_completion(&kim_gdata->kim_rcvd);
- /* the positions 12 & 13 in the response buffer provide with the
+ /*
+ * the positions 12 & 13 in the response buffer provide with the
* chip, major & minor numbers
*/

@@ -263,7 +270,7 @@ static void skip_change_remote_baud(unsigned char **ptr, long *len)
}
}

-/**
+/*
* download_firmware -
* internal function which parses through the .bts firmware
* script file intreprets SEND, DELAY actions only as of now
@@ -295,7 +302,8 @@ static long download_firmware(struct kim_data_s *kim_gdata)
}
ptr = (void *)kim_gdata->fw_entry->data;
len = kim_gdata->fw_entry->size;
- /* bts_header to remove out magic number and
+ /*
+ * bts_header to remove out magic number and
* version
*/
ptr += sizeof(struct bts_header);
@@ -313,8 +321,10 @@ static long download_firmware(struct kim_data_s *kim_gdata)
if (unlikely
(((struct hci_command *)action_ptr)->opcode ==
0xFF36)) {
- /* ignore remote change
- * baud rate HCI VS command */
+ /*
+ * ignore remote change
+ * baud rate HCI VS command
+ */
pr_warn("change remote baud"
" rate command in firmware");
skip_change_remote_baud(&ptr, &len);
@@ -346,7 +356,8 @@ static long download_firmware(struct kim_data_s *kim_gdata)
release_firmware(kim_gdata->fw_entry);
return -ETIMEDOUT;
}
- /* reinit completion before sending for the
+ /*
+ * reinit completion before sending for the
* relevant wait
*/
reinit_completion(&kim_gdata->kim_rcvd);
@@ -418,14 +429,16 @@ void st_kim_recv(void *disc_data, const unsigned char *data, long count)
struct st_data_s *st_gdata = (struct st_data_s *)disc_data;
struct kim_data_s *kim_gdata = st_gdata->kim_data;

- /* proceed to gather all data and distinguish read fw version response
+ /*
+ * proceed to gather all data and distinguish read fw version response
* from other fw responses when data gathering is complete
*/
kim_int_recv(kim_gdata, data, count);
return;
}

-/* to signal completion of line discipline installation
+/*
+ * to signal completion of line discipline installation
* called from ST Core, upon tty_open
*/
void st_kim_complete(void *kim_data)
@@ -434,7 +447,7 @@ void st_kim_complete(void *kim_data)
complete(&kim_gdata->ldisc_installed);
}

-/**
+/*
* st_kim_start - called from ST Core upon 1st registration
* This involves toggling the chip enable gpio, reading
* the firmware version from chip, forming the fw file name
@@ -472,8 +485,10 @@ long st_kim_start(void *kim_data)
err = wait_for_completion_interruptible_timeout(
&kim_gdata->ldisc_installed, msecs_to_jiffies(LDISC_TIME));
if (!err) {
- /* ldisc installation timeout,
- * flush uart, power cycle BT_EN */
+ /*
+ * ldisc installation timeout,
+ * flush uart, power cycle BT_EN
+ */
pr_err("ldisc installation timeout");
err = st_kim_stop(kim_gdata);
continue;
@@ -482,8 +497,10 @@ long st_kim_start(void *kim_data)
pr_info("line discipline installed");
err = download_firmware(kim_gdata);
if (err != 0) {
- /* ldisc installed but fw download failed,
- * flush uart & power cycle BT_EN */
+ /*
+ * ldisc installed but fw download failed,
+ * flush uart & power cycle BT_EN
+ */
pr_err("download firmware failed");
err = st_kim_stop(kim_gdata);
continue;
@@ -495,7 +512,7 @@ long st_kim_start(void *kim_data)
return err;
}

-/**
+/*
* st_kim_stop - stop communication with chip.
* This can be called from ST Core/KIM, on the-
* (a) last un-register when chip need not be powered there-after,
@@ -650,7 +667,7 @@ static const struct attribute_group uim_attr_grp = {
.attrs = uim_attrs,
};

-/**
+/*
* st_kim_ref - reference the core's data
* This references the per-ST platform device in the arch/xx/
* board-xx.c file.
@@ -729,8 +746,7 @@ static int kim_probe(struct platform_device *pdev)
pr_err(" unable to configure gpio %d", kim_gdata->nshutdown);
goto err_sysfs_group;
}
- /* get reference of pdev for request_firmware
- */
+ /* get reference of pdev for request_firmware */
kim_gdata->kim_pdev = pdev;
init_completion(&kim_gdata->kim_rcvd);
init_completion(&kim_gdata->ldisc_installed);
@@ -772,7 +788,8 @@ static int kim_remove(struct platform_device *pdev)

kim_gdata = platform_get_drvdata(pdev);

- /* Free the Bluetooth/FM/GPIO
+ /*
+ * Free the Bluetooth/FM/GPIO
* nShutdown gpio from the system
*/
gpio_free(pdata->nshutdown_gpio);
--
2.25.1

Next message: Lee Jones: "[PATCH 09/10] misc: habanalabs: irq: Add missing struct identifier for 'struct hl_eqe_work'"
Previous message: Lee Jones: "[PATCH 07/10] misc: mic: vop: vop_main: Remove set but unused variable 'ret'"
In reply to: Arnd Bergmann: "Re: [PATCH 07/10] misc: mic: vop: vop_main: Remove set but unused variable 'ret'"
Next in thread: Arnd Bergmann: "Re: [PATCH 03/10] misc: ti-st: st_kim: Tidy-up bespoke commentry"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]