Re: [Qemu-devel] [PATCH v2] docs/devel/loads-stores.rst: Document our various load and store APIs

[Eric Blake <eblake@redhat.com>]

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

On 09/21/2017 12:29 PM, Peter Maydell wrote:
> QEMU has a wide selection of different functions for doing
> loads and stores; provide some overview documentation of
> what they do and how to pick which one to use.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> Changes v1->v2: filled in most of the gaps thanks to the
> comments on v1.
> 
> I have left some TODO markers in where they represent
> fixes we should ideally make to the API. Since this
> is for-developers internals documentation I think it's
> OK to leave those in.
> 
> I found I was referring back to my v1 patch and the replies
> to it quite a bit recently, so I think it would be nice to
> get it into the tree.
> 
> The major question I have left is about the license text
> to apply to this...

> +   Copyright (c) 2017 Linaro Limited
> +   Written by Peter Maydell
> +   TODO: do we have a standard doc license? bitmaps.rst
> +   uses the FreeBSD documentation license, I notice.

The default GPLv2+ seems okay to me for something for internal use, but
of course, if you want something looser like FreeBSD docs, I'm also fine
with that (as it's not the first use in the tree).

> +
> +===================
> +Load and Store APIs
> +===================
> +
> +QEMU internally has multiple families of functions for performing
> +loads and stores. This document attempts to enumerate them all
> +and indicate when to use them. It does not provide detailed
> +documentation of each API -- for that you should look at the
> +documentation comments in the relevant header files.
> +
> +
> +``ld*_p and st_*p``

Difference in placement of * vs. _ - is it intentional?

> +
> +``cpu_{ld,st}_*``
> +~~~~~~~~~~~~~~~~~
> +
> +These functions operate on a guest virtual address. Be aware
> +that these functions may cause a guest CPU exception to be
> +taken (eg for an alignment fault or MMU fault) which will

Do we care about the formal spelling "e.g." ?

> +
> +``cpu_{ld,st}_*_ra``
> +~~~~~~~~~~~~~~~~~~~~
> +
> +Thes functions work like the ``cpu_{ld,st}_*`` functions except

s/Thes/These/

> +that they also take a ``retaddr`` argument. This extra argument
> +allows for correct unwinding of any exception that is taken,
> +and should generally be the result of GETPC() called directly
> +from the top level HELPER(foo) function (ie the return address

Again, is "i.e." better?

> +
> +``helper_*_{ld,st}*mmu``
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +

> +
> +``address_space_*``
> +~~~~~~~~~~~~~~~~~~~
> +

> +
> +``{ld,st}*_phys``
> +~~~~~~~~~~~~~~~~~

> +
> +``cpu_physical_memory_*``
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +

> +``cpu_physical_memory_write_rom``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +

> +
> +``cpu_memory_rw_debug``
> +~~~~~~~~~~~~~~~~~~~~~~~
> +

> +
> +``dma_memory_*``
> +~~~~~~~~~~~~~~~~
> +

> +``pci_dma_*`` and ``{ld,st}*_pci_dma``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +

Lots of cool stuff in there!

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]