linux-pci.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Bjorn Helgaas <helgaas@kernel.org>
To: "Krzysztof Wilczyński" <kw@linux.com>
Cc: Bjorn Helgaas <bhelgaas@google.com>,
	Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>,
	Kishon Vijay Abraham I <kishon@ti.com>,
	Tom Joseph <tjoseph@cadence.com>,
	Murali Karicheri <m-karicheri2@ti.com>,
	Rob Herring <robh@kernel.org>, Russell Currey <ruscur@russell.cc>,
	Oliver O'Halloran <oohall@gmail.com>,
	Geert Uytterhoeven <geert+renesas@glider.be>,
	Arnd Bergmann <arnd@arndb.de>,
	Krzysztof Kozlowski <krzk@kernel.org>,
	Kunihiko Hayashi <hayashi.kunihiko@socionext.com>,
	Sean V Kelley <sean.v.kelley@intel.com>,
	Qiuxu Zhuo <qiuxu.zhuo@intel.com>,
	Jay Fang <f.fangjian@huawei.com>,
	linux-pci@vger.kernel.org
Subject: Re: [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation
Date: Thu, 11 Mar 2021 17:38:40 -0600	[thread overview]
Message-ID: <20210311233840.GA2188908@bjorn-Precision-5520> (raw)
In-Reply-To: <20210311001724.423356-1-kw@linux.com>

On Thu, Mar 11, 2021 at 12:17:17AM +0000, Krzysztof Wilczyński wrote:
> Add missing documentation for the parameters "ntb_epc", "type", "dev",
> and "group" of the following functions:
> 
>   - epf_ntb_add_cfs()
>   - epf_ntb_alloc_peer_mem()
>   - epf_ntb_config_sspad_bar_clear(),
>   - epf_ntb_config_sspad_bar_set()
>   - epf_ntb_peer_spad_bar_clear()
>   - epf_ntb_peer_spad_bar_set()
>   - pci_epc_remove_epf()
> 
> Remove surplus parameter from the epf_ntb_init_epc_bar() function.
> 
> Additionally, fix a non-compliant kernel-doc at the top of the files
> pci-epf-ntb.c and pci-epf-test.c, and resolve number of build time
> warnings related to kernel-doc:
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:1363: warning: Function
>  parameter or member 'dev' not described in 'epf_ntb_alloc_peer_mem'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:2046: warning: Function
>  parameter or member 'group' not described in 'epf_ntb_add_cfs'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:1670: warning: Excess
>  function parameter 'type' description in 'epf_ntb_init_epc_bar'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:45: warning: cannot
>  understand function prototype: 'struct workqueue_struct
>  *kpcintb_workqueue; '
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:727: warning: Excess
>  function parameter 'ntb' description in 'epf_ntb_peer_spad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:727: warning: Function
>  parameter or member 'ntb_epc' not described in
>  'epf_ntb_peer_spad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:771: warning: Function
>  parameter or member 'type' not described in 'epf_ntb_peer_spad_bar_set'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:839: warning: Excess
>  function parameter 'ntb' description in
>  'epf_ntb_config_sspad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:839: warning: Function
>  parameter or member 'ntb_epc' not described in
>  'epf_ntb_config_sspad_bar_clear'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:882: warning: Excess
>  function parameter 'ntb' description in 'epf_ntb_config_sspad_bar_set'
> 
>  drivers/pci/endpoint/functions/pci-epf-ntb.c:882: warning: Function
>  parameter or member 'ntb_epc' not described in
>  'epf_ntb_config_sspad_bar_set'
> 
>  drivers/pci/endpoint/functions/pci-epf-test.c:22: warning: expecting
>  prototype for Test driver to test endpoint functionality(). Prototype
>  was for IRQ_TYPE_LEGACY() instead
> 
> No change to functionality intended.
> 
> Signed-off-by: Krzysztof Wilczyński <kw@linux.com>

Applied all to pci/kernel-doc, thanks!  I squashed them into one patch
since these only change comments.

> ---
>  drivers/pci/endpoint/functions/pci-epf-ntb.c  | 16 +++++++++++-----
>  drivers/pci/endpoint/functions/pci-epf-test.c |  2 +-
>  drivers/pci/endpoint/pci-epc-core.c           |  2 ++
>  3 files changed, 14 insertions(+), 6 deletions(-)
> 
> diff --git a/drivers/pci/endpoint/functions/pci-epf-ntb.c b/drivers/pci/endpoint/functions/pci-epf-ntb.c
> index 338148cf56f5..bce274d02dcf 100644
> --- a/drivers/pci/endpoint/functions/pci-epf-ntb.c
> +++ b/drivers/pci/endpoint/functions/pci-epf-ntb.c
> @@ -1,5 +1,5 @@
>  // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>   * Endpoint Function Driver to implement Non-Transparent Bridge functionality
>   *
>   * Copyright (C) 2020 Texas Instruments
> @@ -696,7 +696,8 @@ static void epf_ntb_cmd_handler(struct work_struct *work)
>  
>  /**
>   * epf_ntb_peer_spad_bar_clear() - Clear Peer Scratchpad BAR
> - * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
> + *	     address.
>   *
>   *+-----------------+------->+------------------+        +-----------------+
>   *|       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -740,6 +741,7 @@ static void epf_ntb_peer_spad_bar_clear(struct epf_ntb_epc *ntb_epc)
>  /**
>   * epf_ntb_peer_spad_bar_set() - Set peer scratchpad BAR
>   * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @type: PRIMARY interface or SECONDARY interface
>   *
>   *+-----------------+------->+------------------+        +-----------------+
>   *|       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -808,7 +810,8 @@ static int epf_ntb_peer_spad_bar_set(struct epf_ntb *ntb,
>  
>  /**
>   * epf_ntb_config_sspad_bar_clear() - Clear Config + Self scratchpad BAR
> - * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
> + *	     address.
>   *
>   * +-----------------+------->+------------------+        +-----------------+
>   * |       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -851,7 +854,8 @@ static void epf_ntb_config_sspad_bar_clear(struct epf_ntb_epc *ntb_epc)
>  
>  /**
>   * epf_ntb_config_sspad_bar_set() - Set Config + Self scratchpad BAR
> - * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> + * @ntb_epc: EPC associated with one of the HOST which holds peer's outbound
> + *	     address.
>   *
>   * +-----------------+------->+------------------+        +-----------------+
>   * |       BAR0      |        |  CONFIG REGION   |        |       BAR0      |
> @@ -1312,6 +1316,7 @@ static int epf_ntb_configure_interrupt(struct epf_ntb *ntb,
>  
>  /**
>   * epf_ntb_alloc_peer_mem() - Allocate memory in peer's outbound address space
> + * @dev: The PCI device.
>   * @ntb_epc: EPC associated with one of the HOST whose BAR holds peer's outbound
>   *   address
>   * @bar: BAR of @ntb_epc in for which memory has to be allocated (could be
> @@ -1660,7 +1665,6 @@ static int epf_ntb_init_epc_bar_interface(struct epf_ntb *ntb,
>   * epf_ntb_init_epc_bar() - Identify BARs to be used for each of the NTB
>   * constructs (scratchpad region, doorbell, memorywindow)
>   * @ntb: NTB device that facilitates communication between HOST1 and HOST2
> - * @type: PRIMARY interface or SECONDARY interface
>   *
>   * Wrapper to epf_ntb_init_epc_bar_interface() to identify the free BARs
>   * to be used for each of BAR_CONFIG, BAR_PEER_SPAD, BAR_DB_MW1, BAR_MW2,
> @@ -2037,6 +2041,8 @@ static const struct config_item_type ntb_group_type = {
>  /**
>   * epf_ntb_add_cfs() - Add configfs directory specific to NTB
>   * @epf: NTB endpoint function device
> + * @group: A pointer to the config_group structure referencing a group of
> + *	   config_items of a specific type that belong to a specific sub-system.
>   *
>   * Add configfs directory specific to NTB. This directory will hold
>   * NTB specific properties like db_count, spad_count, num_mws etc.,
> diff --git a/drivers/pci/endpoint/functions/pci-epf-test.c b/drivers/pci/endpoint/functions/pci-epf-test.c
> index c0ac4e9cbe72..63d5f5c6e3e0 100644
> --- a/drivers/pci/endpoint/functions/pci-epf-test.c
> +++ b/drivers/pci/endpoint/functions/pci-epf-test.c
> @@ -1,5 +1,5 @@
>  // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>   * Test driver to test endpoint functionality
>   *
>   * Copyright (C) 2017 Texas Instruments
> diff --git a/drivers/pci/endpoint/pci-epc-core.c b/drivers/pci/endpoint/pci-epc-core.c
> index cc8f9eb2b177..adec9bee72cf 100644
> --- a/drivers/pci/endpoint/pci-epc-core.c
> +++ b/drivers/pci/endpoint/pci-epc-core.c
> @@ -594,6 +594,8 @@ EXPORT_SYMBOL_GPL(pci_epc_add_epf);
>   * pci_epc_remove_epf() - remove PCI endpoint function from endpoint controller
>   * @epc: the EPC device from which the endpoint function should be removed
>   * @epf: the endpoint function to be removed
> + * @type: identifies if the EPC is connected to the primary or secondary
> + *        interface of EPF
>   *
>   * Invoke to remove PCI endpoint function from the endpoint controller.
>   */
> -- 
> 2.30.1
> 

      parent reply	other threads:[~2021-03-11 23:39 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-03-11  0:17 [PATCH 1/8] PCI: endpoint: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 2/8] PCI/AER: Update functions names in the kernel-doc Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 3/8] PCI/PME: Update function name " Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 4/8] PCI/ATS: " Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 5/8] PCI: " Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 6/8] PCI: j721e: Fix a non-compliant kernel-doc Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 7/8] PCI: dwc: Remove surplus and document missing function parameters Krzysztof Wilczyński
2021-03-11  0:17 ` [PATCH 8/8] PCI: of: Fix kernel-doc formatting and add missing documentation Krzysztof Wilczyński
2021-03-11 23:38 ` Bjorn Helgaas [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210311233840.GA2188908@bjorn-Precision-5520 \
    --to=helgaas@kernel.org \
    --cc=arnd@arndb.de \
    --cc=bhelgaas@google.com \
    --cc=f.fangjian@huawei.com \
    --cc=geert+renesas@glider.be \
    --cc=hayashi.kunihiko@socionext.com \
    --cc=kishon@ti.com \
    --cc=krzk@kernel.org \
    --cc=kw@linux.com \
    --cc=linux-pci@vger.kernel.org \
    --cc=lorenzo.pieralisi@arm.com \
    --cc=m-karicheri2@ti.com \
    --cc=oohall@gmail.com \
    --cc=qiuxu.zhuo@intel.com \
    --cc=robh@kernel.org \
    --cc=ruscur@russell.cc \
    --cc=sean.v.kelley@intel.com \
    --cc=tjoseph@cadence.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).