[PATCH v2] LangRef: clarify that va_arg doesn't work on x86_64

[Tim Northover]

Hi again,

> The example in LangRef actually crashes on my x86_64 machine, and this
> is the problem I'm trying to fix for others.

It works for me, with both Linux and OS X triples. What platform are
you on and what version of LLVM?

> Should we replace it with a working example on x86_64 like:

I don't think we should, it adds more obfuscating target-specific
detail. Maybe add a target triple to the example, if we really want it
to run with no extra effort?

> If the user tries to read anything other than a builtin type, LLVM
> will error out. Are we okay with a minimal working example?

What do you mean here? I'm personally OK with an example that works,
but goes wrong in more complicated cases. It's the nature of va_arg on
x86_64.

> Do you mean that the va_list on those platforms is something other
> than i8**, but the varargs mechanism exposes a pseudo i8** interface?

That gets into weird and wonderful platform ABIs. Briefly: ARM is
i8**; AArch64 (Darwin) is i8**; AArch64 (elsewhere) is similar to the
x86_64 system, va_arg will assert since it's written for Darwin; x86
is i8** as far as I'm aware; x86_64 is a struct but appears to pretend
to be an i8** (in reality it probably doesn't matter).

> True, but wouldn't it be nice to support the common cases for people
> starting out?

Possibly (which I think we do). The risk is that it'll bit-rot if it's
unused, and get edge cases wrong even without the bit-rot.

> In any case, it would be nice to have the vaarg intricacies of x86_64
> documented somewhere (like "look in the other i8* if reading over 40
> bits").

http://www.x86-64.org/documentation/abi.pdf documents what's needed.
I'm not sure we could add much to that except some kind of tutorial on
how to implement generic C in LLVM IR.

Cheers.

Tim.