[llvm-commits] [llvm] r49065 - /llvm/trunk/docs/LangRef.html

[Dan Gohman]

On Apr 1, 2008, at 5:38 PM, Chris Lattner wrote:
> @@ -2787,7 +2787,7 @@
> bytes of memory from the operating system and returns a pointer of the
> appropriate type to the program.  If "NumElements" is specified, it  
> is the
> number of elements allocated, otherwise "NumElements" is defaulted  
> to be one.
> -If an alignment is specified, the value result of the allocation is  
> guaranteed to
> +If a constant alignment is specified, the value result of the  
> allocation is guaranteed to
> be aligned to at least that boundary.  If not specified, or if zero,  
> the target can
> choose to align the allocation on any convenient boundary.</p>

This new wording makes the text a little ambiguous. How about
mentioning the requirement that the value be constant in a
separate sentance?
"The alignment must be a constant integer."

>
>
> @@ -2796,7 +2796,8 @@
> <h5>Semantics:</h5>
>
> <p>Memory is allocated using the system "<tt>malloc</tt>" function,  
> and
> -a pointer is returned.</p>
> +a pointer is returned.  Allocating zero bytes is undefined.  The  
> result is null
> +if there is insufficient memory available.</p>

Allocating zero bytes with malloc is defined in ISO C. Having LLVM
differ from ISO C here breaks -raiseallocs, among other things.

>
>
> <h5>Example:</h5>
>
> @@ -2838,7 +2839,8 @@
> <h5>Semantics:</h5>
>
> <p>Access to the memory pointed to by the pointer is no longer defined
> -after this instruction executes.</p>
> +after this instruction executes.  If the pointer is null, the  
> result is
> +undefined.</p>

Similar to above, calling free on a null pointer is well defined
in ISO C, and it's problematic for LLVM to diverge in this area.

> <h5>Example:</h5>
>
> @@ -2874,7 +2876,7 @@
> bytes of memory on the runtime stack, returning a pointer of the
> appropriate type to the program.  If "NumElements" is specified, it  
> is the
> number of elements allocated, otherwise "NumElements" is defaulted  
> to be one.
> -If an alignment is specified, the value result of the allocation is  
> guaranteed
> +If a constant alignment is specified, the value result of the  
> allocation is guaranteed
> to be aligned to at least that boundary.  If not specified, or if  
> zero, the target
> can choose to align the allocation on any convenient boundary.</p>

Ambiguous; see above.

>
>
> @@ -2887,7 +2889,8 @@
> instruction is commonly used to represent automatic variables that  
> must
> have an address available.  When the function returns (either with  
> the <tt><a
>  href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
> -instructions), the memory is reclaimed.</p>
> +instructions), the memory is reclaimed.  Allocating zero bytes
> +is legal, but the result is undefined.</p>

What does "legal" here mean, especially when paired with an undefined
result?

Also, is it really desirable to have alloca(0) be undefined?

>
> (that is, the alignment of the memory address). A value of 0 or an
> omitted "align" argument means that the operation has the preferential
> alignment for the target. It is the responsibility of the code emitter
> @@ -2947,13 +2950,14 @@
> <h5>Arguments:</h5>
> <p>There are two arguments to the '<tt>store</tt>' instruction: a  
> value
> to store and an address at which to store it.  The type of the  
> '<tt><pointer></tt>'
> -operand must be a pointer to the type of the '<tt><value></tt>'
> +operand must be a pointer to the <a href="#t_firstclass">first  
> class</a> type
> +of the '<tt><value></tt>'

How about:
   "... must be a pointer to the type of the value, which must be a
    first class type."
?

Dan