Updates for v1.1 release.

Author: AmitBM

CMakeLists.txt

@@ -5,9 +5,11 @@ cmake_minimum_required(VERSION 3.0)
 project(isa_spec_manager)
 
 # Setting compiler flags.
-set (CMAKE_CXX_COMPILER g++)
-set (CMAKE_CXX_STANDARD 14)
-set (CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} ${FLAGS})
+if (LINUX)
+    set(CMAKE_CXX_COMPILER g++)
+endif ()
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} ${FLAGS})
 
 # Enable using folders to group projects on Windows (Visual Studio solution).
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
@@ -17,17 +19,27 @@ set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 if (${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
     # Visual Studio
     set(CMAKE_CONFIGURATION_TYPES "Release;Debug")
-endif()
+endif ()
 
 # Setting project directories.
 # XML ISA Spec Decoder API: accepts ISA Spec for specific architecture
 # and provides interface for decoding of instructions or data retrieval
 # for specific instructions in the architecture.
 add_subdirectory(./source/isa_decoder)
 
-# Examples: demonstrates utilities and API features using example apps
-add_subdirectory(./source/examples)
+if (EXCLUDE_ISA_CLI_EXAMPLES_TESTS)
+    message("-- Excluding CLI, examples and tests.")
+else()
+    # Examples: demonstrates utilities and API features using example apps
+    add_subdirectory(./source/examples)
 
-# CLI commands: provides command line interface implementation
-# for generation of various CLI programs.
-add_subdirectory(./source/isa_spec_cli)
+    # CLI commands: provides command line interface implementation
+    # 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

@@ -3,6 +3,8 @@ A set of tools for parsing and using AMD's machine-readable GPU ISA specificatio
 
 The `IsaDecoder` API makes it easy to parse the specification XML files, decode instructions and even decode whole shaders.
 
+The `explorer::Spec` experimental API lets you iterate over the elements of a given specification file.
+
 For usage examples, see the [examples subfolder](https://github.com/GPUOpen-Tools/isa_spec_manager/tree/main/source/examples).
 
 ## Building isa_spec_manager
@@ -26,10 +28,25 @@ cd ./isa_spec_manager/build
 
 The above script will create a windows directory and generate a solution for Visual Studio.
 
+By default, a solution is generated for VS 2022. To generate a solution for a different VS version or to use a different MSVC toolchain use the `--vs` argument.
+For example, to generate the solution for VS 2019 with the VS 2019 toolchain, run:
+
+``
+./prebuild_windows.bat --vs 2019
+``
+
 ## Using the API
+For the API and specification documentation, please see the [documentation subfolder](https://github.com/GPUOpen-Tools/isa_spec_manager/tree/main/documentation).
+
 The following example files can give you a quick overview of how to start using the XML ISA spec in your project:
-* Basic usage example: [./source/examples/basic_decoder.cpp](./source/examples/basic_decoder.cpp)
-* Usage example with multiple architectures in flight: [./source/examples/multi_arch_decoder.cpp](./source/examples/multi_arch_decoder.cpp)
+
+### IsaDecoder
+* Basic usage example: [./source/examples/basic_decoder.cpp](./source/examples/basic_decoder.cpp). This sample requires a single command line argument which is a full path to the XML specification file.
+* Usage example with multiple architectures in flight: [./source/examples/multi_arch_decoder.cpp](./source/examples/multi_arch_decoder.cpp). This sample requires one or more command line arguments which are the full paths to the XML specification files.
+
+### explorer::Spec
+* Basic usage example: [./source/examples/basic_explorer.cpp](./source/examples/basic_explorer.cpp). This sample requires a single command line argument which is a full path to the XML specification file.
+
 
 ## Getting the ISA specification files
-The Machine-Readable GPU ISA specification files can be downloaded from [AMD's Machine-Readable GPU ISA Specification page on GPUOpen.com](https://gpuopen.com/machine-readable-isa/).
+The Machine-Readable GPU ISA specification files can be downloaded from [AMD's Machine-Readable GPU ISA Specification page on GPUOpen.com](https://gpuopen.com/machine-readable-isa).

RELEASE_NOTES.md

@@ -23,12 +23,22 @@ 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.
+
 ## 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 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.
 

build/prebuild_linux.sh

@@ -7,7 +7,29 @@ if [ ! -d $BUILD_DIR ]; then
     mkdir $BUILD_DIR
 fi
 
-# Run cmake.
+# Read the custom path for tinyxml.
+for arg in "$@"; do
+    case $arg in
+        --tinyxml2_src_path=*)
+        TINYXML_SRC_PATH="${arg#*=}" # Extract the value after '='
+        shift # Remove the argument from the list
+        ;;
+        *)
+        echo "Unknown option: $arg"
+        exit 1
+        ;;
+    esac
+done
+
+# Go to the build directory.
 cd $BUILD_DIR
-cmake ../../
+
+# Check if tinyxml2 needs to be overwritten.
+if [ -z "$TINYXML_SRC_PATH" ]; then
+    # Use default tinyxml2.
+    cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ../../
+else
+    # Use the custom tinyxml2.
+    cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DTINYXML_SRC_PATH=$TINYXML_SRC_PATH ../../
+fi
 

build/prebuild_windows.bat

@@ -1,5 +1,5 @@
 @echo off
-:: prebuild.bat --vs 2019
+:: prebuild.bat --vs 2022
 SETLOCAL
 
 rem Print help message
@@ -19,11 +19,14 @@ echo Usage:  prebuild.bat ^[options^]
 echo:
 echo Options:
 echo    --cmake              Path to cmake executable to use. If not specified, the cmake from PATH env variable will be used.
-echo    --vs                 Microsoft Visual Studio version. Currently supported values are: "2015", "2017", "2019" and "2022". The default is "2019".
+echo    --tinyxml2_src_path  Path to TinyXML2 source. If not specified, the default TinyXML2 bundled with the isa_decoder will be used.
+echo    --vs                 Microsoft Visual Studio version. Currently supported values are: "2015", "2017", "2019" and "2022". The default is "2022".
+echo    --decoder_only       Only include the decoder library for this project; skip the command line interface, examples and tests.
 echo:
 echo Examples:
-echo    prebuild.bat
-echo    prebuild.bat --vs 2017
+echo    prebuild_windows.bat
+echo    prebuild_windows.bat --vs 2022
+echo    prebuild_windows.bat --vs 2022 --tinyxml2_src_path [path to custom tinyxml2]
 
 goto :exit
 
@@ -33,25 +36,18 @@ set CURRENT_DIR=%CD%
 
 rem Default values
 set CMAKE_PATH=cmake
-set VS_VER=2019
-set TEST=-DTEST_PROJECT=ON
-set BUILD_INTERNAL=-DBuildInternal=OFF
+set VS_VER=2022
+set DECODER_ONLY=
+set TINYXML=
 
 :begin
 if [%1]==[] goto :start_cmake
-if "%1"=="--no-test" goto :set_notest_flag
-if "%1"=="--public-only" goto :set_public_build_flag
 if "%1"=="--cmake" goto :set_cmake
 if "%1"=="--vs" goto :set_vs
-if "%1"=="--internal" goto :set_internal_build_flag
+if "%1"=="--tinyxml2_src_path" goto :set_tinyxml2_src_path
+if "%1"=="--decoder_only" goto :set_decoder_only
 goto :bad_arg
 
-:set_notest_flag
-goto :start_cmake
-
-:set_internal_build_flag
-goto :start_cmake
-
 :set_cmake
 set CMAKE_PATH=%2
 goto :shift_2args
@@ -60,10 +56,18 @@ goto :shift_2args
 set VS_VER=%2
 goto :shift_2args
 
+:set_tinyxml2_src_path
+set TINYXML=-DTINYXML_SRC_PATH=%2
+goto :shift_2args
+
 :set_verbose
 @echo on
 goto :shift_arg
 
+:set_decoder_only
+set DECODER_ONLY="-DEXCLUDE_ISA_CLI_EXAMPLES_TESTS=ON"
+goto :shift_arg
+
 :shift_2args
 rem Shift to the next pair of arguments
 shift
@@ -109,7 +113,7 @@ rem Invoke cmake with required arguments.
 echo:
 echo Running cmake to generate a VisualStudio solution...
 cd %OUTPUT_FOLDER%
-%CMAKE_PATH% -G %CMAKE_VS% %CMAKE_VSARCH% ..\..\..
+%CMAKE_PATH% %DECODER_ONLY% %TINYXML% -G %CMAKE_VS% %CMAKE_VSARCH% ..\..\..
 if not %ERRORLEVEL%==0 (
     echo "ERROR: cmake failed. Aborting..."
     exit /b 1

documentation/cli_documentation.md

@@ -5,8 +5,8 @@ ISA Spec Manager CLI program is an example program that leverages IsaSpecApi. Th
 To decode an instruction that is represented in the binary (machine code) format using CLI, run the commands below. 
 
 ```bash
-cd isa_spec_manager-Win64/cli
-./isa_spec_cli.exe -x ../../Specification/xml/gfx11.xml -d BE804814
+cd IsaSpecManager-Win64/cli
+./IsaSpecCli.exe -x ../../Specification/xml/gfx11.xml -d BE804814
 ```
 As can be seen from the command, `-x` flag should be followed by the path to the machine-readable XML specification. Next, `-d` flag should be followed by the instruction in the binary form. Note that the provided instruction should be encoded in the specified architecture. After running the command, the CLI outputs the following:
 
@@ -33,8 +33,8 @@ If decoded successfully, CLI outputs the instruction in an assembly form, descri
 To retrieve information about a specific instruction from the spec, the name of the instruction could be provided to the CLI. Refer to the commands below.
 
 ```bash
-cd isa_spec_manager-Win64/cli
-./isa_spec_cli.exe -x ../../Specification/xml/gfx11.xml -i s_setpc_b64
+cd IsaSpecManager-Win64/cli
+./IsaSpecCli.exe -x ../../Specification/xml/gfx11.xml -i s_setpc_b64
 ```
 As can be seen from the command, `-x` flag should be followed by the path to the machine-readable XML specification. Next, `-i` flag should be followed by the name of the instruction which we are interested in. Note, that the requested instruction should be present in the specified architecture. After running the command, CLI outputs the following:
 

documentation/api_documentation.md …ntation/isa_decoder/api_documentation.mddocumentation/api_documentation.md renamed to documentation/isa_decoder/api_documentation.md documentation/api_documentation.md renamed to documentation/isa_decoder/api_documentation.md

@@ -225,8 +225,38 @@ int main ()
     
     return (is_init && is_decoded) ? 0 : -1;
 }
+```
+
+## `amdisa::IsaDecoder::GetDebugLog`
+```c++
+std::vector<std::string> GetDebugLog() const;
+```
+Retrieves a log of error and warning messages generated by the `IsaDecoder` instance. It can be used for debugging purposes to review any issues encountered during the lifetime of the instance.
+
+### Return value
+A `std::vector` of `std::string` containing error and warning messages. If no messages are logged, the vector will be empty.
+
+### Example
+```c++
+#include "isa_decoder.h"
+#include <iostream>
 
+int main ()
+{
+    amdisa::IsaDecoder spec_api;
+    // Assume `Initialize` or other operations have been performed.
+
+    // Retrieve and print internal messages or warnings if present.
+    for (const std::string& message : spec_api.GetDebugLog())
+    {
+        std::cout << message << std::endl;
+    }
+
+    return 0;
+}
 ```
+---
+
 # API structures
 API defines various struct in `isa_decoder.h`.