From: John Hubbard <jhubbard@nvidia.com> To: Andrew Morton <akpm@linux-foundation.org> Cc: "Michael S . Tsirkin" <mst@redhat.com>, "Jason Wang" <jasowang@redhat.com>, "Vlastimil Babka" <vbabka@suse.cz>, "Jérôme Glisse" <jglisse@redhat.com>, "Jan Kara" <jack@suse.cz>, "Dave Chinner" <david@fromorbit.com>, "Souptick Joarder" <jrdr.linux@gmail.com>, "Jonathan Corbet" <corbet@lwn.net>, linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, kvm@vger.kernel.org, virtualization@lists.linux-foundation.org, netdev@vger.kernel.org, LKML <linux-kernel@vger.kernel.org>, linux-mm@kvack.org, "John Hubbard" <jhubbard@nvidia.com> Subject: [PATCH 1/2] docs: mm/gup: pin_user_pages.rst: add a "case 5" Date: Fri, 29 May 2020 16:43:08 -0700 [thread overview] Message-ID: <20200529234309.484480-2-jhubbard@nvidia.com> (raw) In-Reply-To: <20200529234309.484480-1-jhubbard@nvidia.com> There are four cases listed in pin_user_pages.rst. These are intended to help developers figure out whether to use get_user_pages*(), or pin_user_pages*(). However, the four cases do not cover all the situations. For example, drivers/vhost/vhost.c has a "pin, write to page, set page dirty, unpin" case. Add a fifth case, to help explain that there is a general pattern that requires pin_user_pages*() API calls. Cc: Vlastimil Babka <vbabka@suse.cz> Cc: Jan Kara <jack@suse.cz> Cc: Jérôme Glisse <jglisse@redhat.com> Cc: Dave Chinner <david@fromorbit.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Cc: linux-fsdevel@vger.kernel.org Signed-off-by: John Hubbard <jhubbard@nvidia.com> --- Documentation/core-api/pin_user_pages.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst index 4675b04e8829..b9f2688a2c67 100644 --- a/Documentation/core-api/pin_user_pages.rst +++ b/Documentation/core-api/pin_user_pages.rst @@ -171,6 +171,26 @@ If only struct page data (as opposed to the actual memory contents that a page is tracking) is affected, then normal GUP calls are sufficient, and neither flag needs to be set. +CASE 5: Pinning in order to write to the data within the page +------------------------------------------------------------- +Even though neither DMA nor Direct IO is involved, just a simple case of "pin, +access page's data, unpin" can cause a problem. Case 5 may be considered a +superset of Case 1, plus Case 2, plus anything that invokes that pattern. In +other words, if the code is neither Case 1 nor Case 2, it may still require +FOLL_PIN, for patterns like this: + +Correct (uses FOLL_PIN calls): + pin_user_pages() + access the data within the pages + set_page_dirty_lock() + unpin_user_pages() + +INCORRECT (uses FOLL_GET calls): + get_user_pages() + access the data within the pages + set_page_dirty_lock() + put_page() + page_maybe_dma_pinned(): the whole point of pinning =================================================== -- 2.26.2
WARNING: multiple messages have this Message-ID (diff)
From: John Hubbard <jhubbard@nvidia.com> To: Andrew Morton <akpm@linux-foundation.org> Cc: "Jan Kara" <jack@suse.cz>, linux-doc@vger.kernel.org, kvm@vger.kernel.org, "Michael S . Tsirkin" <mst@redhat.com>, netdev@vger.kernel.org, "Jonathan Corbet" <corbet@lwn.net>, "Dave Chinner" <david@fromorbit.com>, LKML <linux-kernel@vger.kernel.org>, virtualization@lists.linux-foundation.org, linux-mm@kvack.org, "Jérôme Glisse" <jglisse@redhat.com>, "Souptick Joarder" <jrdr.linux@gmail.com>, "John Hubbard" <jhubbard@nvidia.com>, linux-fsdevel@vger.kernel.org, "Vlastimil Babka" <vbabka@suse.cz> Subject: [PATCH 1/2] docs: mm/gup: pin_user_pages.rst: add a "case 5" Date: Fri, 29 May 2020 16:43:08 -0700 [thread overview] Message-ID: <20200529234309.484480-2-jhubbard@nvidia.com> (raw) In-Reply-To: <20200529234309.484480-1-jhubbard@nvidia.com> There are four cases listed in pin_user_pages.rst. These are intended to help developers figure out whether to use get_user_pages*(), or pin_user_pages*(). However, the four cases do not cover all the situations. For example, drivers/vhost/vhost.c has a "pin, write to page, set page dirty, unpin" case. Add a fifth case, to help explain that there is a general pattern that requires pin_user_pages*() API calls. Cc: Vlastimil Babka <vbabka@suse.cz> Cc: Jan Kara <jack@suse.cz> Cc: Jérôme Glisse <jglisse@redhat.com> Cc: Dave Chinner <david@fromorbit.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Cc: linux-fsdevel@vger.kernel.org Signed-off-by: John Hubbard <jhubbard@nvidia.com> --- Documentation/core-api/pin_user_pages.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/Documentation/core-api/pin_user_pages.rst b/Documentation/core-api/pin_user_pages.rst index 4675b04e8829..b9f2688a2c67 100644 --- a/Documentation/core-api/pin_user_pages.rst +++ b/Documentation/core-api/pin_user_pages.rst @@ -171,6 +171,26 @@ If only struct page data (as opposed to the actual memory contents that a page is tracking) is affected, then normal GUP calls are sufficient, and neither flag needs to be set. +CASE 5: Pinning in order to write to the data within the page +------------------------------------------------------------- +Even though neither DMA nor Direct IO is involved, just a simple case of "pin, +access page's data, unpin" can cause a problem. Case 5 may be considered a +superset of Case 1, plus Case 2, plus anything that invokes that pattern. In +other words, if the code is neither Case 1 nor Case 2, it may still require +FOLL_PIN, for patterns like this: + +Correct (uses FOLL_PIN calls): + pin_user_pages() + access the data within the pages + set_page_dirty_lock() + unpin_user_pages() + +INCORRECT (uses FOLL_GET calls): + get_user_pages() + access the data within the pages + set_page_dirty_lock() + put_page() + page_maybe_dma_pinned(): the whole point of pinning =================================================== -- 2.26.2 _______________________________________________ Virtualization mailing list Virtualization@lists.linux-foundation.org https://lists.linuxfoundation.org/mailman/listinfo/virtualization
next prev parent reply other threads:[~2020-05-29 23:43 UTC|newest] Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-05-29 23:43 [PATCH 0/2] vhost, docs: convert to pin_user_pages(), new "case 5" John Hubbard 2020-05-29 23:43 ` John Hubbard [this message] 2020-05-29 23:43 ` [PATCH 1/2] docs: mm/gup: pin_user_pages.rst: add a " John Hubbard 2020-05-31 7:11 ` Souptick Joarder 2020-06-01 5:11 ` John Hubbard 2020-06-12 19:24 ` Matthew Wilcox 2020-06-12 20:03 ` John Hubbard 2020-05-29 23:43 ` [PATCH 2/2] vhost: convert get_user_pages() --> pin_user_pages() John Hubbard 2020-06-01 11:30 ` Jan Kara 2020-06-01 11:30 ` Jan Kara 2020-06-02 4:22 ` Michael S. Tsirkin
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=20200529234309.484480-2-jhubbard@nvidia.com \ --to=jhubbard@nvidia.com \ --cc=akpm@linux-foundation.org \ --cc=corbet@lwn.net \ --cc=david@fromorbit.com \ --cc=jack@suse.cz \ --cc=jasowang@redhat.com \ --cc=jglisse@redhat.com \ --cc=jrdr.linux@gmail.com \ --cc=kvm@vger.kernel.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-fsdevel@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-mm@kvack.org \ --cc=mst@redhat.com \ --cc=netdev@vger.kernel.org \ --cc=vbabka@suse.cz \ --cc=virtualization@lists.linux-foundation.org \ /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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.