diff --git a/docs/source/conf.py b/docs/source/conf.py index 9fc2153aac..94c85d1f00 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,11 +3,11 @@ # -- Project information project = "TornadoVM" -copyright = "2013-2023, APT Group, Department of Computer Science" +copyright = "2013-2024, APT Group, Department of Computer Science" author = "The University of Manchester" -release = "v1.0" -version = "v1.0" +release = "v1.0.4" +version = "v1.0.4" # -- General configuration diff --git a/docs/source/index.rst b/docs/source/index.rst index 1540fe419f..7a85db0987 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,23 +2,41 @@ TornadoVM =================================== .. image:: images/logo.jpg - :width: 100 + :width: 150 :alt: Sample Text :align: left -TornadoVM is a plug-in to OpenJDK and other JDK distributions (e.g., GraalVM, Red Hat Mandrel, Amazon Corretto, Microsoft OpenJDK, Azul Zulu) +TornadoVM is a plug-in to OpenJDK and other JDK distributions (e.g., GraalVM, Red Hat Mandrel, Amazon Corretto, Microsoft OpenJDK, SAP, Azul Zulu) that allows developers to automatically run Java programs on heterogeneous hardware. -TornadoVM targets devices compatible with OpenCL, PTX and Level-Zero, which include multi-core CPUs, -dedicated GPUs (Intel, NVIDIA, AMD), integrated GPUs (Intel HD Graphics and ARM Mali), and FPGAs (Intel and Xilinx). +TornadoVM targets devices compatible with OpenCL, NVIDIA PTX and Level-Zero, which include multi-core CPUs, +dedicated GPUs (Intel, NVIDIA, AMD), integrated GPUs (Intel HD Graphics, Apple M1/M2/M3, and ARM Mali), and FPGAs (Intel and Xilinx). -TornadoVM has three backends: OpenCL, NVIDIA CUDA PTX, and SPIR-V. -Developers can choose which backends to install and run. +TornadoVM provides three backends: + - OpenCL C: dispatched through an OpenCL runtime. + - NVIDIA CUDA PTX: dispatched through the NVIDIA driver API. + - SPIR-V: dispatched through the Level-Zero API. -TornadoVM does not replace existing VMs, but it rather complements them with the capability of offloading Java code to OpenCL, PTX and SPIR-V, +Developers can choose which backend/s to install and run. + + +What is unique about TornadoVM? +-------------------------------- + +TornadoVM does not only provide a set of JIT compilers to transpile Java bytecode to the target backend-code. +It also provides a set of runtime features that make it unique in the Java scope: + +- **Dynamic reconfiguration and live-task migration** across devices at runtime. +- **Live profiling:** TornadoVM provides utilities to profile and debug code on multiple platforms, including FPGAs. +- **Batch processing:** TornadoVM provides utilities to perform automatic split and batch processing for acceleration of big-data applications. +- **Multi-device & Multi-backend support:** TornadoVM can offload and run multiple kernels concurrently using different hardware accelerators using different backends. +- **TornadoVM is multi-vendor**, running applications on NVIDIA, Intel, AMD, ARM and even RISC-V hardware accelerators. + + +**Important:** TornadoVM does not replace existing VMs, but it rather complements them with the capability of offloading Java code to OpenCL, PTX and SPIR-V, handling memory management between Java and hardware accelerators, and running/coordinating the compute-kernels. -Contents +Content: -------- .. toctree:: diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 2499b1e905..afa97c79a0 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -6,16 +6,16 @@ Pre-requisites These need to be installed before executing either automatic or manual TornadoVM installation: -* GCC >= 9.0 or LLVM/clang (Linux) -* Xcode >= 15 (macOS) -* Visual Studio Community 2022 (Windows) -* Python >= 3.0 (all OSes) +* GCC >= 10.0 or LLVM/clang (Linux) +* Xcode >= 15 (macOS only) +* Visual Studio Community 2022 (Windows only) +* Python >= 3.6 (all OSes) * At least one of following drivers: * OpenCL drivers: GPUs and CPUs >= 2.1, FPGAs >= 1.0 * NVIDIA drivers and CUDA Toolkit 10.0+ * Intel drivers and Level-Zero >= 1.2 -For macOS users: the OpenCL support for your Apple model can be confirmed `here `_. +For Intel-based MacOS users: the OpenCL support for your Apple model can be confirmed `here `_. Supported Platforms *********************** @@ -27,29 +27,23 @@ The following table includes the platforms that TornadoVM can be executed. +===========================+===========================================================+=================+======================+ | CentOS >= 7.3 | OpenCL for GPUs and CPUs >= 2.1, OpenCL for FPGAs >= 1.0 | CUDA 10.0+ | Level-Zero >= 1.2 | +---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -| Fedora >= 21 | OpenCL for GPUs and CPUs >= 2.1, OpenCL for FPGAs >= 1.0 | CUDA 10.0+ | Level-Zero >= 1.2 | +| Fedora >= 39 | OpenCL for GPUs and CPUs >= 2.1, OpenCL for FPGAs >= 1.0 | CUDA 10.0+ | Level-Zero >= 1.2 | +---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -| Ubuntu >= 16.04 | OpenCL for GPUs and CPUs >= 2.1, OpenCL for FPGAs >= 1.0 | CUDA 10.0+ | Level-Zero >= 1.2 | +| Ubuntu >= 20.04 | OpenCL for GPUs and CPUs >= 2.1, OpenCL for FPGAs >= 1.0 | CUDA 10.0+ | Level-Zero >= 1.2 | +---------------------------+-----------------------------------------------------------+-----------------+----------------------+ | Pop!_OS >= 22.04 | OpenCL for GPUs and CPUs >= 2.1, OpenCL for FPGAs >= 1.0 | CUDA 10.0+ | Level-Zero >= 1.2 | +---------------------------+-----------------------------------------------------------+-----------------+----------------------+ | OpenSuse Leap 15.4 | OpenCL for GPUs and CPUs >= 2.1, OpenCL for FPGAs >= 1.0 | CUDA 10.0+ | Level-Zero >= 1.2 | +---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -| macOS Mojave 10.14.6 | OpenCL for GPUs and CPUs >= 1.2 | Not supported | Not supported | -+---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -| macOS Catalina 10.15.3 | OpenCL for GPUs and CPUs >= 1.2 | Not supported | Not supported | -+---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -| macOS Big Sur 11.5.1 | OpenCL for GPUs and CPUs >= 1.2 | Not supported | Not supported | -+---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -| macOS Sonoma 14.3 | OpenCL for GPUs and CPUs >= 1.2 | Not supported | Not supported | -+---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -| Apple M1 | OpenCL for GPUs and CPUs >= 1.2 | Not supported | Not supported | +| Apple M1/M2/M3 | OpenCL for GPUs and CPUs >= 1.2 | Not supported | Not supported | +---------------------------+-----------------------------------------------------------+-----------------+----------------------+ | Windows 10/11 | OpenCL for GPUs and CPUs >= 2.1, FPGAs not tested | CUDA 12.0+ | Level-Zero >= 1.2 | +---------------------------+-----------------------------------------------------------+-----------------+----------------------+ +| Windows WSL | OpenCL for GPUs and CPUs >= 2.1, FPGAs not tested | Not Supported | Level-Zero >= 1.2 | ++---------------------------+-----------------------------------------------------------+-----------------+----------------------+ -**Note:** The SPIR-V backend of TornadoVM is only supported for Linux OS. -Besides, the SPIR-V backend with Level Zero runs on Intel HD Graphics (integrated GPUs), and Intel ARC GPUs. +**Note:** The SPIR-V backend of TornadoVM is supported for Linux and Windows. +The SPIR-V backend with Level Zero runs on Intel HD Graphics (integrated GPUs), and Intel ARC GPUs. .. _installation: @@ -57,12 +51,11 @@ Installation ***************** TornadoVM can be built with three compiler backends and is able to generate OpenCL, PTX and SPIR-V code. -There are two ways to install TornadoVM: -A) Automatic Installation -=========================== +Installation Script +==================== -The ``tornadovm-installer`` script provided in this repository will compile/download OpenJDK, CMake, Maven and it will build TornadoVM. +The ``tornadovm-installer`` script provided in this repository will compile/download ``OpenJDK``, ``CMake``, ``Maven`` and it will build the TornadoVM project. This installation script has been tested on Linux, macOS and Windows. Additionally, this installation type will automatically trigger all dependencies, therefore it is recommended if users only need to invoke TornadoVM as a library. @@ -70,25 +63,27 @@ Additionally, this installation type will automatically trigger all dependencies $ ./bin/tornadovm-installer usage: tornadovm-installer [-h] [--version] [--jdk JDK] [--backend BACKEND] [--listJDKs] [--javaHome JAVAHOME] + [--polyglot] TornadoVM Installer Tool. It will install all software dependencies except the GPU/FPGA drivers - optional arguments: - -h, --help show this help message and exit - --version Print version of TornadoVM - --jdk JDK Select one of the supported JDKs. Use --listJDKs option to see all supported ones. - --backend BACKEND Select the backend to install: { opencl, ptx, spirv } - --listJDKs List all JDK supported versions - --javaHome JAVAHOME Use a JDK from a user directory + options: + -h, --help show this help message and exit + --version Print version of TornadoVM + --jdk JDK Select one of the supported JDKs. Use --listJDKs option to see all supported ones. + --backend BACKEND Select the backend to install: { opencl, ptx, spirv } + --listJDKs List all JDK supported versions + --javaHome JAVAHOME Use a JDK from a user directory + --polyglot To enable interoperability with Truffle Programming Languages. **Note:** Select the desired backend with the ``--backend`` option: - * ``opencl``: Enables the OpenCL backend (it requires OpenCL drivers) - * ``ptx``: Enables the PTX backend (it requires NVIDIA CUDA drivers) + * ``opencl``: Enables the OpenCL backend (it requires OpenCL drivers and OpenCL SDK installed) + * ``ptx``: Enables the PTX backend (it requires NVIDIA Driver and the CUDA SDK) * ``spirv``: Enables the SPIRV backend (it requires Intel Level Zero drivers) -For example, to build TornadoVM with GraalVM and JDK 21: +For example, to build TornadoVM with GraalVM (JDK21) for all backends: .. code-block:: bash @@ -145,387 +140,113 @@ On Windows by using: C:> setvars.cmd -B) Manual Installation -======================== - -TornadoVM can be executed with the following configurations: - -**Note**: For simplicity you can use `SDKMAN `_ for managing multiple JDK versions. - -Linux -~~~~~~~~ - -- TornadoVM with GraalVM for Linux and macOS (JDK 21): see the installation guide here: :ref:`installation_graalvm`. -- TornadoVM with JDK21 (e.g. OpenJDK 21, Red Hat Mandrel, Amazon Corretto): see the installation guide: :ref:`installation_jdk17plus`. - -Windows -~~~~~~~~~~ - -To run TornadoVM on **Windows 10/11**, install TornadoVM with GraalVM. More information here: :ref:`installation_windows`. - - -ARM Mali GPUs and Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To run TornadoVM on ARM Mali, install TornadoVM with GraalVM and JDK 21. More information here: :ref:`installation_mali`. - - -Compilation with Maven -~~~~~~~~~~~~~~~~~~~~~~~~ -This installation type requires users to manually install all the dependencies, therefore it is recommended for developing TornadoVM. -At least one backend must be specified at build time to the ``make`` command: - -.. code-block:: bash - - ## Choose the desired backend - $ make BACKENDS=opencl,ptx,spirv - +.. _installation_linux: -.. _installation_graalvm: +Installation for Linux +======================= -Installation for GraalVM for JDK 21.0.1 on Linux and macOS -================================================================ - -1. Download GraalVM JDK 21.0.1 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -GraalVM **Community Edition** builds are available to download at: - -`https://github.com/graalvm/graalvm-ce-builds/releases/tag/jdk-21.0.1 `_. - -The examples below show how to download and extract GraalVM for JDK 21.0.0 - - -- Example for GraalVM for JDK 21 Community 21.0.1: +Download dependencies (Red Hat-based): .. code:: bash - $ wget https://github.com/graalvm/graalvm-ce-builds/releases/tag/jdk-21.0.1/graalvm-community-jdk-21.0.1_linux-x64_bin.tar.gz - $ tar -xf graalvm-community-jdk-21.0.1_linux-x64_bin.tar.gz - -with SDKMAN: - -.. code:: bash - - $ sdk install java 21-graalce - $ sdk use java 21-graalce - - -The Java binary will be found in the `graalvm-jdk-{JDK_VERSION}-23.1.0` directory. This directory is used as the JAVA_HOME (See step 2). + sudo dnf install gcc g++ git cmake python3 -**Note** if installed with SDKMAN there is no need to manually set your JAVA_HOME. -For macOS: - -- Example for GraalVM for JDK 21 Community 21.0.1: - -.. code:: bash - - $ wget https://github.com/graalvm/graalvm-ce-builds/releases/tag/jdk-21.0.1/graalvm-community-jdk-21.0.1_macos-x64_bin.tar.gz - -then ``untar`` it to the macOS standard JDK location -``/Library/Java/JavaVirtualMachines/`` or to a folder of your choice. - -1. Download TornadoVM -~~~~~~~~~~~~~~~~~~~~~ +Download dependencies (Ubuntu-based): .. code:: bash - $ cd .. - $ git clone https://github.com/beehive-lab/TornadoVM tornadovm - $ cd tornadovm + sudo apt-get install gcc g++ git cmake python3 -Create/edit your configuration file: -.. code:: bash - - $ vim etc/sources.env - -The first time you need to create the ``etc/sources.env`` file and add -the following code in it **(after updating the paths to your correct -ones)**: - -.. code:: bash +Install the driver/s. Download the required driver/s from the hardware vendor as well as the required SDKs (e.g. CUDA for NVIDIA GPUs). - #!/bin/bash - export JAVA_HOME= ## This path is produced in Step 1 - export PATH=$PWD/bin/bin:$PATH ## This directory will be automatically generated during Tornado compilation - export TORNADO_SDK=$PWD/bin/sdk ## This directory will be automatically generated during Tornado compilation - export CMAKE_ROOT=/usr ## or (see step 4) -This file should be loaded once after opening the command prompt for the -setup of the required paths: +Once the drivers and SDK are installed, download and build TornadoVM. +For example, using JDK 21 for all backends: .. code:: bash - $ source ./etc/sources.env - -For macOS: the exports above may be added to ``~/.profile`` - -3. Install CMAKE (if cmake < 3.6) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For Linux: -^^^^^^^^^^ - -.. code::bash - - $ cmake -version - -**If the version of cmake is > 3.6 then skip the rest of this step and -go to Step 4.** Otherwise try to install cmake. - -For simplicity it might be easier to install cmake in your home -directory. \* Redhat Enterprise Linux / CentOS use cmake v2.8 \* We -require a newer version so that OpenCL is configured properly. - -.. code:: bash - - $ cd ~/Downloads - $ wget https://cmake.org/files/v3.10/cmake-3.10.1-Linux-x86_64.tar.gz - $ cd ~/opt - $ tar -tvf ~/Downloads/cmake-3.10.1-Linux-x86_64.tar.gz - $ mv cmake-3.10.1-Linux-x86_64 cmake-3.10.1 - $ export PATH=$HOME/opt/cmake-3.10.1/bin/:$PATH - $ cmake -version - cmake version 3.10.1 - -Then export ``CMAKE_ROOT`` variable to the cmake installation. You can -add it to the ``./etc/sources.env`` file. - -.. code:: bash - - $ export CMAKE_ROOT=/opt/cmake-3.10.1 - -For macOS: -^^^^^^^^^^^^ - -Install cmake: - -.. code:: bash - - $ brew install cmake - -then - -.. code:: bash - - export CMAKE_ROOT=/usr/local - -which can be added to ``~/.profile`` - -4. Compile TornadoVM with GraalVM -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: bash - - $ cd ~/tornadovm - $ . etc/sources.env - -To build with GraalVM and JDK 21: - -.. code:: bash - - $ make graal-jdk-21 BACKEND={ptx,opencl} - -and done!! - - -.. _installation_jdk17plus: - -TornadoVM for JDK 21 on Linux and macOS -============================================== - - -**DISCLAIMER:** - -TornadoVM is based on the Graal compiler that depends on JVMCI (Java Virtual Machine Compiler Interface). Different JDKs come with different -versions of JVMCI. Therefore, the version of the Graal compiler that TornadoVM uses might not be compatible with the JVMCI version of some -JDKs. Below are listed the Java 21 JDK distributions against which TornadoVM has been tested, but compatibility is not guaranteed. - -.. code:: bash - - ./bin/tornadovm-installer --listJDKs - jdk21 : Install TornadoVM with OpenJDK 21 (Oracle OpenJDK) - graal-jdk-21 : Install TornadoVM with GraalVM and JDK 21 (GraalVM 23.1.0) - mandrel-jdk-21 : Install TornadoVM with Mandrel and JDK 21 (GraalVM 23.1.0) - corretto-jdk-21 : Install TornadoVM with Corretto JDK 21 - zulu-jdk-jdk-21 : Install TornadoVM with Azul Zulu JDK 21 - temurin-jdk-21 : Install TornadoVM with Eclipse Temurin JDK 21 - - -1. Download a JDK 21 distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- OpenJDK distributions are available to download at https://adoptium.net/. -- Red Hat Mandrel releases are available at https://github.com/graalvm/mandrel/releases. -- Amazon Coretto releases are available at https://aws.amazon.com/corretto/. -- Microsoft OpenJDK releases are available at https://docs.microsoft.com/en-us/java/openjdk/download. Azul Zulu -- OpenJDK releases are available at `https://www.azul.com/downloads `__. -- Eclipse Temurin releases are available at `https://github.com/adoptium/temurin21-binaries/releases/tag/jdk-21.0.1%2B12 `__. - -1.1 Manage JDKs manually -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After downloading and extracting the JDK distribution, point your ``JAVA_HOME`` variable to the JDK root. - -Example using Amazon Corretto: - -.. code:: bash - - $ wget https://corretto.aws/downloads/latest/amazon-corretto-21-x64-linux-jdk.tar.gz - $ tar xf amazon-corretto-21-x64-linux-jdk.tar.gz - $ export JAVA_HOME=$PWD/amazon-corretto-21-x64-linux - -1.2 Manage JDKs with SDKMAN -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -There is no need to change your ``JAVA_HOME`` as SDKMAN exports it every time you switch between distributions. - -Example using Amazon Corretto: - -.. code:: bash - - $ sdk install java 21-amzn - $ sdk use java 21-amzn - -A complete list of all available Java Versions for Linux 64bit can be obtained with: - -.. code:: bash - - $ sdk list java - -2. Download TornadoVM -~~~~~~~~~~~~~~~~~~~~~ - -.. code:: bash - - $ git clone https://github.com/beehive-lab/TornadoVM tornadovm - $ cd tornadovm - -Create/edit your configuration file: - -.. code:: bash - - $ vim etc/sources.env - -The first time you need to create the ``etc/sources.env`` file and add -the following code in it **(after updating the paths to your correct -ones)**: - -.. code:: bash + git clone https://github.com/beehive-lab/TornadoVM.git + cd TornadoVM + bin/tornadovm-installer --jdk jdk21 --backend opencl,ptx,spirv + source setvars.sh - #!/bin/bash - export JAVA_HOME= ## This path is produced in Step 1 - export PATH=$PWD/bin/bin:$PATH ## This directory will be automatically generated during Tornado compilation - export TORNADO_SDK=$PWD/bin/sdk ## This directory will be automatically generated during Tornado compilation - export CMAKE_ROOT=/usr ## or (see step 4) -This file should be loaded once after opening the command prompt for the -setup of the required paths: +Check the installation: .. code:: bash - $ source ./etc/sources.env + # list the accelerator devices that are reachable from TornadoVM + tornado --devices -For macOS: the exports above may be added to ``~/.profile`` + # run unit tests + tornado-test -V + ## run specific examples (e.g., NBody) + tornado -m tornado.examples/uk.ac.manchester.tornado.examples.compute.NBody -3. Install CMAKE (if cmake < 3.6) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For Linux: -^^^^^^^^^^ +To recompile TornadoVM to use a different backend: .. code:: bash - $ cmake -version + source setvars.sh + make BACKEND=opencl -**If the version of cmake is > 3.6 then skip the rest of this step and -go to Step 4.** Otherwise try to install cmake. -For simplicity it might be easier to install cmake in your home -directory. -- Redhat Enterprise Linux / CentOS use cmake v2.8 -- We require a newer version so that OpenCL is configured properly. +.. _installation_appleMSeries: -.. code:: bash +Installation for MacOS M1/M2/M3 +================================= - $ cd ~/Downloads - $ wget https://cmake.org/files/v3.10/cmake-3.10.1-Linux-x86_64.tar.gz - $ cd ~/opt - $ tar -tvf ~/Downloads/cmake-3.10.1-Linux-x86_64.tar.gz - $ mv cmake-3.10.1-Linux-x86_64 cmake-3.10.1 - $ export PATH=$HOME/opt/cmake-3.10.1/bin/:$PATH - $ cmake -version - cmake version 3.10.1 -Then export ``CMAKE_ROOT`` variable to the cmake installation. You can -add it to the ``./etc/sources.env`` file. +Download dependencies: .. code:: bash - $ export CMAKE_ROOT=/opt/cmake-3.10.1 + brew install wget + brew install maven -For macOS: -^^^^^^^^^^^^^ -Install cmake: +Download and install TornadoVM. Note that, in OSx Apple M1/M2/M3 chip, the only backend supported is OpenCL. -.. code:: bash - - $ brew install cmake - -then .. code:: bash - export CMAKE_ROOT=/usr/local - -which can be added to ``~/.profile`` - -4. Compile TornadoVM for JDK 21 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: bash + git clone https://github.com/beehive-lab/TornadoVM.git + cd TornadoVM + bin/tornadovm-installer --jdk graal-jdk-21 --backend opencl + source setvars.sh - $ cd ~/tornadovm - $ . etc/sources.env -To build with a distribution of JDK 21 +Check the installation: .. code:: bash - $ make jdk21 BACKEND={ptx,opencl} - -and done!! - -Running with JDK 21 -~~~~~~~~~~~~~~~~~~~~~~~~~~ + # list the accelerator devices that are reachable from TornadoVM + tornado --devices -TornadoVM uses modules: + # run unit tests + tornado-test -V -To run examples: + ## run specific examples (e.g., NBody) + tornado -m tornado.examples/uk.ac.manchester.tornado.examples.compute.NBody -.. code:: bash - $ tornado -m tornado.examples/uk.ac.manchester.tornado.examples.compute.MatrixMultiplication2D --params "512" - -To run benchmarks: +To recompile TornadoVM after an update: .. code:: bash - $ tornado -m tornado.benchmarks/uk.ac.manchester.tornado.benchmarks.BenchmarkRunner --params "dft" - -To run individual tests: - -.. code:: bash + source setvars.sh + make - tornado --jvm "-Dtornado.unittests.verbose=True -Xmx6g" -m tornado.unittests/uk.ac.manchester.tornado.unittests.tools.TornadoTestRunner --params "uk.ac.manchester.tornado.unittests.arrays.TestArrays" .. _installation_windows: -Installing TornadoVM for Windows 10/11 +Installation for Windows 10/11 ====================================== **[DISCLAIMER] Please, note that, although TornadoVM can run on Windows 10/11, it is still experimental.** @@ -609,11 +330,8 @@ Hereafter, the directory with the source code will be referred as ``` 5. Configure/Compile the TornadoVM Project ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are two ways to install it. Choose one of them. We highly recommend the first option, since it will install -the required software dependencies. - -A) Using the automatic installation script. This script downloads the following dependencies: +The installation script downloads the following dependencies: - Java - Maven @@ -628,12 +346,7 @@ A) Using the automatic installation script. This script downloads the following setvars.cmd - -B) Manual installation - -In this case, you need to install all dependencies (Java, maven and cmake) before building the project. -Once all dependencies are provided, execute the following commands: - +And TornadoVM is ready to be used. If you want to recompile with a different backend: .. code:: bash @@ -662,14 +375,13 @@ Once all dependencies are provided, execute the following commands: .. _installation_mali: -TornadoVM on ARM Mali GPUs +Installation for ARM Mali GPUs ==================================== 1. Installation ~~~~~~~~~~~~~~~~~ The installation of TornadoVM to run on ARM Mali GPUs requires JDK21 with GraalVM. -See the :ref:`installation_graalvm` for details about the installation. The OpenCL driver for Mali GPUs on Linux that has been tested is: @@ -696,12 +408,44 @@ However, this extension is not available on Bifrost GPUs. The rest of the unittests should pass. +Running Examples +================= + +TornadoVM uses modules: + +To run examples: + +.. code:: bash + + $ tornado -m tornado.examples/uk.ac.manchester.tornado.examples.compute.MatrixMultiplication2D 1024 + +To run benchmarks: + +.. code:: bash + + $ tornado -m tornado.benchmarks/uk.ac.manchester.tornado.benchmarks.BenchmarkRunner dft + + +Run tests: + +.. code:: bash + + tornado-test -V + + +To run individual tests: + +.. code:: bash + + tornado --jvm "-Dtornado.unittests.verbose=True -Xmx6g" -m tornado.unittests/uk.ac.manchester.tornado.unittests.tools.TornadoTestRunner uk.ac.manchester.tornado.unittests.arrays.TestArrays + + Known issues on Linux -=============================== +======================= -For Ubuntu >= 16.04, install the package ``ocl-icd-opencl-dev`` +- For Ubuntu >= 16.04, install the package ``ocl-icd-opencl-dev`` -In Ubuntu >= 16.04 CMake can cause the following error: +- In Ubuntu >= 16.04 CMake can cause the following error: ``Could NOT find OpenCL (missing: OpenCL_LIBRARY) (found version "2.2").`` diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index a986d91b20..64590367ee 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -8,9 +8,9 @@ Introduction to TornadoVM :align: left TornadoVM is a plug-in to OpenJDK and other JDK distributions (e.g., GraalVM, Red Hat Mandrel, Amazon Corretto, Microsoft OpenJDK, Azul Zulu) -that allows developers to automatically run Java programs on heterogeneous hardware. -TornadoVM targets devices compatible with OpenCL, PTX and Level-Zero, which include multi-core CPUs, -dedicated GPUs (Intel, NVIDIA, AMD), integrated GPUs (Intel HD Graphics and ARM Mali), and FPGAs (Intel and Xilinx). +that allows developers to automatically offload and run a subset of Java programs on heterogeneous hardware. +TornadoVM targets devices compatible with OpenCL, NVIDIA PTX, and Level-Zero, which include multi-core CPUs (Intel and AMD), +dedicated GPUs (Intel, NVIDIA, AMD), integrated GPUs (Intel HD Graphics, Apple M1/M2/M3, and ARM Mali), and FPGAs (Intel and Xilinx). .. image:: images/tornadovm-01.png :width: 800 @@ -19,7 +19,7 @@ dedicated GPUs (Intel, NVIDIA, AMD), integrated GPUs (Intel HD Graphics and ARM TornadoVM currently has three backends: It compiles Java code, at runtime, from Java bytecode to OpenCL C, NVIDIA CUDA PTX, and SPIR-V binary. -Developers can choose which backends to install and run. +Developers can choose which backend/s to install and run. .. image:: images/tornadovm-02.png :width: 800 @@ -44,4 +44,4 @@ TornadoVM includes the following features: - **Containers:** TornadoVM can be used within Docker containers for running on NVIDIA GPUs, Intel CPUs and Intel GPUs. -TornadoVM is a research project developed at APT Group at The University of Manchester. +TornadoVM is a research project in active development created under the `APT Group `_ at `The University of Manchester `_. \ No newline at end of file diff --git a/docs/source/resources.rst b/docs/source/resources.rst index c80df6efb1..7d1473999d 100644 --- a/docs/source/resources.rst +++ b/docs/source/resources.rst @@ -6,17 +6,32 @@ Resources Videos ------ -- A. Stratikopoulos, `Write Once, Run Anywhere... Well, What About Heterogeneous Hardware? `__, FOSDEM 2023 +- M. Papadimitriou, `Revolutionizing Java-based LLMs: Unleashing the Power of GPUs with TornadoVM `_, Devoxx UK 2024. + +- A. Stratikopoulos, `Java… to unlock GPU acceleration for Polyglot Language Runtimes `_, FOSDEM 2024. + +- A. Stratikopoulos, `TornadoVM: Write once, run everywhere everywhere! `_, Devoxx Belgium 2023. + +- J. Fumero, `From CPU to GPU and FPGAs: Supercharging Java Applications with TornadoVM `_, JVMLS 2023. + +- J. Fumero, `oneAPI Meetup TornadoVM with Juan Fumero `_ oneAPI Meetup 2023. + +- A. Stratikopoulos, `Write Once, Run Anywhere... Well, What About Heterogeneous Hardware? `__, FOSDEM 2023. + +- A. Stratikopoulos, `TornadoVM: Hardware Acceleration For Java In Practice `__, FOSDEM 2022. + +- J. Fumero, `TornadoVM: Transparent Hardware Acceleration for Java…and Beyond! `_, JavaZone 2021. - J. Fumero, `TornadoVM: Transparent Hardware Acceleration for Java and Beyond! `__, Devoxx Ukraine 2021. - J. Fumero, `Level up Your Java Performance with TornadoVM `__, QCon Plus 2021. -- A. Stratikopoulos, `TornadoVM: A virtual machine for exploiting high performance heterogeneous hardware of Java programs `__, FOSDEM, 01/02/2020. +- A. Stratikopoulos, `TornadoVM: A virtual machine for exploiting high performance heterogeneous hardware of Java programs `__, FOSDEM 2020. + +- J. Fumero, `TornadoVM: A virtual machine for exploiting high performance heterogeneous hardware `__, Joker 2019. -- J. Fumero, `TornadoVM: A virtual machine for exploiting high performance heterogeneous hardware `__, Joker Conference, 26/10/2019. +- J. Fumero, `Overview of TornadoVM `__, JVMLS 2019. -- J. Fumero, `Overview of TornadoVM `__, JVMLS, 31/07/2019. Presentations ------------- @@ -31,6 +46,10 @@ Presentations Podcast ------------- +- Adam Bien Podcast with Juan Fumero: `TornadoVM, Paravox.ai: Java, AI, LLMs and Hardware Acceleration `_. + +- Adam Bien Podcast with Juan Fumero: `FPGAs, GPUs or Data Science with Java `_. + - Foojay Podcast #17: Execute Java Code with TornadoVM on CPUs, GPUs, and FPGAs (March 2023): `link `__ - TornadoVM at Software Engineering Daily (2019): `link `__