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