1//===--- AMDGPUMetadata.h ---------------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10/// \file
11/// \brief AMDGPU metadata definitions and in-memory representations.
12///
13//
14//===----------------------------------------------------------------------===//
15
16#ifndef LLVM_SUPPORT_AMDGPUMETADATA_H
17#define LLVM_SUPPORT_AMDGPUMETADATA_H
18
19#include <cstdint>
20#include <string>
21#include <system_error>
22#include <vector>
23
24namespace llvm {
25namespace AMDGPU {
26
27//===----------------------------------------------------------------------===//
28// HSA metadata.
29//===----------------------------------------------------------------------===//
30namespace HSAMD {
31
32/// \brief HSA metadata major version.
33constexpr uint32_t VersionMajor = 1;
34/// \brief HSA metadata minor version.
35constexpr uint32_t VersionMinor = 0;
36
37/// \brief HSA metadata beginning assembler directive.
38constexpr char AssemblerDirectiveBegin[] = ".amd_amdgpu_hsa_metadata";
39/// \brief HSA metadata ending assembler directive.
40constexpr char AssemblerDirectiveEnd[] = ".end_amd_amdgpu_hsa_metadata";
41
42/// \brief Access qualifiers.
43enum class AccessQualifier : uint8_t {
44  Default   = 0,
45  ReadOnly  = 1,
46  WriteOnly = 2,
47  ReadWrite = 3,
48  Unknown   = 0xff
49};
50
51/// \brief Address space qualifiers.
52enum class AddressSpaceQualifier : uint8_t {
53  Private  = 0,
54  Global   = 1,
55  Constant = 2,
56  Local    = 3,
57  Generic  = 4,
58  Region   = 5,
59  Unknown  = 0xff
60};
61
62/// \brief Value kinds.
63enum class ValueKind : uint8_t {
64  ByValue                = 0,
65  GlobalBuffer           = 1,
66  DynamicSharedPointer   = 2,
67  Sampler                = 3,
68  Image                  = 4,
69  Pipe                   = 5,
70  Queue                  = 6,
71  HiddenGlobalOffsetX    = 7,
72  HiddenGlobalOffsetY    = 8,
73  HiddenGlobalOffsetZ    = 9,
74  HiddenNone             = 10,
75  HiddenPrintfBuffer     = 11,
76  HiddenDefaultQueue     = 12,
77  HiddenCompletionAction = 13,
78  Unknown                = 0xff
79};
80
81/// \brief Value types.
82enum class ValueType : uint8_t {
83  Struct  = 0,
84  I8      = 1,
85  U8      = 2,
86  I16     = 3,
87  U16     = 4,
88  F16     = 5,
89  I32     = 6,
90  U32     = 7,
91  F32     = 8,
92  I64     = 9,
93  U64     = 10,
94  F64     = 11,
95  Unknown = 0xff
96};
97
98//===----------------------------------------------------------------------===//
99// Kernel Metadata.
100//===----------------------------------------------------------------------===//
101namespace Kernel {
102
103//===----------------------------------------------------------------------===//
104// Kernel Attributes Metadata.
105//===----------------------------------------------------------------------===//
106namespace Attrs {
107
108namespace Key {
109/// \brief Key for Kernel::Attr::Metadata::mReqdWorkGroupSize.
110constexpr char ReqdWorkGroupSize[] = "ReqdWorkGroupSize";
111/// \brief Key for Kernel::Attr::Metadata::mWorkGroupSizeHint.
112constexpr char WorkGroupSizeHint[] = "WorkGroupSizeHint";
113/// \brief Key for Kernel::Attr::Metadata::mVecTypeHint.
114constexpr char VecTypeHint[] = "VecTypeHint";
115/// \brief Key for Kernel::Attr::Metadata::mRuntimeHandle.
116constexpr char RuntimeHandle[] = "RuntimeHandle";
117} // end namespace Key
118
119/// \brief In-memory representation of kernel attributes metadata.
120struct Metadata final {
121  /// \brief 'reqd_work_group_size' attribute. Optional.
122  std::vector<uint32_t> mReqdWorkGroupSize = std::vector<uint32_t>();
123  /// \brief 'work_group_size_hint' attribute. Optional.
124  std::vector<uint32_t> mWorkGroupSizeHint = std::vector<uint32_t>();
125  /// \brief 'vec_type_hint' attribute. Optional.
126  std::string mVecTypeHint = std::string();
127  /// \brief External symbol created by runtime to store the kernel address
128  /// for enqueued blocks.
129  std::string mRuntimeHandle = std::string();
130
131  /// \brief Default constructor.
132  Metadata() = default;
133
134  /// \returns True if kernel attributes metadata is empty, false otherwise.
135  bool empty() const {
136    return !notEmpty();
137  }
138
139  /// \returns True if kernel attributes metadata is not empty, false otherwise.
140  bool notEmpty() const {
141    return !mReqdWorkGroupSize.empty() || !mWorkGroupSizeHint.empty() ||
142           !mVecTypeHint.empty() || !mRuntimeHandle.empty();
143  }
144};
145
146} // end namespace Attrs
147
148//===----------------------------------------------------------------------===//
149// Kernel Argument Metadata.
150//===----------------------------------------------------------------------===//
151namespace Arg {
152
153namespace Key {
154/// \brief Key for Kernel::Arg::Metadata::mName.
155constexpr char Name[] = "Name";
156/// \brief Key for Kernel::Arg::Metadata::mTypeName.
157constexpr char TypeName[] = "TypeName";
158/// \brief Key for Kernel::Arg::Metadata::mSize.
159constexpr char Size[] = "Size";
160/// \brief Key for Kernel::Arg::Metadata::mAlign.
161constexpr char Align[] = "Align";
162/// \brief Key for Kernel::Arg::Metadata::mValueKind.
163constexpr char ValueKind[] = "ValueKind";
164/// \brief Key for Kernel::Arg::Metadata::mValueType.
165constexpr char ValueType[] = "ValueType";
166/// \brief Key for Kernel::Arg::Metadata::mPointeeAlign.
167constexpr char PointeeAlign[] = "PointeeAlign";
168/// \brief Key for Kernel::Arg::Metadata::mAddrSpaceQual.
169constexpr char AddrSpaceQual[] = "AddrSpaceQual";
170/// \brief Key for Kernel::Arg::Metadata::mAccQual.
171constexpr char AccQual[] = "AccQual";
172/// \brief Key for Kernel::Arg::Metadata::mActualAccQual.
173constexpr char ActualAccQual[] = "ActualAccQual";
174/// \brief Key for Kernel::Arg::Metadata::mIsConst.
175constexpr char IsConst[] = "IsConst";
176/// \brief Key for Kernel::Arg::Metadata::mIsRestrict.
177constexpr char IsRestrict[] = "IsRestrict";
178/// \brief Key for Kernel::Arg::Metadata::mIsVolatile.
179constexpr char IsVolatile[] = "IsVolatile";
180/// \brief Key for Kernel::Arg::Metadata::mIsPipe.
181constexpr char IsPipe[] = "IsPipe";
182} // end namespace Key
183
184/// \brief In-memory representation of kernel argument metadata.
185struct Metadata final {
186  /// \brief Name. Optional.
187  std::string mName = std::string();
188  /// \brief Type name. Optional.
189  std::string mTypeName = std::string();
190  /// \brief Size in bytes. Required.
191  uint32_t mSize = 0;
192  /// \brief Alignment in bytes. Required.
193  uint32_t mAlign = 0;
194  /// \brief Value kind. Required.
195  ValueKind mValueKind = ValueKind::Unknown;
196  /// \brief Value type. Required.
197  ValueType mValueType = ValueType::Unknown;
198  /// \brief Pointee alignment in bytes. Optional.
199  uint32_t mPointeeAlign = 0;
200  /// \brief Address space qualifier. Optional.
201  AddressSpaceQualifier mAddrSpaceQual = AddressSpaceQualifier::Unknown;
202  /// \brief Access qualifier. Optional.
203  AccessQualifier mAccQual = AccessQualifier::Unknown;
204  /// \brief Actual access qualifier. Optional.
205  AccessQualifier mActualAccQual = AccessQualifier::Unknown;
206  /// \brief True if 'const' qualifier is specified. Optional.
207  bool mIsConst = false;
208  /// \brief True if 'restrict' qualifier is specified. Optional.
209  bool mIsRestrict = false;
210  /// \brief True if 'volatile' qualifier is specified. Optional.
211  bool mIsVolatile = false;
212  /// \brief True if 'pipe' qualifier is specified. Optional.
213  bool mIsPipe = false;
214
215  /// \brief Default constructor.
216  Metadata() = default;
217};
218
219} // end namespace Arg
220
221//===----------------------------------------------------------------------===//
222// Kernel Code Properties Metadata.
223//===----------------------------------------------------------------------===//
224namespace CodeProps {
225
226namespace Key {
227/// \brief Key for Kernel::CodeProps::Metadata::mKernargSegmentSize.
228constexpr char KernargSegmentSize[] = "KernargSegmentSize";
229/// \brief Key for Kernel::CodeProps::Metadata::mGroupSegmentFixedSize.
230constexpr char GroupSegmentFixedSize[] = "GroupSegmentFixedSize";
231/// \brief Key for Kernel::CodeProps::Metadata::mPrivateSegmentFixedSize.
232constexpr char PrivateSegmentFixedSize[] = "PrivateSegmentFixedSize";
233/// \brief Key for Kernel::CodeProps::Metadata::mKernargSegmentAlign.
234constexpr char KernargSegmentAlign[] = "KernargSegmentAlign";
235/// \brief Key for Kernel::CodeProps::Metadata::mWavefrontSize.
236constexpr char WavefrontSize[] = "WavefrontSize";
237/// \brief Key for Kernel::CodeProps::Metadata::mNumSGPRs.
238constexpr char NumSGPRs[] = "NumSGPRs";
239/// \brief Key for Kernel::CodeProps::Metadata::mNumVGPRs.
240constexpr char NumVGPRs[] = "NumVGPRs";
241/// \brief Key for Kernel::CodeProps::Metadata::mMaxFlatWorkGroupSize.
242constexpr char MaxFlatWorkGroupSize[] = "MaxFlatWorkGroupSize";
243/// \brief Key for Kernel::CodeProps::Metadata::mIsDynamicCallStack.
244constexpr char IsDynamicCallStack[] = "IsDynamicCallStack";
245/// \brief Key for Kernel::CodeProps::Metadata::mIsXNACKEnabled.
246constexpr char IsXNACKEnabled[] = "IsXNACKEnabled";
247} // end namespace Key
248
249/// \brief In-memory representation of kernel code properties metadata.
250struct Metadata final {
251  /// \brief Size in bytes of the kernarg segment memory. Kernarg segment memory
252  /// holds the values of the arguments to the kernel. Required.
253  uint64_t mKernargSegmentSize = 0;
254  /// \brief Size in bytes of the group segment memory required by a workgroup.
255  /// This value does not include any dynamically allocated group segment memory
256  /// that may be added when the kernel is dispatched. Required.
257  uint32_t mGroupSegmentFixedSize = 0;
258  /// \brief Size in bytes of the private segment memory required by a workitem.
259  /// Private segment memory includes arg, spill and private segments. Required.
260  uint32_t mPrivateSegmentFixedSize = 0;
261  /// \brief Maximum byte alignment of variables used by the kernel in the
262  /// kernarg memory segment. Required.
263  uint32_t mKernargSegmentAlign = 0;
264  /// \brief Wavefront size. Required.
265  uint32_t mWavefrontSize = 0;
266  /// \brief Total number of SGPRs used by a wavefront. Optional.
267  uint16_t mNumSGPRs = 0;
268  /// \brief Total number of VGPRs used by a workitem. Optional.
269  uint16_t mNumVGPRs = 0;
270  /// \brief Maximum flat work-group size supported by the kernel. Optional.
271  uint32_t mMaxFlatWorkGroupSize = 0;
272  /// \brief True if the generated machine code is using a dynamically sized
273  /// call stack. Optional.
274  bool mIsDynamicCallStack = false;
275  /// \brief True if the generated machine code is capable of supporting XNACK.
276  /// Optional.
277  bool mIsXNACKEnabled = false;
278
279  /// \brief Default constructor.
280  Metadata() = default;
281
282  /// \returns True if kernel code properties metadata is empty, false
283  /// otherwise.
284  bool empty() const {
285    return !notEmpty();
286  }
287
288  /// \returns True if kernel code properties metadata is not empty, false
289  /// otherwise.
290  bool notEmpty() const {
291    return true;
292  }
293};
294
295} // end namespace CodeProps
296
297//===----------------------------------------------------------------------===//
298// Kernel Debug Properties Metadata.
299//===----------------------------------------------------------------------===//
300namespace DebugProps {
301
302namespace Key {
303/// \brief Key for Kernel::DebugProps::Metadata::mDebuggerABIVersion.
304constexpr char DebuggerABIVersion[] = "DebuggerABIVersion";
305/// \brief Key for Kernel::DebugProps::Metadata::mReservedNumVGPRs.
306constexpr char ReservedNumVGPRs[] = "ReservedNumVGPRs";
307/// \brief Key for Kernel::DebugProps::Metadata::mReservedFirstVGPR.
308constexpr char ReservedFirstVGPR[] = "ReservedFirstVGPR";
309/// \brief Key for Kernel::DebugProps::Metadata::mPrivateSegmentBufferSGPR.
310constexpr char PrivateSegmentBufferSGPR[] = "PrivateSegmentBufferSGPR";
311/// \brief Key for
312///     Kernel::DebugProps::Metadata::mWavefrontPrivateSegmentOffsetSGPR.
313constexpr char WavefrontPrivateSegmentOffsetSGPR[] =
314    "WavefrontPrivateSegmentOffsetSGPR";
315} // end namespace Key
316
317/// \brief In-memory representation of kernel debug properties metadata.
318struct Metadata final {
319  /// \brief Debugger ABI version. Optional.
320  std::vector<uint32_t> mDebuggerABIVersion = std::vector<uint32_t>();
321  /// \brief Consecutive number of VGPRs reserved for debugger use. Must be 0 if
322  /// mDebuggerABIVersion is not set. Optional.
323  uint16_t mReservedNumVGPRs = 0;
324  /// \brief First fixed VGPR reserved. Must be uint16_t(-1) if
325  /// mDebuggerABIVersion is not set or mReservedFirstVGPR is 0. Optional.
326  uint16_t mReservedFirstVGPR = uint16_t(-1);
327  /// \brief Fixed SGPR of the first of 4 SGPRs used to hold the scratch V# used
328  /// for the entire kernel execution. Must be uint16_t(-1) if
329  /// mDebuggerABIVersion is not set or SGPR not used or not known. Optional.
330  uint16_t mPrivateSegmentBufferSGPR = uint16_t(-1);
331  /// \brief Fixed SGPR used to hold the wave scratch offset for the entire
332  /// kernel execution. Must be uint16_t(-1) if mDebuggerABIVersion is not set
333  /// or SGPR is not used or not known. Optional.
334  uint16_t mWavefrontPrivateSegmentOffsetSGPR = uint16_t(-1);
335
336  /// \brief Default constructor.
337  Metadata() = default;
338
339  /// \returns True if kernel debug properties metadata is empty, false
340  /// otherwise.
341  bool empty() const {
342    return !notEmpty();
343  }
344
345  /// \returns True if kernel debug properties metadata is not empty, false
346  /// otherwise.
347  bool notEmpty() const {
348    return !mDebuggerABIVersion.empty();
349  }
350};
351
352} // end namespace DebugProps
353
354namespace Key {
355/// \brief Key for Kernel::Metadata::mName.
356constexpr char Name[] = "Name";
357/// \brief Key for Kernel::Metadata::mSymbolName.
358constexpr char SymbolName[] = "SymbolName";
359/// \brief Key for Kernel::Metadata::mLanguage.
360constexpr char Language[] = "Language";
361/// \brief Key for Kernel::Metadata::mLanguageVersion.
362constexpr char LanguageVersion[] = "LanguageVersion";
363/// \brief Key for Kernel::Metadata::mAttrs.
364constexpr char Attrs[] = "Attrs";
365/// \brief Key for Kernel::Metadata::mArgs.
366constexpr char Args[] = "Args";
367/// \brief Key for Kernel::Metadata::mCodeProps.
368constexpr char CodeProps[] = "CodeProps";
369/// \brief Key for Kernel::Metadata::mDebugProps.
370constexpr char DebugProps[] = "DebugProps";
371} // end namespace Key
372
373/// \brief In-memory representation of kernel metadata.
374struct Metadata final {
375  /// \brief Kernel source name. Required.
376  std::string mName = std::string();
377  /// \brief Kernel descriptor name. Required.
378  std::string mSymbolName = std::string();
379  /// \brief Language. Optional.
380  std::string mLanguage = std::string();
381  /// \brief Language version. Optional.
382  std::vector<uint32_t> mLanguageVersion = std::vector<uint32_t>();
383  /// \brief Attributes metadata. Optional.
384  Attrs::Metadata mAttrs = Attrs::Metadata();
385  /// \brief Arguments metadata. Optional.
386  std::vector<Arg::Metadata> mArgs = std::vector<Arg::Metadata>();
387  /// \brief Code properties metadata. Optional.
388  CodeProps::Metadata mCodeProps = CodeProps::Metadata();
389  /// \brief Debug properties metadata. Optional.
390  DebugProps::Metadata mDebugProps = DebugProps::Metadata();
391
392  /// \brief Default constructor.
393  Metadata() = default;
394};
395
396} // end namespace Kernel
397
398namespace Key {
399/// \brief Key for HSA::Metadata::mVersion.
400constexpr char Version[] = "Version";
401/// \brief Key for HSA::Metadata::mPrintf.
402constexpr char Printf[] = "Printf";
403/// \brief Key for HSA::Metadata::mKernels.
404constexpr char Kernels[] = "Kernels";
405} // end namespace Key
406
407/// \brief In-memory representation of HSA metadata.
408struct Metadata final {
409  /// \brief HSA metadata version. Required.
410  std::vector<uint32_t> mVersion = std::vector<uint32_t>();
411  /// \brief Printf metadata. Optional.
412  std::vector<std::string> mPrintf = std::vector<std::string>();
413  /// \brief Kernels metadata. Required.
414  std::vector<Kernel::Metadata> mKernels = std::vector<Kernel::Metadata>();
415
416  /// \brief Default constructor.
417  Metadata() = default;
418};
419
420/// \brief Converts \p String to \p HSAMetadata.
421std::error_code fromString(std::string String, Metadata &HSAMetadata);
422
423/// \brief Converts \p HSAMetadata to \p String.
424std::error_code toString(Metadata HSAMetadata, std::string &String);
425
426} // end namespace HSAMD
427
428//===----------------------------------------------------------------------===//
429// PAL metadata.
430//===----------------------------------------------------------------------===//
431namespace PALMD {
432
433/// \brief PAL metadata assembler directive.
434constexpr char AssemblerDirective[] = ".amd_amdgpu_pal_metadata";
435
436/// \brief PAL metadata keys.
437enum Key : uint32_t {
438  LS_NUM_USED_VGPRS = 0x10000015,
439  HS_NUM_USED_VGPRS = 0x10000016,
440  ES_NUM_USED_VGPRS = 0x10000017,
441  GS_NUM_USED_VGPRS = 0x10000018,
442  VS_NUM_USED_VGPRS = 0x10000019,
443  PS_NUM_USED_VGPRS = 0x1000001a,
444  CS_NUM_USED_VGPRS = 0x1000001b,
445
446  LS_NUM_USED_SGPRS = 0x1000001c,
447  HS_NUM_USED_SGPRS = 0x1000001d,
448  ES_NUM_USED_SGPRS = 0x1000001e,
449  GS_NUM_USED_SGPRS = 0x1000001f,
450  VS_NUM_USED_SGPRS = 0x10000020,
451  PS_NUM_USED_SGPRS = 0x10000021,
452  CS_NUM_USED_SGPRS = 0x10000022,
453
454  LS_SCRATCH_SIZE = 0x10000038,
455  HS_SCRATCH_SIZE = 0x10000039,
456  ES_SCRATCH_SIZE = 0x1000003a,
457  GS_SCRATCH_SIZE = 0x1000003b,
458  VS_SCRATCH_SIZE = 0x1000003c,
459  PS_SCRATCH_SIZE = 0x1000003d,
460  CS_SCRATCH_SIZE = 0x1000003e
461};
462
463/// \brief PAL metadata represented as a vector.
464typedef std::vector<uint32_t> Metadata;
465
466/// \brief Converts \p PALMetadata to \p String.
467std::error_code toString(const Metadata &PALMetadata, std::string &String);
468
469} // end namespace PALMD
470} // end namespace AMDGPU
471} // end namespace llvm
472
473#endif // LLVM_SUPPORT_AMDGPUMETADATA_H
474