tosa-tools 2026.2.1

TOSA Tools: serialization library, reference model, optional MLIR translator

TOSA Tools

A toolkit for working with the Tensor Operator Set Architecture (TOSA) Specification (https://git.mlplatform.org/tosa/specification.git/), providing serialization, reference implementation, and MLIR translation capabilities.

Introduction

TOSA Tools is a composite project that integrates three main components:

• reference_model – a reference implementation of TOSA operators.
• serialization – provides methods to read and write serialized TOSA graphs.
• mlir_translator – implements translators between the TOSA MLIR dialect and serialized representations.

Each subfolder contains its own README with more detailed information.

PyPI package

From v2026.02.0 onward, the tosa-tools Python package is published on PyPI. For most users, the quickest start is:

python -m pip install tosa-tools

This installs the Python APIs and command-line entrypoints from all the components (serialization + reference model + MLIR translator). For a concise list of the Python modules, executables, console scripts and shared libraries installed by the package, see PYTHON_PACKAGE.md.

Prerequisites

Platform support

The following platforms are supported:

Platform	Architecture	Support level
Linux	x86_64	release
Linux	aarch64	experimental
Windows (r)	x86_64	experimental
macOS (r)	aarch64	experimental

For build instructions see README.md for individual components.

System Requirements

Tool	Version	Note
Python	3.10 or later	tested with 3.12.0
CMake	3.16 or later	tested with 3.30

External Dependencies

LLVM/MLIR

The TOSA MLIR Translator must be linked against a build of LLVM with the MLIR project enabled. Currently, the TOSA MLIR Translator aims to be compatible with the main branch of LLVM. However, when breaking API changes are introduced in LLVM/MLIR, compatibility may not be guaranteed. We regularly update the tested SHA; see ci/vars/llvm-sha.yml for the current SHA.

Quick Build (POSIX)

Build all projects with default configuration:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Selective Build

Use TOSA_ENABLE_PROJECTS to build specific components:

Build only serialization library:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS=serialization
cmake --build build

Build serialization and reference model:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS="serialization;reference_model"
cmake --build build

Build MLIR translator:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS="mlir_translator" \
    -DMLIR_TOSA_OPT=ON \
    -DMLIR_DIR=${LLVM_BUILD}/lib/cmake/mlir \
    -DLLVM_DIR=${LLVM_BUILD}/lib/cmake/llvm
cmake --build build

Build all projects (including MLIR translator):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS=all \
    -DMLIR_TOSA_OPT=ON \
    -DMLIR_DIR=${LLVM_BUILD}/lib/cmake/mlir \
    -DLLVM_DIR=${LLVM_BUILD}/lib/cmake/llvm
cmake --build build

Note: The MLIR translator requires MLIR to be available on your system. It is not enabled by default. LLVM_BUILD must be absolute path to llvm-project build directory.

Debug Build

For debug symbols:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DTOSA_ENABLE_PROJECTS=reference_model
cmake --build build

Build and install with pip

The Python package is built with scikit-build-core, which drives a CMake build under the hood. This means pip install will compile native code and therefore requires a working C/C++ toolchain.

If you just want the prebuilt package, use python -m pip install tosa-tools as shown above. The steps below are for building from source.

Note: Starting with release 2026.05.0, the tooling to build/install the individual component Python packages from subdirectories will be removed. Use the unified tosa-tools package from the repository root (python -m pip install .).

Install default components (serialization + reference model)

This uses the default CMake definitions from pyproject.toml.

python -m venv .venv
source .venv/bin/activate

python -m pip install -U pip

# Build + install from the current checkout
python -m pip install . -v -Cbuild-dir=build/pip-install

Install with MLIR translator enabled

To build the MLIR translator you need a compatible LLVM/MLIR build. The tested LLVM commit is pinned in ci/vars/llvm-sha.yml.

Install tosa-tools with the required CMake config settings:

python -m pip install . -v -Cbuild-dir=build/pip-install \
    --config-settings=cmake.define.TOSA_ENABLE_PROJECTS="serialization;reference_model;mlir_translator" \
    --config-settings=cmake.define.MLIR_TOSA_OPT=ON \
    --config-settings=cmake.define.MLIR_DIR="${LLVM_BUILD}/lib/cmake/mlir" \
    --config-settings=cmake.define.LLVM_DIR="${LLVM_BUILD}/lib/cmake/llvm"

Build a wheel locally (optional)

python -m pip wheel . -w dist -v -Cbuild-dir=build/pip-wheel
python -m pip install --no-deps dist/*.whl

Development Environment

For a consistent setup, use the provided Docker configuration for development. This mirrors the CI environment closely. Please refer to the CI README for more details.

Pre-Commit Checks

Before pushing a commit, pre-commit checks must be run to ensure conformity.

NOTE: All commits pushed to remote must adhere to the structured commit format, please refer to CONTRIBUTING.md for detailed guidelines.

pre-commit install
pre-commit run --all

Versioning

This project uses Calendar Versioning (CalVer) in the format: YYYY.0M.Micro[.Modifier]

• YYYY – 4-digit release year (e.g., 2025)
• 0M – 2-digit Zero-padded release month (e.g., 07 for July)
• Micro – The third and usually final number in the version. Sometimes referred to as the "patch" segment.
• Modifier - Optional text tag used to signify extra information about the build.
  • no tag (empty string) - builds produced for release will have no tag at all.

The main branch is used as the active development branch for the next version.

License

The TOSA Tools components are licensed as follows:

• TOSA Serialization Library: Apache-2.0
• TOSA Reference Model: Apache-2.0
• TOSA MLIR Translator: Apache-2.0 with LLVM Exceptions

See individual component directories for detailed license information and third-party project licenses.