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