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