Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 include/chardev/char.h | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/include/chardev/char.h b/include/chardev/char.h
index d809bb316e9..8b1d5153dfd 100644
--- a/include/chardev/char.h
+++ b/include/chardev/char.h
@@ -223,7 +223,31 @@ 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.
+ */
 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.
+ */
 #define qemu_chr_write_all(s, buf, len) qemu_chr_write(s, buf, len, true)
 int qemu_chr_wait_connected(Chardev *chr, Error **errp);
 
-- 
2.51.0

Hi

On Wed, Oct 22, 2025 at 7:09 PM Philippe Mathieu-Daudé
<philmd@linaro.org> wrote:
>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
>  include/chardev/char.h | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>
> diff --git a/include/chardev/char.h b/include/chardev/char.h
> index d809bb316e9..8b1d5153dfd 100644
> --- a/include/chardev/char.h
> +++ b/include/chardev/char.h
> @@ -223,7 +223,31 @@ 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.
> + */
>  int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all);

extra empty lines would be welcome

> +/**
> + * 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.
> + */
>  #define qemu_chr_write_all(s, buf, len) qemu_chr_write(s, buf, len, true)
>  int qemu_chr_wait_connected(Chardev *chr, Error **errp);
>


Mention that "errno" is expected to be set too?

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


--
Marc-André Lureau