[PATCH v3 04/10] chardev/char: Document qemu_chr_write[_all]()

["Philippe Mathieu-Daudé" <philmd@linaro.org>]

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 include/chardev/char.h | 29 +++++++++++++++++++++++++++++
 chardev/char.c         |  1 +
 2 files changed, 30 insertions(+)

diff --git a/include/chardev/char.h b/include/chardev/char.h
index df55c7f4e67..4aab018938d 100644
--- a/include/chardev/char.h
+++ b/include/chardev/char.h
@@ -223,8 +223,37 @@ void qemu_chr_set_feature(Chardev *chr,
                           ChardevFeature feature);
 QemuOpts *qemu_chr_parse_compat(const char *label, const char *filename,
                                 bool permit_mux_mon);
+
+/**
+ * qemu_chr_write: Write data to a character backend
+ * @s: the character backend to write to
+ * @buf: the data
+ * @len: the number of bytes to write
+ * @write_all: whether to block until all chars are written
+ *
+ * Attempt to write all the data to the backend. If not all
+ * data can be consumed and @write_all is %true, keep retrying
+ * while the backend return EAGAIN, effectively blocking the caller.
+ *
+ * Returns: the number of bytes consumed or -1 on error.
+ * On error, %errno is also set as appropriate.
+ */
 int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all);
+
+/**
+ * qemu_chr_write_all: Write data to a character backend
+ * @s: the character backend to write to
+ * @buf: the data
+ * @len: the number of bytes to write
+ *
+ * Unlike @qemu_chr_write, this call will block if the backend
+ * cannot consume all of the data attempted to be written.
+ *
+ * Returns: the number of bytes consumed or -1 on error.
+ * On error, %errno is also set as appropriate.
+ */
 #define qemu_chr_write_all(s, buf, len) qemu_chr_write(s, buf, len, true)
+
 int qemu_chr_wait_connected(Chardev *chr, Error **errp);
 
 #define TYPE_CHARDEV "chardev"
diff --git a/chardev/char.c b/chardev/char.c
index 3e432195a5a..105b0d53184 100644
--- a/chardev/char.c
+++ b/chardev/char.c
@@ -108,6 +108,7 @@ static void qemu_chr_write_log(Chardev *s, const uint8_t *buf, size_t len)
     }
 }
 
+/* qemu_chr_write_buffer: Return the number of bytes consumed or -1 on error. */
 static int qemu_chr_write_buffer(Chardev *s,
                                  const uint8_t *buf, int len,
                                  int *offset, bool write_all)
-- 
2.51.0