[v2] chardev: Improve @docstring and clarify qemu_chr_write() uses

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

Posted by Philippe Mathieu-Daudé 3 weeks, 2 days ago

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

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

Posted by Marc-André Lureau 2 weeks, 3 days ago

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