misc: ti-st: st_core: Tidy-up bespoke commentry

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@ti.com>
Cc: Naveen Jain <naveen_jain@ti.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Lee Jones <lee.jones@linaro.org>
Link: https://lore.kernel.org/r/20200626130525.389469-3-lee.jones@linaro.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/drivers/misc/ti-st/st_core.c b/drivers/misc/ti-st/st_core.c
index 14136d2..f4ddd1e 100644 (file)
--- 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 @@ done:
        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)