AOCL-Utils 4.1 Release

.clang-format

@@ -0,0 +1,149 @@
+---
+Language:        Cpp
+# BasedOnStyle:  Mozilla
+AccessModifierOffset: -2
+AlignAfterOpenBracket: Align
+AlignConsecutiveMacros: true
+AlignConsecutiveAssignments: true
+AlignConsecutiveBitFields: true
+AlignConsecutiveDeclarations: true
+AlignEscapedNewlines: Right
+AlignOperands:   Align
+AlignTrailingComments: true
+AllowAllArgumentsOnNextLine: true
+AllowAllConstructorInitializersOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortEnumsOnASingleLine: true
+AllowShortBlocksOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortLambdasOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: TopLevel
+AlwaysBreakAfterReturnType: TopLevel
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BraceWrapping:
+  AfterCaseLabel:  false
+  AfterClass:      true
+  AfterControlStatement: Never
+  AfterEnum:       true
+  AfterFunction:   true
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     true
+  AfterUnion:      true
+  AfterExternBlock: true
+  BeforeCatch:     false
+  BeforeElse:      false
+  BeforeLambdaBody: false
+  BeforeWhile:     false
+  IndentBraces:    false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: NonAssignment
+BreakBeforeBraces: Mozilla
+BreakBeforeInheritanceComma: false
+BreakInheritanceList: BeforeComma
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeComma
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit:     80
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: true
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: false
+DeriveLineEnding: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
+    Priority:        2
+    SortPriority:    0
+  - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
+    Priority:        3
+    SortPriority:    0
+  - Regex:           '.*'
+    Priority:        1
+    SortPriority:    0
+IncludeIsMainRegex: '(Test)?$'
+IncludeIsMainSourceRegex: ''
+IndentCaseLabels: true
+IndentCaseBlocks: false
+IndentGotoLabels: true
+IndentPPDirectives: None
+IndentExternBlock: AfterExternBlock
+IndentWidth:     4
+IndentWrappedFunctionNames: false
+InsertTrailingCommas: None
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: Inner
+ObjCBinPackProtocolList: Auto
+ObjCBlockIndentWidth: 4
+ObjCBreakBeforeNestedBlockParam: true
+ObjCSpaceAfterProperty: true
+ObjCSpaceBeforeProtocolList: false
+PenaltyBreakAssignment: 4
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 200
+PointerAlignment: Left
+ReflowComments:  true
+SortIncludes:    true
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyBlock: false
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles:  false
+SpacesInConditionalStatement: false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+SpaceBeforeSquareBrackets: false
+Standard:        Latest
+StatementMacros:
+  - Q_UNUSED
+  - QT_REQUIRE_VERSION
+TabWidth:        4
+UseCRLF:         false
+UseTab:          Never
+WhitespaceSensitiveMacros:
+  - STRINGIZE
+  - PP_STRINGIZE
+  - BOOST_PP_STRINGIZE
+...
+

.gitignore

@@ -0,0 +1,23 @@
+.vscode
+.ccls
+.dir-locals.el
+.clang-format
+**/CMakeCache.txt
+**/CMakeFiles
+CTestTestfile.cmake
+Makefile
+cmake_install.cmake
+docs/Makefile
+docs/cmake_install.cmake
+docs/internal/Makefile
+docs/internal/cmake_install.cmake
+lib/Makefile
+lib/cmake_install.cmake
+libcpu.so
+examples/Makefile
+examples/cmake_install.cmake
+tests/CTestTestfile.cmake
+tests/Makefile
+tests/cmake_install.cmake
+build/
+docs/doxygen/html/

BUILD.md

@@ -0,0 +1,81 @@
+# AOCL-Utils library
+
+------------
+Linux build:
+------------
+With GCC:
+---------
+Tools needed: CMAKE v3.15 or above, GCC v12 or above.
+
+$ mkdir build
+$ cd build
+$ cmake .. (installs to default path)
+
+  [cmake flag "-DCMAKE_INSTALL_PREFIX" can be used to avoid lib installation into defalut path(/home/usr/)
+  and to install in a user specified path.
+
+  usage: cmake -DCMAKE_INSTALL_PREFIX=<custom path> ..(to install library into custom path) ]
+
+$ cmake -DCMAKE_INSTALL_PREFIX=<custom path> ..(to install library into custom path)
+
+$ make          (without installing the library)
+  or
+  make install  (to install library)
+
+Static library binary: libaoclutils.a
+Shared/Dynamic library binary: libaoclutils.so
+
+NOTES:
+If multiple GCC versions are installed in same system, please use below command to perform build with default compilers:
+cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ ..
+(or)
+you can export the compilers path (to be used) in CC, CXX variables before performing cmake command.
+Example: export CC=/usr/bin/gcc; export CXX=/usr/bin/g++;
+
+With AOCC:
+----------
+Tools needed: CMAKE v3.15  or above, AOCC v4.0
+Install AOCC 4.0, go to that path and use below commands:
+$ cd /home/amd/aocc-compiler-4.0.0
+$ ./install.sh
+$ source /home/amd/setenv_AOCC.sh
+$ export CC=clang
+$ export CXX=clang++
+
+And follow the same above steps as per GCC build.
+
+--------------
+Windows build:
+--------------
+Tools needed: CMAKE v3.15 or above, LLVM(Atleast version 15), MS Visual Studio community 2019/2022, Clang v15 or above.
+
+With Clang:
+1. cmake -A x64 -DCMAKE_BUILD_TYPE=RELEASE -B build -T ClangCl
+2. cmake --build ./build --config Release
+3. cmake --install ./build --config Release
+
+Static library binary: libaoclutils_static.lib
+Shared/Dynamic library binary: libaoclutils.lib, libaoclutils.dll
+
+----------------------------
+Doxygen document generation:
+----------------------------
+Tools needed: Doxygen 1.9.6 or above
+Include "-DALCI_DOXYGEN_DOC=ON" along with above commands during compilation.
+
+Example:
+cmake -A x64 -DCMAKE_BUILD_TYPE=RELEASE -B build -T ClangCl -DALCI_DOXYGEN_DOC=ON
+
+After successful command execution, document will be generated in HTML format.
+Open docs/doxygen/html/index.html in any browser to view documentation.
+
+CMake will use the existing Doxygen if already installed. Else user need to install Doxygen and try again.
+
+NOTES:
+1. cmake flag "CMAKE_INSTALL_PREFIX" can be used to avoid lib installation into default path and to install in a user specified path.
+   cmake -A x64 -DCMAKE_BUILD_TYPE=RELEASE -B build -DCMAKE_INSTALL_PREFIX="custom_path" -T ClangCl
+2. In order to use Clang v16, Need to install MS Visual Studio 2019 and below plugin:
+   LLVM 2019 plugin: https://marketplace.visualstudio.com/items?itemName=MarekAniola.mangh-llvm2019
+   Change the command as follows:
+   cmake -A x64 -DCMAKE_BUILD_TYPE=RELEASE -B build -T LLVM
+3. Few warnings are expected in Windows build with Clang.

