{"owner":"openxla","repo":"xla","hasSkills":true,"totalSkillsCount":15,"totalTokensCount":6765,"categories":["plugin-manifest","root-instruction","gemini-rule","project-spec"],"hasMcp":false,"mcpConfig":null,"found":["build_tools/ci/readme.md","tools/toolchains/clang6/README.md","AGENTS.md","xla/GEMINI.md","xla/AGENTS.md","docs/architecture.md","tools/toolchains/embedded/README.md","tools/toolchains/cpus/aarch64/README.md","tools/toolchains/embedded/arm-linux/README.md","xla/tools/multihost_hlo_runner/README.md","xla/mlir/tools/mlir_bisect/README.md","xla/mlir/tools/mlir_interpreter/README.md","xla/mlir/tools/mlir_replay/README.md","xla/pjrt/extensions/example/README.md","xla/tools/benchmarks/hlo_workload_executor/README.md"],"skills":{"build_tools/ci/readme.md":"This folder contains scripts and commands executed by GitHub actions in OpenXLA,\nTensorFlow and JAX OSS repos. The GitHub actions replaced\nKokoroPresubmit-tensorflow* workflows. They run under\n`Copybara_XLA{Presubmit,Submit}` presubmit chip (category) at Google internally.\nThe tests run on several target OS configurations/GCP containers such as Linux\nx86 with GPU or Linux ARM64. They assure that XLA/Tensor Flow/JAX compiles and\nruns on those platforms. The tests uses released OSS c++ clang compiler which\nhas some differences in supporting c++ standards compared Google's internal\nversion.\n\n#### How it works\n\nRepo specific GitHub actions call `build.py --build=\"build_name\"`. E.g. OpenXLA\nuses https://github.com/openxla/xla/blob/main/.github/workflows/ci.yml\n\nThe build here is a set of shell script commands executing the test targets or\ndoing compile only testing. Each GitHub action call translates into compile only\ntest:\n\n1. actual compile `bazel build ... test_targets`\n1. analyse results `bazel analyze-profile ...`\n\nor compile and run test commands:\n\n1. actual test `bazel test ... test_targets`\n1. analyse results `bazel analyze-profile profile.json.gz`\n\nChecking in changes to `build.py` regenerates `golden_commands.txt` which lets\nus see how commands are changing. `golden_commands.txt` are not called as part\nof the continuous integration process.\n\n#### When does it run?\n\nThe GitHub actions are automatically called as part of Google presubmit. The\nGitHub actions are automatically called on GitHub PR commit if the committer is\npart of OpenXLA GitHub org. Committer which are not part of OpenXLA org need an\napproval from OpenXLA org member to run the actions.\n","tools/toolchains/clang6/README.md":"# TensorFlow Bazel Clang\n\nThis is a specialized toolchain that uses an old Debian with a new Clang that\ncan cross compile to any x86_64 microarchitecture. It's intended to build Linux\nbinaries that only require the following ABIs:\n\n- GLIBC_2.18\n- CXXABI_1.3.7 (GCC 4.8.3)\n- GCC_4.2.0\n\nWhich are available on at least the following Linux platforms:\n\n- Ubuntu 14+\n- CentOS 7+\n- Debian 8+\n- SuSE 13.2+\n- Mint 17.3+\n- Manjaro 0.8.11\n\n# System Install\n\nOn Debian 8 (Jessie) Clang 6.0 can be installed as follows:\n\n```sh\ncat >>/etc/apt/sources.list <<'EOF'\ndeb http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\ndeb-src http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\nEOF\nwget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -\napt-key fingerprint |& grep '6084 F3CF 814B 57C1 CF12 EFD5 15CF 4D18 AF4F 7421'\napt-get update\napt-get install clang lld\n```\n\n# Bazel Configuration\n\nThis toolchain can compile TensorFlow in 2m30s on a 96-core Skylake GCE VM if\nthe following `.bazelrc` settings are added:\n\n```\nstartup --host_jvm_args=-Xmx30G\nstartup --host_jvm_args=-Xms30G\nstartup --host_jvm_args=-XX:MaxNewSize=3g\nstartup --host_jvm_args=-XX:-UseAdaptiveSizePolicy\nstartup --host_jvm_args=-XX:+UseConcMarkSweepGC\nstartup --host_jvm_args=-XX:TargetSurvivorRatio=70\nstartup --host_jvm_args=-XX:SurvivorRatio=6\nstartup --host_jvm_args=-XX:+UseCMSInitiatingOccupancyOnly\nstartup --host_jvm_args=-XX:CMSFullGCsBeforeCompaction=1\nstartup --host_jvm_args=-XX:CMSInitiatingOccupancyFraction=75\n\nbuild --jobs=100\nbuild --local_resources=200000,100,100\nbuild --crosstool_top=@local_config_clang6//clang6\nbuild --noexperimental_check_output_files\nbuild --nostamp\nbuild --config=opt\nbuild --noexperimental_check_output_files\nbuild --copt=-march=native\nbuild --host_copt=-march=native\n```\n\n# x86_64 Microarchitectures\n\n## Intel CPU Line\n\n- 2003 P6 M SSE SSE2\n- 2004 prescott SSE3 SSSE3 (-march=prescott)\n- 2006 core X64 SSE4.1 (only on 45nm variety) (-march=core2)\n- 2008 nehalem SSE4.2 VT-x VT-d (-march=nehalem)\n- 2010 westmere CLMUL AES (-march=westmere)\n- 2012 sandybridge AVX TXT (-march=sandybridge)\n- 2012 ivybridge F16C MOVBE (-march=ivybridge)\n- 2013 haswell AVX2 TSX BMI2 FMA (-march=haswell)\n- 2014 broadwell RDSEED ADCX PREFETCHW (-march=broadwell - works on trusty\n gcc4.9)\n- 2015 skylake SGX ADX MPX\n AVX-512[xeon-only](-march=skylake / -march=skylake-avx512 - needs gcc7)\n- 2018 cannonlake AVX-512 SHA (-march=cannonlake - needs clang5)\n\n## Intel Low Power CPU Line\n\n- 2013 silvermont SSE4.1 SSE4.2 VT-x (-march=silvermont)\n- 2016 goldmont SHA (-march=goldmont - needs clang5)\n\n## AMD CPU Line\n\n- 2003 k8 SSE SSE2 (-march=k8)\n- 2005 k8 (Venus) SSE3 (-march=k8-sse3)\n- 2008 barcelona SSE4a?! (-march=barcelona)\n- 2011 bulldozer SSE4.1 SSE4.2 CLMUL AVX AES FMA4?! (-march=bdver1)\n- 2011 piledriver FMA (-march=bdver2)\n- 2015 excavator AVX2 BMI2 MOVBE (-march=bdver4)\n\n## Google Compute Engine Supported CPUs\n\n- 2012 sandybridge 2.6gHz -march=sandybridge\n- 2012 ivybridge 2.5gHz -march=ivybridge\n- 2013 haswell 2.3gHz -march=haswell\n- 2014 broadwell 2.2gHz -march=broadwell\n- 2015 skylake 2.0gHz -march=skylake-avx512\n\nSee: \n","AGENTS.md":"# AI Assistant Guidelines for OpenXLA\n\nWelcome to the OpenXLA (`openxla/xla`) repository.\n\n* **Core XLA compiler guidelines**: When generating, reviewing, or modifying\n code under [`xla/`](xla/), follow the detailed C++, MLIR, testing, and\n Bazel guidelines in [`xla/AGENTS.md`](xla/AGENTS.md).\n* [`build_tools/`](build_tools/) contains CI and developer tooling,\n [`docs/`](docs/) the user-facing documentation, and\n [`third_party/`](third_party/) vendored dependencies and Bazel repository\n rules.\n","xla/GEMINI.md":"\nSee [AGENTS.md](AGENTS.md) for AI coding guidelines and best practices in this\ncodebase.\n","xla/AGENTS.md":"# AI Assistant Guidelines for OpenXLA Development\n\nThis document provides guidelines for AI code assistants when generating,\nsuggesting, or modifying code within the OpenXLA codebase (everything under\n`xla/` in this repository).\n\n## General Context\n\n* **Impact:** OpenXLA is a core compiler for machine learning acceleration. Changes here affect the open-source community and various hardware backends.\n* **Code Quality:** Adhere to [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) and OpenXLA-specific conventions.\n* **Portability:** This code is open-sourced and runs on a number of host platforms (e.g. Linux, Windows, etc.)\n\n## Repository Layout and Build\n\n* Source lives under `xla/`. Include paths are relative to the repository\n root, e.g. `#include \"xla/hlo/ir/hlo_module.h\"`.\n* Bazel labels use the same prefix, e.g. `//xla/hlo/ir:hlo_module`.\n* Build and test with Bazel, e.g. `bazel test //xla/service:hlo_verifier_test`.\n* Common external dependencies and their labels:\n `@com_google_absl//absl/...`, `@llvm-project//mlir/...`,\n `@llvm-project//llvm/...`, `@com_google_googletest//:gtest_main`,\n `@com_google_protobuf//:protobuf`. TSL (the platform layer) lives in-tree\n under `//xla/tsl/...`.\n* Test macros: `xla_cc_test` from `//xla:xla.default.bzl` (hardware-\n independent unit tests) and `xla_test` from `//xla/tests:build_defs.bzl`\n (tests that run on configured hardware backends).\n\n## Coding Guidelines for AI Assistance\n\n1. **Error Handling (`absl::Status`, `absl::StatusOr`)**:\n * **Always** use `absl::Status` or `absl::StatusOr` for functions that can encounter recoverable errors.\n * **Macros**:\n * Use header `absl/status/status_macros.h`.\n * Use `ABSL_RETURN_IF_ERROR` for error propagation.\n * Use `ABSL_ASSIGN_OR_RETURN` for `StatusOr` assignments.\n * **Safely access `StatusOr` values**: Check `.ok()` before accessing.\n\n2. **Assertions & Invariant Checks (`TF_RET_CHECK`)**:\n * **Avoid `DCHECK` / `LOG(DFATAL)`** for checking returnable errors.\n * **Prefer `TF_RET_CHECK`**:\n * Located in `xla/status_macros.h`.\n * Use strict internal invariant checks inside functions returning `absl::Status` / `StatusOr`.\n * Example:\n ```cpp\n #include \"xla/status_macros.h\"\n\n absl::Status Process(const Thing* t) {\n TF_RET_CHECK(t != nullptr) << \"Thing cannot be null\";\n // ...\n return absl::OkStatus();\n }\n ```\n\n3. **Decision making**:\n * **Avoid `bool`** for returning a decision to do or not to do something.\n * **Prefer `Decision`**:\n * Located in `xla/service/decision.h`\n * Example:\n ```cpp\n #include \"xla/service/decision.h\"\n\n using AutotunerDecision = Decision;\n\n AutotunerDecision ShouldAutotuneCublasCall(HloInstruction* instr) {\n // ...\n return AutotunerDecision::Forbid(\"Cublas autotuning was explicitly disabled\");\n }\n\n void AutotuneCublas(const AutotunerDecision& decision) {\n if (decision.IsForbidden()) {\n return;\n }\n ...\n ```\n\n4. **Performance Sensitivity**:\n * OpenXLA is a compiler; patterns should be efficient.\n * Avoid unnecessary string copies or expensive allocations in hot paths (e.g., HLO passes).\n\n5. **Testing**:\n * Write unit tests using `EXPECT_EQ`, `EXPECT_TRUE`, etc.\n * Use the status testing macros `ASSERT_OK_AND_ASSIGN`, `ASSERT_OK`, and\n `EXPECT_OK` from `` and the status matchers\n (`absl_testing::IsOk`, `absl_testing::IsOkAndHolds`,\n `absl_testing::StatusIs`) from `absl/status/status_matchers.h` instead\n of their legacy `TF_*` or `tsl::testing::*` counterparts:\n * DO NOT USE `TF_ASSERT_OK_AND_ASSIGN`, `TF_ASSERT_OK`, and\n `TF_EXPECT_OK`.\n * When you refactor code that uses the `TF_*` macros, replace them,\n but do not touch unrelated code.\n * Put tests into an anonymous namespace.\n * Use `HloInterpreterReferenceMixin` or\n `HloHardwareIndependentTestBase` for compiler pass tests locally where\n possible (do not use `HloTestBaseLegacy`).\n * When running GPU tests, pass `--config=cuda` to the test command.\n * Ensure tests are deterministic and do not flake.\n\n6. **BUILD targets**:\n * When defining BUILD targets prefer these XLA specific rules:\n * Instead of `proto_library` use `tf_proto_library`. There is no need\n to define language specific targets with `tf_proto_library`.\n * Instead of `cc_test` use `xla_cc_test` (or `xla_test` when the test\n requires a real hardware backend).\n\n7. **Explicit Typing**:\n * **Avoid `auto`** in public headers or complex logic chains.\n\n8. **Compiler Phases & Invariants**:\n * **Phase Ordering**: Understand where your pass or change sits in the pipeline (e.g., Optimizations, Layout Assignment, Fusion).\n * **Invariants**: Respect the invariants of the current phase.\n * *Example*: Do not generate `kCustomCall` instructions before the relevant expansion pass if they are not supported by the HLO verifier at that stage.\n * *Example*: Do not rely on layout information before Layout Assignment.\n\n9. **Namespaces**:\n * Prefer `xla::gpu` over nested namespaces.\n\n10. **MLIR Operation Creation**:\n * **Always** use the static `OpTy::create(rewriter, ...)` method when creating MLIR operations.\n * **Avoid** using `rewriter.create(...)`. This syntax is deprecated.\n\n11. **License Headers**:\n * Any new source or build files created in this codebase must include the\n OpenXLA Apache 2.0 copyright header at the top of the file.\n * Replace `` in the template below with the current 4-digit calendar\n year (e.g., `2026`—do not leave `` literally or copy an outdated\n year):\n ```cpp\n /* Copyright The OpenXLA Authors.\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n ==============================================================================*/\n ```\n (Use `#` comment prefixes for Python and `BUILD` files.)\n\n## Editing This File\n\nThis file is shared between the open-source repository and Google-internal\ndevelopment. Keep it in open-source terms only: repository-relative paths\n(`xla/...`), OSS macro names (`ABSL_RETURN_IF_ERROR`, `ABSL_ASSIGN_OR_RETURN`),\nBazel labels (`//xla/...`, `@repo//...`), and `bazel` commands.\n","docs/architecture.md":"# XLA architecture\n\nXLA (Accelerated Linear Algebra) is a machine learning (ML) compiler that\noptimizes linear algebra, providing improvements in execution speed and memory\nusage. This page provides a brief overview of the objectives and architecture of\nthe XLA compiler.\n\n## Objectives\n\nToday, XLA supports several ML framework frontends (including PyTorch,\nTensorFlow, and JAX) and is part of the OpenXLA project – an ecosystem of\nopen-source compiler technologies for ML that's developed collaboratively by\nleading ML hardware and software organizations. Before the OpenXLA project was\ncreated, XLA was developed inside the TensorFlow project, but the fundamental\nobjectives remain the same:\n\n* **Improve execution speed.** Compile subgraphs to reduce the execution time\n of short-lived ops and eliminate overhead from the runtime, fuse pipelined\n operations to reduce memory overhead, and specialize known tensor shapes to\n allow for more aggressive constant propagation.\n\n* **Improve memory usage.** Analyze and schedule memory usage, eliminating\n many intermediate storage buffers.\n\n* **Reduce reliance on custom ops.** Remove the need for many custom ops by\n improving the performance of automatically fused low-level ops to match the\n performance of custom ops that were originally fused by hand.\n\n* **Improve portability.** Make it relatively easy to write a new backend for\n novel hardware, so that a large fraction of ML models can run unmodified on\n that hardware. This is in contrast with the approach of specializing\n individual monolithic ops for new hardware, which requires models to be\n rewritten to make use of those ops.\n\n## How it works\n\nThe XLA compiler takes model graphs from ML frameworks defined in\n[StableHLO](https://github.com/openxla/stablehlo) and compiles them into machine\ninstructions for various architectures. StableHLO defines a versioned operation\nset (HLO = high level operations) that provides a portability layer between ML\nframeworks and the compiler.\n\nIn general, the compilation process that converts the model graph into a\ntarget-optimized executable includes these steps:\n\n1. XLA performs several built-in optimization and analysis passes on the\n StableHLO graph that are target-independent, such as\n [CSE](https://en.wikipedia.org/wiki/Common_subexpression_elimination),\n target-independent operation fusion, and buffer analysis for allocating\n runtime memory for the computation. During this optimization stage, XLA also\n converts the StableHLO dialect into an internal HLO dialect.\n\n2. XLA sends the HLO computation to a backend for further HLO-level\n optimizations, this time with target-specific information and needs in mind.\n For example, the GPU backend may perform operation fusions that are\n beneficial specifically for the GPU programming model and determine how to\n partition the computation into streams. At this stage, backends may also\n pattern-match certain operations or combinations thereof to optimized\n library calls.\n\n3. The backend then performs target-specific code generation. The CPU and GPU\n backends included with XLA use [LLVM](http://llvm.org) for low-level IR,\n optimization, and code generation. These backends emit the LLVM IR necessary\n to represent the HLO computation in an efficient manner, and then invoke\n LLVM to emit native code from this LLVM IR.\n\nWithin this process, the XLA compiler is modular in the sense that it is easy to\nslot in an alternative backend to\n[target some novel HW architecture](./developing_new_backend.md). The GPU\nbackend currently supports NVIDIA GPUs via the LLVM NVPTX backend. The CPU\nbackend supports multiple CPU ISAs.\n","tools/toolchains/embedded/README.md":"# Embedded toolchains\n\nThis repository contains toolchains for various embedded systems such as\nRaspberry Pi and Coral development boards.\n","tools/toolchains/cpus/aarch64/README.md":"# AARCH64 toolchain\n\nToolchain for performing TensorFlow AARCH64 builds such as used in Github\nActions ARM_CI and ARM_CD.\n\nMaintainer: @elfringham (Linaro LDCG)\n\n********************************************************************************\n\nThis repository contains a toolchain for use with the specially constructed\nDocker containers that match those created by SIG Build for x86 architecture\nbuilds, but modified for AARCH64 builds.\n\nThese Docker containers have been constructed to perform builds of TensorFlow\nthat are compatible with manylinux2014 requirements but in an environment that\nhas the C++11 Dual ABI enabled.\n\nThe Docker containers are available from\n[Docker Hub](https://hub.docker.com/r/linaro/tensorflow-arm64-build/tags) The\nsource Dockerfiles are available from\n[Linaro git](https://git.linaro.org/ci/dockerfiles.git/tree/tensorflow-arm64-build)\n","tools/toolchains/embedded/arm-linux/README.md":"# ARM GCC toolchains\n\nThis repository contains Bazel C++ toolchain configurations for ARM GCC. The\nfollowing toolchains are configured:\n\nsource:\nhttps://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads -\ngcc 8.3 - glibc 2.28\n\ntarget cpu: aarch64, armhf\n","xla/tools/multihost_hlo_runner/README.md":"See https://openxla.org/xla/tools_multihost_hlo_runner for public documentation.\nExtra information in the xla/tools/multihost_hlo_runner/hlo_runner_main.cc file.\n","xla/mlir/tools/mlir_bisect/README.md":"# MLIR HLO mlir_bisect\n\nThis is a test case reduction tool, similar in purpose to `mlir-reduce`, but\nspecific to the `mlir-interpreter` infrastructure. In particular, reductions can\ndepend on concrete values encountered during execution, and reductions can (and\nusually do) generate multiple candidates.\n\nFor example, the `ReplaceOpWithConstant` reduction will attempt to replace each\nop with each of its results. If the op is in a loop, each execution will be a\ncandidate for replacement.\n\n## Using this tool\n\n1. Run a JAX test with snapshots enabled:\n\n ```sh\n bazel test some-jax-test\n --test_env=XLA_FLAGS=\"--xla_cpu_use_xla_runtime --xla_dump_to=/tmp/dump\n --xla_dump_hlo_snapshots\" --test_filter=SomeSpecific.Test\n --test_sharding_strategy=disabled --test_strategy=local\n ```\n\n1. Figure out the culprit module and pass (sorry, no automation yet):\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_replay:mlir_replay -- \\\n --mlir-compilation-trace=/tmp/dump/module_0000.jit__something.mlir-trace.pb \\\n --hlo-snapshot=/tmp/dump/module_0000.jit__something.snapshot.0.pb \\\n --print-changes-only \\\n --execution-trace-dir=/tmp/execution\n ```\n\n You should see a pass after which results change. You'll want to use the\n .mlir file in `/tmp/execution` corresponding to the pass *before* that with\n the bisect tool.\n\n Note: If the failing pass is bufferization, you may have to use an earlier\n snapshot, e.g. before `EmptyTensorToAllocTensor`.\n1. Run bisect:\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_bisect:mlir-bisect -- \\\n --hlo-snapshot=/tmp/dump/module_0000.jit_something.snapshot.0.pb \\\n --pass-pipeline=\"builtin.module(empty-tensor-to-alloc-tensor,one-shot-bufferize{allow-return-allocs bufferize-function-boundaries create-deallocs=0})\" \\\n /tmp/execution/0052.ScalarizationPass.mlir\n ```\n\n## Adding a reduction\n\nTo add a reduction, create a function that generates the candidates and register\nit:\n\n```cpp\nSmallVector>\nFrobulateAndDefenestrate(BisectState&, dialect::SomeOp some_op) {\n auto [cloned_module_1, cloned_op_1] = CloneModuleFor(some_op);\n Frobulate(cloned_op_1);\n\n auto [cloned_module_2, cloned_op_2] = CloneModuleFor(some_op);\n Defenestrate(cloned_op_2);\n\n return {cloned_module_1, cloned_module_2};\n}\n\nREGISTER_MLIR_REDUCE_STRATEGY(FrobulateAndDefenestrate);\n```\n\nThen, add a test for the strategy. Make sure your strategy is linked into\nmlir-bisect and has `alwayslink` set.\n\n```mlir\n// RUN: mlir-bisect %s --debug-strategy=FrobulateAndDefenestrate | FileCheck %s\n\nfunc.func @main() {\n dialect.some_op()\n}\n\n// CHECK: func @main()\n// CHECK-NEXT: frobulated\n\n// CHECK: func @main()\n// CHECK-NEXT: defenestrated\n```\n\n`--debug-strategy` will print all candidates generated by the given strategy.\n","xla/mlir/tools/mlir_interpreter/README.md":"# MLIR interpreter\n\nMLIR interpreter is a development tool, mainly intended for debugging. As the\nname implies, it executes MLIR programs. What makes it special is that it\nimplements dialects at all levels of abstraction and all standard data types\n(tensor, memref, vector, scalar). One use case is to track down compiler bugs\nby executing the IR after each one and looking for changed results.\n\nFeatures:\n- Tensors, memrefs, vectors, scalars\n- Many dialects supported: from mhlo via linalg and scf all the way to arith.\n- Easy to extend (look at dialects/affine.cc for an example).\n\n## Creating a new dialect\n\nTo create a new dialect, follow the following steps:\n\n1. Create a `.cc` implementation file in `dialects/`. The name of the file\n should match your dialect name.\n1. Add a dependency to your dialect to the `dialects:dialects` target.\n1. Each op is implemented in a function.\n - Op results:\n - If your op has no result, the function should be `void`.\n - If your op has a tensor, memref or vector result, the return type\n should be `InterpreterValue`.\n - Scalars can be returned as their corresponding C++ type (e.g.\n `int64_t`, `float`)\n - You can also return a `SmallVector` if your op has multiple results.\n - Op arguments:\n - Your function should take an `InterpreterState&`, an instance of\n your op and any arguments your op takes.\n - Like above, arguments can either be taken as `InterpreterValue`s, as\n scalar C++ types or as `SmallVector` thereof (for variadic\n arguments).\n - Error handling:\n - If some of the inputs are invalid, use\n `InterpreterState::AddFailure` to report this.\n1. Register the ops: `REGISTER_MLIR_INTERPRETER_OP(YourOp)`.\n1. Add test cases in `dialects/tests`.\n","xla/mlir/tools/mlir_replay/README.md":"# mlir_replay Documentation\n\nPath: `xla/mlir/tools/mlir_replay/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/mlir/tools/mlir_replay/README.md)","xla/pjrt/extensions/example/README.md":"# example Documentation\n\nPath: `xla/pjrt/extensions/example/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/pjrt/extensions/example/README.md)","xla/tools/benchmarks/hlo_workload_executor/README.md":"# hlo_workload_executor Documentation\n\nPath: `xla/tools/benchmarks/hlo_workload_executor/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/tools/benchmarks/hlo_workload_executor/README.md)"},"files":{"build_tools/ci/readme.md":"This folder contains scripts and commands executed by GitHub actions in OpenXLA,\nTensorFlow and JAX OSS repos. The GitHub actions replaced\nKokoroPresubmit-tensorflow* workflows. They run under\n`Copybara_XLA{Presubmit,Submit}` presubmit chip (category) at Google internally.\nThe tests run on several target OS configurations/GCP containers such as Linux\nx86 with GPU or Linux ARM64. They assure that XLA/Tensor Flow/JAX compiles and\nruns on those platforms. The tests uses released OSS c++ clang compiler which\nhas some differences in supporting c++ standards compared Google's internal\nversion.\n\n#### How it works\n\nRepo specific GitHub actions call `build.py --build=\"build_name\"`. E.g. OpenXLA\nuses https://github.com/openxla/xla/blob/main/.github/workflows/ci.yml\n\nThe build here is a set of shell script commands executing the test targets or\ndoing compile only testing. Each GitHub action call translates into compile only\ntest:\n\n1. actual compile `bazel build ... test_targets`\n1. analyse results `bazel analyze-profile ...`\n\nor compile and run test commands:\n\n1. actual test `bazel test ... test_targets`\n1. analyse results `bazel analyze-profile profile.json.gz`\n\nChecking in changes to `build.py` regenerates `golden_commands.txt` which lets\nus see how commands are changing. `golden_commands.txt` are not called as part\nof the continuous integration process.\n\n#### When does it run?\n\nThe GitHub actions are automatically called as part of Google presubmit. The\nGitHub actions are automatically called on GitHub PR commit if the committer is\npart of OpenXLA GitHub org. Committer which are not part of OpenXLA org need an\napproval from OpenXLA org member to run the actions.\n","tools/toolchains/clang6/README.md":"# TensorFlow Bazel Clang\n\nThis is a specialized toolchain that uses an old Debian with a new Clang that\ncan cross compile to any x86_64 microarchitecture. It's intended to build Linux\nbinaries that only require the following ABIs:\n\n- GLIBC_2.18\n- CXXABI_1.3.7 (GCC 4.8.3)\n- GCC_4.2.0\n\nWhich are available on at least the following Linux platforms:\n\n- Ubuntu 14+\n- CentOS 7+\n- Debian 8+\n- SuSE 13.2+\n- Mint 17.3+\n- Manjaro 0.8.11\n\n# System Install\n\nOn Debian 8 (Jessie) Clang 6.0 can be installed as follows:\n\n```sh\ncat >>/etc/apt/sources.list <<'EOF'\ndeb http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\ndeb-src http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\nEOF\nwget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -\napt-key fingerprint |& grep '6084 F3CF 814B 57C1 CF12 EFD5 15CF 4D18 AF4F 7421'\napt-get update\napt-get install clang lld\n```\n\n# Bazel Configuration\n\nThis toolchain can compile TensorFlow in 2m30s on a 96-core Skylake GCE VM if\nthe following `.bazelrc` settings are added:\n\n```\nstartup --host_jvm_args=-Xmx30G\nstartup --host_jvm_args=-Xms30G\nstartup --host_jvm_args=-XX:MaxNewSize=3g\nstartup --host_jvm_args=-XX:-UseAdaptiveSizePolicy\nstartup --host_jvm_args=-XX:+UseConcMarkSweepGC\nstartup --host_jvm_args=-XX:TargetSurvivorRatio=70\nstartup --host_jvm_args=-XX:SurvivorRatio=6\nstartup --host_jvm_args=-XX:+UseCMSInitiatingOccupancyOnly\nstartup --host_jvm_args=-XX:CMSFullGCsBeforeCompaction=1\nstartup --host_jvm_args=-XX:CMSInitiatingOccupancyFraction=75\n\nbuild --jobs=100\nbuild --local_resources=200000,100,100\nbuild --crosstool_top=@local_config_clang6//clang6\nbuild --noexperimental_check_output_files\nbuild --nostamp\nbuild --config=opt\nbuild --noexperimental_check_output_files\nbuild --copt=-march=native\nbuild --host_copt=-march=native\n```\n\n# x86_64 Microarchitectures\n\n## Intel CPU Line\n\n- 2003 P6 M SSE SSE2\n- 2004 prescott SSE3 SSSE3 (-march=prescott)\n- 2006 core X64 SSE4.1 (only on 45nm variety) (-march=core2)\n- 2008 nehalem SSE4.2 VT-x VT-d (-march=nehalem)\n- 2010 westmere CLMUL AES (-march=westmere)\n- 2012 sandybridge AVX TXT (-march=sandybridge)\n- 2012 ivybridge F16C MOVBE (-march=ivybridge)\n- 2013 haswell AVX2 TSX BMI2 FMA (-march=haswell)\n- 2014 broadwell RDSEED ADCX PREFETCHW (-march=broadwell - works on trusty\n gcc4.9)\n- 2015 skylake SGX ADX MPX\n AVX-512[xeon-only](-march=skylake / -march=skylake-avx512 - needs gcc7)\n- 2018 cannonlake AVX-512 SHA (-march=cannonlake - needs clang5)\n\n## Intel Low Power CPU Line\n\n- 2013 silvermont SSE4.1 SSE4.2 VT-x (-march=silvermont)\n- 2016 goldmont SHA (-march=goldmont - needs clang5)\n\n## AMD CPU Line\n\n- 2003 k8 SSE SSE2 (-march=k8)\n- 2005 k8 (Venus) SSE3 (-march=k8-sse3)\n- 2008 barcelona SSE4a?! (-march=barcelona)\n- 2011 bulldozer SSE4.1 SSE4.2 CLMUL AVX AES FMA4?! (-march=bdver1)\n- 2011 piledriver FMA (-march=bdver2)\n- 2015 excavator AVX2 BMI2 MOVBE (-march=bdver4)\n\n## Google Compute Engine Supported CPUs\n\n- 2012 sandybridge 2.6gHz -march=sandybridge\n- 2012 ivybridge 2.5gHz -march=ivybridge\n- 2013 haswell 2.3gHz -march=haswell\n- 2014 broadwell 2.2gHz -march=broadwell\n- 2015 skylake 2.0gHz -march=skylake-avx512\n\nSee: \n","AGENTS.md":"# AI Assistant Guidelines for OpenXLA\n\nWelcome to the OpenXLA (`openxla/xla`) repository.\n\n* **Core XLA compiler guidelines**: When generating, reviewing, or modifying\n code under [`xla/`](xla/), follow the detailed C++, MLIR, testing, and\n Bazel guidelines in [`xla/AGENTS.md`](xla/AGENTS.md).\n* [`build_tools/`](build_tools/) contains CI and developer tooling,\n [`docs/`](docs/) the user-facing documentation, and\n [`third_party/`](third_party/) vendored dependencies and Bazel repository\n rules.\n","xla/GEMINI.md":"\nSee [AGENTS.md](AGENTS.md) for AI coding guidelines and best practices in this\ncodebase.\n","xla/AGENTS.md":"# AI Assistant Guidelines for OpenXLA Development\n\nThis document provides guidelines for AI code assistants when generating,\nsuggesting, or modifying code within the OpenXLA codebase (everything under\n`xla/` in this repository).\n\n## General Context\n\n* **Impact:** OpenXLA is a core compiler for machine learning acceleration. Changes here affect the open-source community and various hardware backends.\n* **Code Quality:** Adhere to [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) and OpenXLA-specific conventions.\n* **Portability:** This code is open-sourced and runs on a number of host platforms (e.g. Linux, Windows, etc.)\n\n## Repository Layout and Build\n\n* Source lives under `xla/`. Include paths are relative to the repository\n root, e.g. `#include \"xla/hlo/ir/hlo_module.h\"`.\n* Bazel labels use the same prefix, e.g. `//xla/hlo/ir:hlo_module`.\n* Build and test with Bazel, e.g. `bazel test //xla/service:hlo_verifier_test`.\n* Common external dependencies and their labels:\n `@com_google_absl//absl/...`, `@llvm-project//mlir/...`,\n `@llvm-project//llvm/...`, `@com_google_googletest//:gtest_main`,\n `@com_google_protobuf//:protobuf`. TSL (the platform layer) lives in-tree\n under `//xla/tsl/...`.\n* Test macros: `xla_cc_test` from `//xla:xla.default.bzl` (hardware-\n independent unit tests) and `xla_test` from `//xla/tests:build_defs.bzl`\n (tests that run on configured hardware backends).\n\n## Coding Guidelines for AI Assistance\n\n1. **Error Handling (`absl::Status`, `absl::StatusOr`)**:\n * **Always** use `absl::Status` or `absl::StatusOr` for functions that can encounter recoverable errors.\n * **Macros**:\n * Use header `absl/status/status_macros.h`.\n * Use `ABSL_RETURN_IF_ERROR` for error propagation.\n * Use `ABSL_ASSIGN_OR_RETURN` for `StatusOr` assignments.\n * **Safely access `StatusOr` values**: Check `.ok()` before accessing.\n\n2. **Assertions & Invariant Checks (`TF_RET_CHECK`)**:\n * **Avoid `DCHECK` / `LOG(DFATAL)`** for checking returnable errors.\n * **Prefer `TF_RET_CHECK`**:\n * Located in `xla/status_macros.h`.\n * Use strict internal invariant checks inside functions returning `absl::Status` / `StatusOr`.\n * Example:\n ```cpp\n #include \"xla/status_macros.h\"\n\n absl::Status Process(const Thing* t) {\n TF_RET_CHECK(t != nullptr) << \"Thing cannot be null\";\n // ...\n return absl::OkStatus();\n }\n ```\n\n3. **Decision making**:\n * **Avoid `bool`** for returning a decision to do or not to do something.\n * **Prefer `Decision`**:\n * Located in `xla/service/decision.h`\n * Example:\n ```cpp\n #include \"xla/service/decision.h\"\n\n using AutotunerDecision = Decision;\n\n AutotunerDecision ShouldAutotuneCublasCall(HloInstruction* instr) {\n // ...\n return AutotunerDecision::Forbid(\"Cublas autotuning was explicitly disabled\");\n }\n\n void AutotuneCublas(const AutotunerDecision& decision) {\n if (decision.IsForbidden()) {\n return;\n }\n ...\n ```\n\n4. **Performance Sensitivity**:\n * OpenXLA is a compiler; patterns should be efficient.\n * Avoid unnecessary string copies or expensive allocations in hot paths (e.g., HLO passes).\n\n5. **Testing**:\n * Write unit tests using `EXPECT_EQ`, `EXPECT_TRUE`, etc.\n * Use the status testing macros `ASSERT_OK_AND_ASSIGN`, `ASSERT_OK`, and\n `EXPECT_OK` from `` and the status matchers\n (`absl_testing::IsOk`, `absl_testing::IsOkAndHolds`,\n `absl_testing::StatusIs`) from `absl/status/status_matchers.h` instead\n of their legacy `TF_*` or `tsl::testing::*` counterparts:\n * DO NOT USE `TF_ASSERT_OK_AND_ASSIGN`, `TF_ASSERT_OK`, and\n `TF_EXPECT_OK`.\n * When you refactor code that uses the `TF_*` macros, replace them,\n but do not touch unrelated code.\n * Put tests into an anonymous namespace.\n * Use `HloInterpreterReferenceMixin` or\n `HloHardwareIndependentTestBase` for compiler pass tests locally where\n possible (do not use `HloTestBaseLegacy`).\n * When running GPU tests, pass `--config=cuda` to the test command.\n * Ensure tests are deterministic and do not flake.\n\n6. **BUILD targets**:\n * When defining BUILD targets prefer these XLA specific rules:\n * Instead of `proto_library` use `tf_proto_library`. There is no need\n to define language specific targets with `tf_proto_library`.\n * Instead of `cc_test` use `xla_cc_test` (or `xla_test` when the test\n requires a real hardware backend).\n\n7. **Explicit Typing**:\n * **Avoid `auto`** in public headers or complex logic chains.\n\n8. **Compiler Phases & Invariants**:\n * **Phase Ordering**: Understand where your pass or change sits in the pipeline (e.g., Optimizations, Layout Assignment, Fusion).\n * **Invariants**: Respect the invariants of the current phase.\n * *Example*: Do not generate `kCustomCall` instructions before the relevant expansion pass if they are not supported by the HLO verifier at that stage.\n * *Example*: Do not rely on layout information before Layout Assignment.\n\n9. **Namespaces**:\n * Prefer `xla::gpu` over nested namespaces.\n\n10. **MLIR Operation Creation**:\n * **Always** use the static `OpTy::create(rewriter, ...)` method when creating MLIR operations.\n * **Avoid** using `rewriter.create(...)`. This syntax is deprecated.\n\n11. **License Headers**:\n * Any new source or build files created in this codebase must include the\n OpenXLA Apache 2.0 copyright header at the top of the file.\n * Replace `` in the template below with the current 4-digit calendar\n year (e.g., `2026`—do not leave `` literally or copy an outdated\n year):\n ```cpp\n /* Copyright The OpenXLA Authors.\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n ==============================================================================*/\n ```\n (Use `#` comment prefixes for Python and `BUILD` files.)\n\n## Editing This File\n\nThis file is shared between the open-source repository and Google-internal\ndevelopment. Keep it in open-source terms only: repository-relative paths\n(`xla/...`), OSS macro names (`ABSL_RETURN_IF_ERROR`, `ABSL_ASSIGN_OR_RETURN`),\nBazel labels (`//xla/...`, `@repo//...`), and `bazel` commands.\n","docs/architecture.md":"# XLA architecture\n\nXLA (Accelerated Linear Algebra) is a machine learning (ML) compiler that\noptimizes linear algebra, providing improvements in execution speed and memory\nusage. This page provides a brief overview of the objectives and architecture of\nthe XLA compiler.\n\n## Objectives\n\nToday, XLA supports several ML framework frontends (including PyTorch,\nTensorFlow, and JAX) and is part of the OpenXLA project – an ecosystem of\nopen-source compiler technologies for ML that's developed collaboratively by\nleading ML hardware and software organizations. Before the OpenXLA project was\ncreated, XLA was developed inside the TensorFlow project, but the fundamental\nobjectives remain the same:\n\n* **Improve execution speed.** Compile subgraphs to reduce the execution time\n of short-lived ops and eliminate overhead from the runtime, fuse pipelined\n operations to reduce memory overhead, and specialize known tensor shapes to\n allow for more aggressive constant propagation.\n\n* **Improve memory usage.** Analyze and schedule memory usage, eliminating\n many intermediate storage buffers.\n\n* **Reduce reliance on custom ops.** Remove the need for many custom ops by\n improving the performance of automatically fused low-level ops to match the\n performance of custom ops that were originally fused by hand.\n\n* **Improve portability.** Make it relatively easy to write a new backend for\n novel hardware, so that a large fraction of ML models can run unmodified on\n that hardware. This is in contrast with the approach of specializing\n individual monolithic ops for new hardware, which requires models to be\n rewritten to make use of those ops.\n\n## How it works\n\nThe XLA compiler takes model graphs from ML frameworks defined in\n[StableHLO](https://github.com/openxla/stablehlo) and compiles them into machine\ninstructions for various architectures. StableHLO defines a versioned operation\nset (HLO = high level operations) that provides a portability layer between ML\nframeworks and the compiler.\n\nIn general, the compilation process that converts the model graph into a\ntarget-optimized executable includes these steps:\n\n1. XLA performs several built-in optimization and analysis passes on the\n StableHLO graph that are target-independent, such as\n [CSE](https://en.wikipedia.org/wiki/Common_subexpression_elimination),\n target-independent operation fusion, and buffer analysis for allocating\n runtime memory for the computation. During this optimization stage, XLA also\n converts the StableHLO dialect into an internal HLO dialect.\n\n2. XLA sends the HLO computation to a backend for further HLO-level\n optimizations, this time with target-specific information and needs in mind.\n For example, the GPU backend may perform operation fusions that are\n beneficial specifically for the GPU programming model and determine how to\n partition the computation into streams. At this stage, backends may also\n pattern-match certain operations or combinations thereof to optimized\n library calls.\n\n3. The backend then performs target-specific code generation. The CPU and GPU\n backends included with XLA use [LLVM](http://llvm.org) for low-level IR,\n optimization, and code generation. These backends emit the LLVM IR necessary\n to represent the HLO computation in an efficient manner, and then invoke\n LLVM to emit native code from this LLVM IR.\n\nWithin this process, the XLA compiler is modular in the sense that it is easy to\nslot in an alternative backend to\n[target some novel HW architecture](./developing_new_backend.md). The GPU\nbackend currently supports NVIDIA GPUs via the LLVM NVPTX backend. The CPU\nbackend supports multiple CPU ISAs.\n","tools/toolchains/embedded/README.md":"# Embedded toolchains\n\nThis repository contains toolchains for various embedded systems such as\nRaspberry Pi and Coral development boards.\n","tools/toolchains/cpus/aarch64/README.md":"# AARCH64 toolchain\n\nToolchain for performing TensorFlow AARCH64 builds such as used in Github\nActions ARM_CI and ARM_CD.\n\nMaintainer: @elfringham (Linaro LDCG)\n\n********************************************************************************\n\nThis repository contains a toolchain for use with the specially constructed\nDocker containers that match those created by SIG Build for x86 architecture\nbuilds, but modified for AARCH64 builds.\n\nThese Docker containers have been constructed to perform builds of TensorFlow\nthat are compatible with manylinux2014 requirements but in an environment that\nhas the C++11 Dual ABI enabled.\n\nThe Docker containers are available from\n[Docker Hub](https://hub.docker.com/r/linaro/tensorflow-arm64-build/tags) The\nsource Dockerfiles are available from\n[Linaro git](https://git.linaro.org/ci/dockerfiles.git/tree/tensorflow-arm64-build)\n","tools/toolchains/embedded/arm-linux/README.md":"# ARM GCC toolchains\n\nThis repository contains Bazel C++ toolchain configurations for ARM GCC. The\nfollowing toolchains are configured:\n\nsource:\nhttps://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads -\ngcc 8.3 - glibc 2.28\n\ntarget cpu: aarch64, armhf\n","xla/tools/multihost_hlo_runner/README.md":"See https://openxla.org/xla/tools_multihost_hlo_runner for public documentation.\nExtra information in the xla/tools/multihost_hlo_runner/hlo_runner_main.cc file.\n","xla/mlir/tools/mlir_bisect/README.md":"# MLIR HLO mlir_bisect\n\nThis is a test case reduction tool, similar in purpose to `mlir-reduce`, but\nspecific to the `mlir-interpreter` infrastructure. In particular, reductions can\ndepend on concrete values encountered during execution, and reductions can (and\nusually do) generate multiple candidates.\n\nFor example, the `ReplaceOpWithConstant` reduction will attempt to replace each\nop with each of its results. If the op is in a loop, each execution will be a\ncandidate for replacement.\n\n## Using this tool\n\n1. Run a JAX test with snapshots enabled:\n\n ```sh\n bazel test some-jax-test\n --test_env=XLA_FLAGS=\"--xla_cpu_use_xla_runtime --xla_dump_to=/tmp/dump\n --xla_dump_hlo_snapshots\" --test_filter=SomeSpecific.Test\n --test_sharding_strategy=disabled --test_strategy=local\n ```\n\n1. Figure out the culprit module and pass (sorry, no automation yet):\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_replay:mlir_replay -- \\\n --mlir-compilation-trace=/tmp/dump/module_0000.jit__something.mlir-trace.pb \\\n --hlo-snapshot=/tmp/dump/module_0000.jit__something.snapshot.0.pb \\\n --print-changes-only \\\n --execution-trace-dir=/tmp/execution\n ```\n\n You should see a pass after which results change. You'll want to use the\n .mlir file in `/tmp/execution` corresponding to the pass *before* that with\n the bisect tool.\n\n Note: If the failing pass is bufferization, you may have to use an earlier\n snapshot, e.g. before `EmptyTensorToAllocTensor`.\n1. Run bisect:\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_bisect:mlir-bisect -- \\\n --hlo-snapshot=/tmp/dump/module_0000.jit_something.snapshot.0.pb \\\n --pass-pipeline=\"builtin.module(empty-tensor-to-alloc-tensor,one-shot-bufferize{allow-return-allocs bufferize-function-boundaries create-deallocs=0})\" \\\n /tmp/execution/0052.ScalarizationPass.mlir\n ```\n\n## Adding a reduction\n\nTo add a reduction, create a function that generates the candidates and register\nit:\n\n```cpp\nSmallVector>\nFrobulateAndDefenestrate(BisectState&, dialect::SomeOp some_op) {\n auto [cloned_module_1, cloned_op_1] = CloneModuleFor(some_op);\n Frobulate(cloned_op_1);\n\n auto [cloned_module_2, cloned_op_2] = CloneModuleFor(some_op);\n Defenestrate(cloned_op_2);\n\n return {cloned_module_1, cloned_module_2};\n}\n\nREGISTER_MLIR_REDUCE_STRATEGY(FrobulateAndDefenestrate);\n```\n\nThen, add a test for the strategy. Make sure your strategy is linked into\nmlir-bisect and has `alwayslink` set.\n\n```mlir\n// RUN: mlir-bisect %s --debug-strategy=FrobulateAndDefenestrate | FileCheck %s\n\nfunc.func @main() {\n dialect.some_op()\n}\n\n// CHECK: func @main()\n// CHECK-NEXT: frobulated\n\n// CHECK: func @main()\n// CHECK-NEXT: defenestrated\n```\n\n`--debug-strategy` will print all candidates generated by the given strategy.\n","xla/mlir/tools/mlir_interpreter/README.md":"# MLIR interpreter\n\nMLIR interpreter is a development tool, mainly intended for debugging. As the\nname implies, it executes MLIR programs. What makes it special is that it\nimplements dialects at all levels of abstraction and all standard data types\n(tensor, memref, vector, scalar). One use case is to track down compiler bugs\nby executing the IR after each one and looking for changed results.\n\nFeatures:\n- Tensors, memrefs, vectors, scalars\n- Many dialects supported: from mhlo via linalg and scf all the way to arith.\n- Easy to extend (look at dialects/affine.cc for an example).\n\n## Creating a new dialect\n\nTo create a new dialect, follow the following steps:\n\n1. Create a `.cc` implementation file in `dialects/`. The name of the file\n should match your dialect name.\n1. Add a dependency to your dialect to the `dialects:dialects` target.\n1. Each op is implemented in a function.\n - Op results:\n - If your op has no result, the function should be `void`.\n - If your op has a tensor, memref or vector result, the return type\n should be `InterpreterValue`.\n - Scalars can be returned as their corresponding C++ type (e.g.\n `int64_t`, `float`)\n - You can also return a `SmallVector` if your op has multiple results.\n - Op arguments:\n - Your function should take an `InterpreterState&`, an instance of\n your op and any arguments your op takes.\n - Like above, arguments can either be taken as `InterpreterValue`s, as\n scalar C++ types or as `SmallVector` thereof (for variadic\n arguments).\n - Error handling:\n - If some of the inputs are invalid, use\n `InterpreterState::AddFailure` to report this.\n1. Register the ops: `REGISTER_MLIR_INTERPRETER_OP(YourOp)`.\n1. Add test cases in `dialects/tests`.\n","xla/mlir/tools/mlir_replay/README.md":"# mlir_replay Documentation\n\nPath: `xla/mlir/tools/mlir_replay/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/mlir/tools/mlir_replay/README.md)","xla/pjrt/extensions/example/README.md":"# example Documentation\n\nPath: `xla/pjrt/extensions/example/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/pjrt/extensions/example/README.md)","xla/tools/benchmarks/hlo_workload_executor/README.md":"# hlo_workload_executor Documentation\n\nPath: `xla/tools/benchmarks/hlo_workload_executor/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/tools/benchmarks/hlo_workload_executor/README.md)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AI Assistant Guidelines for OpenXLA\n\nWelcome to the OpenXLA (`openxla/xla`) repository.\n\n* **Core XLA compiler guidelines**: When generating, reviewing, or modifying\n code under [`xla/`](xla/), follow the detailed C++, MLIR, testing, and\n Bazel guidelines in [`xla/AGENTS.md`](xla/AGENTS.md).\n* [`build_tools/`](build_tools/) contains CI and developer tooling,\n [`docs/`](docs/) the user-facing documentation, and\n [`third_party/`](third_party/) vendored dependencies and Bazel repository\n rules.\n","isInternal":false,"tokens":136,"sizeBytes":518},{"name":"AGENTS.md","path":"xla/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/AGENTS.md","title":"xla - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AI Assistant Guidelines for OpenXLA Development\n\nThis document provides guidelines for AI code assistants when generating,\nsuggesting, or modifying code within the OpenXLA codebase (everything under\n`xla/` in this repository).\n\n## General Context\n\n* **Impact:** OpenXLA is a core compiler for machine learning acceleration. Changes here affect the open-source community and various hardware backends.\n* **Code Quality:** Adhere to [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) and OpenXLA-specific conventions.\n* **Portability:** This code is open-sourced and runs on a number of host platforms (e.g. Linux, Windows, etc.)\n\n## Repository Layout and Build\n\n* Source lives under `xla/`. Include paths are relative to the repository\n root, e.g. `#include \"xla/hlo/ir/hlo_module.h\"`.\n* Bazel labels use the same prefix, e.g. `//xla/hlo/ir:hlo_module`.\n* Build and test with Bazel, e.g. `bazel test //xla/service:hlo_verifier_test`.\n* Common external dependencies and their labels:\n `@com_google_absl//absl/...`, `@llvm-project//mlir/...`,\n `@llvm-project//llvm/...`, `@com_google_googletest//:gtest_main`,\n `@com_google_protobuf//:protobuf`. TSL (the platform layer) lives in-tree\n under `//xla/tsl/...`.\n* Test macros: `xla_cc_test` from `//xla:xla.default.bzl` (hardware-\n independent unit tests) and `xla_test` from `//xla/tests:build_defs.bzl`\n (tests that run on configured hardware backends).\n\n## Coding Guidelines for AI Assistance\n\n1. **Error Handling (`absl::Status`, `absl::StatusOr`)**:\n * **Always** use `absl::Status` or `absl::StatusOr` for functions that can encounter recoverable errors.\n * **Macros**:\n * Use header `absl/status/status_macros.h`.\n * Use `ABSL_RETURN_IF_ERROR` for error propagation.\n * Use `ABSL_ASSIGN_OR_RETURN` for `StatusOr` assignments.\n * **Safely access `StatusOr` values**: Check `.ok()` before accessing.\n\n2. **Assertions & Invariant Checks (`TF_RET_CHECK`)**:\n * **Avoid `DCHECK` / `LOG(DFATAL)`** for checking returnable errors.\n * **Prefer `TF_RET_CHECK`**:\n * Located in `xla/status_macros.h`.\n * Use strict internal invariant checks inside functions returning `absl::Status` / `StatusOr`.\n * Example:\n ```cpp\n #include \"xla/status_macros.h\"\n\n absl::Status Process(const Thing* t) {\n TF_RET_CHECK(t != nullptr) << \"Thing cannot be null\";\n // ...\n return absl::OkStatus();\n }\n ```\n\n3. **Decision making**:\n * **Avoid `bool`** for returning a decision to do or not to do something.\n * **Prefer `Decision`**:\n * Located in `xla/service/decision.h`\n * Example:\n ```cpp\n #include \"xla/service/decision.h\"\n\n using AutotunerDecision = Decision;\n\n AutotunerDecision ShouldAutotuneCublasCall(HloInstruction* instr) {\n // ...\n return AutotunerDecision::Forbid(\"Cublas autotuning was explicitly disabled\");\n }\n\n void AutotuneCublas(const AutotunerDecision& decision) {\n if (decision.IsForbidden()) {\n return;\n }\n ...\n ```\n\n4. **Performance Sensitivity**:\n * OpenXLA is a compiler; patterns should be efficient.\n * Avoid unnecessary string copies or expensive allocations in hot paths (e.g., HLO passes).\n\n5. **Testing**:\n * Write unit tests using `EXPECT_EQ`, `EXPECT_TRUE`, etc.\n * Use the status testing macros `ASSERT_OK_AND_ASSIGN`, `ASSERT_OK`, and\n `EXPECT_OK` from `` and the status matchers\n (`absl_testing::IsOk`, `absl_testing::IsOkAndHolds`,\n `absl_testing::StatusIs`) from `absl/status/status_matchers.h` instead\n of their legacy `TF_*` or `tsl::testing::*` counterparts:\n * DO NOT USE `TF_ASSERT_OK_AND_ASSIGN`, `TF_ASSERT_OK`, and\n `TF_EXPECT_OK`.\n * When you refactor code that uses the `TF_*` macros, replace them,\n but do not touch unrelated code.\n * Put tests into an anonymous namespace.\n * Use `HloInterpreterReferenceMixin` or\n `HloHardwareIndependentTestBase` for compiler pass tests locally where\n possible (do not use `HloTestBaseLegacy`).\n * When running GPU tests, pass `--config=cuda` to the test command.\n * Ensure tests are deterministic and do not flake.\n\n6. **BUILD targets**:\n * When defining BUILD targets prefer these XLA specific rules:\n * Instead of `proto_library` use `tf_proto_library`. There is no need\n to define language specific targets with `tf_proto_library`.\n * Instead of `cc_test` use `xla_cc_test` (or `xla_test` when the test\n requires a real hardware backend).\n\n7. **Explicit Typing**:\n * **Avoid `auto`** in public headers or complex logic chains.\n\n8. **Compiler Phases & Invariants**:\n * **Phase Ordering**: Understand where your pass or change sits in the pipeline (e.g., Optimizations, Layout Assignment, Fusion).\n * **Invariants**: Respect the invariants of the current phase.\n * *Example*: Do not generate `kCustomCall` instructions before the relevant expansion pass if they are not supported by the HLO verifier at that stage.\n * *Example*: Do not rely on layout information before Layout Assignment.\n\n9. **Namespaces**:\n * Prefer `xla::gpu` over nested namespaces.\n\n10. **MLIR Operation Creation**:\n * **Always** use the static `OpTy::create(rewriter, ...)` method when creating MLIR operations.\n * **Avoid** using `rewriter.create(...)`. This syntax is deprecated.\n\n11. **License Headers**:\n * Any new source or build files created in this codebase must include the\n OpenXLA Apache 2.0 copyright header at the top of the file.\n * Replace `` in the template below with the current 4-digit calendar\n year (e.g., `2026`—do not leave `` literally or copy an outdated\n year):\n ```cpp\n /* Copyright The OpenXLA Authors.\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n ==============================================================================*/\n ```\n (Use `#` comment prefixes for Python and `BUILD` files.)\n\n## Editing This File\n\nThis file is shared between the open-source repository and Google-internal\ndevelopment. Keep it in open-source terms only: repository-relative paths\n(`xla/...`), OSS macro names (`ABSL_RETURN_IF_ERROR`, `ABSL_ASSIGN_OR_RETURN`),\nBazel labels (`//xla/...`, `@repo//...`), and `bazel` commands.\n","isInternal":false,"tokens":1764,"sizeBytes":7257},{"name":"architecture.md","path":"docs/architecture.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/docs/architecture.md","title":"docs - System Architecture & Module Boundaries","category":"project-spec","format":"markdown","content":"# XLA architecture\n\nXLA (Accelerated Linear Algebra) is a machine learning (ML) compiler that\noptimizes linear algebra, providing improvements in execution speed and memory\nusage. This page provides a brief overview of the objectives and architecture of\nthe XLA compiler.\n\n## Objectives\n\nToday, XLA supports several ML framework frontends (including PyTorch,\nTensorFlow, and JAX) and is part of the OpenXLA project – an ecosystem of\nopen-source compiler technologies for ML that's developed collaboratively by\nleading ML hardware and software organizations. Before the OpenXLA project was\ncreated, XLA was developed inside the TensorFlow project, but the fundamental\nobjectives remain the same:\n\n* **Improve execution speed.** Compile subgraphs to reduce the execution time\n of short-lived ops and eliminate overhead from the runtime, fuse pipelined\n operations to reduce memory overhead, and specialize known tensor shapes to\n allow for more aggressive constant propagation.\n\n* **Improve memory usage.** Analyze and schedule memory usage, eliminating\n many intermediate storage buffers.\n\n* **Reduce reliance on custom ops.** Remove the need for many custom ops by\n improving the performance of automatically fused low-level ops to match the\n performance of custom ops that were originally fused by hand.\n\n* **Improve portability.** Make it relatively easy to write a new backend for\n novel hardware, so that a large fraction of ML models can run unmodified on\n that hardware. This is in contrast with the approach of specializing\n individual monolithic ops for new hardware, which requires models to be\n rewritten to make use of those ops.\n\n## How it works\n\nThe XLA compiler takes model graphs from ML frameworks defined in\n[StableHLO](https://github.com/openxla/stablehlo) and compiles them into machine\ninstructions for various architectures. StableHLO defines a versioned operation\nset (HLO = high level operations) that provides a portability layer between ML\nframeworks and the compiler.\n\nIn general, the compilation process that converts the model graph into a\ntarget-optimized executable includes these steps:\n\n1. XLA performs several built-in optimization and analysis passes on the\n StableHLO graph that are target-independent, such as\n [CSE](https://en.wikipedia.org/wiki/Common_subexpression_elimination),\n target-independent operation fusion, and buffer analysis for allocating\n runtime memory for the computation. During this optimization stage, XLA also\n converts the StableHLO dialect into an internal HLO dialect.\n\n2. XLA sends the HLO computation to a backend for further HLO-level\n optimizations, this time with target-specific information and needs in mind.\n For example, the GPU backend may perform operation fusions that are\n beneficial specifically for the GPU programming model and determine how to\n partition the computation into streams. At this stage, backends may also\n pattern-match certain operations or combinations thereof to optimized\n library calls.\n\n3. The backend then performs target-specific code generation. The CPU and GPU\n backends included with XLA use [LLVM](http://llvm.org) for low-level IR,\n optimization, and code generation. These backends emit the LLVM IR necessary\n to represent the HLO computation in an efficient manner, and then invoke\n LLVM to emit native code from this LLVM IR.\n\nWithin this process, the XLA compiler is modular in the sense that it is easy to\nslot in an alternative backend to\n[target some novel HW architecture](./developing_new_backend.md). The GPU\nbackend currently supports NVIDIA GPUs via the LLVM NVPTX backend. The CPU\nbackend supports multiple CPU ISAs.\n","isInternal":false,"tokens":781,"sizeBytes":3727},{"name":"GEMINI.md","path":"xla/GEMINI.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/GEMINI.md","title":"xla - Gemini Agent & Antigravity Instructions","category":"gemini-rule","format":"markdown","content":"\nSee [AGENTS.md](AGENTS.md) for AI coding guidelines and best practices in this\ncodebase.\n","isInternal":false,"tokens":55,"sizeBytes":236},{"name":"readme.md","path":"build_tools/ci/readme.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/build_tools/ci/readme.md","title":"ci Documentation","category":"plugin-manifest","format":"markdown","content":"This folder contains scripts and commands executed by GitHub actions in OpenXLA,\nTensorFlow and JAX OSS repos. The GitHub actions replaced\nKokoroPresubmit-tensorflow* workflows. They run under\n`Copybara_XLA{Presubmit,Submit}` presubmit chip (category) at Google internally.\nThe tests run on several target OS configurations/GCP containers such as Linux\nx86 with GPU or Linux ARM64. They assure that XLA/Tensor Flow/JAX compiles and\nruns on those platforms. The tests uses released OSS c++ clang compiler which\nhas some differences in supporting c++ standards compared Google's internal\nversion.\n\n#### How it works\n\nRepo specific GitHub actions call `build.py --build=\"build_name\"`. E.g. OpenXLA\nuses https://github.com/openxla/xla/blob/main/.github/workflows/ci.yml\n\nThe build here is a set of shell script commands executing the test targets or\ndoing compile only testing. Each GitHub action call translates into compile only\ntest:\n\n1. actual compile `bazel build ... test_targets`\n1. analyse results `bazel analyze-profile ...`\n\nor compile and run test commands:\n\n1. actual test `bazel test ... test_targets`\n1. analyse results `bazel analyze-profile profile.json.gz`\n\nChecking in changes to `build.py` regenerates `golden_commands.txt` which lets\nus see how commands are changing. `golden_commands.txt` are not called as part\nof the continuous integration process.\n\n#### When does it run?\n\nThe GitHub actions are automatically called as part of Google presubmit. The\nGitHub actions are automatically called on GitHub PR commit if the committer is\npart of OpenXLA GitHub org. Committer which are not part of OpenXLA org need an\napproval from OpenXLA org member to run the actions.\n","isInternal":false,"tokens":388,"sizeBytes":1687},{"name":"README.md","path":"tools/toolchains/clang6/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/tools/toolchains/clang6/README.md","title":"clang6 Documentation","category":"plugin-manifest","format":"markdown","content":"# TensorFlow Bazel Clang\n\nThis is a specialized toolchain that uses an old Debian with a new Clang that\ncan cross compile to any x86_64 microarchitecture. It's intended to build Linux\nbinaries that only require the following ABIs:\n\n- GLIBC_2.18\n- CXXABI_1.3.7 (GCC 4.8.3)\n- GCC_4.2.0\n\nWhich are available on at least the following Linux platforms:\n\n- Ubuntu 14+\n- CentOS 7+\n- Debian 8+\n- SuSE 13.2+\n- Mint 17.3+\n- Manjaro 0.8.11\n\n# System Install\n\nOn Debian 8 (Jessie) Clang 6.0 can be installed as follows:\n\n```sh\ncat >>/etc/apt/sources.list <<'EOF'\ndeb http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\ndeb-src http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\nEOF\nwget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -\napt-key fingerprint |& grep '6084 F3CF 814B 57C1 CF12 EFD5 15CF 4D18 AF4F 7421'\napt-get update\napt-get install clang lld\n```\n\n# Bazel Configuration\n\nThis toolchain can compile TensorFlow in 2m30s on a 96-core Skylake GCE VM if\nthe following `.bazelrc` settings are added:\n\n```\nstartup --host_jvm_args=-Xmx30G\nstartup --host_jvm_args=-Xms30G\nstartup --host_jvm_args=-XX:MaxNewSize=3g\nstartup --host_jvm_args=-XX:-UseAdaptiveSizePolicy\nstartup --host_jvm_args=-XX:+UseConcMarkSweepGC\nstartup --host_jvm_args=-XX:TargetSurvivorRatio=70\nstartup --host_jvm_args=-XX:SurvivorRatio=6\nstartup --host_jvm_args=-XX:+UseCMSInitiatingOccupancyOnly\nstartup --host_jvm_args=-XX:CMSFullGCsBeforeCompaction=1\nstartup --host_jvm_args=-XX:CMSInitiatingOccupancyFraction=75\n\nbuild --jobs=100\nbuild --local_resources=200000,100,100\nbuild --crosstool_top=@local_config_clang6//clang6\nbuild --noexperimental_check_output_files\nbuild --nostamp\nbuild --config=opt\nbuild --noexperimental_check_output_files\nbuild --copt=-march=native\nbuild --host_copt=-march=native\n```\n\n# x86_64 Microarchitectures\n\n## Intel CPU Line\n\n- 2003 P6 M SSE SSE2\n- 2004 prescott SSE3 SSSE3 (-march=prescott)\n- 2006 core X64 SSE4.1 (only on 45nm variety) (-march=core2)\n- 2008 nehalem SSE4.2 VT-x VT-d (-march=nehalem)\n- 2010 westmere CLMUL AES (-march=westmere)\n- 2012 sandybridge AVX TXT (-march=sandybridge)\n- 2012 ivybridge F16C MOVBE (-march=ivybridge)\n- 2013 haswell AVX2 TSX BMI2 FMA (-march=haswell)\n- 2014 broadwell RDSEED ADCX PREFETCHW (-march=broadwell - works on trusty\n gcc4.9)\n- 2015 skylake SGX ADX MPX\n AVX-512[xeon-only](-march=skylake / -march=skylake-avx512 - needs gcc7)\n- 2018 cannonlake AVX-512 SHA (-march=cannonlake - needs clang5)\n\n## Intel Low Power CPU Line\n\n- 2013 silvermont SSE4.1 SSE4.2 VT-x (-march=silvermont)\n- 2016 goldmont SHA (-march=goldmont - needs clang5)\n\n## AMD CPU Line\n\n- 2003 k8 SSE SSE2 (-march=k8)\n- 2005 k8 (Venus) SSE3 (-march=k8-sse3)\n- 2008 barcelona SSE4a?! (-march=barcelona)\n- 2011 bulldozer SSE4.1 SSE4.2 CLMUL AVX AES FMA4?! (-march=bdver1)\n- 2011 piledriver FMA (-march=bdver2)\n- 2015 excavator AVX2 BMI2 MOVBE (-march=bdver4)\n\n## Google Compute Engine Supported CPUs\n\n- 2012 sandybridge 2.6gHz -march=sandybridge\n- 2012 ivybridge 2.5gHz -march=ivybridge\n- 2013 haswell 2.3gHz -march=haswell\n- 2014 broadwell 2.2gHz -march=broadwell\n- 2015 skylake 2.0gHz -march=skylake-avx512\n\nSee: \n","isInternal":false,"tokens":1176,"sizeBytes":3265},{"name":"README.md","path":"tools/toolchains/cpus/aarch64/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/tools/toolchains/cpus/aarch64/README.md","title":"aarch64 Documentation","category":"plugin-manifest","format":"markdown","content":"# AARCH64 toolchain\n\nToolchain for performing TensorFlow AARCH64 builds such as used in Github\nActions ARM_CI and ARM_CD.\n\nMaintainer: @elfringham (Linaro LDCG)\n\n********************************************************************************\n\nThis repository contains a toolchain for use with the specially constructed\nDocker containers that match those created by SIG Build for x86 architecture\nbuilds, but modified for AARCH64 builds.\n\nThese Docker containers have been constructed to perform builds of TensorFlow\nthat are compatible with manylinux2014 requirements but in an environment that\nhas the C++11 Dual ABI enabled.\n\nThe Docker containers are available from\n[Docker Hub](https://hub.docker.com/r/linaro/tensorflow-arm64-build/tags) The\nsource Dockerfiles are available from\n[Linaro git](https://git.linaro.org/ci/dockerfiles.git/tree/tensorflow-arm64-build)\n","isInternal":false,"tokens":183,"sizeBytes":870},{"name":"README.md","path":"tools/toolchains/embedded/arm-linux/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/tools/toolchains/embedded/arm-linux/README.md","title":"arm-linux Documentation","category":"plugin-manifest","format":"markdown","content":"# ARM GCC toolchains\n\nThis repository contains Bazel C++ toolchain configurations for ARM GCC. The\nfollowing toolchains are configured:\n\nsource:\nhttps://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads -\ngcc 8.3 - glibc 2.28\n\ntarget cpu: aarch64, armhf\n","isInternal":false,"tokens":78,"sizeBytes":308},{"name":"README.md","path":"tools/toolchains/embedded/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/tools/toolchains/embedded/README.md","title":"embedded Documentation","category":"plugin-manifest","format":"markdown","content":"# Embedded toolchains\n\nThis repository contains toolchains for various embedded systems such as\nRaspberry Pi and Coral development boards.\n","isInternal":false,"tokens":25,"sizeBytes":139},{"name":"README.md","path":"xla/mlir/tools/mlir_bisect/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/mlir/tools/mlir_bisect/README.md","title":"mlir_bisect Documentation","category":"plugin-manifest","format":"markdown","content":"# MLIR HLO mlir_bisect\n\nThis is a test case reduction tool, similar in purpose to `mlir-reduce`, but\nspecific to the `mlir-interpreter` infrastructure. In particular, reductions can\ndepend on concrete values encountered during execution, and reductions can (and\nusually do) generate multiple candidates.\n\nFor example, the `ReplaceOpWithConstant` reduction will attempt to replace each\nop with each of its results. If the op is in a loop, each execution will be a\ncandidate for replacement.\n\n## Using this tool\n\n1. Run a JAX test with snapshots enabled:\n\n ```sh\n bazel test some-jax-test\n --test_env=XLA_FLAGS=\"--xla_cpu_use_xla_runtime --xla_dump_to=/tmp/dump\n --xla_dump_hlo_snapshots\" --test_filter=SomeSpecific.Test\n --test_sharding_strategy=disabled --test_strategy=local\n ```\n\n1. Figure out the culprit module and pass (sorry, no automation yet):\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_replay:mlir_replay -- \\\n --mlir-compilation-trace=/tmp/dump/module_0000.jit__something.mlir-trace.pb \\\n --hlo-snapshot=/tmp/dump/module_0000.jit__something.snapshot.0.pb \\\n --print-changes-only \\\n --execution-trace-dir=/tmp/execution\n ```\n\n You should see a pass after which results change. You'll want to use the\n .mlir file in `/tmp/execution` corresponding to the pass *before* that with\n the bisect tool.\n\n Note: If the failing pass is bufferization, you may have to use an earlier\n snapshot, e.g. before `EmptyTensorToAllocTensor`.\n1. Run bisect:\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_bisect:mlir-bisect -- \\\n --hlo-snapshot=/tmp/dump/module_0000.jit_something.snapshot.0.pb \\\n --pass-pipeline=\"builtin.module(empty-tensor-to-alloc-tensor,one-shot-bufferize{allow-return-allocs bufferize-function-boundaries create-deallocs=0})\" \\\n /tmp/execution/0052.ScalarizationPass.mlir\n ```\n\n## Adding a reduction\n\nTo add a reduction, create a function that generates the candidates and register\nit:\n\n```cpp\nSmallVector>\nFrobulateAndDefenestrate(BisectState&, dialect::SomeOp some_op) {\n auto [cloned_module_1, cloned_op_1] = CloneModuleFor(some_op);\n Frobulate(cloned_op_1);\n\n auto [cloned_module_2, cloned_op_2] = CloneModuleFor(some_op);\n Defenestrate(cloned_op_2);\n\n return {cloned_module_1, cloned_module_2};\n}\n\nREGISTER_MLIR_REDUCE_STRATEGY(FrobulateAndDefenestrate);\n```\n\nThen, add a test for the strategy. Make sure your strategy is linked into\nmlir-bisect and has `alwayslink` set.\n\n```mlir\n// RUN: mlir-bisect %s --debug-strategy=FrobulateAndDefenestrate | FileCheck %s\n\nfunc.func @main() {\n dialect.some_op()\n}\n\n// CHECK: func @main()\n// CHECK-NEXT: frobulated\n\n// CHECK: func @main()\n// CHECK-NEXT: defenestrated\n```\n\n`--debug-strategy` will print all candidates generated by the given strategy.\n","isInternal":false,"tokens":791,"sizeBytes":2857},{"name":"README.md","path":"xla/mlir/tools/mlir_interpreter/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/mlir/tools/mlir_interpreter/README.md","title":"mlir_interpreter Documentation","category":"plugin-manifest","format":"markdown","content":"# MLIR interpreter\n\nMLIR interpreter is a development tool, mainly intended for debugging. As the\nname implies, it executes MLIR programs. What makes it special is that it\nimplements dialects at all levels of abstraction and all standard data types\n(tensor, memref, vector, scalar). One use case is to track down compiler bugs\nby executing the IR after each one and looking for changed results.\n\nFeatures:\n- Tensors, memrefs, vectors, scalars\n- Many dialects supported: from mhlo via linalg and scf all the way to arith.\n- Easy to extend (look at dialects/affine.cc for an example).\n\n## Creating a new dialect\n\nTo create a new dialect, follow the following steps:\n\n1. Create a `.cc` implementation file in `dialects/`. The name of the file\n should match your dialect name.\n1. Add a dependency to your dialect to the `dialects:dialects` target.\n1. Each op is implemented in a function.\n - Op results:\n - If your op has no result, the function should be `void`.\n - If your op has a tensor, memref or vector result, the return type\n should be `InterpreterValue`.\n - Scalars can be returned as their corresponding C++ type (e.g.\n `int64_t`, `float`)\n - You can also return a `SmallVector` if your op has multiple results.\n - Op arguments:\n - Your function should take an `InterpreterState&`, an instance of\n your op and any arguments your op takes.\n - Like above, arguments can either be taken as `InterpreterValue`s, as\n scalar C++ types or as `SmallVector` thereof (for variadic\n arguments).\n - Error handling:\n - If some of the inputs are invalid, use\n `InterpreterState::AddFailure` to report this.\n1. Register the ops: `REGISTER_MLIR_INTERPRETER_OP(YourOp)`.\n1. Add test cases in `dialects/tests`.\n","isInternal":false,"tokens":449,"sizeBytes":1851},{"name":"README.md","path":"xla/mlir/tools/mlir_replay/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/mlir/tools/mlir_replay/README.md","title":"mlir_replay Documentation","category":"plugin-manifest","format":"markdown","content":"# mlir_replay Documentation\n\nPath: `xla/mlir/tools/mlir_replay/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/mlir/tools/mlir_replay/README.md)","tokens":300,"sizeBytes":192},{"name":"README.md","path":"xla/pjrt/extensions/example/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/pjrt/extensions/example/README.md","title":"example Documentation","category":"plugin-manifest","format":"markdown","content":"# example Documentation\n\nPath: `xla/pjrt/extensions/example/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/pjrt/extensions/example/README.md)","tokens":300,"sizeBytes":190},{"name":"README.md","path":"xla/tools/benchmarks/hlo_workload_executor/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/tools/benchmarks/hlo_workload_executor/README.md","title":"hlo_workload_executor Documentation","category":"plugin-manifest","format":"markdown","content":"# hlo_workload_executor Documentation\n\nPath: `xla/tools/benchmarks/hlo_workload_executor/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/tools/benchmarks/hlo_workload_executor/README.md)","tokens":300,"sizeBytes":234},{"name":"README.md","path":"xla/tools/multihost_hlo_runner/README.md","rawUrl":"https://raw.githubusercontent.com/openxla/xla/HEAD/xla/tools/multihost_hlo_runner/README.md","title":"multihost_hlo_runner Documentation","category":"plugin-manifest","format":"markdown","content":"See https://openxla.org/xla/tools_multihost_hlo_runner for public documentation.\nExtra information in the xla/tools/multihost_hlo_runner/hlo_runner_main.cc file.\n","isInternal":false,"tokens":39,"sizeBytes":162}],"systemPromptSnippet":"\n\n# AI Assistant Guidelines for OpenXLA\n\nWelcome to the OpenXLA (`openxla/xla`) repository.\n\n* **Core XLA compiler guidelines**: When generating, reviewing, or modifying\n code under [`xla/`](xla/), follow the detailed C++, MLIR, testing, and\n Bazel guidelines in [`xla/AGENTS.md`](xla/AGENTS.md).\n* [`build_tools/`](build_tools/) contains CI and developer tooling,\n [`docs/`](docs/) the user-facing documentation, and\n [`third_party/`](third_party/) vendored dependencies and Bazel repository\n rules.\n\n\n# AI Assistant Guidelines for OpenXLA Development\n\nThis document provides guidelines for AI code assistants when generating,\nsuggesting, or modifying code within the OpenXLA codebase (everything under\n`xla/` in this repository).\n\n## General Context\n\n* **Impact:** OpenXLA is a core compiler for machine learning acceleration. Changes here affect the open-source community and various hardware backends.\n* **Code Quality:** Adhere to [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) and OpenXLA-specific conventions.\n* **Portability:** This code is open-sourced and runs on a number of host platforms (e.g. Linux, Windows, etc.)\n\n## Repository Layout and Build\n\n* Source lives under `xla/`. Include paths are relative to the repository\n root, e.g. `#include \"xla/hlo/ir/hlo_module.h\"`.\n* Bazel labels use the same prefix, e.g. `//xla/hlo/ir:hlo_module`.\n* Build and test with Bazel, e.g. `bazel test //xla/service:hlo_verifier_test`.\n* Common external dependencies and their labels:\n `@com_google_absl//absl/...`, `@llvm-project//mlir/...`,\n `@llvm-project//llvm/...`, `@com_google_googletest//:gtest_main`,\n `@com_google_protobuf//:protobuf`. TSL (the platform layer) lives in-tree\n under `//xla/tsl/...`.\n* Test macros: `xla_cc_test` from `//xla:xla.default.bzl` (hardware-\n independent unit tests) and `xla_test` from `//xla/tests:build_defs.bzl`\n (tests that run on configured hardware backends).\n\n## Coding Guidelines for AI Assistance\n\n1. **Error Handling (`absl::Status`, `absl::StatusOr`)**:\n * **Always** use `absl::Status` or `absl::StatusOr` for functions that can encounter recoverable errors.\n * **Macros**:\n * Use header `absl/status/status_macros.h`.\n * Use `ABSL_RETURN_IF_ERROR` for error propagation.\n * Use `ABSL_ASSIGN_OR_RETURN` for `StatusOr` assignments.\n * **Safely access `StatusOr` values**: Check `.ok()` before accessing.\n\n2. **Assertions & Invariant Checks (`TF_RET_CHECK`)**:\n * **Avoid `DCHECK` / `LOG(DFATAL)`** for checking returnable errors.\n * **Prefer `TF_RET_CHECK`**:\n * Located in `xla/status_macros.h`.\n * Use strict internal invariant checks inside functions returning `absl::Status` / `StatusOr`.\n * Example:\n ```cpp\n #include \"xla/status_macros.h\"\n\n absl::Status Process(const Thing* t) {\n TF_RET_CHECK(t != nullptr) << \"Thing cannot be null\";\n // ...\n return absl::OkStatus();\n }\n ```\n\n3. **Decision making**:\n * **Avoid `bool`** for returning a decision to do or not to do something.\n * **Prefer `Decision`**:\n * Located in `xla/service/decision.h`\n * Example:\n ```cpp\n #include \"xla/service/decision.h\"\n\n using AutotunerDecision = Decision;\n\n AutotunerDecision ShouldAutotuneCublasCall(HloInstruction* instr) {\n // ...\n return AutotunerDecision::Forbid(\"Cublas autotuning was explicitly disabled\");\n }\n\n void AutotuneCublas(const AutotunerDecision& decision) {\n if (decision.IsForbidden()) {\n return;\n }\n ...\n ```\n\n4. **Performance Sensitivity**:\n * OpenXLA is a compiler; patterns should be efficient.\n * Avoid unnecessary string copies or expensive allocations in hot paths (e.g., HLO passes).\n\n5. **Testing**:\n * Write unit tests using `EXPECT_EQ`, `EXPECT_TRUE`, etc.\n * Use the status testing macros `ASSERT_OK_AND_ASSIGN`, `ASSERT_OK`, and\n `EXPECT_OK` from `` and the status matchers\n (`absl_testing::IsOk`, `absl_testing::IsOkAndHolds`,\n `absl_testing::StatusIs`) from `absl/status/status_matchers.h` instead\n of their legacy `TF_*` or `tsl::testing::*` counterparts:\n * DO NOT USE `TF_ASSERT_OK_AND_ASSIGN`, `TF_ASSERT_OK`, and\n `TF_EXPECT_OK`.\n * When you refactor code that uses the `TF_*` macros, replace them,\n but do not touch unrelated code.\n * Put tests into an anonymous namespace.\n * Use `HloInterpreterReferenceMixin` or\n `HloHardwareIndependentTestBase` for compiler pass tests locally where\n possible (do not use `HloTestBaseLegacy`).\n * When running GPU tests, pass `--config=cuda` to the test command.\n * Ensure tests are deterministic and do not flake.\n\n6. **BUILD targets**:\n * When defining BUILD targets prefer these XLA specific rules:\n * Instead of `proto_library` use `tf_proto_library`. There is no need\n to define language specific targets with `tf_proto_library`.\n * Instead of `cc_test` use `xla_cc_test` (or `xla_test` when the test\n requires a real hardware backend).\n\n7. **Explicit Typing**:\n * **Avoid `auto`** in public headers or complex logic chains.\n\n8. **Compiler Phases & Invariants**:\n * **Phase Ordering**: Understand where your pass or change sits in the pipeline (e.g., Optimizations, Layout Assignment, Fusion).\n * **Invariants**: Respect the invariants of the current phase.\n * *Example*: Do not generate `kCustomCall` instructions before the relevant expansion pass if they are not supported by the HLO verifier at that stage.\n * *Example*: Do not rely on layout information before Layout Assignment.\n\n9. **Namespaces**:\n * Prefer `xla::gpu` over nested namespaces.\n\n10. **MLIR Operation Creation**:\n * **Always** use the static `OpTy::create(rewriter, ...)` method when creating MLIR operations.\n * **Avoid** using `rewriter.create(...)`. This syntax is deprecated.\n\n11. **License Headers**:\n * Any new source or build files created in this codebase must include the\n OpenXLA Apache 2.0 copyright header at the top of the file.\n * Replace `` in the template below with the current 4-digit calendar\n year (e.g., `2026`—do not leave `` literally or copy an outdated\n year):\n ```cpp\n /* Copyright The OpenXLA Authors.\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n ==============================================================================*/\n ```\n (Use `#` comment prefixes for Python and `BUILD` files.)\n\n## Editing This File\n\nThis file is shared between the open-source repository and Google-internal\ndevelopment. Keep it in open-source terms only: repository-relative paths\n(`xla/...`), OSS macro names (`ABSL_RETURN_IF_ERROR`, `ABSL_ASSIGN_OR_RETURN`),\nBazel labels (`//xla/...`, `@repo//...`), and `bazel` commands.\n\n\n# XLA architecture\n\nXLA (Accelerated Linear Algebra) is a machine learning (ML) compiler that\noptimizes linear algebra, providing improvements in execution speed and memory\nusage. This page provides a brief overview of the objectives and architecture of\nthe XLA compiler.\n\n## Objectives\n\nToday, XLA supports several ML framework frontends (including PyTorch,\nTensorFlow, and JAX) and is part of the OpenXLA project – an ecosystem of\nopen-source compiler technologies for ML that's developed collaboratively by\nleading ML hardware and software organizations. Before the OpenXLA project was\ncreated, XLA was developed inside the TensorFlow project, but the fundamental\nobjectives remain the same:\n\n* **Improve execution speed.** Compile subgraphs to reduce the execution time\n of short-lived ops and eliminate overhead from the runtime, fuse pipelined\n operations to reduce memory overhead, and specialize known tensor shapes to\n allow for more aggressive constant propagation.\n\n* **Improve memory usage.** Analyze and schedule memory usage, eliminating\n many intermediate storage buffers.\n\n* **Reduce reliance on custom ops.** Remove the need for many custom ops by\n improving the performance of automatically fused low-level ops to match the\n performance of custom ops that were originally fused by hand.\n\n* **Improve portability.** Make it relatively easy to write a new backend for\n novel hardware, so that a large fraction of ML models can run unmodified on\n that hardware. This is in contrast with the approach of specializing\n individual monolithic ops for new hardware, which requires models to be\n rewritten to make use of those ops.\n\n## How it works\n\nThe XLA compiler takes model graphs from ML frameworks defined in\n[StableHLO](https://github.com/openxla/stablehlo) and compiles them into machine\ninstructions for various architectures. StableHLO defines a versioned operation\nset (HLO = high level operations) that provides a portability layer between ML\nframeworks and the compiler.\n\nIn general, the compilation process that converts the model graph into a\ntarget-optimized executable includes these steps:\n\n1. XLA performs several built-in optimization and analysis passes on the\n StableHLO graph that are target-independent, such as\n [CSE](https://en.wikipedia.org/wiki/Common_subexpression_elimination),\n target-independent operation fusion, and buffer analysis for allocating\n runtime memory for the computation. During this optimization stage, XLA also\n converts the StableHLO dialect into an internal HLO dialect.\n\n2. XLA sends the HLO computation to a backend for further HLO-level\n optimizations, this time with target-specific information and needs in mind.\n For example, the GPU backend may perform operation fusions that are\n beneficial specifically for the GPU programming model and determine how to\n partition the computation into streams. At this stage, backends may also\n pattern-match certain operations or combinations thereof to optimized\n library calls.\n\n3. The backend then performs target-specific code generation. The CPU and GPU\n backends included with XLA use [LLVM](http://llvm.org) for low-level IR,\n optimization, and code generation. These backends emit the LLVM IR necessary\n to represent the HLO computation in an efficient manner, and then invoke\n LLVM to emit native code from this LLVM IR.\n\nWithin this process, the XLA compiler is modular in the sense that it is easy to\nslot in an alternative backend to\n[target some novel HW architecture](./developing_new_backend.md). The GPU\nbackend currently supports NVIDIA GPUs via the LLVM NVPTX backend. The CPU\nbackend supports multiple CPU ISAs.\n\n\n\nSee [AGENTS.md](AGENTS.md) for AI coding guidelines and best practices in this\ncodebase.\n\n\nThis folder contains scripts and commands executed by GitHub actions in OpenXLA,\nTensorFlow and JAX OSS repos. The GitHub actions replaced\nKokoroPresubmit-tensorflow* workflows. They run under\n`Copybara_XLA{Presubmit,Submit}` presubmit chip (category) at Google internally.\nThe tests run on several target OS configurations/GCP containers such as Linux\nx86 with GPU or Linux ARM64. They assure that XLA/Tensor Flow/JAX compiles and\nruns on those platforms. The tests uses released OSS c++ clang compiler which\nhas some differences in supporting c++ standards compared Google's internal\nversion.\n\n#### How it works\n\nRepo specific GitHub actions call `build.py --build=\"build_name\"`. E.g. OpenXLA\nuses https://github.com/openxla/xla/blob/main/.github/workflows/ci.yml\n\nThe build here is a set of shell script commands executing the test targets or\ndoing compile only testing. Each GitHub action call translates into compile only\ntest:\n\n1. actual compile `bazel build ... test_targets`\n1. analyse results `bazel analyze-profile ...`\n\nor compile and run test commands:\n\n1. actual test `bazel test ... test_targets`\n1. analyse results `bazel analyze-profile profile.json.gz`\n\nChecking in changes to `build.py` regenerates `golden_commands.txt` which lets\nus see how commands are changing. `golden_commands.txt` are not called as part\nof the continuous integration process.\n\n#### When does it run?\n\nThe GitHub actions are automatically called as part of Google presubmit. The\nGitHub actions are automatically called on GitHub PR commit if the committer is\npart of OpenXLA GitHub org. Committer which are not part of OpenXLA org need an\napproval from OpenXLA org member to run the actions.\n\n\n# TensorFlow Bazel Clang\n\nThis is a specialized toolchain that uses an old Debian with a new Clang that\ncan cross compile to any x86_64 microarchitecture. It's intended to build Linux\nbinaries that only require the following ABIs:\n\n- GLIBC_2.18\n- CXXABI_1.3.7 (GCC 4.8.3)\n- GCC_4.2.0\n\nWhich are available on at least the following Linux platforms:\n\n- Ubuntu 14+\n- CentOS 7+\n- Debian 8+\n- SuSE 13.2+\n- Mint 17.3+\n- Manjaro 0.8.11\n\n# System Install\n\nOn Debian 8 (Jessie) Clang 6.0 can be installed as follows:\n\n```sh\ncat >>/etc/apt/sources.list <<'EOF'\ndeb http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\ndeb-src http://apt.llvm.org/jessie/ llvm-toolchain-jessie main\nEOF\nwget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -\napt-key fingerprint |& grep '6084 F3CF 814B 57C1 CF12 EFD5 15CF 4D18 AF4F 7421'\napt-get update\napt-get install clang lld\n```\n\n# Bazel Configuration\n\nThis toolchain can compile TensorFlow in 2m30s on a 96-core Skylake GCE VM if\nthe following `.bazelrc` settings are added:\n\n```\nstartup --host_jvm_args=-Xmx30G\nstartup --host_jvm_args=-Xms30G\nstartup --host_jvm_args=-XX:MaxNewSize=3g\nstartup --host_jvm_args=-XX:-UseAdaptiveSizePolicy\nstartup --host_jvm_args=-XX:+UseConcMarkSweepGC\nstartup --host_jvm_args=-XX:TargetSurvivorRatio=70\nstartup --host_jvm_args=-XX:SurvivorRatio=6\nstartup --host_jvm_args=-XX:+UseCMSInitiatingOccupancyOnly\nstartup --host_jvm_args=-XX:CMSFullGCsBeforeCompaction=1\nstartup --host_jvm_args=-XX:CMSInitiatingOccupancyFraction=75\n\nbuild --jobs=100\nbuild --local_resources=200000,100,100\nbuild --crosstool_top=@local_config_clang6//clang6\nbuild --noexperimental_check_output_files\nbuild --nostamp\nbuild --config=opt\nbuild --noexperimental_check_output_files\nbuild --copt=-march=native\nbuild --host_copt=-march=native\n```\n\n# x86_64 Microarchitectures\n\n## Intel CPU Line\n\n- 2003 P6 M SSE SSE2\n- 2004 prescott SSE3 SSSE3 (-march=prescott)\n- 2006 core X64 SSE4.1 (only on 45nm variety) (-march=core2)\n- 2008 nehalem SSE4.2 VT-x VT-d (-march=nehalem)\n- 2010 westmere CLMUL AES (-march=westmere)\n- 2012 sandybridge AVX TXT (-march=sandybridge)\n- 2012 ivybridge F16C MOVBE (-march=ivybridge)\n- 2013 haswell AVX2 TSX BMI2 FMA (-march=haswell)\n- 2014 broadwell RDSEED ADCX PREFETCHW (-march=broadwell - works on trusty\n gcc4.9)\n- 2015 skylake SGX ADX MPX\n AVX-512[xeon-only](-march=skylake / -march=skylake-avx512 - needs gcc7)\n- 2018 cannonlake AVX-512 SHA (-march=cannonlake - needs clang5)\n\n## Intel Low Power CPU Line\n\n- 2013 silvermont SSE4.1 SSE4.2 VT-x (-march=silvermont)\n- 2016 goldmont SHA (-march=goldmont - needs clang5)\n\n## AMD CPU Line\n\n- 2003 k8 SSE SSE2 (-march=k8)\n- 2005 k8 (Venus) SSE3 (-march=k8-sse3)\n- 2008 barcelona SSE4a?! (-march=barcelona)\n- 2011 bulldozer SSE4.1 SSE4.2 CLMUL AVX AES FMA4?! (-march=bdver1)\n- 2011 piledriver FMA (-march=bdver2)\n- 2015 excavator AVX2 BMI2 MOVBE (-march=bdver4)\n\n## Google Compute Engine Supported CPUs\n\n- 2012 sandybridge 2.6gHz -march=sandybridge\n- 2012 ivybridge 2.5gHz -march=ivybridge\n- 2013 haswell 2.3gHz -march=haswell\n- 2014 broadwell 2.2gHz -march=broadwell\n- 2015 skylake 2.0gHz -march=skylake-avx512\n\nSee: \n\n\n# AARCH64 toolchain\n\nToolchain for performing TensorFlow AARCH64 builds such as used in Github\nActions ARM_CI and ARM_CD.\n\nMaintainer: @elfringham (Linaro LDCG)\n\n********************************************************************************\n\nThis repository contains a toolchain for use with the specially constructed\nDocker containers that match those created by SIG Build for x86 architecture\nbuilds, but modified for AARCH64 builds.\n\nThese Docker containers have been constructed to perform builds of TensorFlow\nthat are compatible with manylinux2014 requirements but in an environment that\nhas the C++11 Dual ABI enabled.\n\nThe Docker containers are available from\n[Docker Hub](https://hub.docker.com/r/linaro/tensorflow-arm64-build/tags) The\nsource Dockerfiles are available from\n[Linaro git](https://git.linaro.org/ci/dockerfiles.git/tree/tensorflow-arm64-build)\n\n\n# ARM GCC toolchains\n\nThis repository contains Bazel C++ toolchain configurations for ARM GCC. The\nfollowing toolchains are configured:\n\nsource:\nhttps://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads -\ngcc 8.3 - glibc 2.28\n\ntarget cpu: aarch64, armhf\n\n\n# Embedded toolchains\n\nThis repository contains toolchains for various embedded systems such as\nRaspberry Pi and Coral development boards.\n\n\n# MLIR HLO mlir_bisect\n\nThis is a test case reduction tool, similar in purpose to `mlir-reduce`, but\nspecific to the `mlir-interpreter` infrastructure. In particular, reductions can\ndepend on concrete values encountered during execution, and reductions can (and\nusually do) generate multiple candidates.\n\nFor example, the `ReplaceOpWithConstant` reduction will attempt to replace each\nop with each of its results. If the op is in a loop, each execution will be a\ncandidate for replacement.\n\n## Using this tool\n\n1. Run a JAX test with snapshots enabled:\n\n ```sh\n bazel test some-jax-test\n --test_env=XLA_FLAGS=\"--xla_cpu_use_xla_runtime --xla_dump_to=/tmp/dump\n --xla_dump_hlo_snapshots\" --test_filter=SomeSpecific.Test\n --test_sharding_strategy=disabled --test_strategy=local\n ```\n\n1. Figure out the culprit module and pass (sorry, no automation yet):\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_replay:mlir_replay -- \\\n --mlir-compilation-trace=/tmp/dump/module_0000.jit__something.mlir-trace.pb \\\n --hlo-snapshot=/tmp/dump/module_0000.jit__something.snapshot.0.pb \\\n --print-changes-only \\\n --execution-trace-dir=/tmp/execution\n ```\n\n You should see a pass after which results change. You'll want to use the\n .mlir file in `/tmp/execution` corresponding to the pass *before* that with\n the bisect tool.\n\n Note: If the failing pass is bufferization, you may have to use an earlier\n snapshot, e.g. before `EmptyTensorToAllocTensor`.\n1. Run bisect:\n\n ```sh\n bazel run tensorflow/compiler/xla/mlir/tools/mlir_bisect:mlir-bisect -- \\\n --hlo-snapshot=/tmp/dump/module_0000.jit_something.snapshot.0.pb \\\n --pass-pipeline=\"builtin.module(empty-tensor-to-alloc-tensor,one-shot-bufferize{allow-return-allocs bufferize-function-boundaries create-deallocs=0})\" \\\n /tmp/execution/0052.ScalarizationPass.mlir\n ```\n\n## Adding a reduction\n\nTo add a reduction, create a function that generates the candidates and register\nit:\n\n```cpp\nSmallVector>\nFrobulateAndDefenestrate(BisectState&, dialect::SomeOp some_op) {\n auto [cloned_module_1, cloned_op_1] = CloneModuleFor(some_op);\n Frobulate(cloned_op_1);\n\n auto [cloned_module_2, cloned_op_2] = CloneModuleFor(some_op);\n Defenestrate(cloned_op_2);\n\n return {cloned_module_1, cloned_module_2};\n}\n\nREGISTER_MLIR_REDUCE_STRATEGY(FrobulateAndDefenestrate);\n```\n\nThen, add a test for the strategy. Make sure your strategy is linked into\nmlir-bisect and has `alwayslink` set.\n\n```mlir\n// RUN: mlir-bisect %s --debug-strategy=FrobulateAndDefenestrate | FileCheck %s\n\nfunc.func @main() {\n dialect.some_op()\n}\n\n// CHECK: func @main()\n// CHECK-NEXT: frobulated\n\n// CHECK: func @main()\n// CHECK-NEXT: defenestrated\n```\n\n`--debug-strategy` will print all candidates generated by the given strategy.\n\n\n# MLIR interpreter\n\nMLIR interpreter is a development tool, mainly intended for debugging. As the\nname implies, it executes MLIR programs. What makes it special is that it\nimplements dialects at all levels of abstraction and all standard data types\n(tensor, memref, vector, scalar). One use case is to track down compiler bugs\nby executing the IR after each one and looking for changed results.\n\nFeatures:\n- Tensors, memrefs, vectors, scalars\n- Many dialects supported: from mhlo via linalg and scf all the way to arith.\n- Easy to extend (look at dialects/affine.cc for an example).\n\n## Creating a new dialect\n\nTo create a new dialect, follow the following steps:\n\n1. Create a `.cc` implementation file in `dialects/`. The name of the file\n should match your dialect name.\n1. Add a dependency to your dialect to the `dialects:dialects` target.\n1. Each op is implemented in a function.\n - Op results:\n - If your op has no result, the function should be `void`.\n - If your op has a tensor, memref or vector result, the return type\n should be `InterpreterValue`.\n - Scalars can be returned as their corresponding C++ type (e.g.\n `int64_t`, `float`)\n - You can also return a `SmallVector` if your op has multiple results.\n - Op arguments:\n - Your function should take an `InterpreterState&`, an instance of\n your op and any arguments your op takes.\n - Like above, arguments can either be taken as `InterpreterValue`s, as\n scalar C++ types or as `SmallVector` thereof (for variadic\n arguments).\n - Error handling:\n - If some of the inputs are invalid, use\n `InterpreterState::AddFailure` to report this.\n1. Register the ops: `REGISTER_MLIR_INTERPRETER_OP(YourOp)`.\n1. Add test cases in `dialects/tests`.\n\n\n# mlir_replay Documentation\n\nPath: `xla/mlir/tools/mlir_replay/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/mlir/tools/mlir_replay/README.md)\n\n\n# example Documentation\n\nPath: `xla/pjrt/extensions/example/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/pjrt/extensions/example/README.md)\n\n\n# hlo_workload_executor Documentation\n\nPath: `xla/tools/benchmarks/hlo_workload_executor/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/openxla/xla/HEAD/xla/tools/benchmarks/hlo_workload_executor/README.md)\n\n\nSee https://openxla.org/xla/tools_multihost_hlo_runner for public documentation.\nExtra information in the xla/tools/multihost_hlo_runner/hlo_runner_main.cc file.\n"}