[PATCH 02/10] misc: ti-st: st_core: Tidy-up bespoke commentry
Lee Jones
lee.jones at linaro.org
Fri Jun 26 09:05:17 EDT 2020
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_core.c:132: warning: Function parameter or member 'st_gdata' not described in 'st_reg_complete'
drivers/misc/ti-st/st_core.c:132: warning: Function parameter or member 'err' not described in 'st_reg_complete'
drivers/misc/ti-st/st_core.c:197: warning: Function parameter or member 'st_gdata' not described in 'st_wakeup_ack'
drivers/misc/ti-st/st_core.c:197: warning: Function parameter or member 'cmd' not described in 'st_wakeup_ack'
drivers/misc/ti-st/st_core.c:226: warning: Function parameter or member 'disc_data' not described in 'st_int_recv'
drivers/misc/ti-st/st_core.c:226: warning: Function parameter or member 'data' not described in 'st_int_recv'
drivers/misc/ti-st/st_core.c:226: warning: Function parameter or member 'count' not described in 'st_int_recv'
drivers/misc/ti-st/st_core.c:387: warning: Function parameter or member 'st_gdata' not described in 'st_int_dequeue'
drivers/misc/ti-st/st_core.c:409: warning: Function parameter or member 'st_gdata' not described in 'st_int_enqueue'
drivers/misc/ti-st/st_core.c:409: warning: Function parameter or member 'skb' not described in 'st_int_enqueue'
Cc: Pavan Savoy <pavan_savoy at ti.com>
Cc: Naveen Jain <naveen_jain at ti.com>
Signed-off-by: Lee Jones <lee.jones at linaro.org>
---
drivers/misc/ti-st/st_core.c | 79 ++++++++++++++++++++++--------------
1 file changed, 49 insertions(+), 30 deletions(-)
diff --git a/drivers/misc/ti-st/st_core.c b/drivers/misc/ti-st/st_core.c
index 14136d2cc8f93..f4ddd1e670151 100644
--- a/drivers/misc/ti-st/st_core.c
+++ b/drivers/misc/ti-st/st_core.c
@@ -18,7 +18,8 @@
extern void st_kim_recv(void *, const unsigned char *, long);
void st_int_recv(void *, const unsigned char *, long);
-/* function pointer pointing to either,
+/*
+ * function pointer pointing to either,
* st_kim_recv during registration to receive fw download responses
* st_int_recv after registration to receive proto stack responses
*/
@@ -60,7 +61,8 @@ int st_get_uart_wr_room(struct st_data_s *st_gdata)
return tty->ops->write_room(tty);
}
-/* can be called in from
+/*
+ * can be called in from
* -- KIM (during fw download)
* -- ST Core (during st_write)
*
@@ -100,7 +102,8 @@ static void st_send_frame(unsigned char chnl_id, struct st_data_s *st_gdata)
kfree_skb(st_gdata->rx_skb);
return;
}
- /* this cannot fail
+ /*
+ * this cannot fail
* this shouldn't take long
* - should be just skb_queue_tail for the
* protocol stack driver
@@ -121,9 +124,8 @@ static void st_send_frame(unsigned char chnl_id, struct st_data_s *st_gdata)
return;
}
-/**
- * st_reg_complete -
- * to call registration complete callbacks
+/*
+ * st_reg_complete - to call registration complete callbacks
* of all protocol stack drivers
* This function is being called with spin lock held, protocol drivers are
* only expected to complete their waits and do nothing more than that.
@@ -156,21 +158,24 @@ static inline int st_check_data_len(struct st_data_s *st_gdata,
pr_debug("len %d room %d", len, room);
if (!len) {
- /* Received packet has only packet header and
+ /*
+ * Received packet has only packet header and
* has zero length payload. So, ask ST CORE to
* forward the packet to protocol driver (BT/FM/GPS)
*/
st_send_frame(chnl_id, st_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(st_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 */
st_gdata->rx_state = ST_W4_DATA;
@@ -178,8 +183,7 @@ static inline int st_check_data_len(struct st_data_s *st_gdata,
return len;
}
- /* Change ST state to continue to process next
- * packet */
+ /* Change ST state to continue to process next packet */
st_gdata->rx_state = ST_W4_PACKET_TYPE;
st_gdata->rx_skb = NULL;
st_gdata->rx_count = 0;
@@ -188,7 +192,7 @@ static inline int st_check_data_len(struct st_data_s *st_gdata,
return 0;
}
-/**
+/*
* st_wakeup_ack - internal function for action when wake-up ack
* received
*/
@@ -199,7 +203,8 @@ static inline void st_wakeup_ack(struct st_data_s *st_gdata,
unsigned long flags = 0;
spin_lock_irqsave(&st_gdata->lock, flags);
- /* de-Q from waitQ and Q in txQ now that the
+ /*
+ * de-Q from waitQ and Q in txQ now that the
* chip is awake
*/
while ((waiting_skb = skb_dequeue(&st_gdata->tx_waitq)))
@@ -213,7 +218,7 @@ static inline void st_wakeup_ack(struct st_data_s *st_gdata,
st_tx_wakeup(st_gdata);
}
-/**
+/*
* st_int_recv - ST's internal receive function.
* Decodes received RAW data and forwards to corresponding
* client drivers (Bluetooth,FM,GPS..etc).
@@ -262,8 +267,10 @@ void st_int_recv(void *disc_data,
/* Waiting for complete packet ? */
case ST_W4_DATA:
pr_debug("Complete pkt received");
- /* Ask ST CORE to forward
- * the packet to protocol driver */
+ /*
+ * Ask ST CORE to forward
+ * the packet to protocol driver
+ */
st_send_frame(st_gdata->rx_chnl, st_gdata);
st_gdata->rx_state = ST_W4_PACKET_TYPE;
@@ -276,7 +283,7 @@ void st_int_recv(void *disc_data,
&st_gdata->rx_skb->data
[proto->offset_len_in_hdr];
pr_debug("plen pointing to %x\n", *plen);
- if (proto->len_size == 1)/* 1 byte len field */
+ if (proto->len_size == 1) /* 1 byte len field */
payload_len = *(unsigned char *)plen;
else if (proto->len_size == 2)
payload_len =
@@ -294,18 +301,23 @@ void st_int_recv(void *disc_data,
}
/* end of if rx_count */
- /* Check first byte of packet and identify module
- * owner (BT/FM/GPS) */
+
+ /*
+ * Check first byte of packet and identify module
+ * owner (BT/FM/GPS)
+ */
switch (*ptr) {
case LL_SLEEP_IND:
case LL_SLEEP_ACK:
case LL_WAKE_UP_IND:
pr_debug("PM packet");
- /* this takes appropriate action based on
+ /*
+ * this takes appropriate action based on
* sleep state received --
*/
st_ll_sleep_state(st_gdata, *ptr);
- /* if WAKEUP_IND collides copy from waitq to txq
+ /*
+ * if WAKEUP_IND collides copy from waitq to txq
* and assume chip awake
*/
spin_unlock_irqrestore(&st_gdata->lock, flags);
@@ -331,7 +343,8 @@ void st_int_recv(void *disc_data,
default:
type = *ptr;
- /* Default case means non-HCILL packets,
+ /*
+ * Default case means non-HCILL packets,
* possibilities are packets for:
* (a) valid protocol - Supported Protocols within
* the ST_MAX_CHANNELS.
@@ -377,7 +390,7 @@ void st_int_recv(void *disc_data,
return;
}
-/**
+/*
* st_int_dequeue - internal de-Q function.
* If the previous data set was not written
* completely, return that skb which has the pending data.
@@ -396,7 +409,7 @@ static struct sk_buff *st_int_dequeue(struct st_data_s *st_gdata)
return skb_dequeue(&st_gdata->txq);
}
-/**
+/*
* st_int_enqueue - internal Q-ing function.
* Will either Q the skb to txq or the tx_waitq
* depending on the ST LL state.
@@ -561,7 +574,8 @@ long st_register(struct st_proto_s *new_proto)
/* release lock previously held - re-locked below */
spin_unlock_irqrestore(&st_gdata->lock, flags);
- /* this may take a while to complete
+ /*
+ * this may take a while to complete
* since it involves BT fw download
*/
err = st_kim_start(st_gdata->kim_data);
@@ -583,7 +597,8 @@ long st_register(struct st_proto_s *new_proto)
clear_bit(ST_REG_IN_PROGRESS, &st_gdata->st_state);
st_recv = st_int_recv;
- /* this is where all pending registration
+ /*
+ * this is where all pending registration
* are signalled to be complete by calling callback functions
*/
if ((st_gdata->protos_registered != ST_EMPTY) &&
@@ -593,7 +608,8 @@ long st_register(struct st_proto_s *new_proto)
}
clear_bit(ST_REG_PENDING, &st_gdata->st_state);
- /* check for already registered once more,
+ /*
+ * check for already registered once more,
* since the above check is old
*/
if (st_gdata->is_registered[new_proto->chnl_id] == true) {
@@ -622,7 +638,8 @@ long st_register(struct st_proto_s *new_proto)
}
EXPORT_SYMBOL_GPL(st_register);
-/* to unregister a protocol -
+/*
+ * to unregister a protocol -
* to be called from protocol stack driver
*/
long st_unregister(struct st_proto_s *proto)
@@ -742,7 +759,8 @@ static void st_tty_close(struct tty_struct *tty)
pr_info("%s ", __func__);
- /* TODO:
+ /*
+ * TODO:
* if a protocol has been registered & line discipline
* un-installed for some reason - what should be done ?
*/
@@ -795,7 +813,8 @@ static void st_tty_receive(struct tty_struct *tty, const unsigned char *data,
pr_debug("done %s", __func__);
}
-/* wake-up function called in from the TTY layer
+/*
+ * wake-up function called in from the TTY layer
* inside the internal wakeup function will be called
*/
static void st_tty_wakeup(struct tty_struct *tty)
--
2.25.1
More information about the linux-arm-kernel
mailing list