nortl 1.4.0__tar.gz

nortl-1.4.0/.gitattributes

@@ -0,0 +1,3 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+*.lock -text

nortl-1.4.0/.github/workflows/deploy_pages.yml

@@ -0,0 +1,31 @@
+name: Build and deploy pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    name: Build and deploy pages
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - name: Build Documentation
+        run: uv run mkdocs build --site-dir site --strict
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

nortl-1.4.0/.github/workflows/test_and_publish.yml

@@ -0,0 +1,39 @@
+name: Test and Publish to Pypi
+
+on: [push]
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - name: Install Icarus Verilog
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install iverilog
+      - name: Run tox
+        run: uv run tox
+
+  publish:
+    name: Publish on Pypi
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nortl
+    permissions:
+      id-token: write
+      contents: read
+
+    # Only publish to PyPi on tag pushes
+    if: github.ref_type == 'tag'
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - name: Build Project
+        run: uv build
+      - name: Publish on Pypi
+        run: uv publish

nortl-1.4.0/.gitignore

@@ -0,0 +1,18 @@
+.cache
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.tox
+.venv
+__pycache__
+build
+dist
+reports
+wheels
+docs/site
+.coverage*
+*.py[ocd]
+*.egg-info
+a.out
+scratchpad
+*.vcd

nortl-1.4.0/.python-version

@@ -0,0 +1 @@
+3.12

nortl-1.4.0/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-python.mypy-type-checker",
+        "tamasfe.even-better-toml",
+        "charliermarsh.ruff"
+    ]
+}

nortl-1.4.0/.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit"
+        }
+    },
+    "python.testing.pytestEnabled": true,
+    "files.insertFinalNewline": true,
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/.mypy_cache": true,
+        "**/.pytest_cache": true,
+        "**/.tox": true,
+        "**/.venv": true,
+        "**/*.egg-info": true,
+        "**/*.pyd": true,
+    },
+    "files.trimFinalNewlines": true,
+    "files.trimTrailingWhitespace": true,
+    "mypy-type-checker.importStrategy": "fromEnvironment"
+}

