Index: docs/LangRef.rst =================================================================== --- docs/LangRef.rst +++ docs/LangRef.rst @@ -1048,7 +1048,7 @@ When the call site is reached, the argument allocation must have been the most recent stack allocation that is still live, or the - results are undefined. It is possible to allocate additional stack + behavior is undefined. It is possible to allocate additional stack space after an argument allocation and before its call site, but it must be cleared off with :ref:`llvm.stackrestore `. @@ -1122,12 +1122,13 @@ ``nonnull`` This indicates that the parameter or return pointer is not null. This attribute may only be applied to pointer typed parameters. This is not - checked or enforced by LLVM, the caller must ensure that the pointer - passed in is non-null, or the callee must ensure that the returned pointer - is non-null. + checked or enforced by LLVM; if the parameter or return pointer is null, + the behavior is undefined. ``dereferenceable()`` - This indicates that the parameter or return pointer is dereferenceable. This + This indicates that the parameter or return pointer is dereferenceable for + the duration of the function. If the pointer cannot be dereferenced at any + point in the function, the behavior is undefined. This attribute may only be applied to pointer typed parameters. A pointer that is dereferenceable can be loaded from speculatively without a risk of trapping. The number of bytes known to be dereferenceable must be provided @@ -1387,11 +1388,13 @@ ``inaccessiblememonly`` This attribute indicates that the function may only access memory that is not accessible by the module being compiled. This is a weaker form - of ``readnone``. + of ``readnone``. If the function reads or writes other memory, the + behavior is undefined. ``inaccessiblemem_or_argmemonly`` This attribute indicates that the function may only access memory that is either not accessible by the module being compiled, or is pointed to - by its pointer arguments. This is a weaker form of ``argmemonly`` + by its pointer arguments. This is a weaker form of ``argmemonly``. If the + function reads or writes other memory, the behavior is undefined. ``inlinehint`` This attribute indicates that the source code contained a hint that inlining this function is desirable (such as the "inline" keyword in @@ -1534,6 +1537,10 @@ On an argument, this attribute indicates that the function does not dereference that pointer argument, even though it may read or write the memory that the pointer points to if accessed through other pointers. + + If a readnone function reads or writes memory visible to the program, or + has other side-effects, the behavior is undefined. If a function reads from + or writes to a readnone pointer argument, the behavior is undefined. ``readonly`` On a function, this attribute indicates that the function does not write through any pointer arguments (including ``byval`` arguments) or otherwise @@ -1549,6 +1556,10 @@ On an argument, this attribute indicates that the function does not write through this pointer argument, even though it may write to the memory that the pointer points to. + + If a readonly function writes memory visible to the program, or + has other side-effects, the behavior is undefined. If a function writes to + a readonly pointer argument, the behavior is undefined. ``"stack-probe-size"`` This attribute controls the behavior of stack probes: either the ``"probe-stack"`` attribute, or ABI-required stack probes, if any. @@ -1573,14 +1584,22 @@ On an argument, this attribute indicates that the function may write to but does not read through this pointer argument (even though it may read from the memory that the pointer points to). + + If a readonly function reads memory visible to the program, or + has other side-effects, the behavior is undefined. If a function uses a + value read from a writeonly pointer argument, the behavior is undefined. ``argmemonly`` This attribute indicates that the only memory accesses inside function are loads and stores from objects pointed to by its pointer-typed arguments, with arbitrary offsets. Or in other words, all memory operations in the function can refer to memory only using pointers based on its function arguments. + Note that ``argmemonly`` can be used together with ``readonly`` attribute in order to specify that function reads only from its arguments. + + If an argmemonly function reads or writes memory other than the pointer + arguments, or has other side-effects, the behavior is undefined. ``returns_twice`` This attribute indicates that this function can return twice. The C ``setjmp`` is an example of such a function. The compiler disables @@ -2343,12 +2362,12 @@ ``nnan`` No NaNs - Allow optimizations to assume the arguments and result are not NaN. Such optimizations are required to retain defined behavior over - NaNs, but the value of the result is undefined. + NaNs, but the value of the result is unspecified. ``ninf`` No Infs - Allow optimizations to assume the arguments and result are not +/-Inf. Such optimizations are required to retain defined behavior over - +/-Inf, but the value of the result is undefined. + +/-Inf, but the value of the result is unspecified. ``nsz`` No Signed Zeros - Allow optimizations to treat the sign of a zero @@ -3275,25 +3294,25 @@ integer constant. TYPE must be a scalar or vector integer type. CST must be of scalar or vector floating-point type. Both CST and TYPE must be scalars, or vectors of the same number of elements. If the - value won't fit in the integer type, the results are undefined. + value won't fit in the integer type, the result is ``undef``. ``fptosi (CST to TYPE)`` Convert a floating-point constant to the corresponding signed integer constant. TYPE must be a scalar or vector integer type. CST must be of scalar or vector floating-point type. Both CST and TYPE must be scalars, or vectors of the same number of elements. If the - value won't fit in the integer type, the results are undefined. + value won't fit in the integer type, the result is ``undef``. ``uitofp (CST to TYPE)`` Convert an unsigned integer constant to the corresponding floating-point constant. TYPE must be a scalar or vector floating-point type. CST must be of scalar or vector integer type. Both CST and TYPE must be scalars, or vectors of the same number of elements. If the value - won't fit in the floating-point type, the results are undefined. + won't fit in the floating-point type, the result is ``undef``. ``sitofp (CST to TYPE)`` Convert a signed integer constant to the corresponding floating-point constant. TYPE must be a scalar or vector floating-point type. CST must be of scalar or vector integer type. Both CST and TYPE must be scalars, or vectors of the same number of elements. If the value - won't fit in the floating-point type, the results are undefined. + won't fit in the floating-point type, the result is ``undef``. ``ptrtoint (CST to TYPE)`` Perform the :ref:`ptrtoint operation ` on constants. ``inttoptr (CST to TYPE)`` @@ -4933,10 +4952,11 @@ ``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of integer types. It expresses the possible ranges the loaded value or the value -returned by the called function at this call site is in. The ranges are -represented with a flattened list of integers. The loaded value or the value -returned is known to be in the union of the ranges defined by each consecutive -pair. Each pair has the following properties: +returned by the called function at this call site is in. If the loaded or +returned value is not in the specified range, the behavior is undefined. The +ranges are represented with a flattened list of integers. The loaded value or +the value returned is known to be in the union of the ranges defined by each +consecutive pair. Each pair has the following properties: - The type must match the type loaded by the instruction. - The pair ``a,b`` represents the range ``[a,b)``. @@ -7291,7 +7311,7 @@ The result is a scalar of the same type as the element type of ``val``. Its value is the value at position ``idx`` of ``val``. If ``idx`` -exceeds the length of ``val``, the results are undefined. +exceeds the length of ``val``, the result is ``undef``. Example: """""""" @@ -7332,8 +7352,8 @@ The result is a vector of the same type as ``val``. Its element values are those of ``val`` except at position ``idx``, where it gets the value -``elt``. If ``idx`` exceeds the length of ``val``, the results are -undefined. +``elt``. If ``idx`` exceeds the length of ``val``, the result is +``undef``. Example: """""""" @@ -7543,15 +7563,17 @@ Semantics: """""""""" -Memory is allocated; a pointer is returned. The operation is undefined -if there is insufficient stack space for the allocation. '``alloca``'d +Memory is allocated; a pointer is returned. The behavior is undefined +if there is insufficient stack space for the allocation. (Some targets +provide stronger guarantees for what happens on a stack overflow; see +also the ``"probe-stack"`` attribute.) '``alloca``'d memory is automatically released when the function returns. The '``alloca``' instruction is commonly used to represent automatic variables that must have an address available. When the function returns (either with the ``ret`` or ``resume`` instructions), the memory is -reclaimed. Allocating zero bytes is legal, but the result is undefined. -The order in which memory is allocated (ie., which way the stack grows) -is not specified. +reclaimed. Allocating zero bytes is legal, but the returned pointer is +is ``undef``. The order in which memory is allocated (ie., which way the +stack grows) is not specified. Example: """""""" @@ -7632,7 +7654,8 @@ entries. If a load instruction tagged with the ``!invariant.load`` metadata is executed, the optimizer may assume the memory location referenced by the load contains the same value at all points in the -program where the memory location is known to be dereferenceable. +program where the memory location is known to be dereferenceable; +otherwise, the behavior is undefined. The optional ``!invariant.group`` metadata must reference a single metadata name ```` corresponding to a metadata node with no entries. @@ -7642,14 +7665,15 @@ metadata name ```` corresponding to a metadata node with no entries. The existence of the ``!nonnull`` metadata on the instruction tells the optimizer that the value loaded is known to -never be null. This is analogous to the ``nonnull`` attribute -on parameters and return values. This metadata can only be applied -to loads of a pointer type. +never be null. If the value is null, the behavior is undefined. This is +analogous to the ``nonnull`` attribute on parameters and return values. +This metadata can only be applied to loads of a pointer type. The optional ``!dereferenceable`` metadata must reference a single metadata name ```` corresponding to a metadata node with one ``i64`` entry. The existence of the ``!dereferenceable`` metadata on the instruction -tells the optimizer that the value loaded is known to be dereferenceable. +tells the optimizer that the value loaded is known to be dereferenceable at +any later point in the program. The number of bytes known to be dereferenceable is specified by the integer value in the metadata node. This is analogous to the ''dereferenceable'' attribute on parameters and return values. This metadata can only be applied @@ -7671,7 +7695,8 @@ optimizer that the value loaded is known to be aligned to a boundary specified by the integer value in the metadata node. The alignment must be a power of 2. This is analogous to the ''align'' attribute on parameters and return values. -This metadata can only be applied to loads of a pointer type. +This metadata can only be applied to loads of a pointer type. If the returned +value is not appropriately aligned, the behavior is undefined. Semantics: """""""""" @@ -8135,7 +8160,7 @@ the element selected by the index marked as ``inrange``. The result of a pointer comparison or ``ptrtoint`` (including ``ptrtoint``-like operations involving memory) involving a pointer derived from a ``getelementptr`` with -the ``inrange`` keyword is undefined, with the exception of comparisons +the ``inrange`` keyword is ``undef``, with the exception of comparisons in the case where both operands are in the range of the element selected by the ``inrange`` keyword, inclusive of the address one past the end of that element. Note that the ``inrange`` keyword is currently only allowed @@ -8460,8 +8485,8 @@ The '``fptoui``' instruction converts its :ref:`floating-point ` operand into the nearest (rounding towards zero) -unsigned integer value. If the value cannot fit in ``ty2``, the results -are undefined. +unsigned integer value. If the value cannot fit in ``ty2``, the result +is ``undef``. Example: """""""" @@ -8502,8 +8527,8 @@ The '``fptosi``' instruction converts its :ref:`floating-point ` operand into the nearest (rounding towards zero) -signed integer value. If the value cannot fit in ``ty2``, the results -are undefined. +signed integer value. If the value cannot fit in ``ty2``, the result +is ``undef``. Example: """""""" @@ -8544,8 +8569,9 @@ The '``uitofp``' instruction interprets its operand as an unsigned integer quantity and converts it to the corresponding floating-point -value. If the value cannot fit in the floating-point value, the results -are undefined. +value. The conversion uses round-to-nearest rounding if the input cannot +be represented exactly. If the input cannot fit in the floating-point +value, the result is ``undef``. Example: """""""" @@ -8584,9 +8610,10 @@ """""""""" The '``sitofp``' instruction interprets its operand as a signed integer -quantity and converts it to the corresponding floating-point value. If -the value cannot fit in the floating-point value, the results are -undefined. +quantity and converts it to the corresponding floating-point value. The +conversion uses round-to-nearest rounding if the input cannot be represented +exactly. If the input cannot fit in the floating-point value, the result is +``undef``. Example: """"""""