From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ian Campbell Subject: Re: [PATCH XEN v2 08/15] tools: Refactor /dev/xen/gnt{dev, shr} wrappers into libxengnttab. Date: Tue, 22 Sep 2015 12:25:12 +0100 Message-ID: <1442921112.10338.153.camel@citrix.com> References: <1436975173.32371.121.camel@citrix.com> <1436975223-11098-8-git-send-email-ian.campbell@citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1436975223-11098-8-git-send-email-ian.campbell@citrix.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: ian.jackson@eu.citrix.com, wei.liu2@citrix.com, xen-devel@lists.xen.org Cc: roger.pau@citrix.com, stefano.stabellini@eu.citrix.com List-Id: xen-devel@lists.xenproject.org Any thoughts/preferences on this library interface regarding: The use of a (perhaps to be added) grant_ref_t in preference to uint32_t as it is now? The use of bool rather than int for "writeable"? Mapping functions returning NULL on failure (rather than e.g MAP_FAILED)? (current code squashes any underlying MAP_FAILED into NULL, but of course that prevents mapping things at NULL, but then I'm not sure why we would want to support that). Ian. On Wed, 2015-07-15 at 16:46 +0100, Ian Campbell wrote: > diff --git a/tools/libxengnttab/include/xengnttab.h b/tools/libxengnttab/include/xengnttab.h > new file mode 100644 > index 0000000..b333662 > --- /dev/null > +++ b/tools/libxengnttab/include/xengnttab.h > @@ -0,0 +1,215 @@ > +/* > + * This library is free software; you can redistribute it and/or > + * modify it under the terms of the GNU Lesser General Public > + * License as published by the Free Software Foundation; > + * version 2.1 of the License. > + * > + * This library is distributed in the hope that it will be useful, > + * but WITHOUT ANY WARRANTY; without even the implied warranty of > + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU > + * Lesser General Public License for more details. > + * > + * Split off from: > + * xenctrl.h > + * > + * A library for low-level access to the Xen control interfaces. > + * > + * Copyright (c) 2007-2008, D G Murray > + */ > +#ifndef XENGNTTAB_H > +#define XENGNTTAB_H > + > +#include > + > +#include > +#include > + > +/* Callers who don't care don't need to #include */ > +typedef struct xentoollog_logger xentoollog_logger; > + > +/* > + * Grant Table Interface (making use of grants from other domains) > + */ > + > +typedef struct xengntdev_handle xengnttab_handle; > + > +/* > + * Note: > + * After fork a child process must not use any opened xc gnttab > + * handle inherited from their parent. They must open a new handle if > + * they want to interact with xc. > + * > + * Return an fd onto the grant table driver. Logs errors. > + */ > +xengnttab_handle *xengnttab_open(xentoollog_logger *logger, unsigned open_flags); > + > +/* > + * Close a handle previously allocated with xengnttab_open(). > + * Never logs errors. > + */ > +int xengnttab_close(xengnttab_handle *xgt); > + > +/* > + * Memory maps a grant reference from one domain to a local address range. > + * Mappings should be unmapped with xengnttab_munmap. Logs errors. > + * > + * @parm xgt a handle on an open grant table interface > + * @parm domid the domain to map memory from > + * @parm ref the grant reference ID to map > + * @parm prot same flag as in mmap() > + */ > +void *xengnttab_map_grant_ref(xengnttab_handle *xgt, > + uint32_t domid, > + uint32_t ref, > + int prot); > + > +/** > + * Memory maps one or more grant references from one or more domains to a > + * contiguous local address range. Mappings should be unmapped with > + * xengnttab_munmap. Logs errors. > + * > + * @parm xgt a handle on an open grant table interface > + * @parm count the number of grant references to be mapped > + * @parm domids an array of @count domain IDs by which the corresponding @refs > + * were granted > + * @parm refs an array of @count grant references to be mapped > + * @parm prot same flag as in mmap() > + */ > +void *xengnttab_map_grant_refs(xengnttab_handle *xgt, > + uint32_t count, > + uint32_t *domids, > + uint32_t *refs, > + int prot); > + > +/** > + * Memory maps one or more grant references from one domain to a > + * contiguous local address range. Mappings should be unmapped with > + * xengnttab_munmap. Logs errors. > + * > + * @parm xgt a handle on an open grant table interface > + * @parm count the number of grant references to be mapped > + * @parm domid the domain to map memory from > + * @parm refs an array of @count grant references to be mapped > + * @parm prot same flag as in mmap() > + */ > +void *xengnttab_map_domain_grant_refs(xengnttab_handle *xgt, > + uint32_t count, > + uint32_t domid, > + uint32_t *refs, > + int prot); > + > +/** > + * Memory maps a grant reference from one domain to a local address range. > + * Mappings should be unmapped with xengnttab_munmap. If notify_offset or > + * notify_port are not -1, this version will attempt to set up an unmap > + * notification at the given offset and event channel. When the page is > + * unmapped, the byte at the given offset will be zeroed and a wakeup will be > + * sent to the given event channel. Logs errors. > + * > + * @parm xgt a handle on an open grant table interface > + * @parm domid the domain to map memory from > + * @parm ref the grant reference ID to map > + * @parm prot same flag as in mmap() > + * @parm notify_offset The byte offset in the page to use for unmap > + * notification; -1 for none. > + * @parm notify_port The event channel port to use for unmap notify, or -1 > + */ > +void *xengnttab_map_grant_ref_notify(xengnttab_handle *xgt, > + uint32_t domid, > + uint32_t ref, > + int prot, > + uint32_t notify_offset, > + evtchn_port_t notify_port); > + > +/* > + * Unmaps the @count pages starting at @start_address, which were mapped by a > + * call to xengnttab_map_grant_ref or xengnttab_map_grant_refs. Never logs. > + */ > +int xengnttab_munmap(xengnttab_handle *xgt, > + void *start_address, > + uint32_t count); > + > +/* > + * Sets the maximum number of grants that may be mapped by the given instance > + * to @count. Never logs. > + * > + * N.B. This function must be called after opening the handle, and before any > + * other functions are invoked on it. > + * > + * N.B. When variable-length grants are mapped, fragmentation may be observed, > + * and it may not be possible to satisfy requests up to the maximum number > + * of grants. > + */ > +int xengnttab_set_max_grants(xengnttab_handle *xgt, > + uint32_t count); > + > +/* > + * Grant Sharing Interface (allocating and granting pages) > + */ > + > +typedef struct xengntdev_handle xengntshr_handle; > + > +/* > + * Return an fd onto the grant sharing driver. Logs errors. > + * > + * Note: > + * After fork a child process must not use any opened xc gntshr > + * handle inherited from their parent. They must open a new handle if > + * they want to interact with xc. > + * > + */ > +xengntshr_handle *xengntshr_open(xentoollog_logger *logger, > + unsigned open_flags); > + > +/* > + * Close a handle previously allocated with xengntshr_open(). > + * Never logs errors. > + */ > +int xengntshr_close(xengntshr_handle *xgs); > + > +/* > + * Creates and shares pages with another domain. > + * > + * @parm xgs a handle to an open grant sharing instance > + * @parm domid the domain to share memory with > + * @parm count the number of pages to share > + * @parm refs the grant references of the pages (output) > + * @parm writable true if the other domain can write to the pages > + * @return local mapping of the pages > + */ > +void *xengntshr_share_pages(xengntshr_handle *xgs, uint32_t domid, > + int count, uint32_t *refs, int writable); > + > +/* > + * Creates and shares a page with another domain, with unmap notification. > + * > + * @parm xgs a handle to an open grant sharing instance > + * @parm domid the domain to share memory with > + * @parm refs the grant reference of the pages (output) > + * @parm writable true if the other domain can write to the page > + * @parm notify_offset The byte offset in the page to use for unmap > + * notification; -1 for none. > + * @parm notify_port The event channel port to use for unmap notify, or -1 > + * @return local mapping of the page > + */ > +void *xengntshr_share_page_notify(xengntshr_handle *xgs, uint32_t domid, > + uint32_t *ref, int writable, > + uint32_t notify_offset, > + evtchn_port_t notify_port); > +/* > + * Unmaps the @count pages starting at @start_address, which were mapped by a > + * call to xengntshr_share_*. Never logs. > + */ > +int xengntshr_munmap(xengntshr_handle *xgs, void *start_address, uint32_t count); > + > +#endif > + > +/* > + * Local variables: > + * mode: C > + * c-file-style: "BSD" > + * c-basic-offset: 4 > + * tab-width: 4 > + * indent-tabs-mode: nil > + * End: > + */