Re: [RFC v9 18/32] cpu: Move synchronize_from_tb() to tcg_ops

[Alex Bennée]

Eduardo Habkost <ehabkost@redhat.com> writes:

> On Wed, Dec 09, 2020 at 10:50:29AM +0000, Alex Bennée wrote:
>> 
>> Claudio Fontana <cfontana@suse.de> writes:
>> 
>> > From: Eduardo Habkost <ehabkost@redhat.com>
>> >
>> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
>> > [claudio: wrapped in CONFIG_TCG]
>> > Signed-off-by: Claudio Fontana <cfontana@suse.de>
>> > Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
>> > ---
> [...]
>> > @@ -20,6 +17,17 @@ typedef struct TcgCpuOperations {
>> >       * Called when the first CPU is realized.
>> >       */
>> >      void (*initialize)(void);
>> > +    /**
>> > +     * @synchronize_from_tb: Synchronize state from a TCG 
>> > #TranslationBlock
>> > +     *
>> > +     * This is called when we abandon execution of a TB before
>> > +     * starting it, and must set all parts of the CPU state which
>> > +     * the previous TB in the chain may not have updated. This
>> > +     * will need to do more. If this hook is not implemented then
>> > +     * the default is to call
>> > +     * @set_pc(tb->pc).
>> > +     */
>> 
>> We could clean-up the comment here to better fit the javadoc style API
>> documentation format, i.e.:
>> 
>>     /**
>>      * synchronize_from_tb: Synchronize current TCG execution state
>>      * @cpu: current cpu
>>      * @tb: about to be executed #TranslationBlock
>>      *
>>      * This is called when we abandon execution of a TB before
>>      * starting it, and must set all parts of the CPU state which
>>      * the previous TB in the chain may not have updated. This
>>      * will need to do more. If this hook is not implemented then
>>      * the default is to call @set_pc(tb->pc).
>>      */
>
> Would this work with kernel-doc?  This will be parsed as a
> portion of the documentation of struct TcgCpuOperations, so I was
> not expecting kernel-doc to treat the "@cpu: ..." and "@tb: ..."
> lines as valid.

Hmm looking at the guides it seems they wouldn't be processed:

  
https://www.kernel.org/doc/html/v4.18/doc-guide/kernel-doc.html#structure-union-and-enumeration-documentation

I must admit I had previously just used exec-all.h as my template for
what a well formed function document comment is meant to look like. It
seems for it to work properly you need to use function pointer typedefs
and document those.

However looking at which headers we convert into docs at the moment this
is all moot as we don't process these headers at the moment. IOW ignore
this request ;-)

-- 
Alex Bennée