diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -3553,10 +3553,6 @@ To ensure all uses of a given register observe the same value (even if '``undef``'), the :ref:`freeze instruction ` can be used. -A value is frozen if its uses see the same value. -An aggregate value or vector is frozen if its elements are frozen. -The padding of an aggregate isn't considered, since it isn't visible -without storing it into memory and loading it with a different type. .. code-block:: llvm @@ -3729,6 +3725,23 @@ end: +.. _welldefinedvalues: + +Well-Defined Values +------------------- + +Given a program execution, a value is *well defined* if the value does not +have an undef bit and is not poison in the execution. +An aggregate value or vector is well defined if its elements are well defined. +The padding of an aggregate isn't considered, since it isn't visible +without storing it into memory and loading it with a different type. + +A constant of a :ref:`single value `, non-vector type is well +defined if it is a non-undef constant. Note that there is no poison constant +in LLVM. +The result of :ref:`freeze instruction ` is well defined regardless +of its operand. + .. _blockaddress: Addresses of Basic Blocks @@ -9244,6 +9257,12 @@ padding may be accessed but are ignored, because it is impossible to observe padding from the loaded aggregate value. +If the pointer is not a well-defined value, all of its possible representations +should be dereferenceable. For example, loading a byte from a pointer to an +array of type ``[16 x i8]`` with offset ``undef & 31`` is undefined behavior. +Loading a byte at offset ``undef & 15`` nondeterministically reads one of the +bytes. + Examples: """"""""" @@ -9335,6 +9354,12 @@ If ```` is of aggregate type, padding is filled with :ref:`undef `. +If ```` is not a well-defined value, all of its possible +representations should be dereferenceable. For example, storing a byte to a +pointer to an array of type ``[16 x i8]`` with offset ``undef & 31`` is +undefined behavior. Storing a byte to an offset ``undef & 15`` +nondeterministically stores to one of offsets from 0 to 15. + Example: """""""" @@ -12487,6 +12512,9 @@ If "len" is 0, the pointers may be NULL, dangling, ``undef``, or ``poison`` pointers. However, they must still be appropriately aligned. +If "len" isn't a well-defined value, all of its possible representations should +make the behavior of this ``llvm.memcpy`` defined, otherwise the behavior is +undefined. .. _int_memcpy_inline: @@ -12604,6 +12632,9 @@ If "len" is 0, the pointers may be NULL, dangling, ``undef``, or ``poison`` pointers. However, they must still be appropriately aligned. +If "len" isn't a well-defined value, all of its possible representations should +make the behavior of this ``llvm.memmove`` defined, otherwise the behavior is +undefined. .. _int_memset: @@ -12659,6 +12690,9 @@ If "len" is 0, the pointer may be NULL, dangling, ``undef``, or ``poison`` pointer. However, it must still be appropriately aligned. +If "len" isn't a well-defined value, all of its possible representations should +make the behavior of this ``llvm.memset`` defined, otherwise the behavior is +undefined. '``llvm.sqrt.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^^