[PATCH v2 0/9] chardev: Improve @docstring and clarify qemu_chr_write() uses

[PATCH v2 0/9] chardev: Improve @docstring and clarify qemu_chr_write() uses

[Philippe Mathieu-Daudé]

v2:
- Document ChardevClass::chr_write() and qemu_chr_write[_all]()

Few chardev fixes:
- preserve %errno
- allow partial writes in qemu_chr_write()

Improve chardev methods documentation.

While @c for frontend and @s for backend is accepted, it
confuses me, so I prefer to document for my own mental health.

Based-on: <20251022074612.1258413-1-marcandre.lureau@redhat.com>

Philippe Mathieu-Daudé (9):
  chardev/char-fe: Improve @docstrings
  chardev/char-io: Add @docstrings for io_channel_send[_full]()
  chardev/char: Improve ChardevClass::chr_write() docstring
  chardev/char: Document qemu_chr_write[_all]()
  chardev/char-pty: Do not ignore chr_write() failures
  chardev/char: Allow partial writes in qemu_chr_write()
  chardev/char: Preserve %errno in qemu_chr_write()
  chardev/char-hub: Retry when qemu_chr_fe_write() can not write
  hw/char: Simplify when qemu_chr_fe_write() could not write

 include/chardev/char-fe.h | 24 +++++++++++++++++++++++-
 include/chardev/char-io.h | 18 ++++++++++++++++++
 include/chardev/char.h    | 35 ++++++++++++++++++++++++++++++++++-
 chardev/char-hub.c        |  2 +-
 chardev/char-pty.c        |  2 +-
 chardev/char.c            |  7 ++++++-
 hw/char/cadence_uart.c    |  2 +-
 hw/char/ibex_uart.c       |  2 +-
 hw/char/sifive_uart.c     |  2 +-
 9 files changed, 86 insertions(+), 8 deletions(-)

-- 
2.51.0

[PATCH v2 1/9] chardev/char-fe: Improve @docstrings

[Philippe Mathieu-Daudé]

Describe the @c (this is the *frontend*) and @s (the *backend*)
parameters. Fill qemu_chr_fe_[gs]et_msgfds() method docstrings.

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

