[Qemu-devel] [PATCH] include/qom/cpu.h: Add missing documentation for some CPUClass methods

[Qemu-devel] [PATCH] include/qom/cpu.h: Add missing documentation for some CPUClass methods

[Peter Maydell]

The CPUClass QOM methods virtio_is_big_endian, write_elf{32,64}_note
and write_elf{32,64}_qemunote were added without any description
being added to the doc comment. Correct this omission.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
More informative phrasings for the elf note callbacks welcome...

 include/qom/cpu.h | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/include/qom/cpu.h b/include/qom/cpu.h
index 2098f1c..f2d7de1 100644
--- a/include/qom/cpu.h
+++ b/include/qom/cpu.h
@@ -82,6 +82,10 @@ struct TranslationBlock;
  * @do_unassigned_access: Callback for unassigned access handling.
  * @do_unaligned_access: Callback for unaligned access handling, if
  * the target defines #ALIGNED_ONLY.
+ * @virtio_is_big_endian: Callback to return true if a CPU which supports
+ * runtime configurable endianness is currently big-endian. Non-configurable
+ * CPUs can use the default implementation of this method. This method should
+ * not be used by any callers other than the pre-1.0 virtio devices.
  * @memory_rw_debug: Callback for GDB memory access.
  * @dump_state: Callback for dumping state.
  * @dump_statistics: Callback for dumping statistics.
@@ -96,6 +100,14 @@ struct TranslationBlock;
  * @gdb_read_register: Callback for letting GDB read a register.
  * @gdb_write_register: Callback for letting GDB write a register.
  * @debug_excp_handler: Callback for handling debug exceptions.
+ * @write_elf64_note: Callback for writing a CPU-specific ELF note to a
+ * 64-bit VM coredump.
+ * @write_elf32_qemunote: Callback for writing a CPU- and QEMU-specific ELF
+ * note to a 32 bit VM coredump.
+ * @write_elf32_note: Callback for writing a CPU-specific ELF note to a
+ * 32-bit VM coredump.
+ * @write_elf32_qemunote: Callback for writing a CPU- and QEMU-specific ELF
+ * note to a 32 bit VM coredump.
  * @vmsd: State description for migration.
  * @gdb_num_core_regs: Number of core registers accessible to GDB.
  * @gdb_core_xml_file: File name for core registers GDB XML description.
-- 
1.9.1

Re: [Qemu-devel] [PATCH] include/qom/cpu.h: Add missing documentation for some CPUClass methods

[Greg Kurz]

On Mon,  5 Jan 2015 14:23:32 +0000
Peter Maydell <peter.maydell@linaro.org> wrote:

> The CPUClass QOM methods virtio_is_big_endian, write_elf{32,64}_note
> and write_elf{32,64}_qemunote were added without any description
> being added to the doc comment. Correct this omission.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---

Thanks for this accurate description of virtio_is_big_endian.

Acked-by: Greg Kurz <gkurz@linux.vnet.ibm.com>

> More informative phrasings for the elf note callbacks welcome...
> 
>  include/qom/cpu.h | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/include/qom/cpu.h b/include/qom/cpu.h
> index 2098f1c..f2d7de1 100644
> --- a/include/qom/cpu.h
> +++ b/include/qom/cpu.h
> @@ -82,6 +82,10 @@ struct TranslationBlock;
>   * @do_unassigned_access: Callback for unassigned access handling.
>   * @do_unaligned_access: Callback for unaligned access handling, if
>   * the target defines #ALIGNED_ONLY.
> + * @virtio_is_big_endian: Callback to return true if a CPU which supports
> + * runtime configurable endianness is currently big-endian. Non-configurable
> + * CPUs can use the default implementation of this method. This method should
> + * not be used by any callers other than the pre-1.0 virtio devices.
>   * @memory_rw_debug: Callback for GDB memory access.
>   * @dump_state: Callback for dumping state.
>   * @dump_statistics: Callback for dumping statistics.
> @@ -96,6 +100,14 @@ struct TranslationBlock;
>   * @gdb_read_register: Callback for letting GDB read a register.
>   * @gdb_write_register: Callback for letting GDB write a register.
>   * @debug_excp_handler: Callback for handling debug exceptions.
> + * @write_elf64_note: Callback for writing a CPU-specific ELF note to a
> + * 64-bit VM coredump.
> + * @write_elf32_qemunote: Callback for writing a CPU- and QEMU-specific ELF
> + * note to a 32 bit VM coredump.
> + * @write_elf32_note: Callback for writing a CPU-specific ELF note to a
> + * 32-bit VM coredump.
> + * @write_elf32_qemunote: Callback for writing a CPU- and QEMU-specific ELF
> + * note to a 32 bit VM coredump.
>   * @vmsd: State description for migration.
>   * @gdb_num_core_regs: Number of core registers accessible to GDB.
>   * @gdb_core_xml_file: File name for core registers GDB XML description.

