//===-- AMDGPURuntimeMetadata.h - AMDGPU Runtime Metadata -------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
//
/// \file
///
/// Enums and structure types used by runtime metadata.
///
/// Runtime requests certain information (metadata) about kernels to be able
/// to execute the kernels and answer the queries about the kernels.
/// The metadata is represented as a note element in the .note ELF section of a
/// binary (code object). The desc field of the note element is a YAML string
/// consisting of key-value pairs. Each key is a string. Each value can be
/// an integer, a string, or an YAML sequence. There are 3 levels of YAML maps.
/// At the beginning of the YAML string is the module level YAML map. A
/// kernel-level YAML map is in the amd.Kernels sequence. A
/// kernel-argument-level map is in the amd.Args sequence.
///
/// The format should be kept backward compatible. New enum values and bit
/// fields should be appended at the end. It is suggested to bump up the
/// revision number whenever the format changes and document the change
/// in the revision in this header.
///
//
//===----------------------------------------------------------------------===//
//
#ifndef LLVM_LIB_TARGET_AMDGPU_AMDGPURUNTIMEMETADATA_H
#define LLVM_LIB_TARGET_AMDGPU_AMDGPURUNTIMEMETADATA_H

#include <cstdint>
#include <vector>
#include <string>

namespace AMDGPU {
namespace RuntimeMD {

  // Version and revision of runtime metadata
  const unsigned char MDVersion   = 2;
  const unsigned char MDRevision  = 1;

  // Name of keys for runtime metadata.
  namespace KeyName {

    // Runtime metadata version
    const char MDVersion[] = "amd.MDVersion";

    // Instruction set architecture information
    const char IsaInfo[] = "amd.IsaInfo";
    // Wavefront size
    const char IsaInfoWavefrontSize[] = "amd.IsaInfoWavefrontSize";
    // Local memory size in bytes
    const char IsaInfoLocalMemorySize[] = "amd.IsaInfoLocalMemorySize";
    // Number of execution units per compute unit
    const char IsaInfoEUsPerCU[] = "amd.IsaInfoEUsPerCU";
    // Maximum number of waves per execution unit
    const char IsaInfoMaxWavesPerEU[] = "amd.IsaInfoMaxWavesPerEU";
    // Maximum flat work group size
    const char IsaInfoMaxFlatWorkGroupSize[] = "amd.IsaInfoMaxFlatWorkGroupSize";
    // SGPR allocation granularity
    const char IsaInfoSGPRAllocGranule[] = "amd.IsaInfoSGPRAllocGranule";
    // Total number of SGPRs
    const char IsaInfoTotalNumSGPRs[] = "amd.IsaInfoTotalNumSGPRs";
    // Addressable number of SGPRs
    const char IsaInfoAddressableNumSGPRs[] = "amd.IsaInfoAddressableNumSGPRs";
    // VGPR allocation granularity
    const char IsaInfoVGPRAllocGranule[] = "amd.IsaInfoVGPRAllocGranule";
    // Total number of VGPRs
    const char IsaInfoTotalNumVGPRs[] = "amd.IsaInfoTotalNumVGPRs";
    // Addressable number of VGPRs
    const char IsaInfoAddressableNumVGPRs[] = "amd.IsaInfoAddressableNumVGPRs";

    // Language
    const char Language[] = "amd.Language";
    // Language version
    const char LanguageVersion[] = "amd.LanguageVersion";

    // Kernels
    const char Kernels[] = "amd.Kernels";
    // Kernel name
    const char KernelName[] = "amd.KernelName";
    // Kernel arguments
    const char Args[] = "amd.Args";
    // Kernel argument size in bytes
    const char ArgSize[] = "amd.ArgSize";
    // Kernel argument alignment
    const char ArgAlign[] = "amd.ArgAlign";
    // Kernel argument type name
    const char ArgTypeName[] = "amd.ArgTypeName";
    // Kernel argument name
    const char ArgName[] = "amd.ArgName";
    // Kernel argument kind
    const char ArgKind[] = "amd.ArgKind";
    // Kernel argument value type
    const char ArgValueType[] = "amd.ArgValueType";
    // Kernel argument address qualifier
    const char ArgAddrQual[] = "amd.ArgAddrQual";
    // Kernel argument access qualifier
    const char ArgAccQual[] = "amd.ArgAccQual";
    // Kernel argument is const qualified
    const char ArgIsConst[] = "amd.ArgIsConst";
    // Kernel argument is restrict qualified
    const char ArgIsRestrict[] = "amd.ArgIsRestrict";
    // Kernel argument is volatile qualified
    const char ArgIsVolatile[] = "amd.ArgIsVolatile";
    // Kernel argument is pipe qualified
    const char ArgIsPipe[] = "amd.ArgIsPipe";
    // Required work group size
    const char ReqdWorkGroupSize[] = "amd.ReqdWorkGroupSize";
    // Work group size hint
    const char WorkGroupSizeHint[] = "amd.WorkGroupSizeHint";
    // Vector type hint
    const char VecTypeHint[] = "amd.VecTypeHint";
    // Kernel index for device enqueue
    const char KernelIndex[] = "amd.KernelIndex";
    // No partial work groups
    const char NoPartialWorkGroups[] = "amd.NoPartialWorkGroups";
    // Prinf function call information
    const char PrintfInfo[] = "amd.PrintfInfo";
    // The actual kernel argument access qualifier
    const char ArgActualAcc[] = "amd.ArgActualAcc";
    // Alignment of pointee type
    const char ArgPointeeAlign[] = "amd.ArgPointeeAlign";

  } // end namespace KeyName

  namespace KernelArg {

    enum Kind : uint8_t {
      ByValue                 = 0,
      GlobalBuffer            = 1,
      DynamicSharedPointer    = 2,
      Sampler                 = 3,
      Image                   = 4,
      Pipe                    = 5,
      Queue                   = 6,
      HiddenGlobalOffsetX     = 7,
      HiddenGlobalOffsetY     = 8,
      HiddenGlobalOffsetZ     = 9,
      HiddenNone              = 10,
      HiddenPrintfBuffer      = 11,
      HiddenDefaultQueue      = 12,
      HiddenCompletionAction  = 13,
    };

    enum ValueType : uint16_t {
      Struct  = 0,
      I8      = 1,
      U8      = 2,
      I16     = 3,
      U16     = 4,
      F16     = 5,
      I32     = 6,
      U32     = 7,
      F32     = 8,
      I64     = 9,
      U64     = 10,
      F64     = 11,
    };

    // Avoid using 'None' since it conflicts with a macro in X11 header file.
    enum AccessQualifer : uint8_t {
      AccNone    = 0,
      ReadOnly   = 1,
      WriteOnly  = 2,
      ReadWrite  = 3,
    };

    enum AddressSpaceQualifer : uint8_t {
      Private    = 0,
      Global     = 1,
      Constant   = 2,
      Local      = 3,
      Generic    = 4,
      Region     = 5,
    };

  } // end namespace KernelArg

  // Invalid values are used to indicate an optional key should not be emitted.
  const uint8_t INVALID_ADDR_QUAL     = 0xff;
  const uint8_t INVALID_ACC_QUAL      = 0xff;
  const uint32_t INVALID_KERNEL_INDEX = ~0U;

  namespace KernelArg {

    // In-memory representation of kernel argument information.
    struct Metadata {
      uint32_t Size = 0;
      uint32_t Align = 0;
      uint32_t PointeeAlign = 0;
      uint8_t Kind = 0;
      uint16_t ValueType = 0;
      std::string TypeName;
      std::string Name;
      uint8_t AddrQual = INVALID_ADDR_QUAL;
      uint8_t AccQual = INVALID_ACC_QUAL;
      uint8_t IsVolatile = 0;
      uint8_t IsConst = 0;
      uint8_t IsRestrict = 0;
      uint8_t IsPipe = 0;

      Metadata() = default;
    };

  } // end namespace KernelArg

  namespace Kernel {

    // In-memory representation of kernel information.
    struct Metadata {
      std::string Name;
      std::string Language;
      std::vector<uint8_t> LanguageVersion;
      std::vector<uint32_t> ReqdWorkGroupSize;
      std::vector<uint32_t> WorkGroupSizeHint;
      std::string VecTypeHint;
      uint32_t KernelIndex = INVALID_KERNEL_INDEX;
      uint8_t NoPartialWorkGroups = 0;
      std::vector<KernelArg::Metadata> Args;

      Metadata() = default;
    };

  } // end namespace Kernel

  namespace IsaInfo {

    /// \brief In-memory representation of instruction set architecture
    /// information.
    struct Metadata {
      /// \brief Wavefront size.
      unsigned WavefrontSize = 0;
      /// \brief Local memory size in bytes.
      unsigned LocalMemorySize = 0;
      /// \brief Number of execution units per compute unit.
      unsigned EUsPerCU = 0;
      /// \brief Maximum number of waves per execution unit.
      unsigned MaxWavesPerEU = 0;
      /// \brief Maximum flat work group size.
      unsigned MaxFlatWorkGroupSize = 0;
      /// \brief SGPR allocation granularity.
      unsigned SGPRAllocGranule = 0;
      /// \brief Total number of SGPRs.
      unsigned TotalNumSGPRs = 0;
      /// \brief Addressable number of SGPRs.
      unsigned AddressableNumSGPRs = 0;
      /// \brief VGPR allocation granularity.
      unsigned VGPRAllocGranule = 0;
      /// \brief Total number of VGPRs.
      unsigned TotalNumVGPRs = 0;
      /// \brief Addressable number of VGPRs.
      unsigned AddressableNumVGPRs = 0;

      Metadata() = default;
    };

  } // end namespace IsaInfo

  namespace Program {

    // In-memory representation of program information.
    struct Metadata {
      std::vector<uint8_t> MDVersionSeq;
      IsaInfo::Metadata IsaInfo;
      std::vector<std::string> PrintfInfo;
      std::vector<Kernel::Metadata> Kernels;

      explicit Metadata() = default;

      // Construct from an YAML string.
      explicit Metadata(const std::string &YAML);

      // Convert to YAML string.
      std::string toYAML();

      // Convert from YAML string.
      static Metadata fromYAML(const std::string &S);
    };

  } //end namespace Program

} // end namespace RuntimeMD
} // end namespace AMDGPU

#endif // LLVM_LIB_TARGET_AMDGPU_AMDGPURUNTIMEMETADATA_H