nortl-1.4.0/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2026 Institut für Mikroelektronik- und Mechatronik-Systeme gemeinnützige GmbH (IMMS GmbH)
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nortl-1.4.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: nortl
+Version: 1.4.0
+Summary: Not-only RTL.
+Project-URL: Homepage, https://github.com/IMMS-Ilmenau/nortl
+Project-URL: Documentation, https://IMMS-Ilmenau.github.io/nortl
+Author-email: Florian Koegler <florian.koegler@imms.de>, Georg Glaeser <georg.glaeser@imms.de>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: more-itertools>=10.8.0
+Requires-Dist: networkx>=3.4.2
+Provides-Extra: type-stubs
+Requires-Dist: pytest-stub; extra == 'type-stubs'
+Requires-Dist: types-networkx; extra == 'type-stubs'
+Description-Content-Type: text/markdown
+
+# noRTL - Hardware design beyond register transfer level
+
+**noRTL** (Not-only RTL) is a Python-based code generation framework for designing and implementing hardware description language (HDL) modules, particularly SystemVerilog state machines. It provides a high-level, Pythonic API for describing sets of finite state machines (FSMs) and hardware components with built-in correctness guarantees.
+
+**noRTL** aims to make the design of complex digital systems easier by reducing the shortcommings of current hardware description languages that use the register transfer level (RTL) to model digital circuit's behavior. This tool goes beyond this level of abstraction: We digital designers want to describe behavior with cycle-level accuracy but do not want do deal with the complexity of state naming, state coding, starting parallel processes, etc. **noRTL** realizes this tedious part of digital design inside its core.
+
+The code that is written for **noRTL** is pure Python code. The **noRTL** package realizes state handling and data structure assembly for you while the Python code is executed. **noRTL** can be understood as a fancy generator that assembles state machines and provides the tooling to render it to SystemVerilog and tools for verifying your code.
+
+## Main ideas
+
+**noRTL** is built with the following concepts and ideas.
+
+* Each hardware description is an executable Python program. The hardware structure is assembled during execution. There is no need for static code analysis or parsing.
+* There should be no need to declare states explicitely. The number of states is determined during execution of the code.
+* The behavior description should be easily readable and feel procedural. Control structures should work similar to Python equivalents.
+* Checks and Optimizations are to be done during runtime of the Python code. Post-Optimization has not been necessary (yet).
+
+## Installation
+
+A prerequisite for noRTL is the availablility of icarus Verilog in your path. This can be installed using your system's package manager or using the *oss-cad-suite* (https://github.com/YosysHQ/oss-cad-suite-build)
+
+### Method 1: Using pip (Public Registry)
+
+```bash
+# Install nortl
+pip install nortl
+```
+
+### Method 2: Using uv (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/IMMS-Ilmenau/nortl
+cd nortl
+
+# Install dependencies
+uv sync
+
+# Activate the virtual environment
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+```
+
+### Method 3: Development Installation
+
+For development work, install in editable mode:
+
+```bash
+# Clone the repository
+git clone https://github.com/IMMS-Ilmenau/nortl
+cd nortl
+
+# Install development dependencies
+uv sync --all-extras
+
+# Activate the virtual environment
+source .venv/bin/activate
+```
+
+---
+
+## Your First State Machine
+
+Let's create a simple state machine that toggles an output based on an input.
+
+```python
+from nortl import Engine, Const
+
+# Create an engine with a module name -- Clock and reset signal is automatically included
+engine = Engine("my_first_engine")
+
+# Define input and output signals
+enable = engine.define_input("enable", width=1)
+output = engine.define_output("output", width=1, reset_value=0)
+
+# Don't define states -- define behavior!
+with engine.while_loop(Const(1)):
+    engine.wait_for(enable == 1)
+    engine.set(output, 1)
+    engine.sync() # Wait one clock cycle
+    engine.set(output, 0)
+    engine.wait_for(enable == 0)
+
+# Generate SystemVerilog code
+from nortl.renderer import VerilogRenderer
+renderer = VerilogRenderer()
+verilog_code = renderer.render(engine)
+
+print(verilog_code)
+```

nortl-1.4.0/README.md

@@ -0,0 +1,89 @@
+# noRTL - Hardware design beyond register transfer level
+
+**noRTL** (Not-only RTL) is a Python-based code generation framework for designing and implementing hardware description language (HDL) modules, particularly SystemVerilog state machines. It provides a high-level, Pythonic API for describing sets of finite state machines (FSMs) and hardware components with built-in correctness guarantees.
+
+**noRTL** aims to make the design of complex digital systems easier by reducing the shortcommings of current hardware description languages that use the register transfer level (RTL) to model digital circuit's behavior. This tool goes beyond this level of abstraction: We digital designers want to describe behavior with cycle-level accuracy but do not want do deal with the complexity of state naming, state coding, starting parallel processes, etc. **noRTL** realizes this tedious part of digital design inside its core.
+
+The code that is written for **noRTL** is pure Python code. The **noRTL** package realizes state handling and data structure assembly for you while the Python code is executed. **noRTL** can be understood as a fancy generator that assembles state machines and provides the tooling to render it to SystemVerilog and tools for verifying your code.
+
+## Main ideas
+
+**noRTL** is built with the following concepts and ideas.
+
+* Each hardware description is an executable Python program. The hardware structure is assembled during execution. There is no need for static code analysis or parsing.
+* There should be no need to declare states explicitely. The number of states is determined during execution of the code.
+* The behavior description should be easily readable and feel procedural. Control structures should work similar to Python equivalents.
+* Checks and Optimizations are to be done during runtime of the Python code. Post-Optimization has not been necessary (yet).
+
+## Installation
+
+A prerequisite for noRTL is the availablility of icarus Verilog in your path. This can be installed using your system's package manager or using the *oss-cad-suite* (https://github.com/YosysHQ/oss-cad-suite-build)
+
+### Method 1: Using pip (Public Registry)
+
+```bash
+# Install nortl
+pip install nortl
+```
+
+### Method 2: Using uv (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/IMMS-Ilmenau/nortl
+cd nortl
+
+# Install dependencies
+uv sync
+
+# Activate the virtual environment
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+```
+
+### Method 3: Development Installation
+
+For development work, install in editable mode:
+
+```bash
+# Clone the repository
+git clone https://github.com/IMMS-Ilmenau/nortl
+cd nortl
+
+# Install development dependencies
+uv sync --all-extras
+
+# Activate the virtual environment
+source .venv/bin/activate
+```
+
+---
+
+## Your First State Machine
+
+Let's create a simple state machine that toggles an output based on an input.
+
+```python
+from nortl import Engine, Const
+
+# Create an engine with a module name -- Clock and reset signal is automatically included
+engine = Engine("my_first_engine")
+
+# Define input and output signals
+enable = engine.define_input("enable", width=1)
+output = engine.define_output("output", width=1, reset_value=0)
+
+# Don't define states -- define behavior!
+with engine.while_loop(Const(1)):
+    engine.wait_for(enable == 1)
+    engine.set(output, 1)
+    engine.sync() # Wait one clock cycle
+    engine.set(output, 0)
+    engine.wait_for(enable == 0)
+
+# Generate SystemVerilog code
+from nortl.renderer import VerilogRenderer
+renderer = VerilogRenderer()
+verilog_code = renderer.render(engine)
+
+print(verilog_code)
+```