CMakeLists.txt

@@ -0,0 +1,93 @@
+##Copyright (C) 2023, Advanced Micro Devices, Inc.##
+
+CMAKE_MINIMUM_REQUIRED(VERSION 3.15)
+PROJECT (aoclutils)
+IF(NOT CMAKE_BUILD_TYPE)
+  SET(CMAKE_BUILD_TYPE "Release" CACHE STRING
+     "Choose the type of build, options are: Debug Release"
+     FORCE)
+ENDIF()
+
+# ADDING INCLUDE DIRECTORY
+INCLUDE_DIRECTORIES(INCLUDE)
+
+# SPECIFY THE C STANDARD
+SET(CMAKE_C_STANDARD 11)
+SET(CMAKE_CXX_STANDARD 17)
+SET(CMAKE_C_STANDARD_REQUIRED TRUE)
+SET(CMAKE_CXX_STANDARD_REQUIRED TRUE)
+
+IF(UNIX)
+SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -std=gnu11 -Wall -Werror -Wpedantic")
+SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=gnu++17 -Wall -Werror -Wpedantic")
+ELSEIF(WIN32)
+SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /std:c11 -Wall -Wpedantic")
+# Disable C++98 compatibility warnings.
+SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /std:c++17 -Wall -Wpedantic -Wno-c++98-compat -Wno-c++98-compat-pedantic")
+# Prefix all shared libraries with 'lib'.
+SET(CMAKE_SHARED_LIBRARY_PREFIX "lib")
+# Prefix all static libraries with 'lib'.
+SET(CMAKE_STATIC_LIBRARY_PREFIX "lib")
+# Export all symbols.
+SET(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
+ENDIF()
+
+SET(AOCL_RELEASE_VERSION "4.1.0")
+
+STRING(TIMESTAMP AOCL_UTILS_RELEASE_VERSION_STRING "AOCL-Utils ${AOCL_RELEASE_VERSION} Build %Y%m%d")
+
+SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+
+# CONTROL WHERE THE STATIC AND SHARED LIBRARIES ARE BUILT SO THAT ON WINDOWS
+# WE DON'T NEED TO TINKER WITH THE PATH TO RUN THE EXECUTABLE
+SET(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
+SET(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
+SET(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
+
+SET(CMAKE_INSTALL_LIBDIR "lib")
+
+OPTION(ALCI_DOCS "ENABLE DOCUMENTATION" ON)
+OPTION(ALCI_DOXYGEN_DOC "ENABLE DOXYGEN DOCUMENTATION" OFF)
+
+SET(CMAKE_DEBUG_POSTFIX _DEBUG)
+
+ADD_SUBDIRECTORY(lib)
+
+IF (ALCI_DOCS)
+	if (ALCI_DOXYGEN_DOC)
+    find_package(Doxygen 1.9.6)
+    set(W_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/doxygen")
+    if(NOT (DOXYGEN_FOUND))
+        message(STATUS "Doxygen not found please install doxygen and try again.")
+    else()
+        execute_process(COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
+                WORKING_DIRECTORY ${W_DIR}
+                COMMAND_ECHO STDOUT)
+    endif()
+    if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/docs/doxygen/html/index.html)
+        message(STATUS "Documentation generated successfully, to view documentation open docs/doxygen/html/index.html")
+    else()
+        message(STATUS "Document generation failed.")
+    endif()
+  endif()
+ENDIF()
+
+IF (ALCI_BENCH)
+  IF (NOT EXISTS ${CMAKE_CURRENT_LIST_DIR}/BENCHMARK)
+    MESSAGE(FATAL_ERROR "BENCHMARKS NOT SUPPORTED")
+  ENDIF()
+
+  ENABLE_TESTING()
+  ADD_SUBDIRECTORY(TEST/BENCHMARK)
+ENDIF()
+
+# Add library install path
+
+INSTALL(TARGETS aoclutils aoclutils_static)
+
+INSTALL(DIRECTORY ${CMAKE_SOURCE_DIR}/include/alci
+        TYPE INCLUDE
+        )
+
+# Add library version in file.
+FILE(WRITE ${CMAKE_BINARY_DIR}/version.h ${AOCL_UTILS_RELEASE_VERSION_STRING})

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Advanced Micro Devices, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.