[Xen-changelog] [xen master] tools/libs/call: Describe return values and error semantics for xencall*

[patchbot@xxxxxxx]

commit 139ff8ffc94d173531610e093c9a40c4688fa593
Author:     Ian Campbell <ian.campbell@xxxxxxxxxx>
AuthorDate: Fri Nov 27 12:08:32 2015 +0000
Commit:     Ian Campbell <ian.campbell@xxxxxxxxxx>
CommitDate: Fri Jan 22 12:24:20 2016 +0000

    tools/libs/call: Describe return values and error semantics for xencall*

    This behaviour has been confirmed by inspection on:

     - Linux
     - NetBSD & FreeBSD (NB: hcall->retval is the hypercall return value
       only for values >= 0. For negative values the underlying privcmd
       driver translates the value from Xen to {Net,Free}BSD errno space
       and returns it as the result of the ioctl, which becomes
       ret=-1/errno=EFOO in userspace)
     - MiniOS (which takes care of errno in this library)

    Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
    Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>
    Acked-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
    Acked-by: Roger Pau Monné <roger.pau@xxxxxxxxxx>
    Cc: Roger Pau Monné <roger.pau@xxxxxxxxxx>
---
 tools/libs/call/include/xencall.h |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/tools/libs/call/include/xencall.h 
b/tools/libs/call/include/xencall.h
index 0d91aa8..3f325f0 100644
--- a/tools/libs/call/include/xencall.h
+++ b/tools/libs/call/include/xencall.h
@@ -46,6 +46,21 @@ int xencall_close(xencall_handle *xcall);

 /*
  * Call hypercalls with varying numbers of arguments.
+ *
+ * On success the return value of the hypercall is the return value of
+ * the xencall function.  On error these functions set errno and
+ * return -1.
+ *
+ * The errno values will be either:
+ * - The Xen hypercall error return (from xen/include/public/errno.h)
+ *   translated into the corresponding local value for that POSIX error.
+ * - An errno value produced by the OS driver or the library
+ *   implementation. Such values may be defined by POSIX or by the OS.
+ *
+ * Note that under some circumstances it will not be possible to tell
+ * whether an error came from Xen or from the OS/library.
+ *
+ * These functions never log.
  */
 int xencall0(xencall_handle *xcall, unsigned int op);
 int xencall1(xencall_handle *xcall, unsigned int op,
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog