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

[Peter Maydell]

On 21 September 2017 at 20:17, Eric Blake <address@hidden> wrote:
> 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 <address@hidden>
>> ---
>> 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).

I was wondering how GPLv2+ would work with things like the
"readthedocs" website -- if we used that for providing a
nice rendering of the documentation does it get awkward
license-wise?

But yes, just not saying anything and going with our
default is probably simplest.

>> +
>> +===================
>> +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?

No, it should be st*_p. (If in doubt, trust the regexs;
I tested them all.)

>> +
>> +``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." ?

I don't personally, tending to the BBC and Guardian style
guide recommended approach of using no punctuation:
https://www.theguardian.com/guardian-observer-style-guide-e
http://www.bbc.co.uk/academy/journalism/article/art20130716140724183

but grep suggests that 'e.g.' is the much more common
style in docs/ so I guess we should follow that
for consistency.

thanks
-- PMM