From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 62C27C47089 for ; Fri, 28 May 2021 03:07:26 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2F1C4610C7 for ; Fri, 28 May 2021 03:07:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S236252AbhE1DI7 (ORCPT ); Thu, 27 May 2021 23:08:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49934 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236229AbhE1DI6 (ORCPT ); Thu, 27 May 2021 23:08:58 -0400 Received: from mail-oi1-x22e.google.com (mail-oi1-x22e.google.com [IPv6:2607:f8b0:4864:20::22e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EB855C06174A for ; Thu, 27 May 2021 20:07:23 -0700 (PDT) Received: by mail-oi1-x22e.google.com with SMTP id x15so2886425oic.13 for ; Thu, 27 May 2021 20:07:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=89Ift1OU78vKtiGlNnIxDJCwM07AOIScHSivLdjVYhE=; b=rn4NEkcrpv1c/o1jdjygsc3kzakWgXejAkh0y1fGD1jSkvspt5vZv+KUbcnjnTjZ9H zlS2ox/g2O+oQBf53t1niN+/XlEmpiWCHOd1X7vK9OkmlfPtMhLkjqFLKs45elo1z642 7fVvKztv7sbNjq2c2zKKeyVqhajiW+OgNiPCs3qY+uB9z8EcL2GaKwbyOhLu56QXB5Sz 5lXxL7enT8hcp7UhIHuhCkZkcRx/Q20aN87kEO29Wr9Jy4soHZdoEICnZ894JwPuH/d5 aEmEVx8mAHksbR2iLe8CUQrNDPuOpnaSiwhmO3ApTAeqqC4taueSEQLJ4xifBgwWw9zx GJ+A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=89Ift1OU78vKtiGlNnIxDJCwM07AOIScHSivLdjVYhE=; b=d0NnXcKmi95qsUYGATzyEEFQFil+MUHAC7RjBQWJLOXVS+f49LYVrDjQkKmjug9B4h bInNdP7gPSjlgMkEt9vfC6zmbm842bPSzReq5Obh+kr1Jv8CplbsDQoWdGM0IbkkE305 c4e/zBPzkQua2jbDJfOHbgJHCBE+md3CluEJmJsYXJhOnX+pWyuA7z3H+3ugHDHsX5r0 7uX/KQGYsFEIkumTk8GLQp/blp+x4WD0kZQ64BuJ3BX4iY7Ikzu0nO9Q7dWcXKUz+xpc edwddIBpNO5ijpSK2Ami5KEs426w08dcE+1Rz2AmbVJQBjDWb3zG2mNZHjGcLMVqmFtm 9r5A== X-Gm-Message-State: AOAM533TRMa+/q4kJuSLSutFB3plOS1cAaP5oj374isFc2nFPBivFyIL yYOMrqVv+rZl+E7E/zLE/2EaCQ== X-Google-Smtp-Source: ABdhPJy3bKWc2VMwI2rT0Nf0xgty4fAnT+udrJLeLwBkNxnBNKtnjPN2Q3vPH3brtW8w7DJZ6oZPHQ== X-Received: by 2002:aca:1916:: with SMTP id l22mr4606188oii.48.1622171243112; Thu, 27 May 2021 20:07:23 -0700 (PDT) Received: from builder.lan (104-57-184-186.lightspeed.austtx.sbcglobal.net. [104.57.184.186]) by smtp.gmail.com with ESMTPSA id i17sm825381oou.37.2021.05.27.20.07.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 27 May 2021 20:07:22 -0700 (PDT) Date: Thu, 27 May 2021 22:07:20 -0500 From: Bjorn Andersson To: Mathieu Poirier Cc: Suman Anna , linux-remoteproc@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH 2/2] remoteproc: Fix various kernel-doc warnings Message-ID: References: <20210519180304.23563-1-s-anna@ti.com> <20210519180304.23563-3-s-anna@ti.com> <20210525180006.GD1113058@xps15> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20210525180006.GD1113058@xps15> Precedence: bulk List-ID: X-Mailing-List: linux-remoteproc@vger.kernel.org On Tue 25 May 13:00 CDT 2021, Mathieu Poirier wrote: > On Wed, May 19, 2021 at 01:03:04PM -0500, Suman Anna wrote: > > diff --git a/drivers/remoteproc/remoteproc_elf_loader.c b/drivers/remoteproc/remoteproc_elf_loader.c [..] > > @@ -362,7 +366,7 @@ EXPORT_SYMBOL(rproc_elf_load_rsc_table); > > * This function finds the location of the loaded resource table. Don't > > * call this function if the table wasn't loaded yet - it's a bug if you do. > > * > > - * Returns the pointer to the resource table if it is found or NULL otherwise. > > + * Return: pointer to the resource table if it is found or NULL otherwise. > > Here the '.' has been kept while it was remove for all of the above. I don't > know that the right guidelines are for this. > Reviewing https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html I don't see that this is defined. So I'm fine with whatever looks good. That said, the section about "Return values" shows that the "Return: ..." line should be short and concise and if needed followed by a newline and then a longer paragraph. I'll fix the capitalization of "the" below and apply this as is and we can go back an reformat these multiline Return entries later... > > * If the table wasn't loaded yet the result is unspecified. > > */ [..] > > diff --git a/include/linux/remoteproc.h b/include/linux/remoteproc.h [..] > > + * 2. immediately following this structure is the virtio config space for > > + * this vdev (which is specific to the vdev; for more info, read the virtio > > + * spec). the size of the config space is specified by @config_len. > > s/the/The > [..] > > struct rproc { > > @@ -613,10 +617,10 @@ struct rproc_vring { > > * struct rproc_vdev - remoteproc state for a supported virtio device > > * @refcount: reference counter for the vdev and vring allocations > > * @subdev: handle for registering the vdev as a rproc subdevice > > + * @dev: device struct used for reference count semantics > > * @id: virtio device id (as in virtio_ids.h) > > * @node: list node > > * @rproc: the rproc handle > > - * @vdev: the virio device > > * @vring: the vrings for this vdev > > * @rsc_offset: offset of the vdev's resource entry > > * @index: vdev position versus other vdev declared in resource table > > With or without the above: > > Reviewed-by: Mathieu Poirier > Thanks Mathieu, and thanks Suman. Regards, Bjorn From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-14.1 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 25DB6C4707F for ; Fri, 28 May 2021 03:09:04 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (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 D7BB961402 for ; Fri, 28 May 2021 03:09:03 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org D7BB961402 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+linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:In-Reply-To:MIME-Version:References: Message-ID:Subject:To:From:Date:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=z6lM42sZAmFgqSf6DE8vkVi6X2tMuzLhN2lg2kC2KRQ=; b=ltjBd20EKG5HVO RLTlqqePkmeIOiltrtCDJRNNFG2Dm/45JuDbDJ2PlgNSj75F7S+RxmoFU+r4CocYa6RSjDAyMMhen Qv8RSCsKlmUcEUzf+hg5QWn/jqKO4sIWlYGve/3KoTpLn8yqdIXMkXMC7PZzFkZ99bNayDJ4VTolH HFQ0EnGVqBcvYcBJ3VMEL8DTNeDCsiObEZP2aIvQXCpBIwzGDJJvJLHGfX0rCnv8KRldsTWjLkyFp z+0EUlpUu5Ejpbvm7/GLEFKRZ1F6TzRbfx7itEGfg+KSSCrs0BNu3zEn7CohRTBGqfbjIq82cAh79 dV7YLr8Ubps3N5m7Bfnw==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux)) id 1lmSqP-00BUVY-76; Fri, 28 May 2021 03:07:29 +0000 Received: from mail-oi1-x229.google.com ([2607:f8b0:4864:20::229]) by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux)) id 1lmSqL-00BUUE-P1 for linux-arm-kernel@lists.infradead.org; Fri, 28 May 2021 03:07:27 +0000 Received: by mail-oi1-x229.google.com with SMTP id c3so2900091oic.8 for ; Thu, 27 May 2021 20:07:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=89Ift1OU78vKtiGlNnIxDJCwM07AOIScHSivLdjVYhE=; b=rn4NEkcrpv1c/o1jdjygsc3kzakWgXejAkh0y1fGD1jSkvspt5vZv+KUbcnjnTjZ9H zlS2ox/g2O+oQBf53t1niN+/XlEmpiWCHOd1X7vK9OkmlfPtMhLkjqFLKs45elo1z642 7fVvKztv7sbNjq2c2zKKeyVqhajiW+OgNiPCs3qY+uB9z8EcL2GaKwbyOhLu56QXB5Sz 5lXxL7enT8hcp7UhIHuhCkZkcRx/Q20aN87kEO29Wr9Jy4soHZdoEICnZ894JwPuH/d5 aEmEVx8mAHksbR2iLe8CUQrNDPuOpnaSiwhmO3ApTAeqqC4taueSEQLJ4xifBgwWw9zx GJ+A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=89Ift1OU78vKtiGlNnIxDJCwM07AOIScHSivLdjVYhE=; b=NkdGLqgtmQKA+Rm+w9FNYQB8Q1yrHgnHQSRdw57CglPVCFMaIFWch4rF/HpJ/Bv8V7 oPmmD0Joi49KOPAZWuG9x2YzLPfy32QiWUMxR0ExpKiex0xhggFqieQ6oDJ+Cs0UEAPg RtL8q62TX8xgFCSGwJ+rPRBz7WCmZTS7ByQZwivZc5C4Z5TxXDqTYqMxasbTWpW8DGPu AvAJhqnc740wrhtiM1w3N/nGceZj11q46KgrfZDke8bR81n1C7IhX6zbcKx72WfWB231 QmV9hLsAM3lL5VTecSvH++9Jxb6AA5uX+G9srk5HNpZErY5qGm1bBRRTDE+aLCH0Vw28 yJSg== X-Gm-Message-State: AOAM5337sq8q73yxBad7JSWe4W8RTjXMt2S3oxNioUIC3d+c0Iam1xLU I5cv5RV+w7nDrR6vAbnh66UXCg== X-Google-Smtp-Source: ABdhPJy3bKWc2VMwI2rT0Nf0xgty4fAnT+udrJLeLwBkNxnBNKtnjPN2Q3vPH3brtW8w7DJZ6oZPHQ== X-Received: by 2002:aca:1916:: with SMTP id l22mr4606188oii.48.1622171243112; Thu, 27 May 2021 20:07:23 -0700 (PDT) Received: from builder.lan (104-57-184-186.lightspeed.austtx.sbcglobal.net. [104.57.184.186]) by smtp.gmail.com with ESMTPSA id i17sm825381oou.37.2021.05.27.20.07.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 27 May 2021 20:07:22 -0700 (PDT) Date: Thu, 27 May 2021 22:07:20 -0500 From: Bjorn Andersson To: Mathieu Poirier Subject: Re: [PATCH 2/2] remoteproc: Fix various kernel-doc warnings Message-ID: References: <20210519180304.23563-1-s-anna@ti.com> <20210519180304.23563-3-s-anna@ti.com> <20210525180006.GD1113058@xps15> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20210525180006.GD1113058@xps15> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210527_200725_850120_4E6C4BAD X-CRM114-Status: GOOD ( 26.11 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: linux-remoteproc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org On Tue 25 May 13:00 CDT 2021, Mathieu Poirier wrote: > On Wed, May 19, 2021 at 01:03:04PM -0500, Suman Anna wrote: > > diff --git a/drivers/remoteproc/remoteproc_elf_loader.c b/drivers/remoteproc/remoteproc_elf_loader.c [..] > > @@ -362,7 +366,7 @@ EXPORT_SYMBOL(rproc_elf_load_rsc_table); > > * This function finds the location of the loaded resource table. Don't > > * call this function if the table wasn't loaded yet - it's a bug if you do. > > * > > - * Returns the pointer to the resource table if it is found or NULL otherwise. > > + * Return: pointer to the resource table if it is found or NULL otherwise. > > Here the '.' has been kept while it was remove for all of the above. I don't > know that the right guidelines are for this. > Reviewing https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html I don't see that this is defined. So I'm fine with whatever looks good. That said, the section about "Return values" shows that the "Return: ..." line should be short and concise and if needed followed by a newline and then a longer paragraph. I'll fix the capitalization of "the" below and apply this as is and we can go back an reformat these multiline Return entries later... > > * If the table wasn't loaded yet the result is unspecified. > > */ [..] > > diff --git a/include/linux/remoteproc.h b/include/linux/remoteproc.h [..] > > + * 2. immediately following this structure is the virtio config space for > > + * this vdev (which is specific to the vdev; for more info, read the virtio > > + * spec). the size of the config space is specified by @config_len. > > s/the/The > [..] > > struct rproc { > > @@ -613,10 +617,10 @@ struct rproc_vring { > > * struct rproc_vdev - remoteproc state for a supported virtio device > > * @refcount: reference counter for the vdev and vring allocations > > * @subdev: handle for registering the vdev as a rproc subdevice > > + * @dev: device struct used for reference count semantics > > * @id: virtio device id (as in virtio_ids.h) > > * @node: list node > > * @rproc: the rproc handle > > - * @vdev: the virio device > > * @vring: the vrings for this vdev > > * @rsc_offset: offset of the vdev's resource entry > > * @index: vdev position versus other vdev declared in resource table > > With or without the above: > > Reviewed-by: Mathieu Poirier > Thanks Mathieu, and thanks Suman. Regards, Bjorn _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel