'ptr' Dialect

Pointer dialect

Operations ¶

source

ptr.from_ptr (ptr::FromPtrOp) ¶

Casts a !ptr.ptr value to a ptr-like value.

Syntax:

operation ::= `ptr.from_ptr` $ptr (`metadata` $metadata^)? attr-dict `:` type($ptr) `->` type($result)

The from_ptr operation casts a ptr value to a ptr-like object. It’s important to note that:

• The ptr-like object cannot be a !ptr.ptr.
• The memory-space of both the ptr and ptr-like object must match.
• The cast is Pure (no UB and side-effect free).

The optional metadata operand exists to provide any ptr-like metadata that might be required to perform the cast.

Example:

%typed_ptr = ptr.from_ptr %ptr : !ptr.ptr<#ptr.generic_space> -> !my.ptr<f32, #ptr.generic_space>
%memref = ptr.from_ptr %ptr metadata %md : !ptr.ptr<#ptr.generic_space> -> memref<f32, #ptr.generic_space>

// Cast the `%ptr` to a memref without utilizing metadata.
%memref = ptr.from_ptr %ptr : !ptr.ptr<#ptr.generic_space> -> memref<f32, #ptr.generic_space>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

ptr.get_metadata (ptr::GetMetadataOp) ¶

SSA value representing pointer metadata.

Syntax:

operation ::= `ptr.get_metadata` $ptr attr-dict `:` type($ptr)

The get_metadata operation produces an opaque value that encodes the metadata of the ptr-like type.

Example:

%metadata = ptr.get_metadata %memref : memref<?x?xf32>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

ptr.load (ptr::LoadOp) ¶

Syntax:

operation ::= `ptr.load` (`volatile` $volatile_^)? $ptr
              (`atomic` (`syncscope` `(` $syncscope^ `)`)? $ordering^)?
              oilist(
              `nontemporal` $nontemporal |
              `invariant` $invariant |
              `invariant_group` $invariantGroup |
              `alignment` `=` $alignment
              )
              attr-dict `:` qualified(type($ptr)) `->` type($value)

The load operation is used to read from memory. A load may be marked as atomic, volatile, and/or nontemporal.

An atomic load only supports a limited set of value types, and requires an explicit alignment.

Examples:

// A volatile load of a float variable.
%0 = ptr.load volatile %ptr : !ptr.ptr -> f32

// A nontemporal load of a float variable.
%0 = ptr.load %ptr nontemporal : !ptr.ptr -> f32

// An atomic load of an integer variable.
%0 = ptr.load %ptr atomic monotonic alignment = 8 : !ptr.ptr -> i64

See the following link for more details on the meaning of alignment, volatile_, nontemporal, invariant, invariant_group, ordering, and syncscope: https://llvm.org/docs/LangRef.html#load-instruction

Interfaces: MemoryEffectOpInterface

Attributes: ¶

Operands: ¶

Results: ¶

ptr.ptr_add (ptr::PtrAddOp) ¶

Pointer add operation

Syntax:

operation ::= `ptr.ptr_add` ($flags^)? $base `,` $offset attr-dict `:` type($base) `,` type($offset)

The ptr_add operation adds an integer offset to a pointer to produce a new pointer. The input and output pointer types are always the same.

Example:

%x_off  = ptr.ptr_add %x, %off : !ptr.ptr<#ptr.generic_space>, i32
%x_off0 = ptr.ptr_add nusw %x, %off : !ptr.ptr<#ptr.generic_space>, i32

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), ViewLikeOpInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

ptr.store (ptr::StoreOp) ¶

Syntax:

operation ::= `ptr.store` (`volatile` $volatile_^)? $value `,` $ptr
              (`atomic` (`syncscope` `(` $syncscope^ `)`)? $ordering^)?
              oilist(
              `nontemporal` $nontemporal |
              `invariant_group` $invariantGroup |
              `alignment` `=` $alignment
              )
              attr-dict `:` type($value) `,` qualified(type($ptr))

The store operation is used to write to memory. A store may be marked as atomic, volatile, and/or nontemporal.

An atomic store only supports a limited set of value types, and requires an explicit alignment.

Examples:

// A volatile store of a float variable.
ptr.store volatile %val, %ptr : f32, !ptr.ptr

