Re: RFC: Implementation of QMP documentation retrieval command

[Stefan Hajnoczi <stefanha@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 5496 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]