You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Update the main README to reflect the current project status
- Rework the main API generation documentation. General fixes/tidying,
but also spell out explicitly how to make API changes at the top of the
document since this is what most people will care about.
---------
Co-authored-by: Martin Grant <martingrant@outlook.com>
**Note**: This is a work-in-progress. It is loosely based on equivalent
4
-
tooling in Unified Runtime.
5
-
6
3
The Tablegen files in this directory are used to define the Offload API. They
7
4
are used with the `offload-tblgen` tool to generate API headers, print headers,
8
5
and other implementation details.
9
6
10
7
The root file is `OffloadAPI.td` - additional `.td` files can be included in
11
8
this file to add them to the API.
12
9
10
+
## Modifying the API
11
+
12
+
API modifications, including additions, can be made by modifying the existing
13
+
`.td` files. It is also possible to add a new tablegen file to the API by adding
14
+
it to the includes in `OffloadAPI.td`. When Offload is rebuilt the new
15
+
definition will be included in the generated files.
16
+
17
+
Most API changes and additions do not require any additional work beyond this,
18
+
other than new functions which are described below.
19
+
20
+
### Adding a new function to the API
21
+
22
+
When a new function is added (e.g. `offloadDeviceFoo`), the actual entry
23
+
point is automatically generated, which contains validation and tracing code.
24
+
It expects an implementation function (`offloadDeviceFoo_impl`) to be defined,
25
+
which it will call into. The definition of this implementation function should
26
+
be added to `liboffload/src/OffloadImpl.cpp`
27
+
28
+
In short, the steps to add a new function are:
29
+
* Add the new function definition to the `.td` files.
30
+
* Build the `LLVMOffload` target. The relevant files will be regenerated, but
31
+
the library will fail to link because it is missing the implementation
32
+
function.
33
+
* Add the new implementation function to `liboffload/src/OffloadImpl.cpp`. You
34
+
can copy the new function declaration from the generated
35
+
`OffloadImplFuncDecls.inc` file.
36
+
* Rebuild `LLVMOffload`
37
+
13
38
## API Objects
39
+
14
40
The API consists of a number of objects, which always have a *name* field and
15
41
*description* field, and are one of the following types:
16
42
17
43
### Function
44
+
18
45
Represents an API entry point function. Has a list of returns and parameters.
19
-
Also has fields for details (representing a bullet-point list of
20
-
information about the function that would otherwise be too detailed for the
21
-
description), and analogues (equivalent functions in other APIs).
46
+
Also has fields for details (representing a bullet-point list of information
47
+
about the function that would otherwise be too detailed for the description),
48
+
and analogues (equivalent functions in other APIs).
22
49
23
50
#### Parameter
51
+
24
52
Represents a parameter to a function, has *type*, *name*, and *desc* fields.
25
53
Also has a *flags* field containing flags representing whether the parameter is
26
54
in, out, or optional.
@@ -30,17 +58,24 @@ A *handle* type is a pointer to an opaque struct, used to abstract over
30
58
plugin-specific implementation details.
31
59
32
60
There are two special variants of a *parameter*:
33
-
***RangedParameter** - Represents a parameter that has a range described by other parameters. Generally these are pointers to an arbitrary number of objects. The range is used for generating validation and printing code. E.g, a range might be between `(0, NumDevices)`
34
-
***TypeTaggedParameter** - Represents a parameter (usually of `void*` type) that has the type and size of its pointee data described by other function parameters. The type is usually described by a type-tagged enum. This allows functions (e.g. `olGetDeviceInfo`) to return data of an arbitrary type.
61
+
***RangedParameter** - Represents a parameter that has a range described by
62
+
other parameters. Generally these are pointers to an arbitrary number of
63
+
objects. The range is used for generating validation and printing code. E.g,
64
+
a range might be between `(0, NumDevices)`
65
+
***TypeTaggedParameter** - Represents a parameter (usually of `void*` type)
66
+
that has the type and size of its pointee data described by other function
67
+
parameters. The type is usually described by a type-tagged enum. This allows
68
+
functions (e.g. `olGetDeviceInfo`) to return data of an arbitrary type.
35
69
36
70
#### Return
71
+
37
72
A return represents a possible return code from the function, and optionally a
38
73
list of conditions in which this value may be returned. The conditions list is
39
-
not expected to be exhaustive. A condition is considered free-form text, but
40
-
if it is wrapped in \`backticks\` then it is treated as literal code
41
-
representing an error condition (e.g. `someParam < 1`). These conditions are
42
-
used to automatically create validation checks by the `offload-tblgen`
43
-
validation generator.
74
+
not expected to be exhaustive. A condition is considered free-form text, but if
75
+
it is wrapped in \`backticks\` then it is treated as literal code representing
76
+
an error condition (e.g. `someParam < 1`). These conditions are used to
77
+
automatically create validation checks by the `offload-tblgen` validation
78
+
generator.
44
79
45
80
Returns are automatically generated for functions with pointer or handle
46
81
parameters, so API authors do not need to exhaustively add null checks for
@@ -49,6 +84,7 @@ values automatically.
49
84
50
85
51
86
### Struct
87
+
52
88
Represents a struct. Contains a list of members, which each have a *type*,
53
89
*name*, and *desc*.
54
90
@@ -59,24 +95,28 @@ actual C++ inheritance, but instead explicitly has those members copied in,
59
95
which preserves ABI compatibility with C.
60
96
61
97
### Enum
98
+
62
99
Represents a C-style enum. Contains a list of `etor` values, which have a name
63
100
and description.
64
101
65
-
A `TaggedEtor` record type also exists which additionally takes a type. This type
66
-
is used when the enum is used as a parameter to a function with a type-tagged
67
-
function parameter (e.g. `olGetDeviceInfo`).
102
+
A `TaggedEtor` record type also exists which additionally takes a type. This
103
+
type is used when the enum is used as a parameter to a function with a
104
+
type-tagged function parameter (e.g. `olGetDeviceInfo`).
68
105
69
106
All enums automatically get a `<enum_name>_FORCE_UINT32 = 0x7fffffff` value,
70
107
which forces the underlying type to be uint32.
71
108
72
109
### Handle
110
+
73
111
Represents a pointer to an opaque struct, as described in the Parameter section.
74
112
It does not take any extra fields.
75
113
76
114
### Typedef
115
+
77
116
Represents a typedef, contains only a *value* field.
78
117
79
118
### Macro
119
+
80
120
Represents a C preprocessor `#define`. Contains a *value* field. Optionally
81
121
takes a *condition* field, which allows the macro to be conditionally defined,
82
122
and an *alt_value* field, which represents the value if the condition is false.
@@ -90,15 +130,20 @@ files, rather than requiring a mix of C source and tablegen.
The comments in the generated header are in Doxygen format, although
97
138
generating documentation from them hasn't been implemented yet.
98
139
99
-
The entirety of this header is generated by Tablegen, rather than having a predefined header file that includes one or more `.inc` files. This is because this header is expected to be part of the installation and distributed to end-users, so should be self-contained.
140
+
The entirety of this header is generated by Tablegen, rather than having a
141
+
predefined header file that includes one or more `.inc` files. This is because
142
+
this header is expected to be part of the installation and distributed to
0 commit comments