Lira Integration

.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: LIRA CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  python-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - run: pip install ruamel.yaml pytest pytest-cov
+      - name: Unit tests
+        run: pytest python/tests/unit/ -v
+      - name: Unit coverage
+        run: pytest --cov=python/lira python/tests/unit/ --cov-report=term
+      - name: Integration tests
+        run: pytest python/tests/integration/ -v
+      - name: Diff integration output vs reference
+        run: diff python/tests/integration/integration.yaml tests/integration/reference.yaml
+
+  ruby-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - run: pip install ruamel.yaml
+      - run: gem install minitest simplecov
+      - name: Unit tests
+        run: |
+          ruby -I ruby -I ruby/lib ruby/tests/unit/test_ir_ser_txt.rb
+          ruby -I ruby -I ruby/lib ruby/tests/unit/test_arch_ser_yaml.rb
+          ruby -I ruby -I ruby/lib ruby/tests/unit/test_ir_builder.rb
+      - name: Unit coverage
+        run: |
+          ruby -r simplecov -I ruby -I ruby/lib -e 'SimpleCov.start; Dir["ruby/tests/unit/*.rb"].each { |f| require_relative f }'
+      - name: Integration tests
+        run: ruby -I ruby -I ruby/lib ruby/tests/integration/test_integration.rb
+      - name: Diff integration output vs reference
+        run: diff ruby/tests/integration/integration.yaml tests/integration/reference.yaml
+
+  rust-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - run: pip install ruamel.yaml
+      - name: Integration tests
+        run: cd rust && cargo test -p lira-tests --test integration
+      - name: Diff integration output vs reference
+        run: diff rust/tests/integration/integration.yaml tests/integration/reference.yaml
+
+  cross-language:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+      - uses: dtolnay/rust-toolchain@stable
+      - run: pip install ruamel.yaml pytest
+      - run: gem install minitest
+
+      - name: Python writes native YAML
+        run: pytest tests/cross_language/test_cross.py -k "write" -v
+      - name: Ruby writes native YAML
+        run: ruby -I ruby -I ruby/lib tests/cross_language/test_cross.rb --name test_ruby_write_and_self_read
+      - name: Rust writes native YAML
+        run: cd rust && cargo test -p lira-tests --test cross_language test_rust_write_and_self_read
+
+      - name: Python reads Ruby and Rust
+        run: pytest tests/cross_language/test_cross.py -k "reads" -v
+      - name: Ruby reads Python and Rust
+        run: ruby -I ruby -I ruby/lib tests/cross_language/test_cross.rb --name '/test_ruby_reads/'
+      - name: Rust reads Python and Ruby
+        run: cd rust && cargo test -p lira-tests --test cross_language test_rust_reads

.gitignore

@@ -1,2 +1,6 @@
 __pycache__
 target
+
+*coverage
+
+build/

README.md

@@ -0,0 +1,32 @@
+# LIRA
+
+LIRA is a framework that provides a data-flow Intermediate Representation.
+
+**Libraries:**
+- [python/lira](python/lira) — Python 3 library
+- [ruby/lira](ruby/lira) — Ruby library
+- [rust/lira](rust/lira) — Rust library
+
+## Install
+
+- Python (pip):
+```bash
+pip install -e python/
+```
+
+- Ruby (gem)
+```bash
+gem build ruby/lira.gemspec && gem install lira-*.gem
+# or via Gemfile:
+#   gem "lira", path: "ruby"
+```
+- Rust (Cargo)
+```bash
+cargo add --path rust/lira
+```
+
+## Examples
+
+- [Python 3 examples](python/examples)
+- [Ruby examples](ruby/examples)
+- [Rust examples](rust/examples)

docs/ir_ops.md

@@ -0,0 +1,113 @@
+# Basic operations
+
+All basic LIRA operations are inherited from the standard operation from the lira/arch module.
+
+Below is an implementation of a standard operation in [python](../python/lira/arch.py):
+
+```python3
+@dataclass
+class Operation(Component):
+    inputs: list[int]
+    outputs: list[int]
+    semantic_base: Optional[str] = None
+    semantic_func: Optional[str] = None
+    semantic_func_128: Optional[str] = None
+    semantic_table: Optional[str] = None
+```
+
+# Types
+
+In general, base operations work on bit-vector (BV) values.
+
+Note: `BV<1>` is used instead of `Bool`.
+
+# Name Conventions
+
+Operations are grouped by operand signature.
+The `name` field follows the specific pattern.
+
+## Unary
+
+`BV<n> -> BV<n>` - `<semnatic_base>_<n>`
+
+| Operation | Description |
+|-----------|-------------|
+| `not`     | bitwise NOT |
+| `neg`     | two's complement negation |
+| `popcnt`  | population count (number of set bits) |
+| `ctz`     | count trailing zeros |
+| `clz`     | count leading zeros |
+| `reverse` | reverse bit order |
+
+## Binary
+
+`BV<n> BV<n> -> BV<n>` – `<semnatic_base>_<n>`
+
+| Operation | Description |
+|-----------|-------------|
+| `add`     | addition |
+| `sub`     | subtraction |
+| `mul`     | multiplication |
+| `and`     | bitwise AND |
+| `orr`     | bitwise OR |
+| `xor`     | bitwise XOR |
+| `lsl`     | logical shift left |
+| `lsr`     | logical shift right |
+| `asr`     | arithmetic shift right |
+| `rem_u`   | unsigned remainder (`rem(a,0)=a`) |
+| `rem_s`   | signed remainder (`rem(a,0)=a`) |
+| `ror`     | rotate right |
+| `rol`     | rotate left |
+
+## Comparison
+
+`BV<n> BV<n> -> BV<1>` - `<semnatic_base>_<n>`
+
+| Operation | Description |
+|-----------|-------------|
+| `eq`  | equality |x
+| `ne`  | not equal |
+| `slt` | signed less than |
+| `sle` | signed less or equal |
+| `sgt` | signed greater than |
+| `sge` | signed greater or equal |
+| `ult` | unsigned less than |
+| `ule` | unsigned less or equal |
+| `ugt` | unsigned greater than |
+| `uge` | unsigned greater or equal |
+| `add_overflow` | signed addition overflow |
+| `sub_overflow` | signed subtraction overflow |
+
+## Ternary
+
+`BV<n> BV<n> BV<n> -> BV<n>` - `<semnatic_base>_<n>`
+
+| Operation | Description |
+|-----------|-------------|
+| `div_u` | unsigned division: `div(a,b,c) = b != 0 ? a/b : c` |
+| `div_s` | signed division: `div(a,b,c) = b != 0 ? a/b : c` |
+
+## Select
+
+`BV<1> BV<n> BV<n> -> BV<n>` - `<semnatic_base>_<n>`
+
+| Operation | Description |
+|-----------|-------------|
+| `select` | multiplexer: `select(cond, true, false)` |
+
+## Cast
+
+`BV<in> -> BV<out>` - `<semnatic_base>_<in>_to_<out>`
+
+| Operation | Description |
+|-----------|-------------|
+| `extract_low`  | extract low bits (`out` <= `in`) |
+| `extend_sign`  | sign-extend (`out` > `in`) |
+| `extend_zero`  | zero-extend (`out` > `in`) |
+
+## Derivatives
+
+Some compound operations are derived from the standard set and need semantic definitions in the LIRA architecture:
+
+- `extract(v, start, width)` = `extract_low(lsr(v, start), width)`
+- `concat(low, high)` = `orr(extend_zero(low, high_bits + low_bits), lsl(extend_zero(high, high_bits + low_bits), low_bits))`