diff --git a/include/chardev/char-fe.h b/include/chardev/char-fe.h
index 7901856f951..c183432825b 100644
--- a/include/chardev/char-fe.h
+++ b/include/chardev/char-fe.h
@@ -26,6 +26,8 @@ struct CharFrontend {
 
 /**
  * qemu_chr_fe_init:
+ * @c: the character frontend
+ * @s: the character backend
  *
  * Initializes the frontend @c for the given Chardev backend @s. Call
  * qemu_chr_fe_deinit() to remove the association and release the backend.
@@ -47,6 +49,7 @@ void qemu_chr_fe_deinit(CharFrontend *c, bool del);
 
 /**
  * qemu_chr_fe_get_driver:
+ * @c: the character frontend
  *
  * Returns: the driver associated with a CharFrontend or NULL if no
  * associated Chardev.
@@ -58,6 +61,7 @@ Chardev *qemu_chr_fe_get_driver(CharFrontend *c);
 
 /**
  * qemu_chr_fe_backend_connected:
+ * @c: the character frontend
  *
  * Returns: true if there is a backend associated with @c.
  */
@@ -102,6 +106,7 @@ void qemu_chr_fe_set_handlers_full(CharFrontend *c,
 
 /**
  * qemu_chr_fe_set_handlers:
+ * @c: the character frontend
  *
  * Version of qemu_chr_fe_set_handlers_full() with sync_state = true.
  */
@@ -116,6 +121,7 @@ void qemu_chr_fe_set_handlers(CharFrontend *c,
 
 /**
  * qemu_chr_fe_take_focus:
+ * @c: the character frontend
  *
  * Take the focus (if the front end is muxed).
  *
@@ -125,6 +131,7 @@ void qemu_chr_fe_take_focus(CharFrontend *c);
 
 /**
  * qemu_chr_fe_accept_input:
+ * @c: the character frontend
  *
  * Notify that the frontend is ready to receive data
  */
@@ -132,6 +139,7 @@ void qemu_chr_fe_accept_input(CharFrontend *c);
 
 /**
  * qemu_chr_fe_disconnect:
+ * @c: the character frontend
  *
  * Close a fd accepted by character backend.
  * Without associated Chardev, do nothing.
@@ -148,6 +156,7 @@ int qemu_chr_fe_wait_connected(CharFrontend *c, Error **errp);
 
 /**
  * qemu_chr_fe_set_echo:
+ * @c: the character frontend
  * @echo: true to enable echo, false to disable echo
  *
  * Ask the backend to override its normal echo setting.  This only really
@@ -169,6 +178,7 @@ void qemu_chr_fe_set_open(CharFrontend *c, bool is_open);
 
 /**
  * qemu_chr_fe_printf:
+ * @c: the character frontend
  * @fmt: see #printf
  *
  * Write to a character backend using a printf style interface.  This
@@ -197,6 +207,7 @@ typedef gboolean (*FEWatchFunc)(void *do_not_use, GIOCondition condition, void *
 
 /**
  * qemu_chr_fe_add_watch:
+ * @c: the character frontend
  * @cond: the condition to poll for
  * @func: the function to call when the condition happens
  * @user_data: the opaque pointer to pass to @func
@@ -219,6 +230,7 @@ guint qemu_chr_fe_add_watch(CharFrontend *c, GIOCondition cond,
 
 /**
  * qemu_chr_fe_write:
+ * @c: the character frontend to write to
  * @buf: the data
  * @len: the number of bytes to send
  *
@@ -233,6 +245,7 @@ int qemu_chr_fe_write(CharFrontend *c, const uint8_t *buf, int len);
 
 /**
  * qemu_chr_fe_write_all:
+ * @c: the character frontend to write to
  * @buf: the data
  * @len: the number of bytes to send
  *
@@ -248,6 +261,7 @@ int qemu_chr_fe_write_all(CharFrontend *c, const uint8_t *buf, int len);
 
 /**
  * qemu_chr_fe_read_all:
+ * @c: the character frontend to read from
  * @buf: the data buffer
  * @len: the number of bytes to read
  *
@@ -260,6 +274,7 @@ int qemu_chr_fe_read_all(CharFrontend *c, uint8_t *buf, int len);
 
 /**
  * qemu_chr_fe_ioctl:
+ * @c: the character frontend to control
  * @cmd: see CHR_IOCTL_*
  * @arg: the data associated with @cmd
  *
@@ -273,6 +288,7 @@ int qemu_chr_fe_ioctl(CharFrontend *c, int cmd, void *arg);
 
 /**
  * qemu_chr_fe_get_msgfd:
+ * @c: the character frontend to access
  *
  * For backends capable of fd passing, return the latest file descriptor passed
  * by a client.
@@ -286,9 +302,12 @@ int qemu_chr_fe_get_msgfd(CharFrontend *c);
 
 /**
  * qemu_chr_fe_get_msgfds:
+ * @c: the character frontend
+ * @fds: an array of ancillary file descriptors to get
+ * @num: the maximum number of ancillary file descriptors to get in @fds
  *
  * For backends capable of fd passing, return the number of file received
- * descriptors and fills the fds array up to num elements
+ * descriptors and fills the fds array up to @num elements
  *
  * Returns: -1 if fd passing isn't supported or there are no pending file
  *          descriptors.  If file descriptors are returned, subsequent calls to
@@ -299,6 +318,9 @@ int qemu_chr_fe_get_msgfds(CharFrontend *c, int *fds, int num);
 
 /**
  * qemu_chr_fe_set_msgfds:
+ * @c: the character frontend
+ * @fds: an array of ancillary file descriptors to set
+ * @num: the number of ancillary file descriptors to set
  *
  * For backends capable of fd passing, set an array of fds to be passed with
  * the next send operation.
-- 
2.51.0

[PATCH v2 2/9] chardev/char-io: Add @docstrings for io_channel_send[_full]()

[Philippe Mathieu-Daudé]

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

diff --git a/include/chardev/char-io.h b/include/chardev/char-io.h
index ac379ea70e3..f14d1d7ef00 100644
--- a/include/chardev/char-io.h
+++ b/include/chardev/char-io.h
@@ -38,8 +38,26 @@ GSource *io_add_watch_poll(Chardev *chr,
 
 void remove_fd_in_watch(Chardev *chr);
 
+/**
+ * io_channel_send:
+ * @ioc: the IO channel object
+ * @buf: the data
+ * @len: the number of bytes to send
+ *
+ * Returns: the number of bytes consumed or -1 on error.
+ */
 int io_channel_send(QIOChannel *ioc, const void *buf, size_t len);
 
+/**
+ * io_channel_send_full:
+ * @ioc: the IO channel object
+ * @buf: the data
+ * @len: the number of bytes to send
+ * @fds: an array of file handles to send
+ * @nfds: number of file handles in @fds
+ *
+ * Returns: the number of bytes consumed or -1 on error.
+ */
 int io_channel_send_full(QIOChannel *ioc, const void *buf, size_t len,
                          int *fds, size_t nfds);
 
-- 
2.51.0

[PATCH v2 3/9] chardev/char: Improve ChardevClass::chr_write() docstring

[Philippe Mathieu-Daudé]

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

diff --git a/include/chardev/char.h b/include/chardev/char.h
index b65e9981c14..d809bb316e9 100644
--- a/include/chardev/char.h
+++ b/include/chardev/char.h
@@ -263,7 +263,16 @@ struct ChardevClass {
     void (*open)(Chardev *chr, ChardevBackend *backend,
                  bool *be_opened, Error **errp);
 
-    /* write buf to the backend */
+    /**
+     * chr_write: Write data to a character backend
+     * @s: the character backend to write to
+     * @buf: the data to write
+     * @len: the number of bytes to write
+     *
+     * Called with chr_write_lock held.
+     *
+     * Returns: the number of bytes consumed or -1 on error.
+     */
     int (*chr_write)(Chardev *s, const uint8_t *buf, int len);
 
     /*
-- 
2.51.0

[PATCH v2 4/9] chardev/char: Document qemu_chr_write[_all]()

[Philippe Mathieu-Daudé]

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

[PATCH v2 5/9] chardev/char-pty: Do not ignore chr_write() failures

[Philippe Mathieu-Daudé]

Cc: qemu-stable@nongnu.org
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
If ignoring this is deliberate, this must be described in a comment
to avoid any confusion.
---
 chardev/char-pty.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/chardev/char-pty.c b/chardev/char-pty.c
index b066f014126..652b0bd9e73 100644
--- a/chardev/char-pty.c
+++ b/chardev/char-pty.c
@@ -125,7 +125,7 @@ static int char_pty_chr_write(Chardev *chr, const uint8_t *buf, int len)
     rc = RETRY_ON_EINTR(g_poll(&pfd, 1, 0));
     g_assert(rc >= 0);
     if (!(pfd.revents & G_IO_HUP) && (pfd.revents & G_IO_OUT)) {
-        io_channel_send(s->ioc, buf, len);
+        return io_channel_send(s->ioc, buf, len);
     }
 
     return len;
-- 
2.51.0

[PATCH v2 6/9] chardev/char: Allow partial writes in qemu_chr_write()

[Philippe Mathieu-Daudé]

If qemu_chr_write_buffer() returned an error, but could
write some characters, return the number of character
written. Otherwise frontends able to recover and resume
writes re-write the partial chars already written.

Cc: qemu-stable@nongnu.org
Suggested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 chardev/char.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/chardev/char.c b/chardev/char.c
index 30b21fedce4..5c8130b2435 100644
--- a/chardev/char.c
+++ b/chardev/char.c
@@ -189,7 +189,7 @@ int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all)
         replay_char_write_event_save(res, offset);
     }
 
-    if (res < 0) {
+    if (res < 0 && offset == 0) {
         return res;
     }
     return offset;
-- 
2.51.0

[PATCH v2 7/9] chardev/char: Preserve %errno in qemu_chr_write()

[Philippe Mathieu-Daudé]

qemu_chr_write() dispatches to ChardevClass::chr_write(),
and is expected to propagate the backend error, not some
unrelated one produce by "best effort" logfile or replay.
Preserve and return the relevant %errno.

Cc: qemu-stable@nongnu.org
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 chardev/char.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/chardev/char.c b/chardev/char.c
index 5c8130b2435..2af402d9855 100644
--- a/chardev/char.c
+++ b/chardev/char.c
@@ -113,6 +113,7 @@ static int qemu_chr_write_buffer(Chardev *s,
                                  int *offset, bool write_all)
 {
     ChardevClass *cc = CHARDEV_GET_CLASS(s);
+    int saved_errno;
     int res = 0;
     *offset = 0;
 
@@ -138,6 +139,7 @@ static int qemu_chr_write_buffer(Chardev *s,
             break;
         }
     }
+    saved_errno = errno;
     if (*offset > 0) {
         /*
          * If some data was written by backend, we should
@@ -154,6 +156,7 @@ static int qemu_chr_write_buffer(Chardev *s,
          */
         qemu_chr_write_log(s, buf, len);
     }
+    errno = saved_errno;
     qemu_mutex_unlock(&s->chr_write_lock);
 
     return res;
@@ -186,7 +189,9 @@ int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all)
     res = qemu_chr_write_buffer(s, buf, len, &offset, write_all);
 
     if (qemu_chr_replay(s) && replay_mode == REPLAY_MODE_RECORD) {
+        int saved_errno = errno;
         replay_char_write_event_save(res, offset);
+        errno = saved_errno;
     }
 
     if (res < 0 && offset == 0) {
-- 
2.51.0

[PATCH v2 8/9] chardev/char-hub: Retry when qemu_chr_fe_write() can not write

[Philippe Mathieu-Daudé]

When qemu_chr_fe_write() can not write to a backend and there
is no error, it might return '0' to let the caller retry.

Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 chardev/char-hub.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/chardev/char-hub.c b/chardev/char-hub.c
index d0967c22336..4bbde9fb033 100644
--- a/chardev/char-hub.c
+++ b/chardev/char-hub.c
@@ -65,7 +65,7 @@ static int hub_chr_write(Chardev *chr, const uint8_t *buf, int len)
             continue;
         }
         r = qemu_chr_fe_write(&d->backends[i].fe, buf, len);
-        if (r < 0) {
+        if (r <= 0) {
             if (errno == EAGAIN) {
                 /* Set index and expect to be called soon on watch wake up */
                 d->be_eagain_ind = i;
-- 
2.51.0

[PATCH v2 9/9] hw/char: Simplify when qemu_chr_fe_write() could not write

[Philippe Mathieu-Daudé]

If no chars were written, avoid to access the FIFO.

Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 hw/char/cadence_uart.c | 2 +-
 hw/char/ibex_uart.c    | 2 +-
 hw/char/sifive_uart.c  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/hw/char/cadence_uart.c b/hw/char/cadence_uart.c
index 0dfa356b6d0..8908ebbe34a 100644
--- a/hw/char/cadence_uart.c
+++ b/hw/char/cadence_uart.c
@@ -316,7 +316,7 @@ static gboolean cadence_uart_xmit(void *do_not_use, GIOCondition cond,
 
     ret = qemu_chr_fe_write(&s->chr, s->tx_fifo, s->tx_count);
 
-    if (ret >= 0) {
+    if (ret > 0) {
         s->tx_count -= ret;
         memmove(s->tx_fifo, s->tx_fifo + ret, s->tx_count);
     }
diff --git a/hw/char/ibex_uart.c b/hw/char/ibex_uart.c
index d6f0d18c777..b7843c7a741 100644
--- a/hw/char/ibex_uart.c
+++ b/hw/char/ibex_uart.c
@@ -161,7 +161,7 @@ static gboolean ibex_uart_xmit(void *do_not_use, GIOCondition cond,
 
     ret = qemu_chr_fe_write(&s->chr, s->tx_fifo, s->tx_level);
 
-    if (ret >= 0) {
+    if (ret > 0) {
         s->tx_level -= ret;
         memmove(s->tx_fifo, s->tx_fifo + ret, s->tx_level);
     }
diff --git a/hw/char/sifive_uart.c b/hw/char/sifive_uart.c
index e7357d585a1..e5b381425a9 100644
--- a/hw/char/sifive_uart.c
+++ b/hw/char/sifive_uart.c
@@ -83,7 +83,7 @@ static gboolean sifive_uart_xmit(void *do_not_use, GIOCondition cond,
                                    fifo8_num_used(&s->tx_fifo), &numptr);
     ret = qemu_chr_fe_write(&s->chr, characters, numptr);
 
-    if (ret >= 0) {
+    if (ret > 0) {
         /* We wrote the data, actually pop the fifo */
         fifo8_pop_bufptr(&s->tx_fifo, ret, NULL);
     }
-- 
2.51.0

Re: [PATCH v2 7/9] chardev/char: Preserve %errno in qemu_chr_write()

[Philippe Mathieu-Daudé]

On 22/10/25 17:07, Philippe Mathieu-Daudé wrote:
> qemu_chr_write() dispatches to ChardevClass::chr_write(),
> and is expected to propagate the backend error, not some
> unrelated one produce by "best effort" logfile or replay.
> Preserve and return the relevant %errno.
> 
> Cc: qemu-stable@nongnu.org

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

> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
>   chardev/char.c | 5 +++++
>   1 file changed, 5 insertions(+)
> 
> diff --git a/chardev/char.c b/chardev/char.c
> index 5c8130b2435..2af402d9855 100644
> --- a/chardev/char.c
> +++ b/chardev/char.c
> @@ -113,6 +113,7 @@ static int qemu_chr_write_buffer(Chardev *s,
>                                    int *offset, bool write_all)
>   {
>       ChardevClass *cc = CHARDEV_GET_CLASS(s);
> +    int saved_errno;
>       int res = 0;
>       *offset = 0;
>   
> @@ -138,6 +139,7 @@ static int qemu_chr_write_buffer(Chardev *s,
>               break;
>           }
>       }
> +    saved_errno = errno;
>       if (*offset > 0) {
>           /*
>            * If some data was written by backend, we should
> @@ -154,6 +156,7 @@ static int qemu_chr_write_buffer(Chardev *s,
>            */
>           qemu_chr_write_log(s, buf, len);
>       }
> +    errno = saved_errno;
>       qemu_mutex_unlock(&s->chr_write_lock);
>   
>       return res;
> @@ -186,7 +189,9 @@ int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all)
>       res = qemu_chr_write_buffer(s, buf, len, &offset, write_all);
>   
>       if (qemu_chr_replay(s) && replay_mode == REPLAY_MODE_RECORD) {
> +        int saved_errno = errno;
>           replay_char_write_event_save(res, offset);
> +        errno = saved_errno;
>       }
>   
>       if (res < 0 && offset == 0) {

Re: [PATCH v2 0/9] chardev: Improve @docstring and clarify qemu_chr_write() uses

[Philippe Mathieu-Daudé]

On 22/10/25 17:07, Philippe Mathieu-Daudé wrote:
> v2:
> - Document ChardevClass::chr_write() and qemu_chr_write[_all]()
> 
> Few chardev fixes:
> - preserve %errno
> - allow partial writes in qemu_chr_write()
> 
> Improve chardev methods documentation.

Sigh, this is still missing the qemu_chr_fe_write() @docstring
update requested by Peter:
https://lore.kernel.org/qemu-devel/CAFEAcA_kEndvNtw4EHySXWwQPoGs029yAzZGGBcV=zGHaj7KUQ@mail.gmail.com/

Re: [PATCH v2 3/9] chardev/char: Improve ChardevClass::chr_write() docstring

[Marc-André Lureau]

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 | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
>
> diff --git a/include/chardev/char.h b/include/chardev/char.h
> index b65e9981c14..d809bb316e9 100644
> --- a/include/chardev/char.h
> +++ b/include/chardev/char.h
> @@ -263,7 +263,16 @@ struct ChardevClass {
>      void (*open)(Chardev *chr, ChardevBackend *backend,
>                   bool *be_opened, Error **errp);
>
> -    /* write buf to the backend */
> +    /**
> +     * chr_write: Write data to a character backend
> +     * @s: the character backend to write to
> +     * @buf: the data to write
> +     * @len: the number of bytes to write
> +     *
> +     * Called with chr_write_lock held.
> +     *
> +     * Returns: the number of bytes consumed or -1 on error.

you could add that "errno" is expected to be set in that case.

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

> +     */
>      int (*chr_write)(Chardev *s, const uint8_t *buf, int len);
>
>      /*
> --
> 2.51.0
>
>


-- 
Marc-André Lureau

Re: [PATCH v2 4/9] chardev/char: Document qemu_chr_write[_all]()

[Marc-André Lureau]

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

Re: [PATCH v2 5/9] chardev/char-pty: Do not ignore chr_write() failures

[Marc-André Lureau]

Hi

On Wed, Oct 22, 2025 at 7:09 PM Philippe Mathieu-Daudé
<philmd@linaro.org> wrote:
>
> Cc: qemu-stable@nongnu.org
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
> If ignoring this is deliberate, this must be described in a comment
> to avoid any confusion.

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

This is from commit 4f7689f08 ("chardev/char-pty: Avoid losing bytes
when the other side just (re-)connected")

note: It's mildly annoying that the pty backend has still
!s->connected and we are writing. I wonder why the frontend is not
respecting the backend opened state, probably some race or buffering.


> ---
>  chardev/char-pty.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/chardev/char-pty.c b/chardev/char-pty.c
> index b066f014126..652b0bd9e73 100644
> --- a/chardev/char-pty.c
> +++ b/chardev/char-pty.c
> @@ -125,7 +125,7 @@ static int char_pty_chr_write(Chardev *chr, const uint8_t *buf, int len)
>      rc = RETRY_ON_EINTR(g_poll(&pfd, 1, 0));
>      g_assert(rc >= 0);
>      if (!(pfd.revents & G_IO_HUP) && (pfd.revents & G_IO_OUT)) {
> -        io_channel_send(s->ioc, buf, len);
> +        return io_channel_send(s->ioc, buf, len);
>      }
>
>      return len;
> --
> 2.51.0
>
>


-- 
Marc-André Lureau

Re: [PATCH v2 6/9] chardev/char: Allow partial writes in qemu_chr_write()

[Marc-André Lureau]

Hi

On Wed, Oct 22, 2025 at 7:10 PM Philippe Mathieu-Daudé
<philmd@linaro.org> wrote:
>
> If qemu_chr_write_buffer() returned an error, but could
> write some characters, return the number of character
> written. Otherwise frontends able to recover and resume
> writes re-write the partial chars already written.
>
> Cc: qemu-stable@nongnu.org
> Suggested-by: Alex Bennée <alex.bennee@linaro.org>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
>  chardev/char.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/chardev/char.c b/chardev/char.c
> index 30b21fedce4..5c8130b2435 100644
> --- a/chardev/char.c
> +++ b/chardev/char.c
> @@ -189,7 +189,7 @@ int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all)
>          replay_char_write_event_save(res, offset);
>      }
>
> -    if (res < 0) {
> +    if (res < 0 && offset == 0) {
>          return res;

If write_all==true, we should still return an error, I guess.


>      }
>      return offset;
> --
> 2.51.0
>
>


-- 
Marc-André Lureau

Re: [PATCH v2 7/9] chardev/char: Preserve %errno in qemu_chr_write()

[Marc-André Lureau]

Hi

On Wed, Oct 22, 2025 at 7:10 PM Philippe Mathieu-Daudé
<philmd@linaro.org> wrote:
>
> qemu_chr_write() dispatches to ChardevClass::chr_write(),
> and is expected to propagate the backend error, not some
> unrelated one produce by "best effort" logfile or replay.
> Preserve and return the relevant %errno.

Indeed.. imho we should avoid using errno, it's too easy to clutter.
Even qemu mutex, which may use trace, may change it...

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

>
> Cc: qemu-stable@nongnu.org
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
>  chardev/char.c | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/chardev/char.c b/chardev/char.c
> index 5c8130b2435..2af402d9855 100644
> --- a/chardev/char.c
> +++ b/chardev/char.c
> @@ -113,6 +113,7 @@ static int qemu_chr_write_buffer(Chardev *s,
>                                   int *offset, bool write_all)
>  {
>      ChardevClass *cc = CHARDEV_GET_CLASS(s);
> +    int saved_errno;
>      int res = 0;
>      *offset = 0;
>
> @@ -138,6 +139,7 @@ static int qemu_chr_write_buffer(Chardev *s,
>              break;
>          }
>      }
> +    saved_errno = errno;
>      if (*offset > 0) {
>          /*
>           * If some data was written by backend, we should
> @@ -154,6 +156,7 @@ static int qemu_chr_write_buffer(Chardev *s,
>           */
>          qemu_chr_write_log(s, buf, len);
>      }
> +    errno = saved_errno;
>      qemu_mutex_unlock(&s->chr_write_lock);
>
>      return res;
> @@ -186,7 +189,9 @@ int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all)
>      res = qemu_chr_write_buffer(s, buf, len, &offset, write_all);
>
>      if (qemu_chr_replay(s) && replay_mode == REPLAY_MODE_RECORD) {
> +        int saved_errno = errno;
>          replay_char_write_event_save(res, offset);
> +        errno = saved_errno;
>      }
>
>      if (res < 0 && offset == 0) {
> --
> 2.51.0
>
>


-- 
Marc-André Lureau

Re: [PATCH v2 8/9] chardev/char-hub: Retry when qemu_chr_fe_write() can not write

[Marc-André Lureau]

Hi

On Wed, Oct 22, 2025 at 7:10 PM Philippe Mathieu-Daudé
<philmd@linaro.org> wrote:
>
> When qemu_chr_fe_write() can not write to a backend and there
> is no error, it might return '0' to let the caller retry.
>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
> ---
>  chardev/char-hub.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/chardev/char-hub.c b/chardev/char-hub.c
> index d0967c22336..4bbde9fb033 100644
> --- a/chardev/char-hub.c
> +++ b/chardev/char-hub.c
> @@ -65,7 +65,7 @@ static int hub_chr_write(Chardev *chr, const uint8_t *buf, int len)
>              continue;
>          }
>          r = qemu_chr_fe_write(&d->backends[i].fe, buf, len);
> -        if (r < 0) {
> +        if (r <= 0) {

I don't think IO can return 0 and set errno. Can you detail a case?
thanks

>              if (errno == EAGAIN) {
>                  /* Set index and expect to be called soon on watch wake up */
>                  d->be_eagain_ind = i;
> --
> 2.51.0
>
>


-- 
Marc-André Lureau

Re: [PATCH v2 9/9] hw/char: Simplify when qemu_chr_fe_write() could not write

[Marc-André Lureau]

On Wed, Oct 22, 2025 at 7:10 PM Philippe Mathieu-Daudé
<philmd@linaro.org> wrote:
>
> If no chars were written, avoid to access the FIFO.
>
> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>

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

> ---
>  hw/char/cadence_uart.c | 2 +-
>  hw/char/ibex_uart.c    | 2 +-
>  hw/char/sifive_uart.c  | 2 +-
>  3 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/hw/char/cadence_uart.c b/hw/char/cadence_uart.c
> index 0dfa356b6d0..8908ebbe34a 100644
> --- a/hw/char/cadence_uart.c
> +++ b/hw/char/cadence_uart.c
> @@ -316,7 +316,7 @@ static gboolean cadence_uart_xmit(void *do_not_use, GIOCondition cond,
>
>      ret = qemu_chr_fe_write(&s->chr, s->tx_fifo, s->tx_count);
>
> -    if (ret >= 0) {
> +    if (ret > 0) {
>          s->tx_count -= ret;
>          memmove(s->tx_fifo, s->tx_fifo + ret, s->tx_count);
>      }
> diff --git a/hw/char/ibex_uart.c b/hw/char/ibex_uart.c
> index d6f0d18c777..b7843c7a741 100644
> --- a/hw/char/ibex_uart.c
> +++ b/hw/char/ibex_uart.c
> @@ -161,7 +161,7 @@ static gboolean ibex_uart_xmit(void *do_not_use, GIOCondition cond,
>
>      ret = qemu_chr_fe_write(&s->chr, s->tx_fifo, s->tx_level);
>
> -    if (ret >= 0) {
> +    if (ret > 0) {
>          s->tx_level -= ret;
>          memmove(s->tx_fifo, s->tx_fifo + ret, s->tx_level);
>      }
> diff --git a/hw/char/sifive_uart.c b/hw/char/sifive_uart.c
> index e7357d585a1..e5b381425a9 100644
> --- a/hw/char/sifive_uart.c
> +++ b/hw/char/sifive_uart.c
> @@ -83,7 +83,7 @@ static gboolean sifive_uart_xmit(void *do_not_use, GIOCondition cond,
>                                     fifo8_num_used(&s->tx_fifo), &numptr);
>      ret = qemu_chr_fe_write(&s->chr, characters, numptr);
>
> -    if (ret >= 0) {
> +    if (ret > 0) {
>          /* We wrote the data, actually pop the fifo */
>          fifo8_pop_bufptr(&s->tx_fifo, ret, NULL);
>      }
> --
> 2.51.0
>
>


-- 
Marc-André Lureau

Re: [PATCH v2 7/9] chardev/char: Preserve %errno in qemu_chr_write()

[Daniel P. Berrangé]

On Tue, Oct 28, 2025 at 06:00:33PM +0400, Marc-André Lureau wrote:
> Hi
> 
> On Wed, Oct 22, 2025 at 7:10 PM Philippe Mathieu-Daudé
> <philmd@linaro.org> wrote:
> >
> > qemu_chr_write() dispatches to ChardevClass::chr_write(),
> > and is expected to propagate the backend error, not some
> > unrelated one produce by "best effort" logfile or replay.
> > Preserve and return the relevant %errno.
> 
> Indeed.. imho we should avoid using errno, it's too easy to clutter.
> Even qemu mutex, which may use trace, may change it...
> 
> patch lgtm anyway
> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

Given you say 'qemu mutex, which may use trace, may change it...'
then surely this patch is broken....


> > @@ -154,6 +156,7 @@ static int qemu_chr_write_buffer(Chardev *s,
> >           */
> >          qemu_chr_write_log(s, buf, len);
> >      }
> > +    errno = saved_errno;
> >      qemu_mutex_unlock(&s->chr_write_lock);

^^^ This mutex_unlock call may clobber 'errno' that we've just tried
to restore.

> >
> >      return res;

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH v2 7/9] chardev/char: Preserve %errno in qemu_chr_write()

[Peter Maydell]

On Wed, 22 Oct 2025 at 16:14, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>
> On 22/10/25 17:07, Philippe Mathieu-Daudé wrote:
> > qemu_chr_write() dispatches to ChardevClass::chr_write(),
> > and is expected to propagate the backend error, not some
> > unrelated one produce by "best effort" logfile or replay.
> > Preserve and return the relevant %errno.
> >
> > Cc: qemu-stable@nongnu.org
>
> Suggested-by: Peter Maydell <peter.maydell@linaro.org>

...did I? I remember being confused by the errno usage
in these functions but I don't remember what I thought
was the best way to untangle it...

-- PMM