UbiquitousOS
/
OpenCloudOS-Kernel
mirror of https://gitee.com/OpenCloudOS/OpenCloudOS-Kernel.git
11
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
Lee Jones 2020-06-26 14:05:17 +01:00 committed by Greg Kroah-Hartman
parent b23d5151f3
commit 7e8eebef1c
1 changed files with 49 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
drivers/misc/ti-st/st_core.c
View File

@ -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)