Merge remote-tracking branch 'remotes/armbru/tags/pull-error-2018-02-06' into staging

Error reporting patches for 2018-02-06

# gpg: Signature made Tue 06 Feb 2018 19:48:30 GMT
# gpg:                using RSA key 3870B400EB918653
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>"
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>"
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-error-2018-02-06:
  tcg: Replace fprintf(stderr, "*\n" with error_report()
  hw/xen*: Replace fprintf(stderr, "*\n" with error_report()
  hw/sparc*: Replace fprintf(stderr, "*\n" with error_report()
  hw/sd: Replace fprintf(stderr, "*\n" with DPRINTF()
  hw/ppc: Replace fprintf(stderr, "*\n" with error_report()
  hw/pci*: Replace fprintf(stderr, "*\n" with error_report()
  hw/openrisc: Replace fprintf(stderr, "*\n" with error_report()
  hw/moxie: Replace fprintf(stderr, "*\n" with error_report()
  hw/mips: Replace fprintf(stderr, "*\n" with error_report()
  hw/lm32: Replace fprintf(stderr, "*\n" with error_report()
  hw/dma: Replace fprintf(stderr, "*\n" with error_report()
  hw/arm: Replace fprintf(stderr, "*\n" with error_report()
  audio: Replace AUDIO_FUNC with __func__
  error: Improve documentation of error_append_hint()

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 8 insertions, 0 deletions

diff --git a/include/qapi/error.h b/include/qapi/error.h
index 341b229066..c2115a6a4a 100644
--- a/include/qapi/error.h
+++ b/include/qapi/error.h
@@ -230,6 +230,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().
@@ -267,11 +273,13 @@ 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);