nortl-1.4.0/docs/scripts/gen_ref_pages.py

@@ -0,0 +1,70 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+from typing import Sequence
+
+import mkdocs_gen_files
+
+INIT_TEMPLATE = """
+::: {identifier}
+    options:
+        members: [{members}]
+        members_order: alphabetical
+"""
+
+
+def find_submodules(dir: Path) -> Sequence[str]:
+    """Find submodules within a directory."""
+    submodules = []
+    for path in dir.iterdir():
+        if path.is_dir():
+            if (path / '__init__.py').exists():
+                submodules.append(path.name)
+        elif path.suffix == '.py' and path.stem != '__init__':
+            submodules.append(path.stem)
+    return sorted(submodules)
+
+
+def gen_ref_pages():
+    nav = mkdocs_gen_files.Nav()
+    mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+    root = Path(__file__).parent.parent.parent
+    src = root / 'src'
+
+    for path in sorted(src.rglob('*.py')):
+        # Skip Python files that are not in a module
+        if not (path.parent / '__init__.py').exists():
+            continue
+
+        module_path = path.relative_to(src).with_suffix('')
+        doc_path = path.relative_to(src).with_suffix('.md')
+        full_doc_path = Path('reference', doc_path)
+
+        parts = tuple(module_path.parts)
+
+        if is_init := parts[-1] == '__init__':
+            parts = parts[:-1]
+            doc_path = doc_path.with_name('index.md')
+            full_doc_path = full_doc_path.with_name('index.md')
+        elif parts[-1] == '__main__':
+            continue
+
+        nav_parts = [f'{mod_symbol} {part}' for part in parts]
+        nav[tuple(nav_parts)] = doc_path.as_posix()
+
+        with mkdocs_gen_files.open(full_doc_path, 'w') as fd:
+            identifier = '.'.join(parts)
+            if is_init:
+                text = INIT_TEMPLATE.format(identifier=identifier, members=','.join(find_submodules(path.parent)))
+            else:
+                text = f'::: {identifier}\n'
+            print(text, file=fd)
+
+        mkdocs_gen_files.set_edit_path(full_doc_path, Path('../../') / path.relative_to(root))
+
+    with mkdocs_gen_files.open('reference/summary.nav', 'w') as nav_file:
+        nav_file.writelines(nav.build_literate_nav())
+
+
+gen_ref_pages()