Merge branch 'amaranth-lang:main' into main

Author: slagernate

.coveragerc

@@ -3,7 +3,7 @@ branch = True
 include =
   amaranth/*
 omit =
-  amaranth/test/*
+  tests/*
 
 [report]
 exclude_lines =

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+end_of_line = lf
+indent_style = space
+indent_size = 4
+max_line_length = 100
+trim_trailing_whitespace = true
+insert_final_newline = true

.github/workflows/main.yaml

@@ -24,15 +24,15 @@ jobs:
         include:
         - python-version: '3.13-dev'
           allow-failure: true
-    continue-on-error: '${{ matrix.allow-failure }}'
+    continue-on-error: ${{ matrix.allow-failure }}
     name: 'test (${{ matrix.python-version }})'
     steps:
     - name: Check out source code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
     - name: Set up PDM
-      uses: pdm-project/setup-pdm@v3
+      uses: pdm-project/setup-pdm@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -41,10 +41,10 @@ jobs:
         sudo add-apt-repository 'deb http://ppa.launchpad.net/sri-csl/formal-methods/ubuntu bionic main'
         sudo apt-get update
         sudo apt-get install yices2
-        pip install codecov
+        pip install codecov build
         pdm install --dev
     - name: Cache YoWASP build products
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: ~/.cache/YoWASP
         key: YoWASP-${{ runner.os }}-${{ hashFiles('./.venv/**/*.wasm') }}
@@ -54,21 +54,65 @@ jobs:
       run: |
         pdm run test
     - name: Submit code coverage
-      run:
+      run: |
         codecov
 
+  smoketest: # If we plug this into downstream projects, does magic smoke escape?
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project:
+          - amaranth-lang/amaranth-boards
+          - amaranth-lang/amaranth-stdio
+          - amaranth-lang/amaranth-soc
+    name: 'smoke (${{ matrix.project }})'
+    steps:
+    - name: Check out Amaranth source code
+      uses: actions/checkout@v4
+      with:
+        path: amaranth
+        fetch-depth: 0
+    - name: Check out source code
+      uses: actions/checkout@v4
+      with:
+        repository: ${{ matrix.project }}
+        path: project
+        fetch-depth: 0
+    - name: Set up PDM
+      uses: pdm-project/setup-pdm@v4
+    - name: Install dependencies
+      working-directory: project
+      run: |
+        pdm install --dev
+    - name: Use Amaranth HEAD revision
+      working-directory: project
+      run: |
+        pdm add ../amaranth
+    - name: Cache YoWASP build products
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/YoWASP
+        key: YoWASP-${{ runner.os }}-${{ hashFiles('./.venv/**/*.wasm') }}
+        restore-keys: |
+          YoWASP-${{ runner.os }}-
+    - name: Run tests
+      working-directory: project
+      run: |
+        pdm run test
+
   document:
     runs-on: ubuntu-latest
     steps:
       - name: Check out source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Fetch tags from upstream repository
         run: |
           git fetch --tags https://github.com/amaranth-lang/amaranth.git
       - name: Set up PDM
-        uses: pdm-project/setup-pdm@v3
+        uses: pdm-project/setup-pdm@v4
         with:
           python-version: '3.12'
       - name: Install dependencies
@@ -78,36 +122,52 @@ jobs:
         run: |
           pdm run document
       - name: Upload documentation archive
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: docs
           path: docs/_build
 
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v4
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: |
+          pdm install --dev
+      - name: Check links in documentation
+        run: |
+          pdm run document-linkcheck
+
   required: # group all required workflows into one to avoid reconfiguring this in Actions settings
     needs:
       - test
       - document
-    if: always() && !contains(needs.*.result, 'cancelled')
+    if: ${{ always() && !contains(needs.*.result, 'cancelled') }}
     runs-on: ubuntu-latest
     steps:
       - run: ${{ contains(needs.*.result, 'failure') && 'false' || 'true' }}
 
   publish-docs:
     needs: document
-    if: github.repository == 'amaranth-lang/amaranth'
+    if: ${{ github.repository == 'amaranth-lang/amaranth' }}
     runs-on: ubuntu-latest
     steps:
       - name: Check out source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Download documentation archive
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: docs
           path: docs/
       - name: Publish development documentation
