Updates for v1.2 release.

Author: Amit Ben-Moshe

CMakeLists.txt

@@ -26,6 +26,8 @@ endif ()
 # and provides interface for decoding of instructions or data retrieval
 # for specific instructions in the architecture.
 add_subdirectory(./source/isa_decoder)
+# ISA explorer API
+add_subdirectory(./source/isa_explorer)
 
 if (EXCLUDE_ISA_CLI_EXAMPLES_TESTS)
     message("-- Excluding CLI, examples and tests.")
@@ -37,9 +39,6 @@ else()
     # for generation of various CLI programs.
     add_subdirectory(./source/isa_spec_cli)
 
-    # ISA explorer API
-    add_subdirectory(./source/isa_explorer)
-
     # Unit testing suite
     add_subdirectory(./test/source)
 endif ()

README.md

@@ -8,7 +8,7 @@ The `explorer::Spec` experimental API lets you iterate over the elements of a gi
 For usage examples, see the [examples subfolder](https://github.com/GPUOpen-Tools/isa_spec_manager/tree/main/source/examples).
 
 ## Building isa_spec_manager
-To build the project, use the build scripts located in the ./build subfolder. Please note that the build process requires CMake with minimum version of 3.0.
+To build the project, use the build scripts located in the ./build subfolder. Please note that the build process requires CMake with minimum version of 3.10.
 
 ### Building on Linux
 ```

RELEASE_NOTES.md

@@ -4,10 +4,11 @@
 
 AMD's machine-readable GPU Instruction Set Architecture specifications is a set of XML files that describe AMD's latest GPU ISA: instructions, encodings, operands, data formats and even human-readable description strings. 
 
-The first release includes the specification XML files for the following GPU architectures:
-* AMD CDNA™ 3 (Instinct™ MI300)
-* AMD CDNA™ 2 (Instinct™ MI200)
-* AMD CDNA™ 1 (Instinct™ MI100)
+The release includes the specification XML files for the following GPU architectures:
+* AMD CDNA™ 4 (AMD MI350 Instinct™)
+* AMD CDNA™ 3 (AMD MI300 Instinct™)
+* AMD CDNA™ 2 (AMD MI200 Instinct™)
+* AMD CDNA™ 1 (AMD MI100 Instinct™)
 * AMD RDNA™ 3
 * AMD RDNA™ 2
 * AMD RDNA™ 1
@@ -24,21 +25,17 @@ For usage examples and instructions on how to build the project, please see [sou
 **Note:** while the `IsaDecoder` API is a good way to get started with parsing the XML files, nothing prevents you from parsing the files yourself and building your own custom workflow. To do that please refer to the XML schema documentation [XML schema documentation](https://github.com/GPUOpen-Tools/isa_spec_manager/blob/main/documentation/spec_documentation.md).
 
 New in this release:
-* Added support for operand subtypes (requires XML schema version `v1.1.0`).
-* Introducing the experimental `explorer::Spec` API for iterating over the elements of a given specification file. See the [documentation](https://github.com/GPUOpen-Tools/isa_spec_manager/tree/main/documentation) and [examples](https://github.com/GPUOpen-Tools/isa_spec_manager/tree/main/source/examples) subfolders for more details.
-* On Windows, the solution is now generated for the VS2022 toolchain by default.
-* Unit tests are now part of the repository.
-* Bug fixes and performance improvements.
+* Fixed decoding of `MIMG` instructions (such as `IMAGE_STORE` and `IMAGE_LOAD`)
+* Fixed decoding of `MUBUF` and `MTBUF` instructions of RDNA™2 targets in binary representation.
+* Fixed an issue where `DS` instructions returned the wrong operands when decoded via `IsaDecoder::DecodeInstruction()` with an `uint64_t` argument.
+* The `explorer` API now supports Functional Groups.
+* Added basic test for the `explorer` API.
+* Documentation updates.
+
 
 ## Known issues ##
 
 ### Specification ###
 * Information about encoding modifiers is not provided in the specification.
-* `S_ATOMIC_*` instructions have a `VMEM` functional group (instead of `SMEM`).
-
-### API and tools ###
-
-* Decoding of `MIMG` instructions (such as `IMAGE_STORE` and `IMAGE_LOAD`) may produce the wrong register indices for source vector register operands.
-* Decoding binary representation of certain RDNA™2 `MIMG`, `MUBUF` and `MTBUF` instructions may produce the wrong results.
-* Decoding `DS` instructions may return the wrong operands when decoded via `IsaDecoder::DecodeInstruction()` with an `uint64_t` argument.
 
+### API and tools ###

documentation/isa_decoder/api_documentation.md

@@ -71,7 +71,10 @@ bool DecodeInstructionStream(
     std::vector<InstructionInfoBundle>& instruction_info_stream,
     std::string& err_message) const;
 ```
-Decodes a sequence of binary instructions. 
+Decodes a sequence of binary instructions.
+
+> [!NOTE]
+> Branch resolution will not be performed when decoding a single instruction. If branch resolution is required,  use DecodeShaderDisassemblyText() or DecodeShaderDisassemblyFile() with the flag for branch target resolution set to `true`.
 
 ### Parameters
 parameter name | type | description | input/output
@@ -129,6 +132,9 @@ bool DecodeInstruction(uint64_t machine_code,
 ```
 Decodes a single instruction encoded in binary format. This API is limited to a 64-bit instruction. If the instruction of interest is longer than 64 bits, `amdisa::IsaDecoder::DecodeInstructionStream` should be used instead.
 
+> [!NOTE]
+> Branch resolution will not be performed when decoding a single instruction. If branch resolution is required,  use DecodeShaderDisassemblyText() or DecodeShaderDisassemblyFile() with the flag for branch target resolution set to `true`.
+
 ### Parameters
 parameter name | type | description | input/output
 -|-|-|-

documentation/isa_explorer/api_tutorial.md

@@ -62,10 +62,6 @@ std::advance(it, dist(gen));
 print_instruction(it->second);
 ```
 
-- **Random Device and Generator:** Creates a random number generator seeded with a hardware-based random device.
-- **Uniform Distribution:** Ensures the random number falls within the valid range of instruction indices.
-- **Iterator Advancement:** Randomly selects an instruction by advancing the iterator to the generated index.
-
 The selected instruction is printed using the `print_instruction` function.
 
 As an exmple, you can use the following print function:
@@ -82,4 +78,4 @@ static void print_instruction(const amdisa::explorer::Instruction& instruction)
     std::cout << "\t\t Description: " << instruction.FuncGroup()->Description() << std::endl << std::endl;
     std::cout << "\tFunctionalSubgroup: " << instruction.FuncSubgroup()->Name() << std::endl;
 }
-```
+```

documentation/spec_documentation.md

@@ -156,7 +156,7 @@ List of child elements:
 | -- | ---------------- | ---------------- | - |
 | 1. | Field name       | \<FieldName\>      | Encoding field name. Should match one of the fields in [\<BitMap\>](#bitmap-microcodeformat). |
 | 2. | Data format name | \<DataFormatName\> | Data format of the operand. Should match one of the formats in [\<DataFormats\>](#dataformats). |
-| 3. | Operand type     | \<OperantType\>    | Type of the operand. Should match one of the types in [\<OperandTypes\>](#operandtypes)|
+| 3. | Operand type     | \<OperandType\>    | Type of the operand. Should match one of the types in [\<OperandTypes\>](#operandtypes)|
 | 4. | Operand size     | \<OperandSize\>    | The size of this operand in bits. |
 
 

include/amdisa/api_version.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved.
+ * Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
  */
 #ifndef API_VERSION_H_
 #define API_VERSION_H_
@@ -10,7 +10,7 @@
 
 // IsaDecoder version.
 #define AMDISA_DECODE_API_VERSION_MAJOR 1
-#define AMDISA_DECODE_API_VERSION_MINOR 1
+#define AMDISA_DECODE_API_VERSION_MINOR 2
 #define AMDISA_DECODE_API_VERSION_PATCH 0
 
 // IsaExplorer version.

include/amdisa/isa_decoder.h

@@ -29,9 +29,10 @@ namespace amdisa
     // Constants.
     static const uint32_t kBranchOffsetOutOfRange = (1 << 16);
     static const uint64_t kInvalidBranchTarget    = UINT64_MAX;
+    static const uint64_t kSrcNull                = 0x7c;
 
     // Instruction's functional group.
-    enum class kFunctionalGroup
+    enum class FunctionalGroups
     {
         kFunctionalGroupUnknown,      // Unknown
         kFunctionalGroupSalu,         // Scalar ALU
@@ -45,7 +46,7 @@ namespace amdisa
         kFunctionalGroupTrap          // Trap
     };
 
-    static constexpr const char* kFunctionalGroupName[] = {
+    constexpr const char* FunctionalGroupNames[] = {
         "Unknown",        // Unknown
         "Scalar ALU",     // Scalar ALU
         "Scalar Memory",  // Scalar Memory
@@ -59,7 +60,7 @@ namespace amdisa
     };
 
     // Instruction's functional group's subgroup.
-    enum class kFunctionalSubgroup
+    enum class FunctionalSubgroups
     {
         kFunctionalSubgroupUnknown,        // Unknown
         kFunctionalSubgroupFloatingPoint,  // Floating Point
@@ -78,7 +79,7 @@ namespace amdisa
         kFunctionalSubgroupTranscendental  // Transcendental
     };
 
-    static constexpr const char* kFunctionalSubgroupName[] = {
+    constexpr const char* FunctionalSubgroupNames[] = {
         "Unknown",         // Unknown
         "Floating Point",  // Floating Point
         "Buffer",          // Buffer
@@ -90,7 +91,7 @@ namespace amdisa
         "Atomic",          // Atomic
         "Flat",            // Flat
         "Data Share",      // Data Share
-        "Static"           // Static
+        "Static",          // Static
         "MFMA",            // MFMA
         "WMMA",            // WMMA
         "Transcendental"   // Transcendental
@@ -130,6 +131,12 @@ namespace amdisa
         // Size of the operand.
         uint32_t operand_size = 0;
 
+        // Data Format of the operand.
+        std::string data_format;
+
+        // The name of the encoded field that corresponds to this operand.
+        std::string encoding_field_name;
+
         // True if the operand is an input to an instruction (source).
         bool is_input = false;
 
@@ -181,11 +188,20 @@ namespace amdisa
         bool is_immediately_executed = false;
     };
 
+    // Describes an instruction's primary functional group and any more specific
+    // subgroups it belongs to within an instruction set architecture.
     struct FunctionalGroupSubgroupInfo
     {
-        std::string         description;
-        kFunctionalGroup    IsaFunctionalGroup    = kFunctionalGroup::kFunctionalGroupUnknown;
-        kFunctionalSubgroup IsaFunctionalSubgroup = kFunctionalSubgroup::kFunctionalSubgroupUnknown;
+        // Functional group description.
+        std::string description;
+
+        // Functional group.
+        FunctionalGroups isa_functional_group = FunctionalGroups::kFunctionalGroupUnknown;
+
+        // The subgroups of this instruction, where each subgroup forms
+        // a pair with the group in the form of { <fg, sub_fg1>,
+        // <fg, sub_fg2>, <fg, sub_fg3>, ... }.
+        std::vector<FunctionalSubgroups> isa_functional_subgroups;
     };
 
     // InstructionInfo is a structure that gets populated as a result of API
@@ -251,6 +267,16 @@ namespace amdisa
      */
         bool Initialize(const std::string& input_xml_file_path, std::string& err_message);
 
+        /*
+     * Initialize --
+     *
+     * Reads in XML ISA specification from memory and populates the internal structures.
+     *
+     * Returns true if the spec was successfully read, or false otherwise
+     * with the error message in err_message.
+     */
+        bool Initialize(const char *input_xml_data, const size_t datalen, std::string& err_message);
+
         /*
      * GetVersion --
      *
@@ -277,6 +303,9 @@ namespace amdisa
      * instruction) was decoded successfully and populates instruction_info with
      * corresponding information about the decoded instruction.
      * Returns false otherwise with the error string output.
+     *
+     * Note: branch resolution will not be performed when decoding a single instruction.
+     * If branch resolution is required, use DecodeShaderDisassemblyText() or DecodeShaderDisassemblyFile().
      */
         bool DecodeInstruction(uint64_t machine_code, InstructionInfoBundle& instruction_info, std::string& err_message) const;
 
@@ -301,6 +330,9 @@ namespace amdisa
      * successful decode, the function outputs a vector of InstructionInfoGroup.
      * Each of the objects in the vector correspond to a decoded instruction in
      * the input instruction stream.
+     *
+     * Note: branch resolution will not be performed when decoding a single instruction.
+     * If branch resolution is required, use DecodeShaderDisassemblyText() or DecodeShaderDisassemblyFile().
      */
         bool DecodeInstructionStream(const std::vector<uint32_t>&        machine_code_stream,
                                      std::vector<InstructionInfoBundle>& instruction_info_stream,

include/amdisa/isa_explorer.h

@@ -302,7 +302,7 @@ namespace amdisa
             ///@brief Get the subgroups in the functional group
             ///
             /// @returns Subgroups in the functional group
-            const std::vector<FunctionalSubgroup>& FuncSubgroups() const noexcept;
+            const std::vector<FunctionalSubgroup> FuncSubgroups() const noexcept;
 
         private:
             /// @brief Add the instruction to the functional group
@@ -495,7 +495,7 @@ namespace amdisa
                         bool                                    is_immediately_executed,
                         bool                                    is_program_terminator,
                         FunctionalGroup&                        functional_group,
-                        FunctionalSubgroup&                     functional_subgroup,
+                        const std::vector<FunctionalSubgroup>&  functional_subgroups,
                         const std::vector<InstructionEncoding>& encodings);
             /// @brief Get the name of the instruction
             ///
@@ -540,7 +540,7 @@ namespace amdisa
             /// @brief Get the functional subgroup to which the instruction belongs
             ///
             /// @returns Functional subgroup to which the instruction belongs
-            const FunctionalSubgroup* const FuncSubgroup() const noexcept;
+            const std::vector<FunctionalSubgroup> FuncSubgroups() const noexcept;
 
             /// @brief Get the encodings of the instruction
             ///
@@ -556,7 +556,7 @@ namespace amdisa
             const bool                             is_immediately_executed_;  ///< Whether the instruction is immediately executed
             const bool                             is_program_terminator_;    ///< Whether the instruction is a program terminator
             FunctionalGroup* const                 functional_group_;         ///< Functional group to which the instruction belongs
-            FunctionalSubgroup* const              functional_subgroup_;      ///< Functional subgroup to which the instruction belongs
+            const std::vector<FunctionalSubgroup>  functional_subgroups_;     ///< Functional subgroup to which the instruction belongs
             const std::vector<InstructionEncoding> encodings_;                ///< Encodings of the instruction
         };
 
@@ -589,6 +589,21 @@ namespace amdisa
              */
             bool Init(const std::string& input_xml_file_path, std::string& err_message) noexcept;
 
+            /*
+             * Init --
+             *
+             * Reads in an XML file containing the ISA specification from memory and populates the
+             * internal data structures.
+             *
+             * @param input_xml_file_path  Path to the XML file containing the ISA specification.
+             * @param err_message          Reference to a string that will be populated with
+             *                             an error message if initialization fails.
+             *
+             * @return True if the XML file was successfully parsed and the internal
+             *         structures were initialized, false otherwise.
+             */
+            bool Init(const char *input_xml_data, const size_t datalen, std::string& err_message) noexcept;
+
             /*
              * GetArchitecture --
              *
@@ -628,6 +643,16 @@ namespace amdisa
              */
             const std::map<std::string, OperandType>& GetOperandTypes() const noexcept;
 
+            /*
+             * GetFunctionalGroups --
+             *
+             * Returns the functional groups defined in this ISA.
+             *
+             * @return A const reference to a map where the key is the name of the functional group
+             *         type and the value is the corresponding FunctionalGroup object.
+             */
+            const std::map<std::string, FunctionalGroup>& GetFunctionalGroups() const noexcept;
+
             // Constructor control.
             Spec();
             ~Spec();

source/common/amdisa_expression_tree_consts.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024 Advanced Micro Devices, Inc. All rights reserved.
+ * Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
  */
 #ifndef AMDISA_EXPRESSION_TREE_CONSTS_H_
 #define AMDISA_EXPRESSION_TREE_CONSTS_H_
@@ -28,6 +28,7 @@ namespace amdisa
         kBaseType,
         kArrayType,
         kLambdaType,
+        kRecordType,
         kUndefined
     };
 
@@ -68,20 +69,24 @@ namespace amdisa
     static const char* kJsonBaseTypeName   = "!base";
     static const char* kJsonArrayTypeName  = "!array";
     static const char* kJsonLambdaTypeName = "!lambda";
+    static const char* kJsonRecordTypeName = "!record";
 
     // XML type names.
     static const char* kXmlBaseTypeName   = "Base";
     static const char* kXmlArrayTypeName  = "Array";
     static const char* kXmlLambdaTypeName = "Lambda";
+    static const char* kXmlRecordTypeName = "Record";
 
     // Map from JSON type tree string names to enum.
     static const std::map<std::string, TypeTreeNodes> kMapJsonTypeTreeNodeNamesToEnum = {{kJsonBaseTypeName, TypeTreeNodes::kBaseType},
                                                                                          {kJsonArrayTypeName, TypeTreeNodes::kArrayType},
-                                                                                         {kJsonLambdaTypeName, TypeTreeNodes::kLambdaType}};
+                                                                                         {kJsonLambdaTypeName, TypeTreeNodes::kLambdaType},
+                                                                                         {kJsonRecordTypeName, TypeTreeNodes::kRecordType}};
 
     // Map from XML type tree string names to enum.
     static const std::map<std::string, TypeTreeNodes> kMapXmlTypeTreeNodeNamesToEnum = {{kXmlBaseTypeName, TypeTreeNodes::kBaseType},
                                                                                         {kXmlArrayTypeName, TypeTreeNodes::kArrayType},
-                                                                                        {kXmlLambdaTypeName, TypeTreeNodes::kLambdaType}};
+                                                                                        {kXmlLambdaTypeName, TypeTreeNodes::kLambdaType},
+                                                                                        {kXmlRecordTypeName, TypeTreeNodes::kRecordType}};
 }  // namespace amdisa
 #endif  // AMDISA_EXPRESSION_TREE_CONSTANTS_H_