[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Xen-devel] [PATCH XEN v6 25/32] tools/libs/gnttab: Extensive updates to API documentation.

On 03/12/15 06:22, Ian Campbell wrote:
In particular around error handling, behaviour on fork and the unmap
notification mechanism.

Behaviour of xengnttab_map_*grant_refs and xengntshr_share_pages on
partial failure has been confirmed/inferred (by inspection) on Linux
and Mini-os (the only two known implementations. Likewise the
behaviour of the notification mechanism has been confirmed/inferred
(by inspection) of the Linux implementation (currently the only
implementation) and libvchan (primary known user).

These updates are not folded into "tools: Refactor
/dev/xen/gnt{dev,shr} wrappers into libxengnttab." to try and reduce
the amount of non-movement changes in that patch.

While I'm not convinced by javadoc/doxygen cause the existing comments
which appear to use that syntax to have the appropriate /** marker.

Also fix a typo in a code comment.

Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
Cc: Daniel De Graaf <dgdegra@xxxxxxxxxxxxx>
Daniel, you input on the description of the unmap notification stuff
would be much appreciated.

The description looks complete and correct to me.  The statement that
the interfaces operate on a single page only might be misleading - the
interface will work on multi-page mappings, but only allows one notify
on the mapping.  I'm not sure this distinction is important for most
users of the interface, since the notify is almost always used on a
one-page mapping.

Reviewed-by: Daniel De Graaf <dgdegra@xxxxxxxxxxxxx>

@@ -71,6 +154,10 @@ void *xengnttab_map_grant_ref(xengnttab_handle *xgt,
   * contiguous local address range. Mappings should be unmapped with
   * xengnttab_munmap.  Logs errors.
+ * On failure sets errno and returns NULL.
+ *
+ * If notify_offset or notify_port a requested and cannot be set up an
+ * error will be returned and no mapping will be made.

Typo: "a requested" => "are requested"

Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.