diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -1135,15 +1135,22 @@ the behavior is undefined. ``dereferenceable()`` - This indicates that the parameter or return pointer is dereferenceable. 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 - in parentheses. It is legal for the number of bytes to be less than the - size of the pointee type. The ``nonnull`` attribute does not imply - dereferenceability (consider a pointer to one element past the end of an - array), however ``dereferenceable()`` does imply ``nonnull`` in - ``addrspace(0)`` (which is the default address space). + This indicates that the annotated value, e.g., a parameter or return + value, is dereferenceable *at its definition*, which would be the beginning + of the function entry or the call site for annotated parameters and return + values respectively. This attribute may only be applied to values with + pointer type. A pointer that is known to be dereferenceable can be loaded + from speculatively without a risk of trapping. The number of bytes known to + be dereferenceable must be provided in parentheses. It is legal for the + number of bytes to be less than the size of the pointee type. If, at + runtime, the annotated pointer is not dereferenceable, the behavior is + undefined. The ``nonnull`` attribute does not imply dereferenceability + (consider a pointer to one element past the end of an array), however + ``dereferenceable()`` does imply ``nonnull`` in ``addrspace(0)`` (which + is the default address space). The dereferenceability property provided + through this argument is tied to the definition because it can be lost, + e.g., via a call to ``free``. Use ``dereferenceable_globally()`` for + pointer values that cannot be deallocated. ``dereferenceable_or_null()`` This indicates that the parameter or return value isn't both @@ -1154,9 +1161,24 @@ a pointer is exactly one of ``dereferenceable()`` or ``null``, and in other address spaces ``dereferenceable_or_null()`` implies that a pointer is at least one of ``dereferenceable()`` - or ``null`` (i.e. it may be both ``null`` and - ``dereferenceable()``). This attribute may only be applied to - pointer typed parameters. + or ``null`` (i.e. it may be both ``null`` and ``dereferenceable()``). + This attribute may only be applied to pointer typed parameters. + +``dereferenceable_globally()`` + This indicates that the annotated pointer value has the + ``dereferenceable()`` property *at any program point*, starting from the + definition of the value to the termination of the program. Thus, unlike + pointer values annotated with ``dereferenceable()``, + ``dereferenceable_globally()`` pointer values can never lose the + ``dereferenceable()`` property. + +``dereferenceable_or_null_globally()`` + This indicates that the annotated pointer value has the + ``dereferenceable_or_null()`` property *at any program point*, starting + from the definition of the value to the termination of the program. Thus, + unlike pointer values annotated with ``dereferenceable_or_null()``, + ``dereferenceable_or_null_globally()`` pointer values can never lose the + ``dereferenceable_or_null()`` property. ``swiftself`` This indicates that the parameter is the self/context parameter. This is not diff --git a/llvm/include/llvm/IR/Attributes.td b/llvm/include/llvm/IR/Attributes.td --- a/llvm/include/llvm/IR/Attributes.td +++ b/llvm/include/llvm/IR/Attributes.td @@ -45,6 +45,12 @@ /// Pointer is either null or dereferenceable. def DereferenceableOrNull : EnumAttr<"dereferenceable_or_null">; +/// Pointer is known to be dereferenceable_globally. +def DereferenceableGlobally : EnumAttr<"dereferenceable_globally">; + +/// Pointer is either null or dereferenceable_globally. +def DereferenceableOrNullGlobally : EnumAttr<"dereferenceable_or_null_globally">; + /// Function may only access memory that is inaccessible from IR. def InaccessibleMemOnly : EnumAttr<"inaccessiblememonly">;