224 lines · plain
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-exception6//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 value16// is agreed upon.17defvar PREFIX = "OL";18defvar prefix = !tolower(PREFIX);19 20// Parameter flags21defvar PARAM_IN = 0x1;22defvar PARAM_OUT = 0x2;23defvar PARAM_OPTIONAL = 0x4;24defvar PARAM_IN_OPTIONAL = !or(PARAM_IN, PARAM_OPTIONAL);25defvar PARAM_OUT_OPTIONAL = !or(PARAM_OUT, PARAM_OPTIONAL);26 27// Does the type end with '_handle_t'?28class IsHandleType<string Type> {29 // size("_handle_t") == 930 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 '_cb_t'?35class IsCallbackType<string Type> {36 // size("_cb_t") == 537 bit ret = !if(!lt(!size(Type), 5), 0,38 !ne(!find(Type, "_cb_t", !sub(!size(Type), 5)), -1));39}40 41// Does the type end with '*'?42class IsPointerType<string Type> {43 bit ret = !ne(!find(Type, "*", !sub(!size(Type), 1)), -1);44}45 46// Describes the valid range of a pointer parameter that represents an array47class Range<string Begin, string End> {48 string begin = Begin;49 string end = End;50}51 52// Names the parameters that indicate the type and size of the data pointed to53// by an opaque pointer parameter54class TypeInfo<string TypeEnum, string TypeSize> {55 string enum = TypeEnum;56 string size = TypeSize;57}58 59class Param<string Type, string Name, string Desc, bits<3> Flags = 0> {60 string type = Type;61 string name = Name;62 string desc = Desc;63 bits<3> flags = Flags;64 Range range = Range<"", "">;65 TypeInfo type_info = TypeInfo<"", "">;66 bit IsHandle = IsHandleType<type>.ret;67 bit IsPointer = IsPointerType<type>.ret;68 bit IsCallback = IsCallbackType<type>.ret;69}70 71// A parameter whose range is described by other parameters in the function.72class RangedParam<string Type, string Name, string Desc, bits<3> Flags, Range ParamRange> : Param<Type, Name, Desc, Flags> {73 let range = ParamRange;74}75 76// A parameter (normally of type void*) which has its pointee type and size77// described by other parameters in the function.78class TypeTaggedParam<string Type, string Name, string Desc, bits<3> Flags, TypeInfo ParamTypeInfo> : Param<Type, Name, Desc, Flags> {79 let type_info = ParamTypeInfo;80}81 82class Return<string Value, list<string> Conditions = []> {83 string value = Value;84 list<string> conditions = Conditions;85}86 87class ShouldCheckHandle<Param P> {88 bit ret = !and(P.IsHandle, !eq(!and(PARAM_OPTIONAL, P.flags), 0));89}90 91class ShouldCheckPointer<Param P> {92 bit ret = !and(!or(P.IsPointer, P.IsCallback), !eq(!and(PARAM_OPTIONAL, P.flags), 0));93}94 95// For a list of returns that contains a specific return code, find and append96// new conditions to that return97class AppendConditionsToReturn<list<Return> Returns, string ReturnValue,98 list<string> Conditions> {99 list<Return> ret =100 !foreach(Ret, Returns,101 !if(!eq(Ret.value, ReturnValue),102 Return<Ret.value, Ret.conditions#Conditions>, Ret));103}104 105// Add null handle checks to a function's return value descriptions106class AddHandleChecksToReturns<list<Param> Params, list<Return> Returns> {107 list<string> handle_params =108 !foreach(P, Params, !if(ShouldCheckHandle<P>.ret, P.name, ""));109 list<string> handle_params_filt =110 !filter(param, handle_params, !ne(param, ""));111 list<string> handle_param_conds =112 !foreach(handle, handle_params_filt, "`NULL == "#handle#"`");113 114 // Does the list of returns already contain ERROR_INVALID_NULL_HANDLE?115 bit returns_has_inv_handle = !foldl(116 0, Returns, HasErr, Ret,117 !or(HasErr, !eq(Ret.value, PREFIX#"_ERRC_INVALID_NULL_HANDLE")));118 119 list<Return> returns_out = !if(returns_has_inv_handle,120 AppendConditionsToReturn<Returns, PREFIX # "_ERRC_INVALID_NULL_HANDLE", handle_param_conds>.ret,121 !listconcat(Returns, [Return<PREFIX # "_ERRC_INVALID_NULL_HANDLE", handle_param_conds>])122 );123}124 125// Add null pointer checks to a function's return value descriptions126class AddPointerChecksToReturns<list<Param> Params, list<Return> Returns> {127 list<string> ptr_params =128 !foreach(P, Params, !if(ShouldCheckPointer<P>.ret, P.name, ""));129 list<string> ptr_params_filt = !filter(param, ptr_params, !ne(param, ""));130 list<string> ptr_param_conds =131 !foreach(ptr, ptr_params_filt, "`NULL == "#ptr#"`");132 133 // Does the list of returns already contain ERROR_INVALID_NULL_POINTER?134 bit returns_has_inv_ptr = !foldl(135 0, Returns, HasErr, Ret,136 !or(HasErr, !eq(Ret.value, PREFIX#"_ERRC_INVALID_NULL_POINTER")));137 list<Return> returns_out = !if(returns_has_inv_ptr,138 AppendConditionsToReturn<Returns, PREFIX # "_ERRC_INVALID_NULL_POINTER", ptr_param_conds>.ret,139 !listconcat(Returns, [Return<PREFIX # "_ERRC_INVALID_NULL_POINTER", ptr_param_conds>])140 );141}142 143defvar DefaultReturns = [Return<PREFIX#"_RESULT_SUCCESS">,144 Return<PREFIX#"_ERRC_UNINITIALIZED">,145 Return<PREFIX#"_ERRC_DEVICE_LOST">];146 147class APIObject {148 string desc;149}150 151class Function : APIObject {152 list<Param> params;153 list<Return> returns;154 list<string> details = [];155 list<string> analogues = [];156 157 list<Return> returns_with_def = !listconcat(DefaultReturns, returns);158 list<Return> all_returns = AddPointerChecksToReturns<params,159 AddHandleChecksToReturns<params, returns_with_def>.returns_out>.returns_out;160}161 162class Etor<string Name, string Desc> {163 string name = Name;164 string desc = Desc;165 string tagged_type;166}167 168class TaggedEtor<string Name, string Type, string Desc> : Etor<Name, Desc> {169 let tagged_type = Type;170}171 172class Enum : APIObject {173 // This refers to whether the enumerator descriptions specify a return174 // type for functions where this enum may be used as an output type. If set,175 // all Etor values must be TaggedEtor records176 bit is_typed = 0;177 178 // This refers to whether the enumerator is used to name bits of a bit field,179 // where consecutive values are bit-shifted rather than incremented.180 bit is_bit_field = 0;181 182 list<Etor> etors = [];183}184 185class StructMember<string Type, string Name, string Desc> {186 string type = Type;187 string name = Name;188 string desc = Desc;189}190 191defvar DefaultPropStructMembers =192 [StructMember<prefix#"_structure_type_t", "stype",193 "type of this structure">,194 StructMember<"void*", "pNext", "pointer to extension-specific structure">];195 196class StructHasInheritedMembers<string BaseClass> {197 bit ret = !or(!eq(BaseClass, prefix#"_base_properties_t"),198 !eq(BaseClass, prefix#"_base_desc_t"));199}200 201class Struct : APIObject {202 string base_class = "";203 list<StructMember> members;204 list<StructMember> all_members =205 !if(StructHasInheritedMembers<base_class>.ret,206 DefaultPropStructMembers, [])#members;207}208 209class Typedef : APIObject { string value; }210 211class FptrTypedef : APIObject {212 list<Param> params;213 string return;214}215 216class Macro : APIObject {217 string value;218 219 string condition;220 string alt_value;221}222 223class Handle : APIObject;224