Improve docs for IOCTL_GNTDEV_MAP_GRANT_REF
PATCH v2 1/1 Improve docs for IOCTL_GNTDEV_MAP_GRANT_REF
The current implementation of gntdev guarantees that the first call to IOCTL_GNTDEV_MAP_GRANT_REF will set @index to 0. This is required to use gntdev for Wayland, which is a future desire of Qubes OS. Additionally, requesting zero grants results in an error, but this was not documented either. Document both of these.
--- include/uapi/xen/gntdev.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)
include/uapi/xen/gntdev.h +7 -1
@@ -47,7 +47,13 @@ struct ioctl_gntdev_grant_ref {/* * Inserts the grant references into the mapping table of an instance * of gntdev. N.B. This does not perform the mapping, which is deferred -* until mmap() is called with @index as the offset. +* until mmap() is called with @index as the offset. @index should be +* considered opaque to userspace, with one exception: if no grant +* references have ever been inserted into the mapping table of this +* instance, @index will be set to 0. This is necessary to use gntdev +* with userspace APIs that expect a file descriptor that can be +* mmap()'d at offset 0, such as Wayland. If @count is set to 0, this +* ioctl will fail. */ #define IOCTL_GNTDEV_MAP_GRANT_REF \ _IOC(_IOC_NONE, 'G', 0, sizeof(struct ioctl_gntdev_map_grant_ref))
Signature · 3 lines
Sincerely, Demi Marie Obenour she/her/hers
Quoted 7 lines · Demi Marie Obenour
The current implementation of gntdev guarantees that the first call to
IOCTL_GNTDEV_MAP_GRANT_REFwill set @index to 0. This is required to use gntdev for Wayland, which is a future desire of Qubes OS. Additionally, requesting zero grants results in an error, but this was not documented either. Document both of these.Signed-off-by Demi Marie Obenour <[email protected]>
Juergen
Quoted 7 lines · Demi Marie Obenour
The current implementation of gntdev guarantees that the first call to
IOCTL_GNTDEV_MAP_GRANT_REFwill set @index to 0. This is required to use gntdev for Wayland, which is a future desire of Qubes OS. Additionally, requesting zero grants results in an error, but this was not documented either. Document both of these.Signed-off-by Demi Marie Obenour <[email protected]>
Pushed to xen/tip.git for-linus-5.17a
Juergen