bolt/deps/llvm-18.1.8/mlir/docs/Dialects/OpenACCDialect.md

'acc' Dialect

The acc dialect is an MLIR dialect for representing the OpenACC programming model. OpenACC is a standardized directive-based model which is used with C, C++, and Fortran to enable programmers to expose parallelism in their code. The descriptive approach used by OpenACC allows targeting of parallel multicore and accelerator targets like GPUs by giving the compiler the freedom of how to parallelize for specific architectures. OpenACC also provides the ability to optimize the parallelism through increasingly more prescriptive clauses.

This dialect models the constructs from the [OpenACC 3.3 specification] (https://www.openacc.org/sites/default/files/inline-images/Specification/OpenACC-3.3-final.pdf)

This document describes the design of the OpenACC dialect in MLIR. It lists and explains design goals and design choices along with their rationale. It also describes specifics with regards to acc dialect operations, types, and attributes.

[TOC]

Dialect Design Goals

• Needs to have complete representation of the OpenACC language.
  • A frontend requires this in order to properly generate a representation of possible acc pragmas in MLIR. Additionally, this dialect is expected to be further lowered when materializing its semantics. Without a complete representation, a frontend might choose a lower abstraction (such as direct runtime call) - but this would impact the ability to do analysis and optimizations on the dialect.
• Allow representation at the same semantic level as the OpenACC language while having capability to represent nuances of the source language semantics (such as Fortran descriptors) in an agnostic manner.
  • Using abstractions that closely model the OpenACC language simplifies frontend implementation. It also allows for easier debugging of the IR. However, sometimes source language specific behavior is needed when materializing OpenACC. In these cases, such as privatization of C++ objects with default constructor, the frontend fills in the recipe along with the private operation which can be packaged neatly with the acc dialect operations.
• Be able to regenerate the semantic equivalent of the user pragmas from the dialect (including bounds, names, clauses, modifiers, etc).
  • This is a strong measure of making sure that the dialect is not lossy in semantics. It also allows capability to generate appropriate and useful debug information outside of the frontend.
• Be dialect agnostic so that it can be used and coexist with other dialects including but not limited to hlfir, fir, llvm, cir.
  • Directive-based models such as OpenACC are always used with a source language, so the acc dialect coexisting with other dialect(s) is necessary by construction. Through proper abstractions, neither the acc dialect nor the source language dialect should have dependencies on each other; where needed, interfaces should be used to ensure acc dialect can verify expected properties.
• The dialect must allow dataflow to be modeled accurately and performantly using MLIR's existing facilities.
  • Appropriate dataflow modeling is important for analyses and IR reasoning - even something as simple as walking the uses. Therefore operations, like data operations, are expected to generate results which can be used in modeling behavior. For example, consider an acc copyin clause. After the acc.copyin operation, a pointer which lives on devices should be distinguishable from one that lives in host memory.
• Be friendly to MLIR optimization passes by implementing common interfaces.
  • Interfaces, such as MemoryEffects, are the key way MLIR transformations and analyses are designed to interact with the IR. In order for the operations in the acc dialect to be optimizable (either directly or even indirectly by not blocking optimizations of nested IR), implementing relevant common interfaces is needed.

The design philosophy of the acc dialect is one where the design goals are adhered to. Current and planned operations, attributes, types must adhere to the design goals.

Operation Categories

The OpenACC dialect includes both high-level operations (which retain the same semantic meaning as their OpenACC language equivalent), intermediate-level operations (which are used to decompose clauses from constructs), and low-level operations (to encode specifics associated with source language in a generic way).

The high-level operations list contains the following OpenACC language constructs and their corresponding operations:

• acc parallel → acc.parallel
• acc kernels → acc.kernels
• acc serial → acc.serial
• acc data → acc.data
• acc loop → acc.loop
• acc enter data → acc.enter_data
• acc exit data → acc.exit_data
• acc host_data → acc.host_data
• acc init → acc.init
• acc shutdown → acc.shutdown
• acc update → acc.update
• acc set → acc.set
• acc wait → acc.wait
• acc atomic read → acc.atomic.read
• acc atomic write → acc.atomic.write
• acc atomic update → acc.atomic.update
• acc atomic capture → acc.atomic.capture

This second group contains operations which are used to represent either decomposed constructs or clauses for more accurate modeling:

• acc routine → acc.routine + acc.routine_info attribute
• acc declare → acc.declare_enter + acc.declare_exit or acc.declare
• acc {construct} copyin → acc.copyin (before region) + acc.delete (after region)
• acc {construct} copy → acc.copyin (before region) + acc.copyout (after region)
• acc {construct} copyout → acc.create (before region) + acc.copyout (after region)
• acc {construct} attach → acc.attach (before region) + acc.detach (after region)
• acc {construct} create → acc.create (before region) + acc.delete (after region)
• acc {construct} present → acc.present (before region) + acc.delete (after region)
• acc {construct} no_create → acc.nocreate (before region) + acc.delete (after region)
• acc {construct} deviceptr → acc.deviceptr
• acc {construct} private → acc.private
• acc {construct} firstprivate → acc.firstprivate
• acc {construct} reduction → acc.reduction
• acc cache → acc.cache
• acc update device → acc.update_device
• acc update host → acc.update_host
• acc host_data use_device → acc.use_device
• acc declare device_resident → acc.declare_device_resident
• acc declare link → acc.declare_link
• acc exit data delete → acc.delete (with structured flag as false)
• acc exit data detach → acc.detach (with structured flag as false)
• acc {construct} {data_clause}(var[lb:ub]) → acc.bounds

The low-level operations are:

• acc.private.recipe
• acc.reduction.recipe
• acc.firstprivate.recipe
• acc.global_ctor
• acc.global_dtor
• acc.yield
• acc.terminator The low-level operations semantics and reasoning are further explained in sections below.

Data Operations

Data Clause Decomposition

The data clauses are decomposed from their constructs for better dataflow modeling in MLIR. There are multiple reasons for this which are consistent with the dialect goals:

• Correctly represents dataflow. Data clauses have different effects at entry to region and at exit from region.
• Friendlier to add attributes such as MemoryEffects to a single operation. This can better reflect semantics (like the fact that an acc.copyin operation only reads host memory)
• Operations can be moved or optimized individually (eg CSE).
• Easier to keep track of debug information. Line location can point to the text representing the data clause instead of the construct. Additionally, attributes can be used to keep track of variable names in clauses without having to walk the IR tree in attempt to recover the information (this makes acc dialect more agnostic with regards to what other dialect it is used with).
• Clear operation ordering since all data operations are on same list.

Each of the acc dialect data operations represents either the entry or the exit portion of the data action specification. Thus, acc.copyin represents the semantics defined in section 2.7.7 copyin clause whose wording starts with At entry to a region. The decomposed exit operation acc.delete represents the second part of that section, whose wording starts with At exit from the region. The delete action may be performed after checking and updating of the relevant reference counters noted.

The acc data operations, even when decomposed, retain their original data clause in an operation operand dataClause for possibility to recover this information during debugging. For example, acc copy, does not translate to acc.copy operation, but instead to acc.copyin for entry and acc.copyout for exit. Both the decomposed operations hold a dataClause field that specifies this was an acc copy.

The link between the decomposed entry and exit operations is the ssa value produced by the entry operation. Namely, it is the accPtr result which is used both in the dataOperands of the operation used for the construct and in the accPtr operand of the exit operation.

Bounds

OpenACC data clauses allow the use of bounds specifiers as per 2.7.1 Data Specification in Data Clauses. However, array dimensions for the data are not always required in the clause if the source language's type system captures this information - the user can just specify the variable name in the data clause. So the acc.bounds operation is an important piece to ensure uniform representation of both explicit user set dimensions and implicit type-based dimensions. It contains several key features to allow properly encoding sizes in a manner flexible and agnostic to the source language's dialect:

• Multi-dimensional arrays can be represented by using multiple ordered acc.bounds operations.
• Bounds are required to be zero-normalized. This works well with the PointerLikeType requirement in data clauses - since a lowerbound of 0 means looking at data at the zero offset from pointer. This requirement also works well in ensuring the acc dialect is agnostic to source language dialect since it prevents ambiguity such as the case of Fortran arrays where the lower bound is not a fixed value.
• If the source dialect does not encode the dimensions in the type (eg !fir.array<?x?xi32>) but instead encodes it in some other way (such as through descriptors), then the frontend must fill in the acc.bounds operands with appropriate information (such as loads from descriptor). The acc.bounds operation also permits lossy source dialect, such as if the frontend uses aggressive pointer decay and cannot represent the dimensions in the type system (eg using !llvm.ptr for arrays). Both of these aspects show acc.bounds' operation's flexibility to allow the representation to be agnostic since the acc dialect is not expected to be able to understand how to extract dimension information from the types of the source dialect.
• The OpenACC specification allows either extent or upperbound in the data clause depending on whether it is Fortran or C and C++. The acc.bounds operation is rich enough to accept either or both - for convenience in lowering to the dialect and for ability to precisely capture the meaning from the clause.
• The stride, either in units or bytes, can be also captured in the acc.bounds operation. This is also an important part to be able to accept a source language's arrays without forcing the frontend to normalize them in some way. For example, consider a case where in a parent function, a whole array is mapped to device. Then only a view of a non-1 stride is passed to child function (eg Fortran array slice with non-1 stride). A copy operation of this data in child should be able to avoid remapping this array. If instead the operation required normalizing the array (such as making it contiguous), then unexpected disjoint mapping of the same host data would be error-prone since it would result in multiple mappings to device.

Counters

The data operations also maintain semantics described in the OpenACC specification related to runtime counters. More specifically, consider the specification of the entry portion of acc copyin in section 2.7.7:

At entry to a region, the structured reference counter is used. On an
enter data directive, the dynamic reference counter is used.
- If var is present and is not a null pointer, a present increment
action with the appropriate reference counter is performed.
- If var is not present, a copyin action with the appropriate reference
counter is performed.
- If var is a pointer reference, an attach action is performed.

The acc.copyin operation includes these semantics, including those related to attach, which is specified through the varPtrPtr operand. The structured flag on the operation is important since the structured reference counter should be used when the flag is true; and the dynamic reference counter should be used when it is false.

At exit from structured regions (acc data, acc kernels), the acc copyin operation is decomposed to acc.delete (with the structured flag as true). The semantics of the acc.delete are also consistent with the OpenACC specification noted for the exit portion of the acc copyin clause:

At exit from the region:
- If the structured reference counter for var is zero, no action is
taken.
- Otherwise, a detach action is performed if var is a pointer reference,
and a present decrement action with the structured reference counter is
performed if var is not a null pointer. If both structured and dynamic
reference counters are zero, a delete action is performed.

Types

There are a few acc dialect type categories to describe:

• type of acc data clause operation input varPtr
  • The type of varPtr must be pointer-like. This is done by attaching the PointerLikeType interface to the appropriate MLIR type. Although memory/storage concept is a lower level abstraction, it is useful because the OpenACC model distinguishes between host and device memory explicitly - and the mapping between the two is done through pointers. Thus, by explicitly requiring it in the dialect, the appropriate language frontend must create storage or use type that satisfies the mapping constraint.
• type of result of acc data clause operations
  • The type of the acc data clause operation is exactly the same as varPtr. This was done intentionally instead of introducing an acc.ref/ptr type so that IR compatibility and the dialect's existing strong type checking can be maintained. This is needed since the acc dialect must live within another dialect whose type system is unknown to it. The only constraint is that the appropriate dialect type must use the PointerLikeType interface.
• type of decomposed clauses
  • Decomposed clauses, such as acc.bounds and acc.declare_enter produce types to allow their results to be used only in specific operations.

Recipes

Recipes are a generic way to express source language specific semantics.

There are currently two categories of recipes, but the recipe concept can be extended for any additional low-level information that needs to be captured for successful lowering of OpenACC. The two categories are:

• recipes used in the context of privatization associated with a construct
• recipes used in the context of additional specification of data semantics

The intention of the recipes is to specify how materialization of action, such as privatization, should be done when the semantics of the action needs interpreted and lowered, such as before generating LLVM dialect.

The recipes used for privatization provide a source-language independent way of specifying the creation of a local variable of that type. This means using the appropriate alloca instruction and being able to specify default initialization or default constructor.

Routine

The routine directive is used to note that a procedure should be made available for the accelerator in a way that is consistent with its modifiers, such as those that describe the parallelism. In the acc dialect, an acc routine is represented through two joint pieces - an attribute and an operation:

• The acc.routine operation is simply a specifier which notes which symbol (or string) the acc routine is needed for, along with parallelism associated. This defines a symbol that can be referenced in attribute.
• The acc.routine_info attribute is an attribute used on the source dialect specific operation which specifies one or multiple acc.routine symbols. Typically, this is attached to func.func which either provides the declaration (in case of externals) or provides the actual body of the acc routine in the dialect that the source language was translated to.

Declare

OpenACC declare is a mechanism which declares a definition of a global or a local to be accessible to accelerator with an implicit lifetime as that of the scope where it was declared in. Thus, declare semantics are represented through multiple operations and attributes:

• acc.declare - This is a structured operation which contains an MLIR region and can be used in similar manner as acc.data to specify an implicit data region with specific procedure lifetime. This is typically used inside func.func after variable declarations.
• acc.declare_enter - This is an unstructured operation which is used as a decomposed form of acc declare. It effectively allows the entry operation to exist in a scope different than the exit operation. It can also be used along acc.declare_exit which consumes its token to define a scoped region without using MLIR region. This operation is also used in acc.global_ctor.
• acc.declare_exit - The matching equivalent of acc.declare_enter except that it specifies exit semantics. This operation is typically used inside a func.func at the exit points or with acc.global_dtor.
• acc.global_ctor - Lives at the same level as source dialect globals and is used to specify data actions to be done at program entry. This is used in conjunction with source dialect globals whose lifetime is not just a single procedure.
• acc.global_dtor - Defines the exit data actions that should be done at program exit. Typically used to revert the actions of acc.global_ctor.

The attributes:

• acc.declare - This is a facility for easier determination of variables which are acc declare'd. This attribute is used on operations producing globals and on operations producing locals such as dialect specific alloca's. Having this attribute is required in order to appear in a data mapping operation associated with any of the acc.declare* operations.
• acc.declare_action - Since the OpenACC specification allows declaration of variables that have yet to be allocated, this attribute is used at the allocation and deallocation points. More specifically, this attribute captures symbols of functions to be called to perform an action either pre-allocate, post-allocate, pre-deallocate, or post-deallocate. Calls to these functions should be materialized when lowering OpenACC semantics to ensure proper data actions are done after the allocation/deallocation.

OpenACC Transforms and Analyses

The design goal for the acc dialect is to be friendly to MLIR optimization passes including CSE and LICM. Additionally, since it is designed to recover original clauses, it makes late verification and analysis possible in the MLIR framework outside of the frontend.

This section describes a few MLIR-level passes for which the acc dialect design should be friendly for. This section is currently solely outlining the possibilities intended by the design and not necessarily existing passes.

Verification

Since the OpenACC dialect is not lossy with regards to its representation, it is possible to do OpenACC language semantic checking at the MLIR-level. What follows is a list of various semantic checks needed.

This first list is required to be done in the frontend because the acc dialect operations must be valid when constructed:

• Ensure that only listed clauses are allowed for each directive.
• Ensure that only listed modifiers are allowed for each clause.

However, the following are semantic checks that can be done at the MLIR-level (either in a separate pass or as part of the operation verifier):

• Specify the validity checks that each modifier needs. (eg num_gangs may need a positive integer).
• Ensure valid clause nesting.
• Validate clause restrictions which cannot appear with others.
• Validate that no conflicting clauses are used on variables.

Note that some of these checks can be even more precise when done at the MLIR level because optimizations like inlining and constant propagation expose detail that wouldn't have been visible in the frontend.

Implicit Data Attributes

The OpenACC specification includes a section on 2.6.2 Variables with Implicitly Determined Data Attributes. What this section describes are the data actions that should be applied to a variable for which user did not specify a data action for. The action depends on the construct being used and also on the default clause. However, the point to note here is that variables which are live-in into the acc region must employ some data mapping so the data can be passed to accelerator.

One possible optimizations that affects data attributes needed is Scalar Replacement of Aggregates (SROA). The acc dialect should not prevent this from happening on the source dialect.

Because it is intended to be possible to apply optimizations across an acc region, the analysis/transformation pass that applies the implicit data attributes should be run as late as possible - ideally right before any outlining process which uses the acc region body to create an accelerator procedure. It is expected that existing MLIR facilities, such as mlir::Liveness will work for the acc region and thus can be used to perform this analysis.

Redundant Clause Elimination

The data operations are modeled in a way where data entry operations look like loads and data exit operations look like stores. Thus these operations are intended to be optimized in the following ways:

• Be able to eliminate redundant operations such as when an acc.copyin dominates another.
• Be able to hoist/sink such operations out of loops.

Operations TOC

[include "Dialects/OpenACCDialectOps.md"]