Makefile: install the edk2 firmware images and their descriptors

[qemu.git] / include / qapi / error.h

diff --git a/include/qapi/error.h b/include/qapi/error.h
index 45d6c72dee6d7b4d679670792da1bccd41570e5b..51b63dd4b5289ffaf3a32e44ac2ca76c7f812621 100644 (file)
--- a/include/qapi/error.h
+++ b/include/qapi/error.h
@@ -27,11 +27,11 @@
  *     error_setg(&err, "invalid quark\n"
  *                "Valid quarks are up, down, strange, charm, top, bottom.");
  *
- * Report an error to stderr:
+ * Report an error to the current monitor if we have one, else stderr:
  *     error_report_err(err);
  * This frees the error object.
  *
- * Report an error to stderr with additional text prepended:
+ * Likewise, but with additional text prepended:
  *     error_reportf_err(err, "Could not frobnicate '%s': ", name);
  *
  * Report an error somewhere else:
@@ -52,8 +52,12 @@
  * where Error **errp is a parameter, by convention the last one.
  *
  * Pass an existing error to the caller with the message modified:
+ *     error_propagate_prepend(errp, err);
+ *
+ * Avoid
  *     error_propagate(errp, err);
  *     error_prepend(errp, "Could not frobnicate '%s': ", name);
+ * because this fails to prepend when @errp is &error_fatal.
  *
  * Create a new error and pass it to the caller:
  *     error_setg(errp, "situation normal, all fouled up");
@@ -115,15 +119,7 @@
 #ifndef ERROR_H
 #define ERROR_H
 
-#include <stdarg.h>
-#include <stdbool.h>
-#include "qemu/compiler.h"
-#include "qapi-types.h"
-
-/*
- * Opaque error object.
- */
-typedef struct Error Error;
+#include "qapi/qapi-types-common.h"
 
 /*
  * Overall category of an error.
@@ -133,7 +129,6 @@ typedef struct Error Error;
 typedef enum ErrorClass {
     ERROR_CLASS_GENERIC_ERROR = QAPI_ERROR_CLASS_GENERICERROR,
     ERROR_CLASS_COMMAND_NOT_FOUND = QAPI_ERROR_CLASS_COMMANDNOTFOUND,
-    ERROR_CLASS_DEVICE_ENCRYPTED = QAPI_ERROR_CLASS_DEVICEENCRYPTED,
     ERROR_CLASS_DEVICE_NOT_ACTIVE = QAPI_ERROR_CLASS_DEVICENOTACTIVE,
     ERROR_CLASS_DEVICE_NOT_FOUND = QAPI_ERROR_CLASS_DEVICENOTFOUND,
     ERROR_CLASS_KVM_MISSING_CAP = QAPI_ERROR_CLASS_KVMMISSINGCAP,
@@ -142,7 +137,7 @@ typedef enum ErrorClass {
 /*
  * Get @err's human-readable error message.
  */
-const char *error_get_pretty(Error *err);
+const char *error_get_pretty(const Error *err);
 
 /*
  * Get @err's error class.
@@ -162,6 +157,9 @@ ErrorClass error_get_class(const Error *err);
  * human-readable error message is made from printf-style @fmt, ...
  * The resulting message should be a single phrase, with no newline or
  * trailing punctuation.
+ * Please don't error_setg(&error_fatal, ...), use error_report() and
+ * exit(), because that's more obvious.
+ * Likewise, don't error_setg(&error_abort, ...), use assert().
  */
 #define error_setg(errp, fmt, ...)                              \
     error_setg_internal((errp), __FILE__, __LINE__, __func__,   \
@@ -175,6 +173,9 @@ void error_setg_internal(Error **errp,
  * Just like error_setg(), with @os_error info added to the message.
  * If @os_error is non-zero, ": " + strerror(os_error) is appended to
  * the human-readable error message.
+ *
+ * The value of errno (which usually can get clobbered by almost any
+ * function call) will be preserved.
  */
 #define error_setg_errno(errp, os_error, fmt, ...)                      \
     error_setg_errno_internal((errp), __FILE__, __LINE__, __func__,     \
@@ -213,9 +214,21 @@ void error_setg_win32_internal(Error **errp,
  * the error object.
  * Else, move the error object from @local_err to *@dst_errp.
  * On return, @local_err is invalid.
+ * Please don't error_propagate(&error_fatal, ...), use
+ * error_report_err() and exit(), because that's more obvious.
  */
 void error_propagate(Error **dst_errp, Error *local_err);
 
+
+/*
+ * Propagate error object (if any) with some text prepended.
+ * Behaves like
+ *     error_prepend(&local_err, fmt, ...);
+ *     error_propagate(dst_errp, local_err);
+ */
+void error_propagate_prepend(Error **dst_errp, Error *local_err,
+                             const char *fmt, ...);
+
 /*
  * Prepend some text to @errp's human-readable error message.
  * The text is made by formatting @fmt, @ap like vprintf().
@@ -231,6 +244,12 @@ void error_prepend(Error **errp, const char *fmt, ...)
 
 /*
  * Append a printf-style human-readable explanation to an existing error.
+ * If the error is later reported to a human user with
+ * error_report_err() or warn_report_err(), the hints will be shown,
+ * too.  If it's reported via QMP, the hints will be ignored.
+ * Intended use is adding helpful hints on the human user interface,
+ * e.g. a list of valid values.  It's not for clarifying a confusing
+ * error message.
  * @errp may be NULL, but not &error_fatal or &error_abort.
  * Trivially the case if you call it only after error_setg() or
  * error_propagate().
@@ -266,11 +285,24 @@ void error_free(Error *err);
  */
 void error_free_or_abort(Error **errp);
 
+/*
+ * Convenience function to warn_report() and free @err.
+ * The report includes hints added with error_append_hint().
+ */
+void warn_report_err(Error *err);
+
 /*
  * Convenience function to error_report() and free @err.
+ * The report includes hints added with error_append_hint().
  */
 void error_report_err(Error *err);
 
+/*
+ * Convenience function to error_prepend(), warn_report() and free @err.
+ */
+void warn_reportf_err(Error *err, const char *fmt, ...)
+    GCC_FMT_ATTR(2, 3);
+
 /*
  * Convenience function to error_prepend(), error_report() and free @err.
  */
@@ -291,12 +323,14 @@ void error_set_internal(Error **errp,
     GCC_FMT_ATTR(6, 7);
 
 /*
- * Pass to error_setg() & friends to abort() on error.
+ * Special error destination to abort on error.
+ * See error_setg() and error_propagate() for details.
  */
 extern Error *error_abort;
 
 /*
- * Pass to error_setg() & friends to exit(1) on error.
+ * Special error destination to exit(1) on error.
+ * See error_setg() and error_propagate() for details.
  */
 extern Error *error_fatal;