Repository files navigation

MIOpen is AMD's library for high-performance machine learning primitives.

You can find sources and binaries in ourGitHub repository.

MIOpen supports these programming models (backends):

• HIP
• OpenCL (deprecated)

To build the MIOpen documentation locally, run the following code from within thedocs folder inour repository:

cd docspip3 install -r sphinx/requirements.txtpython3 -m sphinx -T -E -b html -d _build/doctrees -D language=en. _build/html

To install MIOpen, you must first install these prerequisites:

• AROCm-enabled platform
• A base software stack that includes either:*HIP (HIP and HCC libraries and header files)
  • OpenCL (OpenCL libraries and header files)--this is now deprecated
• ROCm CMake: provides CMake modules for common buildtasks needed for the ROCm software stack
• Half: IEEE 754-based, half-precision floating-point library
• Boost: Version 1.79 is recommended, as older versions may need patches towork on newer systems
  • MIOpen usesboost-system andboost-filesystem packages to enable persistentkernel cache
• SQLite3: A reading and writing performance database
• lbzip2: A multi-threaded compress or decompress utility
• rocBLAS: AMD's library for Basic Linear Algebra Subprograms(BLAS) on the ROCm platform.
  • Minimum version branch for pre-ROCm 3.5master-rocm-2.10
  • Minimum version branch for post-ROCm 3.5master-rocm-3.5
• hipBLASLt: AMD's flexible Basic Linear Algebra Subprograms(BLAS) API.
• hipBLAS: AMD's (BLAS) marshalling library.
• Multi-Level Intermediate Representation (MLIR) with itsMIOpen dialect to support and complement kernel development
• Composable Kernel: A C++ templated device libraryfor GEMM-like and reduction-like operators.

You can install MIOpen on Ubuntu usingapt-get install miopen-hip.

If using OpenCL, you can useapt-get install miopen-opencl (but this is not recommended, as OpenCLis deprecated).

Note that you can't install both backends on the same system simultaneously. If you want a differentbackend other than what currently exists, completely uninstall the existing backend prior to installingthe new backend.

MIOpen provides an optional pre-compiled kernels package to reduce startup latency. Theseprecompiled kernels comprise a select set of popular input configurations. We'll expand these kernelsin future releases to include additional coverage.

Note that all compiled kernels are locally cached in the$HOME/.cache/miopen/ folder, soprecompiled kernels reduce the startup latency only for the first run of a neural network. Precompiledkernels don't reduce startup time on subsequent runs.

To install the kernels package for your GPU architecture, use the following command:

apt-get install miopen-hip-<arch>kdb

Where<arch> is the GPU architecture (e.g.,gfx900,gfx906,gfx1030 ).

Theutils/install_precompiled_kernels.sh script provided as part of MIOpen automates the precedingprocess. It queries the user machine for the GPU architecture and then installs the appropriatepackage. You can invoke it using:

./utils/install_precompiled_kernels.sh

The preceding script depends on therocminfo package to query the GPU architecture. Refer toInstalling pre-compiled kernelsfor more information.

You can install dependencies using theinstall_deps.cmake script (cmake -P install_deps.cmake).

By default, this installs to/usr/local, but you can specify another location using the--prefixargument:

cmake -P install_deps.cmake --prefix<miopen-dependency-path>

An example CMake step is:

cmake -P install_deps.cmake --minimum --prefix /root/MIOpen/install_dir

You can use this prefix to specify the dependency path during the configuration phase usingCMAKE_PREFIX_PATH.

MIOpen's HIP backend usesrocBLAS by default. You can installrocBLAS' minimum release usingapt-get install rocblas. To disable rocBLAS, set the configuration flag-DMIOPEN_USE_ROCBLAS=Off. rocBLAS isnot available with OpenCL.

MIOpen's HIP backend can usehipBLASLt. You can install hipBLASLt's minimumrelease usingapt-get install hipblaslt. In addition to needing hipblaslt, you will also need to installhipBLAS.You can install hipBLAS's minimum release usingapt-get install hipblas.To disable hipBLASLt, set the configuration flag-DMIOPEN_USE_HIPBLASLT=Off.hipBLASLt isnot available with OpenCL.

You can build MIOpen form source with a HIP backend or an OpenCL backend.

First, create a build directory:

mkdir build;cd build;

Next, configure CMake. You can set the backend using the-DMIOPEN_BACKEND CMake variable.

Set the C++ compiler toclang++. For the HIP backend (ROCm 3.5 and later), run:

export CXX=<location-of-clang++-compiler>cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH="<hip-installed-path>;<rocm-installed-path>;<miopen-dependency-path>" ..

An example CMake step is:

export CXX=/opt/rocm/llvm/bin/clang++&& \cmake -DMIOPEN_BACKEND=HIP -DCMAKE_PREFIX_PATH="/opt/rocm/;/opt/rocm/hip;/root/MIOpen/install_dir" ..

First, run:

cmake -DMIOPEN_BACKEND=OpenCL ..

