From patchwork Fri Jun 26 13:05:17 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lee Jones X-Patchwork-Id: 11627575 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id B255613B4 for ; Fri, 26 Jun 2020 13:08:05 +0000 (UTC) Received: from merlin.infradead.org (merlin.infradead.org [205.233.59.134]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 6BE6F2080C for ; Fri, 26 Jun 2020 13:08:05 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="1GtFi+Ou"; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="HlFLionZ" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 6BE6F2080C Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=merlin.20170209; h=Sender:Content-Transfer-Encoding: Content-Type:Cc:List-Subscribe:List-Help:List-Post:List-Archive: List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To:Message-Id:Date: Subject:To:From:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=D5H+0GDV6+7sdTve2VI0MK/jKMXdkwl7dsid/kKkQ6E=; b=1GtFi+OuD4ej0mw9OFzyJyEkC IYoVU7zZBB2JKT0Iz5xupe/eog9bWPFUkp6uaAB6hA7vz2NHamWkZI+HvwJrRmvmjYZYkAkWXVU5h nd60mZvc6Yd8qLecd8BLWh8+wcv27aBCm3jHYmKypy9X53bEuMe9MtytULVYjv2HAeAJ5iNdtbplN 0KyaOD2NcZkHI2Ij7YF9lfomzEv6LEQ/hlECgcxAv5IuVLbFmoUXfuMMQFLYi4rN2zXfvzZ+K5PC6 cmzDZU8YarGChxuvJkk2lDH2pfmTdfmlLwUmvlUHgF2lhNbSfwGsXGN0It1LFu0QxLSrMPNa9Uhm8 g9P+UNzhg==; Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1joo39-0002jH-0U; Fri, 26 Jun 2020 13:05:47 +0000 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]) by merlin.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1joo2u-0002g8-Bj for linux-arm-kernel@lists.infradead.org; Fri, 26 Jun 2020 13:05:34 +0000 Received: by mail-wr1-x442.google.com with SMTP id b6so9419675wrs.11 for ; Fri, 26 Jun 2020 06:05:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=daHyuJlZ21yTucBCriQSJRjQqcObN26/yVHvenxInRk=; b=HlFLionZgSOs6uB5R/XFj+QIIQ5tQl7fhImDsr1EeJhlVxOL9n404r1ANLopHwWtlY zywtHNZ54HiqUqgmPyiXkVySsIX4Hdk5SWXj59y9VIkehX/2bWPlhpcP7bkThFYisB7L aYoLNSR3p1LB8G0Ts1jI1ig5BPgz25+wFct97UzGfn349NuZSZqSwCDKY2W2oZlGBzV0 YmvLsIPf7g1dPN95thFlze08d6GIffTkmWyjaxSaff6/6ReJBYwwFa4XTK8Y5ZeTsUPA dz6N/RJAHapYtB681ADXg6GWRBLyVeyCUflJ7MAVPiXKoqzUEY+U6C8hRybcrFPGTzfF p12Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=daHyuJlZ21yTucBCriQSJRjQqcObN26/yVHvenxInRk=; b=Mf1RZ55llEpY7czmL2hxfSyptjs3hU9azZe37sXlzQx5aJkHOrCJ4XF0eVGEuokY9e H4/wnWrzKycEYKueDhFkgr9F8EdO3qrGwotsAxNipjLG+/2shBqIFh9/NX5OfoSgdqo1 GQbTNBY8zgZhjLcA8y9+QbRRANY2F6lMQu3CuoqjTGgG3dO4/1Doi64eNFUsDp0nierg ROTPaUcyMTBSMWEN6QI4bBmHs+PgSP22vPWEJAasQUwEk1CTEAgeeFVO7Yr4k0bBlOQQ 8ddztQMphDcuVZK25FOorTXlzxcigO7CuI6f47zyaaz7/kbKhQ43D7mnjUyKdf1yKxqM slQw== X-Gm-Message-State: AOAM533iLwG46BmJoAnuUK+obyjTXDwnoeOXTGWmkPCyep+wh60ZjPkv x+MhgXyw2O3aKTIYG57CN2DLcw== X-Google-Smtp-Source: ABdhPJzdQdsAOHVLeNWM/Vp1yS4sRgT3xxrd2+IrFxsYUcMKcsL2YoQVIt2KlUvCS/9L2F4AxW13NQ== X-Received: by 2002:adf:e90d:: with SMTP id f13mr3565068wrm.146.1593176731129; Fri, 26 Jun 2020 06:05:31 -0700 (PDT) Received: from localhost.localdomain ([2.27.35.144]) by smtp.gmail.com with ESMTPSA id u20sm16746904wmc.44.2020.06.26.06.05.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 26 Jun 2020 06:05:30 -0700 (PDT) From: Lee Jones To: arnd@arndb.de, gregkh@linuxfoundation.org Subject: [PATCH 02/10] misc: ti-st: st_core: Tidy-up bespoke commentry Date: Fri, 26 Jun 2020 14:05:17 +0100 Message-Id: <20200626130525.389469-3-lee.jones@linaro.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200626130525.389469-1-lee.jones@linaro.org> References: <20200626130525.389469-1-lee.jones@linaro.org> MIME-Version: 1.0 X-Spam-Note: CRM114 invocation failed X-Spam-Score: -0.2 (/) X-Spam-Report: SpamAssassin version 3.4.4 on merlin.infradead.org summary: Content analysis details: (-0.2 points) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at https://www.dnswl.org/, no trust [2a00:1450:4864:20:0:0:0:442 listed in] [list.dnswl.org] -0.0 SPF_PASS SPF: sender matches SPF record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record -0.1 DKIM_VALID_EF Message has a valid DKIM or DK signature from envelope-from domain -0.1 DKIM_VALID_AU Message has a valid DKIM or DK signature from author's domain 0.1 DKIM_SIGNED Message has a DKIM or DK signature, not necessarily valid -0.1 DKIM_VALID Message has at least one valid DKIM or DK signature X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Naveen Jain , Lee Jones , linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, Pavan Savoy Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org 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 Cc: Naveen Jain Signed-off-by: Lee Jones Acked-by: Arnd Bergmann --- 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)