Re: [Qemu-devel] [PATCH] include/qom/cpu.h: Add missing documentation for some CPUClass methods

[Andreas Färber]

Hi,

Am 05.01.2015 um 20:54 schrieb Greg Kurz:
> On Mon,  5 Jan 2015 14:23:32 +0000
> Peter Maydell <peter.maydell@linaro.org> wrote:
> 
>> The CPUClass QOM methods virtio_is_big_endian, write_elf{32,64}_note
>> and write_elf{32,64}_qemunote were added without any description
>> being added to the doc comment. Correct this omission.
>>
>> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>> ---
> 
> Thanks for this accurate description of virtio_is_big_endian.
> 
> Acked-by: Greg Kurz <gkurz@linux.vnet.ibm.com>
> 
>> More informative phrasings for the elf note callbacks welcome...
>>
>>  include/qom/cpu.h | 12 ++++++++++++
>>  1 file changed, 12 insertions(+)
>>
>> diff --git a/include/qom/cpu.h b/include/qom/cpu.h
>> index 2098f1c..f2d7de1 100644
>> --- a/include/qom/cpu.h
>> +++ b/include/qom/cpu.h
>> @@ -82,6 +82,10 @@ struct TranslationBlock;
>>   * @do_unassigned_access: Callback for unassigned access handling.
>>   * @do_unaligned_access: Callback for unaligned access handling, if
>>   * the target defines #ALIGNED_ONLY.
>> + * @virtio_is_big_endian: Callback to return true if a CPU which supports

%true

>> + * runtime configurable endianness is currently big-endian. Non-configurable
>> + * CPUs can use the default implementation of this method. This method should
>> + * not be used by any callers other than the pre-1.0 virtio devices.
>>   * @memory_rw_debug: Callback for GDB memory access.
>>   * @dump_state: Callback for dumping state.
>>   * @dump_statistics: Callback for dumping statistics.
>> @@ -96,6 +100,14 @@ struct TranslationBlock;
>>   * @gdb_read_register: Callback for letting GDB read a register.
>>   * @gdb_write_register: Callback for letting GDB write a register.
>>   * @debug_excp_handler: Callback for handling debug exceptions.
>> + * @write_elf64_note: Callback for writing a CPU-specific ELF note to a
>> + * 64-bit VM coredump.
>> + * @write_elf32_qemunote: Callback for writing a CPU- and QEMU-specific ELF
>> + * note to a 32 bit VM coredump.
>> + * @write_elf32_note: Callback for writing a CPU-specific ELF note to a
>> + * 32-bit VM coredump.
>> + * @write_elf32_qemunote: Callback for writing a CPU- and QEMU-specific ELF
>> + * note to a 32 bit VM coredump.

Let's consistently use "32-bit". :)

>>   * @vmsd: State description for migration.
>>   * @gdb_num_core_regs: Number of core registers accessible to GDB.
>>   * @gdb_core_xml_file: File name for core registers GDB XML description.

Thanks, applied to qom-cpu with those changes:
https://github.com/afaerber/qemu-cpu/commits/qom-cpu

Regards,
Andreas

-- 
SUSE Linux GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
Graham Norton; HRB 21284 (AG Nürnberg)