Seal5

Note

Starting July 11, 2024 we will be offering (monthly) Seal5 Development/User meetings.

Next call: Sep 12, 2024, 11:00

Click here for details, if you are interested!

Note

Seal5 was recently presented at the RISC-V Summit Europe 2024. Click here to access the poster, slides & recording.

Overview

The RISC-V instruction set architecture (ISA) is popular for its extensibility. However, a quick exploration of instruction candidates fails due to the lack of tools to auto-generate embedded software toolchain support. Seal5 work establishes a semi-automated flow to generate LLVM compiler support for custom instructions based on the CoreDSL2 ISA description language. Seal5 is capable of generating support for functionalities ranging from baseline assembler-level support, over builtin functions to compiler code generation patterns for scalar as well as vector instructions, while requiring no deeper compiler know-how.

Eliminating manual efforts for Retargeting is crutial for the automated exploration of custom RISC-V instructions as depicted in the following image. Seal5's code-generation support allows to make use of custom instructions without needing to make changes to the programs/benchmarks source code (i.e. adding inline-assembly calls).

Prerequisites

To be able to run the examples, make sure to clone the Seal5 repo using the --recursive flag. Otherwise run the following command to fetch (and update) the referenced submodules.

git submodule update --init --recursive

Ubuntu Packages

First, a set of APT packages needs to be installed:

sudo apt install python3-pip python3-venv cmake make ninja-build

Python Requirements

First, setup a virtual environment with Python v3.8 or newer.

Install all required python packages using the following command:

pip install -r requirements.txt.

For development (linting, packaging,...) there are a few more dependencies which can be installed via:

pip install -r requirements_dev.txt.

System Requirements

The initial cloning of the llvm-project repo will take a long time, hence a good internet connection is recommended. To run the demo, make sure to have at least 20GB (>40GB for debug builds) of disk space available in the destination (/tmp/seal5_llvm_demo) directory. The target directory can be changed as follows: DEST=$HOME/seal5_demo.

Installation

Warning: It is highly recommended to install seal5 into a new virtual environment. Follow these steps to initialize and enter a venv in your seal5 repo directory:

# alternative: python3 -m venv venv
virtualenv -p python3.8 venv
source venv/bin/activate

From PyPI

pip install seal5

Local Development Version

First prepare your shell by executing export PYTHONPATH=$(pwd):$PYTHONPATH inside the seal5 repository. Then you should be able to use Seal5 without needing to reinstall it.

Alternatively you should be able to use pip install -e ..

Usage

Python API

The flow can be sketched as follows (see Example below for functional code!):

# Create flow
seal5_flow = Seal5Flow(...)
# Initialize LLVM repo and .seal5 directories
seal5_flow.initialize(...)
# Optional: remove artifacts from previous builds
seal5_flow.reset(...)
# Install Seal5 dependencies (CDSL2LLVM/PatternGen)
seal5_flow.setup(...)
# Load CoreDSL2+CFG files (Git config, filters,...)
seal5_flow.load(...)
# Transform Seal5 model (Extract side effects, operands,...)
seal5_flow.transform(...)
# Generate patches based on Seal5 model (ISel patterns, RISC-V features,...)
seal5_flow.generate(...)
# Apply generated (and manual) patches to LLVM codebase
seal5_flow.patch(...)
# Build patches LLVM (This will take a while)
seal5_flow.build(...)
# Run LLVM+Seal5 tests to verify functionality
seal5_flow.test(...)
# Combine patches and install LLVM
seal5_flow.deploy(...)
# Archive final LLVM (optionally inclusing logs, reports,...)
seal5_flow.export(...)
# Optional: Cleanup all artifacts
seal5_flow.cleanup(...)

Command-Line Interface

Command line interface is aligned with the Python API. See examples/demo.sh for an full usage example

export SEAL5_HOME=...
seal5 --dir $SEAL5_HOME reset  --settings
seal5 init [--non-interactive] [-c]
seal5 load --files ...
seal5 setup ...
seal5 transform ...
seal5 generate ...
seal5 patch ...
seal5 build ...
seal5 test ...
seal5 deploy ...
seal5 export ...
seal5 clean [--temp] [--patches] [--models] [--inputs]

Examples

See examples/demo.py for example of end-to-end flow!

Documentation

Checkout Seal5's ReadTheDocs Page!

Limitations

See here.

CI/CD Flow

We added a (manual) CI job to run the examples/demo.py script via GitHub actions.

Contributions

Seal5 issue tracker: https://github.com/tum-ei-eda/seal5/issues

CoreDSL2LLVM/PatternGen issue tracker: https://github.com/mathis-s/CoreDSL2LLVM/issues

References

N/A

Acknowledgment

This research is partially funded by the German Federal Ministry of Education and Research (BMBF) within the projects Scale4Edge (grant number 16ME0465) and MANNHEIM-FlexKI (grant number 01IS22086L).

Allow adding user-provided tests files

Assume that a user provides some basic LLVM tests for the instructions being processed by Seal5.

The s4e-mac.test.c from https://github.com/DLR-SE/riscv-coredsl-extensions is a good example:

// Basic test of assembly and layout of sample S4E MAC instruction extensions

// RUN: %clang --target=riscv32 -march=rv32ixs4emac -c -o %t.o %s
// RUN: llvm-objdump --disassembler-options=numeric -d %t.o | FileCheck %s

int main() {
  // Non-ISAX canary instruction, to flag an unwanted case of endian/width/compression/whatever
  // CHECK: b3 01 52 00 add x3, x4, x5
  asm("add x3, x4, x5");

  // CHECK: 0b 00 00 00 reset_acc
  asm("reset_acc");

  // CHECK: 0b 03 00 02 get_acc_lo x6
  asm("get_acc_lo x6");

  // CHECK: 8b 0c 00 04 get_acc_hi x25
  asm("get_acc_hi x25");

  // CHECK: 0b 90 1a 01 macu_32 x21, x17
  asm("macu_32 x21, x17");

  // CHECK: 0b 90 1a 03 macs_32 x21, x17
  asm("macs_32 x21, x17");

  // CHECK: 0b a0 1a 01 macu_64 x21, x17
  asm("macu_64 x21, x17");

  // CHECK: 0b a0 1a 03 macs_64 x21, x17
  asm("macs_64 x21, x17");

  return 42;
}

It would be great if those files could used in Seal5's TEST stage.

Proposed Usage:

flow.load("s4e-mac.test.c") -> Detect supported file types (.c .cpp .cc .s .ll .mir) -> call flow.load_test automatically
Optional: flow.load("s4e-mac.test.yml") to customize how the test is used (Needs new Seal5TestSettings dataclass?)
During: flow.test(): Run the tests via the llvm-lit suite. 2 approaches:

A: Copy test to llvm-project/llvm/tests/CodeGen/RISCV/seal5/s4e-mac.test.c (or custom path) and run together with all the other RISC-V tests
B: Store test just in llvm-projejct/.seal5/tests/s4e-mac.test.c and run it seperately from the default LLVM tests.

tum-ei-eda / seal5 Goto Github PK

seal5's Introduction

Seal5

Overview

Prerequisites

Ubuntu Packages

Python Requirements

System Requirements

Installation

From PyPI

Local Development Version

Usage

Python API

Command-Line Interface

Examples

Documentation

Limitations

CI/CD Flow

Contributions

References

Acknowledgment

seal5's People

Contributors

Stargazers

Watchers

Forkers

seal5's Issues

Recommend Projects

Recommend Topics

Recommend Org