Skip to content

Commit bc68d45

Browse files
callumfareronlieb
callumfare
authored and
ronlieb
committed
Reland llvm#118503: [Offload] Introduce offload-tblgen and initial new API implementation (llvm#118614)
Reland llvm#118503. Added a fix for builds with `-DBUILD_SHARED_LIBS=ON` (see last commit). Otherwise the changes are identical. Disables until OMPT adapts to this. Previous discussions at the LLVM/Offload meeting have brought up the need for a new API for exposing the functionality of the plugins. This change introduces a very small subset of a new API, which is primarily for testing the offload tooling and demonstrating how a new API can fit into the existing code base without being too disruptive. Exact designs for these entry points and future additions can be worked out over time. The new API does however introduce the bare minimum functionality to implement device discovery for Unified Runtime and SYCL. This means that the `urinfo` and `sycl-ls` tools can be used on top of Offload. A (rough) implementation of a Unified Runtime adapter (aka plugin) for Offload is available [here](https://github.com/callumfare/unified-runtime/tree/offload_adapter). Our intention is to maintain this and use it to implement and test Offload API changes with SYCL. ```sh $ ninja LibomptUnitTests $ OFFLOAD_TRACE=1 ./offload/unittests/OffloadAPI/offload.unittests ``` * Only some of the available device info is exposed, and not all the possible device queries needed for SYCL are implemented by the plugins. A sensible next step would be to refactor and extend the existing device info queries in the plugins. The existing info queries are all strings, but the new API introduces the ability to return any arbitrary type. * It may be sensible at some point for the plugins to implement the new API directly, and the higher level code on top of it could be made generic, but this is more of a long-term possibility. Change-Id: I355ac2cc4122d8023a88bc7f427174e16dfa76b9
1 parent d56ed32 commit bc68d45

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+4930
-2
lines changed

‎offload/CMakeLists.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -438,6 +438,10 @@ add_subdirectory(DeviceRTL)
438438
# Build target agnostic offloading library.
439439
add_subdirectory(src)
440440

441+
# FIXME: Re-enable once OMPT design allows
442+
# add_subdirectory(tools/offload-tblgen)
443+
# add_subdirectory(liboffload)
444+
441445
# Add tests.
442446
add_subdirectory(test)
443447

‎offload/cmake/OpenMPTesting.cmake‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,17 @@ function(find_standalone_test_dependencies)
3737
return()
3838
endif()
3939

