From: "Michael S. Tsirkin" <mst@redhat.com>
To: "Philippe Mathieu-Daudé" <philmd@redhat.com>
Cc: qemu-devel@nongnu.org,
Marcel Apfelbaum <marcel.apfelbaum@gmail.com>,
Richard Henderson <rth@twiddle.net>,
Rob Bradford <robert.bradford@intel.com>,
Eduardo Habkost <ehabkost@redhat.com>,
kvm@vger.kernel.org, Marcelo Tosatti <mtosatti@redhat.com>,
Samuel Ortiz <sameo@linux.intel.com>,
Yang Zhong <yang.zhong@intel.com>,
Paolo Bonzini <pbonzini@redhat.com>
Subject: Re: [PATCH v2 05/20] hw/i386/pc: Add documentation to the e820_*() functions
Date: Thu, 20 Jun 2019 11:36:50 -0400 [thread overview]
Message-ID: <20190620113132-mutt-send-email-mst@kernel.org> (raw)
In-Reply-To: <20190613143446.23937-6-philmd@redhat.com>
On Thu, Jun 13, 2019 at 04:34:31PM +0200, Philippe Mathieu-Daudé wrote:
> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> ---
> include/hw/i386/pc.h | 37 +++++++++++++++++++++++++++++++++++--
> 1 file changed, 35 insertions(+), 2 deletions(-)
>
> diff --git a/include/hw/i386/pc.h b/include/hw/i386/pc.h
> index 7c07185dd5..fc66b61ff8 100644
> --- a/include/hw/i386/pc.h
> +++ b/include/hw/i386/pc.h
> @@ -293,9 +293,42 @@ typedef enum {
> E820_UNUSABLE = 5
> } E820Type;
>
> -ssize_t e820_add_entry(uint64_t, uint64_t, uint32_t);
> +/**
> + * e820_add_entry: Add an #e820_entry to the @e820_table.
> + *
> + * Returns the number of entries of the e820_table on success,
> + * or a negative errno otherwise.
> + *
> + * @address: The base address of the structure which the BIOS is to fill in.
> + * @length: The length in bytes of the structure passed to the BIOS.
> + * @type: The #E820Type of the address range.
> + */
> +ssize_t e820_add_entry(uint64_t address, uint64_t length, E820Type type);
> +
> +/**
> + * e820_get_num_entries: The number of entries of the @e820_table.
> + *
> + * Returns the number of entries of the e820_table.
> + */
> size_t e820_get_num_entries(void);
> -bool e820_get_entry(unsigned int, uint32_t, uint64_t *, uint64_t *);
> +
> +/**
> + * e820_get_entry: Get the address/length of an #e820_entry.
> + *
> + * If the #e820_entry stored at @index is of #E820Type @type, fills @address
> + * and @length with the #e820_entry values and return @true.
> + * Return @false otherwise.
> + *
> + * @index: The index of the #e820_entry to get values.
> + * @type: The @E820Type of the address range expected.
> + * @address: Pointer to the base address of the #e820_entry structure to
> + * be filled.
> + * @length: Pointer to the length (in bytes) of the #e820_entry structure
> + * to be filled.
> + * @return: true if the entry was found, false otherwise.
I don't actually care whether it's @E820Type, #E820Type or just type,
we should be consistent. I also find this style of documentation
underwhelming. what is to be filled? length or the structure?
upper case after : also looks somewhat wrong.
Same applies to other comments too.
> + */
> +bool e820_get_entry(unsigned int index, E820Type type,
> + uint64_t *address, uint64_t *length);
>
> extern GlobalProperty pc_compat_4_0_1[];
> extern const size_t pc_compat_4_0_1_len;
> --
> 2.20.1
next prev parent reply other threads:[~2019-06-20 15:36 UTC|newest]
Thread overview: 29+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-06-13 14:34 [PATCH v2 00/20] hw/i386/pc: Do not restrict the fw_cfg functions to the PC machine Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 01/20] hw/i386/pc: Use unsigned type to index arrays Philippe Mathieu-Daudé
2019-06-20 15:27 ` Michael S. Tsirkin
2019-06-21 14:44 ` Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 02/20] hw/i386/pc: Use size_t type to hold/return a size of array Philippe Mathieu-Daudé
2019-06-20 15:28 ` Michael S. Tsirkin
2019-06-21 14:46 ` Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 03/20] hw/i386/pc: Let e820_add_entry() return a ssize_t type Philippe Mathieu-Daudé
2019-06-20 15:29 ` Michael S. Tsirkin
2019-06-13 14:34 ` [PATCH v2 04/20] hw/i386/pc: Add the E820Type enum type Philippe Mathieu-Daudé
2019-06-20 15:31 ` Michael S. Tsirkin
2019-06-21 14:48 ` Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 05/20] hw/i386/pc: Add documentation to the e820_*() functions Philippe Mathieu-Daudé
2019-06-20 15:36 ` Michael S. Tsirkin [this message]
2019-06-13 14:34 ` [PATCH v2 06/20] hw/i386/pc: Use e820_get_num_entries() to access e820_entries Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 07/20] hw/i386/pc: Extract e820 memory layout code Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 08/20] hw/i386/pc: Use address_space_memory in place Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 09/20] hw/i386/pc: Rename bochs_bios_init as more generic fw_cfg_arch_create Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 10/20] hw/i386/pc: Pass the boot_cpus value by argument Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 11/20] hw/i386/pc: Pass the apic_id_limit " Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 12/20] hw/i386/pc: Pass the CPUArchIdList array " Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 13/20] hw/i386/pc: Let fw_cfg_init() use the generic MachineState Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 14/20] hw/i386/pc: Let pc_build_smbios() take a FWCfgState argument Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 15/20] hw/i386/pc: Let pc_build_smbios() take a generic MachineState argument Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 16/20] hw/i386/pc: Rename pc_build_smbios() as generic fw_cfg_build_smbios() Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 17/20] hw/i386/pc: Let pc_build_feature_control() take a FWCfgState argument Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 18/20] hw/i386/pc: Let pc_build_feature_control() take a MachineState argument Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 19/20] hw/i386/pc: Rename pc_build_feature_control() as generic fw_cfg_build_* Philippe Mathieu-Daudé
2019-06-13 14:34 ` [PATCH v2 20/20] hw/i386/pc: Extract the x86 generic fw_cfg code Philippe Mathieu-Daudé
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190620113132-mutt-send-email-mst@kernel.org \
--to=mst@redhat.com \
--cc=ehabkost@redhat.com \
--cc=kvm@vger.kernel.org \
--cc=marcel.apfelbaum@gmail.com \
--cc=mtosatti@redhat.com \
--cc=pbonzini@redhat.com \
--cc=philmd@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=robert.bradford@intel.com \
--cc=rth@twiddle.net \
--cc=sameo@linux.intel.com \
--cc=yang.zhong@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).