-        if: github.event_name == 'push' && github.event.ref == 'refs/heads/main'
+        if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
         uses: JamesIves/github-pages-deploy-action@releases/v4
         with:
           repository-name: amaranth-lang/amaranth-lang.github.io
@@ -116,7 +176,7 @@ jobs:
           folder: docs/
           target-folder: docs/amaranth/latest/
       - name: Publish release documentation
-        if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
+        if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') }}
         uses: JamesIves/github-pages-deploy-action@releases/v4
         with:
           repository-name: amaranth-lang/amaranth-lang.github.io
@@ -127,15 +187,15 @@ jobs:
 
   publish-docs-dev:
     needs: document
-    if: github.repository != 'amaranth-lang/amaranth'
+    if: ${{ github.repository != 'amaranth-lang/amaranth' }}
     runs-on: ubuntu-latest
     steps:
       - name: Check out source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Download documentation archive
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: docs
           path: pages/docs/${{ github.ref_name }}/
@@ -147,3 +207,57 @@ jobs:
         with:
           folder: pages/
           clean: false
+
+  publish-package:
+    needs: required
+    runs-on: ubuntu-latest
+    environment: publish
+    permissions:
+      id-token: write
+    steps:
+    - name: Check out source code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Build package
+      run: |
+        pip install build
+        python -m build
+    - name: Upload package artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: package
+        path: dist/
+    - name: Verify package metadata
+      run: |
+        pip install twine
+        twine check dist/*
+    - name: Publish package to Test PyPI
+      if: ${{ github.repository == 'amaranth-lang/amaranth' && github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+    - name: Publish package to PyPI
+      if: ${{ github.repository == 'amaranth-lang/amaranth' && github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/') }}
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-release:
+    needs: publish-package
+    if: ${{ github.repository == 'amaranth-lang/amaranth' && github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - name: Determine release metadata
+      id: metadata
+      env:
+        REF_NAME: ${{ github.ref_name }}
+      run: |
+        echo name=${REF_NAME/v/} >>$GITHUB_OUTPUT
+    - name: Create release
+      uses: comnoco/create-release-action@v2
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ github.ref_name }}
+        release_name: ${{ steps.metadata.outputs.name }}

CONTRIBUTING.txt

@@ -4,6 +4,9 @@ We love contributions from the community. Please send pull requests and raise
 issues! All code submissions require review. We use GitHub pull requests for
 this purpose.
 
+See the "Contributing" section of the documentation manual for more details
+about contributing to Amaranth.
+
 
 COPYRIGHTS and LICENSE
 

README.md

@@ -22,19 +22,27 @@ See the [Introduction](https://amaranth-lang.org/docs/amaranth/latest/intro.html
 
 See the [Installation](https://amaranth-lang.org/docs/amaranth/latest/install.html) section of the documentation.
 
-## Supported devices
+## Usage
+
+See the [Language guide](https://amaranth-lang.org/docs/amaranth/latest/guide.html) section of the documentation.
+
+## Platform support
 
 Amaranth can be used to target any FPGA or ASIC process that accepts behavioral Verilog-2001 as input. It also offers extended support for many FPGA families, providing toolchain integration, abstractions for device-specific primitives, and more. Specifically:
 
   * Lattice iCE40 (toolchains: **Yosys+nextpnr**, LSE-iCECube2, Synplify-iCECube2);
   * Lattice MachXO2 (toolchains: Diamond);
   * Lattice MachXO3L (toolchains: Diamond);
   * Lattice ECP5 (toolchains: **Yosys+nextpnr**, Diamond);
-  * Xilinx Spartan 3A (toolchains: ISE);
-  * Xilinx Spartan 6 (toolchains: ISE);
-  * Xilinx 7-series (toolchains: Vivado);
-  * Xilinx UltraScale (toolchains: Vivado);
-  * Intel (toolchains: Quartus);
+  * Lattice Nexus (toolchains: **Yosys+nextpnr**, Diamond);
+  * AMD Virtex, Virtex E, Spartan 2, Spartan 2E (toolchains: ISE);
+  * AMD Virtex II, Virtex II Pro (toolchains: ISE);
+  * AMD Spartan 3, Spartan 3E, Spartan 3A, Spartan 3AN, Spartan 3A DSP (toolchains: ISE);
+  * AMD Virtex 4, Virtex 5, Virtex 6 (toolchains: ISE);
+  * AMD Spartan 6 (toolchains: ISE);
+  * AMD 7-series (toolchains: Vivado, ISE);
+  * AMD UltraScale, UltraScale+ (toolchains: Vivado);
+  * Altera (toolchains: Quartus);
   * Quicklogic EOS S3 (toolchains: **Yosys+VPR**).
 
 FOSS toolchains are listed in **bold**.
@@ -47,4 +55,4 @@ Amaranth has a dedicated IRC channel, [#amaranth-lang at libera.chat](https://we
 
 ## License
 
-Amaranth is released under the very permissive [two-clause BSD license](LICENSE.txt). Under the terms of this license, you are authorized to use Amaranth for closed-source proprietary designs.
+Amaranth is released under the [two-clause BSD license](LICENSE.txt). You are permitted to use Amaranth for open-source and proprietary designs provided that the copyright notice in the license file is reproduced.

amaranth/__init__.py

@@ -12,10 +12,11 @@
 
 from .hdl import *
 
-
+# must be kept in sync with docs/reference.rst!
 __all__ = [
     "Shape", "unsigned", "signed",
-    "Value", "Const", "C", "Mux", "Cat", "Repl", "Array", "Signal", "ClockSignal", "ResetSignal",
+    "Value", "Const", "C", "Mux", "Cat", "Array", "Signal", "ClockSignal", "ResetSignal",
+    "Format", "Print", "Assert",
     "Module",
     "ClockDomain",
     "Elaboratable", "Fragment", "Instance",

amaranth/_toolchain/yosys.py

@@ -120,8 +120,8 @@ def available(cls):
     @classmethod
     def version(cls):
         version = importlib_metadata.version(cls.YOSYS_PACKAGE)
-        match = re.match(r"^(\d+)\.(\d+)(?:\.post(\d+))?", version)
-        return (int(match[1]), int(match[2]), int(match[3] or 0))
+        match = re.match(r"^(\d+)\.(\d+)\.(?:\d+)(?:\.(\d+))?(?:\.post(\d+))?", version)
+        return (int(match[1]), int(match[2]), int(match[3] or 0), int(match[4] or 0))
 
     @classmethod
     def data_dir(cls):
@@ -177,6 +177,47 @@ def run(cls, args, stdin="", *, ignore_warnings=False, src_loc_at=0):
         return cls._process_result(popen.returncode, stdout, stderr, ignore_warnings, src_loc_at)
 
 
+class _JavaScriptYosys(YosysBinary):
+    """
+    This toolchain proxy is compatible with Pyodide_. The JavaScript environment must include
+    the following function:
+
+    .. code::
+
+        runAmaranthYosys(args: string[], stdin: string): (exit_code: int, stdout: string, stderr: string);
+
+    .. _Pyodide: https://pyodide.org/
+    """
+
+    @classmethod
+    def available(cls):
+        try:
+            return hasattr(__import__("js"), "runAmaranthYosys")
+        except ImportError:
+            return False
+
+    @classmethod
+    def version(cls):
+        version = cls.run(["-V"])
+        match = re.match(r"^Yosys (\d+)\.(\d+)(?:\+(\d+))?", version)
+        if match:
+            return (int(match[1]), int(match[2]), int(match[3] or 0))
+        else:
+            return None
+
+    @classmethod
+    def data_dir(cls):
+        # Not yet clear how this could work in a design with Wasm components. Most likely,
+        # the component would have to export its filesystem wholesale, and this method would
+        # return some kind of non-filesystem path-like object.
+        raise NotImplementedError
+
+    @classmethod
+    def run(cls, args, stdin="", *, ignore_warnings=False, src_loc_at=0):
+        exit_code, stdout, stderr = __import__("js").runAmaranthYosys(args, stdin)
+        return cls._process_result(exit_code, stdout, stderr, ignore_warnings, src_loc_at)
+
+
 def find_yosys(requirement):
     """Find an available Yosys executable of required version.
 
@@ -202,6 +243,8 @@ def find_yosys(requirement):
             proxies.append(_BuiltinYosys)
         elif clause == "system":
             proxies.append(_SystemYosys)
+        elif clause == "javascript":
+            proxies.append(_JavaScriptYosys)
         else:
             raise YosysError("The AMARANTH_USE_YOSYS environment variable contains "
                              "an unrecognized clause {!r}"