Re: [Qemu-devel] [PATCH qom-cpu] HACKING: Document vaddr type usage

[Peter Maydell]

On 22 July 2013 17:36, Andreas Färber <address@hidden> wrote:
> Signed-off-by: Andreas Färber <address@hidden>
> ---
>  HACKING | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/HACKING b/HACKING
> index e73ac79..d9dbb46 100644
> --- a/HACKING
> +++ b/HACKING
> @@ -42,6 +42,7 @@ ram_addr_t.
>
>  Use target_ulong (or abi_ulong) for CPU virtual addresses, however
>  devices should not need to use target_ulong.
> +Use vaddr for CPU virtual addresses in target-independent code.

Here's my suggestion for this paragraph (ie to replace
both the "Use target_ulong..." and "Use vaddr" sentences
above):

===begin===
For CPU virtual addresses there are several possible types.
vaddr is the best type to use to hold a CPU virtual address
in target-independent code, including most devices. It is
guaranteed to be large enough to hold a virtual address for
any target, and it does not change size from target to target.
It is always unsigned.
target_ulong is a type the size of a virtual address on the CPU;
this means it may be 32 or 64 bits depending on which target
is being built. It should therefore be used only in target
specific code, and in some performance-critical built-per-target
core code such as the TLB code. There is also a signed version,
target_long.
abi_ulong is for the *-user targets, and represents a type the
size of 'void *' in that target's ABI. (This may not be the same
as the size of a full CPU virtual address in the case of target
ABIs which use 32 bit pointers on 64 bit CPUs, like sparc32plus.)
Definitions of structures that must match the target's ABI
must use this type for anything that on the target is defined
to be an 'unsigned long' or a pointer type. There is also a
signed version, abi_long.
===endit===

(cc'ing Paolo to check I didn't mangle the abi_ulong/target_ulong
distinction.)

thanks
-- PMM