40+
find_program(OFFLOAD_TBLGEN_EXECUTABLE
41+
NAMES offload-tblgen
42+
PATHS ${OPENMP_LLVM_TOOLS_DIR})
43+
if (NOT OFFLOAD_TBLGEN_EXECUTABLE)
44+
message(STATUS "Cannot find 'offload-tblgen'.")
45+
message(STATUS "Please put 'not' in your PATH, set OFFLOAD_TBLGEN_EXECUTABLE to its full path, or point OPENMP_LLVM_TOOLS_DIR to its directory.")
46+
message(WARNING "The check targets will not be available!")
47+
set(ENABLE_CHECK_TARGETS FALSE PARENT_SCOPE)
48+
return()
49+
endif()
50+
4051
find_program(OPENMP_NOT_EXECUTABLE
4152
NAMES not
4253
PATHS ${OPENMP_LLVM_TOOLS_DIR})
@@ -73,6 +84,7 @@ else()
7384
set(OPENMP_NOT_EXECUTABLE ${LLVM_RUNTIME_OUTPUT_INTDIR}/not)
7485
endif()
7586
set(OFFLOAD_DEVICE_INFO_EXECUTABLE ${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-offload-device-info)
87+
set(OFFLOAD_TBLGEN_EXECUTABLE ${LLVM_RUNTIME_OUTPUT_INTDIR}/offload-tblgen)
7688

7789
# Macro to extract information about compiler from file. (no own scope)
7890
macro(extract_test_compiler_information lang file)

‎offload/liboffload/API/APIDefs.td‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
//===-- APIDefs.td - Base definitions for Offload tablegen -*- tablegen -*-===//
2+
//
3+
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4+
// See https://llvm.org/LICENSE.txt for license information.
5+
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6+
//
7+
//===----------------------------------------------------------------------===//
8+
//
9+
// This file contains the class definitions used to implement the Offload API,
10+
// as well as helper functions used to help populate relevant records.
11+
// See offload/API/README.md for more detailed documentation.
12+
//
13+
//===----------------------------------------------------------------------===//
14+
15+
// Prefix for API naming. This could be hard-coded in the future when a value
16+
// is agreed upon.
17+
defvar PREFIX = "OL";
18+
defvar prefix = !tolower(PREFIX);
19+
20+
// Parameter flags
21+
defvar PARAM_IN = 0x1;
22+
defvar PARAM_OUT = 0x2;
23+
defvar PARAM_OPTIONAL = 0x4;
24+
defvar PARAM_IN_OPTIONAL = !or(PARAM_IN, PARAM_OPTIONAL);
25+
defvar PARAM_OUT_OPTIONAL = !or(PARAM_OUT, PARAM_OPTIONAL);
26+
27+
// Does the type end with '_handle_t'?
28+
class IsHandleType<string Type> {
29+
// size("_handle_t") == 9
30+
bit ret = !if(!lt(!size(Type), 9), 0,
31+
!ne(!find(Type, "_handle_t", !sub(!size(Type), 9)), -1));
32+
}
33+
34+
// Does the type end with '*'?
35+
class IsPointerType<string Type> {
36+
bit ret = !ne(!find(Type, "*", !sub(!size(Type), 1)), -1);
37+
}
38+
39+
// Describes the valid range of a pointer parameter that reperesents an array
40+
class Range<string Begin, string End> {
41+
string begin = Begin;
42+
string end = End;
43+
}
44+
45+
// Names the parameters that indicate the type and size of the data pointed to
46+
// by an opaque pointer parameter
47+
class TypeInfo<string TypeEnum, string TypeSize> {
48+
string enum = TypeEnum;
49+
string size = TypeSize;
50+
}
51+
52+
class Param<string Type, string Name, string Desc, bits<3> Flags = 0> {
53+
string type = Type;
54+
string name = Name;
55+
string desc = Desc;
56+
bits<3> flags = Flags;
57+
Range range = Range<"", "">;
58+
TypeInfo type_info = TypeInfo<"", "">;
59+
bit IsHandle = IsHandleType<type>.ret;
60+
bit IsPointer = IsPointerType<type>.ret;
61+
}
62+
63+
// A parameter whose range is described by other parameters in the function.
64+
class RangedParam<string Type, string Name, string Desc, bits<3> Flags, Range ParamRange> : Param<Type, Name, Desc, Flags> {
65+
let range = ParamRange;
66+
}
67+
68+
// A parameter (normally of type void*) which has its pointee type and size
69+
// described by other parameters in the function.
70+
class TypeTaggedParam<string Type, string Name, string Desc, bits<3> Flags, TypeInfo ParamTypeInfo> : Param<Type, Name, Desc, Flags> {
71+
let type_info = ParamTypeInfo;
72+
}
73+
74+
class Return<string Value, list<string> Conditions = []> {
75+
string value = Value;
76+
list<string> conditions = Conditions;
77+
}
78+
79+
class ShouldCheckHandle<Param P> {
80+
bit ret = !and(P.IsHandle, !eq(!and(PARAM_OPTIONAL, P.flags), 0));
81+
}
82+
83+
class ShouldCheckPointer<Param P> {
84+
bit ret = !and(P.IsPointer, !eq(!and(PARAM_OPTIONAL, P.flags), 0));
85+
}
86+
87+
// For a list of returns that contains a specific return code, find and append
88+
// new conditions to that return
89+
class AppendConditionsToReturn<list<Return> Returns, string ReturnValue,
90+
list<string> Conditions> {
91+
list<Return> ret =
92+
!foreach(Ret, Returns,
93+
!if(!eq(Ret.value, ReturnValue),
94+
Return<Ret.value, Ret.conditions#Conditions>, Ret));
95+
}
96+
97+
// Add null handle checks to a function's return value descriptions
98+
class AddHandleChecksToReturns<list<Param> Params, list<Return> Returns> {
99+
list<string> handle_params =
100+
!foreach(P, Params, !if(ShouldCheckHandle<P>.ret, P.name, ""));
101+
list<string> handle_params_filt =
102+
!filter(param, handle_params, !ne(param, ""));
103+
list<string> handle_param_conds =
104+
!foreach(handle, handle_params_filt, "`NULL == "#handle#"`");
105+
106+
// Does the list of returns already contain ERROR_INVALID_NULL_HANDLE?
107+
bit returns_has_inv_handle = !foldl(
108+
0, Returns, HasErr, Ret,
109+
!or(HasErr, !eq(Ret.value, PREFIX#"_ERRC_INVALID_NULL_HANDLE")));
110+
111+
list<Return> returns_out = !if(returns_has_inv_handle,
112+
AppendConditionsToReturn<Returns, PREFIX # "_ERRC_INVALID_NULL_HANDLE", handle_param_conds>.ret,
113+
!listconcat(Returns, [Return<PREFIX # "_ERRC_INVALID_NULL_HANDLE", handle_param_conds>])
114+
);
115+
}
116+
117+
// Add null pointer checks to a function's return value descriptions
118+
class AddPointerChecksToReturns<list<Param> Params, list<Return> Returns> {
119+
list<string> ptr_params =
120+
!foreach(P, Params, !if(ShouldCheckPointer<P>.ret, P.name, ""));
121+
list<string> ptr_params_filt = !filter(param, ptr_params, !ne(param, ""));
122+
list<string> ptr_param_conds =
123+
!foreach(ptr, ptr_params_filt, "`NULL == "#ptr#"`");
124+
125+
// Does the list of returns already contain ERROR_INVALID_NULL_POINTER?
126+
bit returns_has_inv_ptr = !foldl(
127+
0, Returns, HasErr, Ret,
128+
!or(HasErr, !eq(Ret.value, PREFIX#"_ERRC_INVALID_NULL_POINTER")));
129+
list<Return> returns_out = !if(returns_has_inv_ptr,
130+
AppendConditionsToReturn<Returns, PREFIX # "_ERRC_INVALID_NULL_POINTER", ptr_param_conds>.ret,
131+
!listconcat(Returns, [Return<PREFIX # "_ERRC_INVALID_NULL_POINTER", ptr_param_conds>])
132+
);
133+
}
134+
135+
defvar DefaultReturns = [Return<PREFIX#"_RESULT_SUCCESS">,
136+
Return<PREFIX#"_ERRC_UNINITIALIZED">,
137+
Return<PREFIX#"_ERRC_DEVICE_LOST">];
138+
139+
class APIObject {
140+
string name;
141+
string desc;
142+
}
143+
144+
class Function : APIObject {
145+
list<Param> params;
146+
list<Return> returns;
147+
list<string> details = [];
148+
list<string> analogues = [];
149+
150+
list<Return> returns_with_def = !listconcat(DefaultReturns, returns);
151+
list<Return> all_returns = AddPointerChecksToReturns<params,
152+
AddHandleChecksToReturns<params, returns_with_def>.returns_out>.returns_out;
153+
}
154+
155+
class Etor<string Name, string Desc> {
156+
string name = Name;
157+
string desc = Desc;
158+
string tagged_type;
159+
}
160+
161+
class TaggedEtor<string Name, string Type, string Desc> : Etor<Name, Desc> {
162+
let tagged_type = Type;
163+
}
164+
165+
class Enum : APIObject {
166+
// This refers to whether the enumerator descriptions specify a return
167+
// type for functions where this enum may be used as an output type. If set,
168+
// all Etor values must be TaggedEtor records
169+
bit is_typed = 0;
170+
171+
list<Etor> etors = [];
172+
}
173+
174+
class StructMember<string Type, string Name, string Desc> {
175+
string type = Type;
176+
string name = Name;
177+
string desc = Desc;
178+
}
179+
180+
defvar DefaultPropStructMembers =
181+
[StructMember<prefix#"_structure_type_t", "stype",
182+
"type of this structure">,
183+
StructMember<"void*", "pNext", "pointer to extension-specific structure">];
184+
185+
class StructHasInheritedMembers<string BaseClass> {
186+
bit ret = !or(!eq(BaseClass, prefix#"_base_properties_t"),
187+
!eq(BaseClass, prefix#"_base_desc_t"));
188+
}
189+
190+
class Struct : APIObject {
191+
string base_class = "";
192+
list<StructMember> members;
193+
list<StructMember> all_members =
194+
!if(StructHasInheritedMembers<base_class>.ret,
195+
DefaultPropStructMembers, [])#members;
196+
}
197+
198+
class Typedef : APIObject { string value; }
199+
200+
class FptrTypedef : APIObject {
201+
list<Param> params;
202+
list<Return> returns;
203+
}
204+
205+
class Macro : APIObject {
206+
string value;
207+
208+
string condition;
209+
string alt_value;
210+
}
211+
212+
class Handle : APIObject;

‎offload/liboffload/API/CMakeLists.txt‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# The OffloadGenerate target is used to regenerate the generated files in the
2+
# include directory. These files are checked in with the rest of the source,
3+
# therefore it is only needed when making changes to the API.
4+
5+
find_program(CLANG_FORMAT clang-format PATHS ${LLVM_TOOLS_BINARY_DIR} NO_DEFAULT_PATH)
6+
if (CLANG_FORMAT)
7+
set(LLVM_TARGET_DEFINITIONS ${CMAKE_CURRENT_SOURCE_DIR}/OffloadAPI.td)
8+
9+
tablegen(OFFLOAD OffloadAPI.h -gen-api)
10+
tablegen(OFFLOAD OffloadEntryPoints.inc -gen-entry-points)
11+
tablegen(OFFLOAD OffloadFuncs.inc -gen-func-names)
12+
tablegen(OFFLOAD OffloadImplFuncDecls.inc -gen-impl-func-decls)
13+
tablegen(OFFLOAD OffloadPrint.hpp -gen-print-header)
14+
15+
set(OFFLOAD_GENERATED_FILES ${TABLEGEN_OUTPUT})
16+
add_public_tablegen_target(OffloadGenerate)
17+
add_custom_command(TARGET OffloadGenerate POST_BUILD COMMAND ${CLANG_FORMAT}
18+
-i ${OFFLOAD_GENERATED_FILES})
19+
add_custom_command(TARGET OffloadGenerate POST_BUILD COMMAND ${CMAKE_COMMAND}
20+
-E copy_if_different ${OFFLOAD_GENERATED_FILES} "${CMAKE_CURRENT_SOURCE_DIR}/../include/generated")
21+
else()
22+
message(WARNING "clang-format was not found, so the OffloadGenerate target\
23+
will not be available. Offload will still build, but you will not be\
24+
able to make changes to the API.")
25+
endif()

0 commit comments

Comments
 (0)