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