qemu-s390x
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH v2 01/53] docs/devel: rename file for writing monitor command


From: Markus Armbruster
Subject: Re: [PATCH v2 01/53] docs/devel: rename file for writing monitor commands
Date: Mon, 20 Sep 2021 09:42:02 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux)

Daniel P. Berrangé <berrange@redhat.com> writes:

> The file already covers writing new style HMP commands, in addition to
> the QMP commands, so it deserves a more general name.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  docs/devel/index.rst                                        | 2 +-
>  ...riting-qmp-commands.rst => writing-monitor-commands.rst} | 6 +++---
>  2 files changed, 4 insertions(+), 4 deletions(-)
>  rename docs/devel/{writing-qmp-commands.rst => writing-monitor-commands.rst} 
> (99%)
>
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index f95df10b3e..7c25177c5d 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -44,4 +44,4 @@ modifying QEMU's source code.
>     ebpf_rss
>     vfio-migration
>     qapi-code-gen
> -   writing-qmp-commands
> +   writing-monitor-commands
> diff --git a/docs/devel/writing-qmp-commands.rst 
> b/docs/devel/writing-monitor-commands.rst
> similarity index 99%
> rename from docs/devel/writing-qmp-commands.rst
> rename to docs/devel/writing-monitor-commands.rst
> index 6a10a06c48..497c9ce0d5 100644
> --- a/docs/devel/writing-qmp-commands.rst
> +++ b/docs/devel/writing-monitor-commands.rst
> @@ -1,8 +1,8 @@
> -How to write QMP commands using the QAPI framework
> -==================================================
> +How to write monitor commands
> +=============================
>  
>  This document is a step-by-step guide on how to write new QMP commands using
> -the QAPI framework. It also shows how to implement new style HMP commands.
> +the QAPI framework and new style HMP commands.

Recommend to drop "new style", here and in the commit message.

Back when this file was written, we did have several "styles" of HMP
commands:

    typedef struct mon_cmd_t {
        const char *name;
        const char *args_type;
        const char *params;
        const char *help;
        void (*user_print)(Monitor *mon, const QObject *data);
        union {
            void (*info)(Monitor *mon);
            void (*cmd)(Monitor *mon, const QDict *qdict);
            int  (*cmd_new)(Monitor *mon, const QDict *params, QObject 
**ret_data);
            int  (*cmd_async)(Monitor *mon, const QDict *params,
                              MonitorCompletion *cb, void *opaque);
        } mhandler;
        bool qapi;
        int flags;
    } mon_cmd_t;
    [...]
    static void handle_user_command(Monitor *mon, const char *cmdline)
    {
        QDict *qdict;
        const mon_cmd_t *cmd;

        qdict = qdict_new();

        cmd = monitor_parse_command(mon, cmdline, qdict);
        if (!cmd)
            goto out;

        if (handler_is_async(cmd)) {
            user_async_cmd_handler(mon, cmd, qdict);
        } else if (handler_is_qobject(cmd)) {
            QObject *data = NULL;

            /* XXX: ignores the error code */
            cmd->mhandler.cmd_new(mon, qdict, &data);
            assert(!monitor_has_error(mon));
            if (data) {
                cmd->user_print(mon, data);
                qobject_decref(data);
            }
        } else {
            cmd->mhandler.cmd(mon, qdict);
        }

    out:
        QDECREF(qdict);
    }

Async: add MONITOR_CMD_ASYNC to ->flags, use ->mhandler.async().

New: set ->user_print and ->mhandler.cmd_new.

Old: keep ->user_print() null, and set ->mhandler.cmd().

"Async" style never really worked, and was buried in commit 65207c59d9
"monitor: Drop broken, unused asynchronous command interface".

"New" style was buried in commit 8a4f501c09 "monitor: Drop unused "new"
HMP command interface".

Both burials got merged into master in June 2015.  "Old" style has been
the only style since then.

>  This document doesn't discuss QMP protocol level details, nor does it dive
>  into the QAPI framework implementation.




reply via email to

[Prev in Thread] Current Thread [Next in Thread]