From 82030b8e28fe2e1b5509f86e82469a15fb084681 Mon Sep 17 00:00:00 2001 From: Marko Rakita Date: Wed, 4 Dec 2024 16:07:28 +0100 Subject: [PATCH] Update README.md (#101) Updating the readme docs after some feedback from community and new devs --- README.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 7495730..f9c4c8f 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,34 @@ # tt-xla -tt-xla leverages pjrt to provide a hardware and framework independent interface for compilers and runtimes and simplifies the integration of hardware with frameworks. Please see the [blog](https://opensource.googleblog.com/2023/05/pjrt-simplifying-ml-hardware-and-framework-integration.html) for more information about PJRT project. This project is a fork of [iree-pjrt](https://github.com/stellaraccident/iree-pjrt) +tt-xla leverages [PJRT](https://github.com/openxla/xla/tree/main/xla/pjrt/c#pjrt---uniform-device-api) to integrate JAX (and in the future other frameworks), [tt-mlir](https://github.com/tenstorrent/tt-mlir) and Tenstorrent hardware. Please see [this](https://opensource.googleblog.com/2023/05/pjrt-simplifying-ml-hardware-and-framework-integration.html) blog post for more information about PJRT project. This project is a fork of [iree-pjrt](https://github.com/stellaraccident/iree-pjrt). -**Note** This project is currently only supported for `nebula` boards and does not provide support for `galaxy` boards. +**Note:** Currently only Tenstorrent `nebula` boards are supported and `galaxy` boards are not yet supported. ## Build Process -tt-xla and stableHLO integration with tt-mlir compiler is still under progress. This build flow provides an easy way to experiment with tt-xla, stableHLO, and tt-mlir infrastructure. This build process will be updated to enhance the user experience. Before compiling, please ensure environtment variable `TTMLIR_TOOLCHAIN_DIR` is set. +tt-xla integration with tt-mlir compiler is still under progress and currently it depends on tt-mlir toolchain for build. This build flow provides an easy way to experiment with tt-xla, StableHLO and tt-mlir infrastructure. Build process will be updated in the future to enhance the user experience. -### tt-mlir environment -- clone tt-mlir [repo](https://github.com/tenstorrent/tt-mlir). -- Follow tt-mlir build [instructions](https://docs.tenstorrent.com/tt-mlir/build.html) to build tt-mlir environment and install all dependencies. +### tt-mlir toolchain +Before compiling tt-xla, tt-mlir toolchain needs to be built: +- Clone [tt-mlir](https://github.com/tenstorrent/tt-mlir) repo +- Follow tt-mlir [build instructions](https://docs.tenstorrent.com/tt-mlir/build.html) to setup the environment and build the toolchain ### tt-xla -This `tt-xla` repo is updated to use cmake instead of bazel and made compatible with tt-mlir compiler. -``` +Before running these commands to build tt-xla, please ensure that the environtment variable `TTMLIR_TOOLCHAIN_DIR` is set to point to the tt-mlir toolchain directory created above as part of tt-mlir environment setup (for example `export TTMLIR_TOOLCHAIN_DIR=/opt/ttmlir-toolchain/`). You can also set `export LOGGER_LEVEL=DEBUG` in order to enable debug logs. + +```bash git clone git@github.com:tenstorrent/tt-xla.git cd tt-xla source venv/activate -cmake -G Ninja -B build +cmake -G Ninja -B build # -DCMAKE_BUILD_TYPE=Debug in case you want debug build cmake --build build ``` ## Testing -tt-xla repo contains various tests in `tests` directory. To run them, please run `pytest -v tests` from project root directory. +tt-xla repo contains various tests in `tests` directory. To run them all, please run `pytest -v tests` from project root directory. To run individual test, `pytest -svv` is recommended in order to capture all potential error messages down the line. -## Common Build Errors (tt-xla repo) +## Common Build Errors - Building `tt-xla` requires `clang-17`. Please make sure that `clang-17` is installed on the system and `clang/clang++` link to correct version of respective tools. -- `tt-xla` also builds `tt-metal` and it may cause `sfpi-trisc-ncrisc-build-failure`. Please use this [fix](https://docs.tenstorrent.com/tt-mlir/build.html#sfpi-trisc-ncrisc-build-failure). +- `tt-xla` also builds `tt-metal` and it may cause `sfpi-trisc-ncrisc-build-failure`. Please use [this](https://docs.tenstorrent.com/tt-mlir/build.html#sfpi-trisc-ncrisc-build-failure) fix. +- Please see tt-mlir [docs](https://docs.tenstorrent.com/tt-mlir/build.html#common-build-errors) for common build errors. ### Pre-Commit Pre-Commit applies a git hook to the local repository such that linting is checked and applied on every `git commit` action. Install from the root of the repository using: @@ -35,10 +38,10 @@ source venv/activate pre-commit install ``` -If you have already committed before installing the pre-commit hooks, you can run on all files to "catch up": +If you have already committed something locally before installing the pre-commit hooks, you can run this command to "catch up" on all files: ```bash pre-commit run --all-files ``` -For more information visit [pre-commit](https://pre-commit.com/) +For more information please visit [pre-commit](https://pre-commit.com/).