Documenting return values of hypervisor API calls.
Change-Id: I8f6ee8a43e9b05e1728fde63af626b7599962000
diff --git a/inc/vmapi/hf/call.h b/inc/vmapi/hf/call.h
index 771997a..ac1ddff 100644
--- a/inc/vmapi/hf/call.h
+++ b/inc/vmapi/hf/call.h
@@ -44,6 +44,8 @@
/**
* Runs the given vcpu of the given vm.
+ *
+ * Returns an hf_vcpu_run_return struct telling the scheduler what to do next.
*/
static inline struct hf_vcpu_run_return hf_vcpu_run(uint32_t vm_id,
uint32_t vcpu_idx)
@@ -71,6 +73,8 @@
/**
* Configures the pages to send/receive data through. The pages must not be
* shared.
+ *
+ * Returns 0 on success or -1 or failure.
*/
static inline int64_t hf_vm_configure(hf_ipaddr_t send, hf_ipaddr_t recv)
{
@@ -79,6 +83,11 @@
/**
* Copies data from the sender's send buffer to the recipient's receive buffer.
+ *
+ * Returns -1 on failure, and on success either:
+ * - 0, if the caller is a secondary VM
+ * - the ID of the vCPU to run to receive the message, if the caller is the
+ * primary VM.
*/
static inline int64_t hf_mailbox_send(uint32_t vm_id, size_t size)
{
@@ -100,7 +109,10 @@
}
/**
- * Clears the mailbox so a new message can be received.
+ * Clears the caller's mailbox so a new message can be received.
+ *
+ * Returns 0 on success, or -1 if the mailbox hasn't been read or is already
+ * empty.
*/
static inline int64_t hf_mailbox_clear(void)
{