The preceding code assumes OpenCL is installed in one of the standard locations. If not, then manuallyset these CMake variables:

cmake -DMIOPEN_BACKEND=OpenCL -DMIOPEN_HIP_COMPILER=<hip-compiler-path> -DOPENCL_LIBRARIES=<opencl-library-path> -DOPENCL_INCLUDE_DIRS=<opencl-headers-path> ..

Here's an example dependency path for an environment in ROCm 3.5 and later:

cmake -DMIOPEN_BACKEND=OpenCL -DMIOPEN_HIP_COMPILER=/opt/rocm/llvm/bin/clang++ -DCMAKE_PREFIX_PATH="/opt/rocm/;/opt/rocm/hip;/root/MIOpen/install_dir" ..

By default, the install location is set to/opt/rocm. You can change this usingCMAKE_INSTALL_PREFIX:

cmake -DMIOPEN_BACKEND=HIP -DCMAKE_INSTALL_PREFIX=<miopen-installed-path> ..

The default path to the system performance database (System PerfDb) ismiopen/share/miopen/db/within the install location. The default path to the user performance database (User PerfDb) is~/.config/miopen/. For development purposes, settingBUILD_DEV changes the default path to bothdatabase files to the source directory:

cmake -DMIOPEN_BACKEND=HIP -DBUILD_DEV=On ..

Database paths can be explicitly customized using theMIOPEN_SYSTEM_DB_PATH (System PerfDb)andMIOPEN_USER_DB_PATH (User PerfDb) CMake variables.

To learn more, refer to theperformance databasedocumentation.

By default, MIOpen caches device programs in the~/.cache/miopen/ directory. Within the cachedirectory, there is a directory for each version of MIOpen. You can change the location of the cachedirectory during configuration using the-DMIOPEN_CACHE_DIR=<cache-directory-path> flag.

You can also disable the cache during runtime using theMIOPEN_DISABLE_CACHE=1 environmentalvariable.

If the compiler changes, or you modify the kernels, then you must delete the cache for the MIOpenversion in use (e.g.,rm -rf ~/.cache/miopen/<miopen-version-number>). You can find moreinformation in thecachedocumentation.

MIOpen's kernel cache directory is versioned so that your cached kernels won't collide when upgradingfrom an earlier version.

The configuration can be changed after running CMake (usingccmake):

ccmake ..orcmake-gui:cmake-gui ..

Theccmake program can be downloaded as a Linux package (cmake-curses-gui), but is not availableon Windows.

You can build the library from thebuild directory using the 'Release' configuration:

cmake --build . --config Releaseormake

You can install it using the 'install' target:

cmake --build . --config Release --target installormake install

This installs the library to theCMAKE_INSTALL_PREFIX path that you specified.

MIOpen provides anapplication-driver thatyou can use to run any layer in isolation, and measure library performance and verification.

You can build the driver using theMIOpenDriver target:

cmake --build . --config Release --target MIOpenDriverormake MIOpenDriver

To learn more, refer to thedriverdocumentation.

You can run tests using the 'check' target:

cmake --build . --config Release --target checkORmake check

To build and run a single test, use the following code:

cmake --build. --config Release --target test_tensor./bin/test_tensor

Check gtests formats

cd ./test/utils&& python3 gtest_formating_checks.py

All the code is formatted usingclang-format. To format a file, use:

clang-format-10 -style=file -i<path-to-source-file>

To format the code per commit, you can install githooks:

./.githooks/install

Git Large File Storage (LFS) replaces large files, such as audio samples, videos, datasets, and graphicswith text pointers inside Git, while storing the file contents on a remote server. In MIOpen, we use GiLFS to store our large files, such as our kernel database files (*.kdb) that are normally > 0.5 GB.

You can install Git LFS using the following code:

sudo apt install git-lfsgit lfs install

In the Git repository where you want to use Git LFS, track the file type using the following code (if thefile type has already been tracked, you can skip this step):

git lfs track"*.file_type"git add .gitattributes

You can pull all or a single large file using:

git lfs pull --exclude=orgit lfs pull --exclude= --include"filename"

Update the large files and push to GitHub using:

git add my_large_filesgit commit -m"the message"git push

If you're using Ubuntu v16, you can install theBoost packages using:

sudo apt-get install libboost-devsudo apt-get install libboost-system-devsudo apt-get install libboost-filesystem-dev

You must install thehalf header from thehalf website.

The easiest way to build MIOpen is via Docker. You can build the top-level Docker file using:

docker build -t miopen-image.

Then, to enter the development environment, usedocker run. For example:

docker run -it -v$HOME:/data --privileged --rm --device=/dev/kfd --device /dev/dri:/dev/dri:rw  --volume /dev/dri:/dev/dri:rw -v /var/lib/docker/:/var/lib/docker --group-add video --cap-add=SYS_PTRACE --security-opt seccomp=unconfined miopen-image

You can find prebuilt Docker images onROCm's public Docker Hub.

Ourporting guidehighlights the key differences between cuDNN and MIOpen APIs.