include/llvm/Support/AMDGPUMetadata.h

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