[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: RFC: Implementation of QMP documentation retrieval command
From: |
Stefan Hajnoczi |
Subject: |
Re: RFC: Implementation of QMP documentation retrieval command |
Date: |
Wed, 23 Jun 2021 09:44:31 +0100 |
On Wed, Jun 23, 2021 at 12:27:55AM +0530, Niteesh G. S. wrote:
> Hi Stefan,
> On Tue, Jun 22, 2021 at 3:05 PM Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> > On Mon, Jun 21, 2021 at 11:56:30PM +0530, Niteesh G. S. wrote:
> > > TLDR: The goal of this mail wasn't to review the dummy command I had
> > posted
> > > but
> > > rather start a discussion regarding the implementation of the QMP
> > > documentation
> > > retrieval command for the TUI.
> >
> > It's not clear to me what exactly you wanted to discuss. Here is the QMP
> > schema from the commit you linked. It's something concrete that we can
> > discuss:
> >
>
> I wanted to discuss the implementation of the documentation retrieval
> command. Things like
> 1) The JSON schema we will be using to represent the documentation.
This is similar to the question I asked about markup below.
> 2) How will we be parsing documentation from the JSON files under qemu/qapi?
> 3) How will/where we'll be storing this parsed information?
qapi/*.json files are processed when QEMU is built. The QAPI code
generator (scripts/qapi/) can be extended if necessary to generate
convenient output (e.g. C code containing an array of structs with the
QMP command documentation).
> And other questions which will have to be answered before proceeding to
> implement this command.
> 4) Where to get data for autocomplete for the TUI?
>
> - One easy way is to hardcode all available commands in the TUI
> autocomplete. But then we have to make sure to update the autocomplete
> list for TUI every time one new command gets added to QMP.
The query-qmp-schema QMP command provides the information needed for
autocompletion.
>
>
> ##
> > # @CommandDocumentation:
> > #
> > # A object representing documentation for a command.
> > #
> > # @name: Command name
> > #
> > # @doc: A string containing the documentation.
> >
> > Is @doc in some kind of markup or plain text?
> >
>
> Since this is just a prototype I have used plain text. But for the real
> command
> I expect something more structured since the comments I have seen in the
> QAPI schema has some structure associated with them.
> eg:
> ##
> # @query-status:
> #
> # Query the run status of all VCPUs
> #
> # Returns: @StatusInfo reflecting all VCPUs
> #
> # Since: 0.14
> #
> # Example:
> #
> # -> { "execute": "query-status" }
> # <- { "return": { "running": true,
> # "singlestep": false,
> # "status": "running" } }
> #
> ##
> We have the following structure
> 1) Command name
> 2) Documentation
> 3) Arguments (if any)
> 4) Return type with reference to non-primitive data types like
> structs/enums etc
> 5) Since
> 6) Example
>
> In the case of commands referring structures/enums and other non-primitive
> data types
> if possible we should also add their documentation along with the
> documentation
> for the command.
> Yes, we could find out all the data types referenced by the current command
> and
> add them to the documentation if possible. This will make it easy for the
> user.
> If it isn't possible then we must allow to also query documentation related
> to struct/enums etc.
>
> #
> > ##
> > { 'struct': 'CommandDocumentation',
> > 'data': {'name': 'str', 'doc': 'str'} }
> >
> > ##
> > # @query-cmd-doc:
> > #
> > # (A simple *prototype* implementation)
> > # Command query-cmd-doc will return the documentation for the command
> > # specified. This will help QMP clients currently the AQMP TUI to show
> > # documentation related to a specific command.
> > #
> > # @command-name: The command name to query documentation for
> > #
> > # Returns: A @CommandDocumentation object containing the documentation.
> > #
> > # Since: TODO: Add a number
> > ##
> > { 'command': 'query-cmd-doc',
> > 'data': { 'command-name': 'str' },
> > 'returns': 'CommandDocumentation' }
> >
> > Is there a way to retrieve struct/enum/etc documentation?
> >
> Not sure. I have gone through the parser code in qemu/scripts/qapi and also
> have
> seen the parser being used for documentation generation but I still don't
> understand
> the capabilities of the parser.
>
>
> > Do you see a need to query multiple items of documentation in a single
> > command? A single item query command can become a performance bottleneck
> > if the clients wants to query the documentation for all commands, for
> > example. This can be solved by making the the return value an array and
> > allowing multiple commands to be queried at once.
> >
> Why will clients want to query the documentation for all commands? Even if
> they do
> won't that be an infrequent operation?
> From the TUI perspective, I think it will be enough if we just have the
> capability to
> service one command at a time. We can also have the TUI cache the results
> and
> validate the cache during the greeting process by sending some kind of hash
> to
> notify if any documentation has changed or not.
Querying multiple commands is probably not necessary in the interactive
TUI use case. But if we're adding a new command it's nice to make it
general so it can be used for other things in the future.
That said, I don't have a strong opinion either way. I was just curious
if anyone can think of a reason to support multiple items in a single
query.
Stefan
signature.asc
Description: PGP signature