[PATCH doc] Document crosvm memfd server
--- Looking for another set of eyes on this to check it makes sense to people who haven't dedicated several weeks of their life to thinking about it. ;) developer-manual.adoc | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/developer-manual.adoc b/developer-manual.adoc index a538437..5a5f80d 100644 --- a/developer-manual.adoc +++ b/developer-manual.adoc @@ -194,6 +194,31 @@ compile the policy files into the crosvm binary so paths don't have to be hardcoded. +==== The memfd server + +Spectrum's crosvm has been augmented with a feature called the +"`memfd server`", (currently only on the +https://spectrum-os.org/git/crosvm/log/?h=interguest[interguest] +branch). This is a small server that listens on a Unix stream socket. +It receives a request consisting of a name and a size, uses those to +allocate a receives requests for a +https://man7.org/linux/man-pages/man2/memfd_create.2.html[memfd], and +then sends the resulting memfd file descriptor back over the socket in +response, along with a single byte status code. + +The purpose of this is that it can be exposed to the guest over +virtio_wl. This means that the guest can request and receive +allocations of host memory. This is important, because virtio_wl only +allows file descriptors pointing to host memory to be sent over +virtio_wl -- a memfd allocated in a guest cannot be sent over virtio_wl. +It is rare that a guest needs to be able to allocate and send shared +memory in this way, but it is important for a Wayland compositor +running in a guest to be able to do this. + +The memfd server is disabled by default, but is enabled at startup +time with the `--wl-memfd` flag. + + === Sommelier https://chromium.googlesource.com/chromiumos/platform2/+/master/vm_tools/sommelier[Sommelier] -- 2.26.2
Makes sense to me, but I think there's a typo here:
+It receives a request consisting of a name and a size, uses those to +allocate a receives requests for a +https://man7.org/linux/man-pages/man2/memfd_create.2.html[memfd],
"receives requests" is repeated from the previous line.
--- Thanks for the comments. Should be addressed now. Please take a(nother) look. If you think it looks good, I'd appreciate a Reviewed-by tag from you. :) (Last bit is just something nice for me to put in the git log, e.g. Reviewed-by: Alyssa Ross <hi@alyssa.is>, and means that you had a look and don't see anything wrong with the changes. By convention those should be sent by the reviewer rather than just made up by me. :)) developer-manual.adoc | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/developer-manual.adoc b/developer-manual.adoc index a538437..d69707d 100644 --- a/developer-manual.adoc +++ b/developer-manual.adoc @@ -194,6 +194,31 @@ compile the policy files into the crosvm binary so paths don't have to be hardcoded. +==== The memfd server + +Spectrum's crosvm has been augmented with a feature called the "`memfd +server`", (currently only on the +https://spectrum-os.org/git/crosvm/log/?h=interguest[interguest] +branch). This is a small server that listens on a Unix stream socket. +It receives a request consisting of a name and a size, uses those to +allocate a +https://man7.org/linux/man-pages/man2/memfd_create.2.html[memfd], and +then sends the resulting memfd file descriptor back over the socket in +response, along with a single byte status code. + +The purpose of this is that it can be exposed to the guest over +virtio_wl. This means that the guest can request and receive +allocations of host memory. This is important, because virtio_wl only +allows file descriptors pointing to host memory to be sent over +virtio_wl -- a memfd allocated in a guest cannot be sent over virtio_wl. +It is rare that a guest needs to be able to allocate and send shared +memory in this way, but it is important for a Wayland compositor +running in a guest to be able to do this. + +The memfd server is disabled by default, but is enabled at startup +with the `--wl-memfd` flag. + + === Sommelier https://chromium.googlesource.com/chromiumos/platform2/+/master/vm_tools/sommelier[Sommelier] -- 2.26.2
Looks good. One minor nitpick, take it or leave it:
+Spectrum's crosvm has been augmented with a feature called the "`memfd +server`", (currently only on the +https://spectrum-os.org/git/crosvm/log/?h=interguest[interguest] +branch). This is a small server that listens on a Unix stream socket.
This should be either a comma or parenthesis, not both. This is just a personal preference of mine, but one I wish were more widely adopted: when writing markdown I only wrap the "proper nouns" in `code blocks` for consistency, e.g. "`memfd` server" not "`memfd server`". But this isn't a hill I'm prepared to die on. Reviewed-by: impaqt <impaqt@vendek.net> ^^^ Is this what you meant by a tag?
Looks good. One minor nitpick, take it or leave it:
+Spectrum's crosvm has been augmented with a feature called the "`memfd +server`", (currently only on the +https://spectrum-os.org/git/crosvm/log/?h=interguest[interguest] +branch). This is a small server that listens on a Unix stream socket.
This should be either a comma or parenthesis, not both.
Will fix, thank you.
This is just a personal preference of mine, but one I wish were more widely adopted: when writing markdown I only wrap the "proper nouns" in `code blocks` for consistency, e.g. "`memfd` server" not "`memfd server`". But this isn't a hill I'm prepared to die on.
I strongly agree! But this isn't Markdown. That's just the syntax for double quotes in AsciiDoctor. :)
Reviewed-by: impaqt <impaqt@vendek.net> ^^^ Is this what you meant by a tag?
Yes! Thank you. :)
On Wed May 27, 2020 at 11:27 PM, Alyssa Ross wrote:
--- Thanks for the comments. Should be addressed now.
Please take a(nother) look. If you think it looks good, I'd appreciate a Reviewed-by tag from you. :)
(Last bit is just something nice for me to put in the git log, e.g. Reviewed-by: Alyssa Ross <hi@alyssa.is>, and means that you had a look and don't see anything wrong with the changes. By convention those should be sent by the reviewer rather than just made up by me. :))
developer-manual.adoc | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+)
LGTM. Sorry for the late response! Reviewed-by: Cole Helbling <cole.e.helbling@outlook.com>
Committed as fb12866ffe94dda9879d8879dee3043df2d60e7a. Thank you both. Nice to be starting to get feedback on here. :)
participants (3)
-
Alyssa Ross -
Cole Helbling -
impaqt