LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Dong Jia Shi <bjsdjshi@linux.ibm.com>
To: linux-kernel@vger.kernel.org, linux-s390@vger.kernel.org,
	kvm@vger.kernel.org
Cc: cohuck@redhat.com, borntraeger@de.ibm.com,
	bjsdjshi@linux.ibm.com, pasic@linux.ibm.com,
	pmorel@linux.ibm.com, Dong Jia Shi <bjsdjshi@linux.vnet.ibm.com>
Subject: [PATCH v3 1/4] vfio: ccw: shorten kernel doc description for pfn_array_pin()
Date: Wed, 23 May 2018 04:44:59 +0200	[thread overview]
Message-ID: <20180523024502.94244-2-bjsdjshi@linux.ibm.com> (raw)
In-Reply-To: <20180523024502.94244-1-bjsdjshi@linux.ibm.com>

From: Dong Jia Shi <bjsdjshi@linux.vnet.ibm.com>

The kernel doc description for usage of the struct pfn_array in
pfn_array_pin() is unnecessary long. Let's shorten it by describing
the contents of the struct pfn_array fields at the struct's definition
instead.

Suggested-by: Cornelia Huck <cohuck@redhat.com>
Signed-off-by: Dong Jia Shi <bjsdjshi@linux.ibm.com>
---
 drivers/s390/cio/vfio_ccw_cp.c | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/drivers/s390/cio/vfio_ccw_cp.c b/drivers/s390/cio/vfio_ccw_cp.c
index dce92b2a895d..b38ef387e4f0 100644
--- a/drivers/s390/cio/vfio_ccw_cp.c
+++ b/drivers/s390/cio/vfio_ccw_cp.c
@@ -23,9 +23,13 @@
 #define CCWCHAIN_LEN_MAX	256
 
 struct pfn_array {
+	/* Starting guest physical I/O address. */
 	unsigned long		pa_iova;
+	/* Array that stores PFNs of the pages need to pin. */
 	unsigned long		*pa_iova_pfn;
+	/* Array that receives PFNs of the pages pinned. */
 	unsigned long		*pa_pfn;
+	/* Number of pages to pin/pinned from @pa_iova. */
 	int			pa_nr;
 };
 
@@ -53,14 +57,8 @@ struct ccwchain {
  * Attempt to pin user pages in memory.
  *
  * Usage of pfn_array:
- * @pa->pa_iova     starting guest physical I/O address. Assigned by caller.
- * @pa->pa_iova_pfn array that stores PFNs of the pages need to pin. Allocated
- *                  by caller.
- * @pa->pa_pfn      array that receives PFNs of the pages pinned. Allocated by
- *                  caller.
- * @pa->pa_nr       number of pages from @pa->pa_iova to pin. Assigned by
- *                  caller.
- *                  number of pages pinned. Assigned by callee.
+ * Any field in this structure should be initialized by caller.
+ * We expect @pa->pa_nr > 0, and its value will be assigned by callee.
  *
  * Returns:
  *   Number of pages pinned on success.
-- 
2.16.3

  reply	other threads:[~2018-05-23  2:45 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-05-23  2:44 [PATCH v3 0/4] vfio: ccw: error handling fixes and improvements Dong Jia Shi
2018-05-23  2:44 ` Dong Jia Shi [this message]
2018-05-23  2:45 ` [PATCH v3 2/4] vfio: ccw: refactor and improve pfn_array_alloc_pin() Dong Jia Shi
2018-05-23  2:45 ` [PATCH v3 3/4] vfio: ccw: set ccw->cda to NULL defensively Dong Jia Shi
2018-05-23  2:45 ` [PATCH v3 4/4] vfio: ccw: add traceponits for interesting error paths Dong Jia Shi

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=20180523024502.94244-2-bjsdjshi@linux.ibm.com \
    --to=bjsdjshi@linux.ibm.com \
    --cc=bjsdjshi@linux.vnet.ibm.com \
    --cc=borntraeger@de.ibm.com \
    --cc=cohuck@redhat.com \
    --cc=kvm@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-s390@vger.kernel.org \
    --cc=pasic@linux.ibm.com \
    --cc=pmorel@linux.ibm.com \
    --subject='Re: [PATCH v3 1/4] vfio: ccw: shorten kernel doc description for pfn_array_pin()' \
    /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

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