// A nontemporal store of a float variable.
ptr.store %val, %ptr nontemporal : f32, !ptr.ptr

// An atomic store of an integer variable.
ptr.store %val, %ptr atomic monotonic alignment = 8: i64, !ptr.ptr

See the following link for more details on the meaning of alignment, volatile_, nontemporal, invariant_group, ordering, and syncscope: https://llvm.org/docs/LangRef.html#store-instruction

Interfaces: MemoryEffectOpInterface

Attributes: ¶

Operands: ¶

ptr.to_ptr (ptr::ToPtrOp) ¶

Casts a ptr-like value to a !ptr.ptr value.

Syntax:

operation ::= `ptr.to_ptr` $ptr attr-dict `:` type($ptr) `->` type($result)

The to_ptr operation casts a ptr-like object to a !ptr.ptr. It’s important to note that:

• The ptr-like object cannot be a !ptr.ptr.
• The memory-space of both the ptr and ptr-like object must match.
• The cast is side-effect free.

Example:

%ptr0 = ptr.to_ptr %my_ptr : !my.ptr<f32, #ptr.generic_space> -> !ptr.ptr<#ptr.generic_space>
%ptr1 = ptr.to_ptr %memref : memref<f32, #ptr.generic_space> -> !ptr.ptr<#ptr.generic_space>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

ptr.type_offset (ptr::TypeOffsetOp) ¶

Type offset operation

Syntax:

operation ::= `ptr.type_offset` $elementType attr-dict `:` type($result)

The type_offset operation produces an int or index-typed SSA value equal to a target-specific constant representing the offset of a single element of the given type.

Example:

// Return the offset between two f32 stored in memory
%0 = ptr.type_offset f32 : index
// Return the offset between two memref descriptors stored in memory
%1 = ptr.type_offset memref<12 x f64> : i32

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Attributes: ¶

Results: ¶

Attributes ¶

GenericSpaceAttr ¶

Generic memory space

Syntax: #ptr.generic_space

The generic_space attribute defines a memory space attribute with the following properties:

• Load and store operations are always valid, regardless of the type.
• Atomic operations are always valid, regardless of the type.
• Cast operations to generic_space are always valid.

Example:

#ptr.generic_space

SpecAttr ¶

Ptr data layout spec

Syntax:

#ptr.spec<
  uint32_t,   # size
  uint32_t,   # abi
  uint32_t,   # preferred
  uint32_t   # index
>

Defines the data layout spec for a pointer type. This attribute has 4 fields:

• [Required] size: size of the pointer in bits.
• [Required] abi: ABI-required alignment for the pointer in bits.
• [Required] preferred: preferred alignment for the pointer in bits.
• [Optional] index: bitwidth that should be used when performing index computations for the type. Setting the field to kOptionalSpecValue, means the field is optional.

Furthermore, the attribute will verify that all present values are divisible by 8 (number of bits in a byte), and that preferred > abi.

Example:

// Spec for a 64 bit ptr, with a required alignment of 64 bits, but with
// a preferred alignment of 128 bits and an index bitwidth of 64 bits.
#ptr.spec<size = 64, abi = 64, preferred = 128, index = 64>

Parameters: ¶

Types ¶

PtrMetadataType ¶

Pointer metadata type

Syntax:

!ptr.ptr_metadata<
  PtrLikeTypeInterface   # type
>

The ptr_metadata type represents an opaque-view of the metadata associated with a ptr-like object type.

Note: It’s a verification error to construct a ptr_metadata type using a ptr-like type with no metadata.

Example:

// The metadata associated with a `memref` type.
!ptr.ptr_metadata<memref<f32>>

Parameters: ¶

PtrType ¶

Pointer type

Syntax:

!ptr.ptr<
  MemorySpaceAttrInterface   # memorySpace
>

The ptr type is an opaque pointer type. This type typically represents a handle to an object in memory or target-dependent values like nullptr. Pointers are parameterized by a memory space.

Syntax:

pointer ::= `ptr` (`<` memory-space `>`)?
memory-space ::= attribute-value

Parameters: ¶

Enums ¶

AtomicBinOp ¶

Ptr.atomicrmw binary operations

Cases: ¶

AtomicOrdering ¶

Atomic ordering for LLVM’s memory model

Cases: ¶

PtrAddFlags ¶

Pointer add flags

Cases: ¶