diff --git a/.github/workflows/Pipeline.yml b/.github/workflows/Pipeline.yml index 5ce60eb..7321b92 100644 --- a/.github/workflows/Pipeline.yml +++ b/.github/workflows/Pipeline.yml @@ -7,7 +7,18 @@ on: schedule: - cron: '0 15 * * *' +permissions: + contents: read + pages: write + id-token: write + jobs: + Prepare: + uses: pyTooling/Actions/.github/workflows/PrepareJob.yml@r7 + with: + main_branch: 'main' + release_branch: 'main' + NVC: name: ${{ matrix.icon }}${{ matrix.name }} - NVC runs-on: ${{ matrix.image }} @@ -25,7 +36,7 @@ jobs: steps: - name: ⏬ Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v6 with: submodules: recursive @@ -65,9 +76,9 @@ jobs: cat temp/*.xml - name: '📤 Upload artifact: logs' - uses: actions/upload-artifact@v4 + uses: pyTooling/upload-artifact@v7 with: - name: junit-${{ matrix.name }}-nvc + name: Interfaces-NVC-XML-${{ matrix.name }} include-hidden-files: true path: | temp/*.xml @@ -75,12 +86,91 @@ jobs: retention-days: 1 PublishTestResults: - uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@r5 + uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@r7 needs: - NVC with: - unittest_artifacts_pattern: "junit-*" + unittest_artifacts_pattern: "Interfaces-NVC-XML-*" testsuite-summary-name: "Interfaces" + additional_merge_args: '"--pytest=reduce-depth:Interfaces" --render=tree' + merged_junit_artifact: 'Interfaces-Report-XML' dorny: true # codecov: true +# secrets: +# CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + + IntermediateCleanUp: + uses: pyTooling/Actions/.github/workflows/CleanupArtifacts.yml@r7 + needs: + - PublishTestResults + with: + others: | + Interfaces-NVC-XML-* + + Documentation: + uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r7 + needs: + - PublishTestResults +# if: success() || failure() + with: + requirements: '-r doc/requirements.txt' + doc_directory: 'doc' + unittest_xml_artifact: 'Interfaces-Report-XML' + html_artifact: 'Interfaces-HTML' + latex_artifact: 'Interfaces-LaTeX' + + PDFDocumentation: + uses: pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml@r7 + needs: + - Documentation + if: (success() || failure()) && needs.Documentation.result == 'success' + with: + document: 'Interfaces' + latex_artifact: 'Interfaces-LaTeX' + pdf_artifact: 'Interfaces-PDF' + can-fail: 'true' + + PublishToGitHubPages: + uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r7 + needs: + - NVC + - Documentation +# if: (success() || failure()) && needs.Documentation.result == 'success' + with: + doc: 'Interfaces-HTML' +# coverage: 'Interfaces-Coverage-HTML' + + AutoTag: + uses: pyTooling/Actions/.github/workflows/TagReleaseCommit.yml@r7 + needs: + - Prepare + - PublishToGitHubPages + if: needs.Prepare.outputs.is_release_commit == 'true' && github.event_name != 'schedule' + permissions: + contents: write # required for create tag + actions: write # required for trigger workflow + with: + version: ${{ needs.Prepare.outputs.version }} + auto_tag: ${{ needs.Prepare.outputs.is_release_commit }} + + Release: + uses: pyTooling/Actions/.github/workflows/PublishReleaseNotes.yml@r7 + needs: + - Prepare + - PublishToGitHubPages + if: needs.Prepare.outputs.is_release_tag == 'true' + permissions: + contents: write + actions: write + with: + prerelease: true + replacements: | + version=${{ needs.Prepare.outputs.version }} + tag: ${{ needs.Prepare.outputs.version }} + description: | + # Interfaces %version% + inventory-json: "inventory.json" + inventory-version: ${{ needs.Prepare.outputs.version }} + assets: | + secrets: inherit diff --git a/AMBA/AXI/v4/AXI4.vhdl b/AMBA/AXI/v4/AXI4.vhdl index 8b521f4..4e32d0e 100644 --- a/AMBA/AXI/v4/AXI4.vhdl +++ b/AMBA/AXI/v4/AXI4.vhdl @@ -11,7 +11,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -176,5 +176,4 @@ package Axi4 is ReadData : view Axi4_ReadData_ManagerView; end view; alias Axi4_SubordinateView is Axi4_ManagerView'converse; - end package; diff --git a/AMBA/AXI/v4/AXI4Common.vhdl b/AMBA/AXI/v4/AXI4Common.vhdl index 8f4caa4..09a4211 100644 --- a/AMBA/AXI/v4/AXI4Common.vhdl +++ b/AMBA/AXI/v4/AXI4Common.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -88,5 +88,4 @@ package Axi4Common is Clock : std_ulogic; Reset : std_ulogic; end record; - end package; diff --git a/AMBA/AXI/v4/AXI4Lite.presized.vhdl b/AMBA/AXI/v4/AXI4Lite.presized.vhdl index a2f957d..ac8924d 100644 --- a/AMBA/AXI/v4/AXI4Lite.presized.vhdl +++ b/AMBA/AXI/v4/AXI4Lite.presized.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. diff --git a/AMBA/AXI/v4/AXI4Lite.vhdl b/AMBA/AXI/v4/AXI4Lite.vhdl index 38fb10f..6d53a44 100644 --- a/AMBA/AXI/v4/AXI4Lite.vhdl +++ b/AMBA/AXI/v4/AXI4Lite.vhdl @@ -11,7 +11,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. diff --git a/AMBA/AXI/v4/AXI4Lite_Generic.vhdl b/AMBA/AXI/v4/AXI4Lite_Generic.vhdl index a66632d..0f562ab 100644 --- a/AMBA/AXI/v4/AXI4Lite_Generic.vhdl +++ b/AMBA/AXI/v4/AXI4Lite_Generic.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. diff --git a/AMBA/AXI/v4/AXI4Stream.vhdl b/AMBA/AXI/v4/AXI4Stream.vhdl index 30c67cb..26861ee 100644 --- a/AMBA/AXI/v4/AXI4Stream.vhdl +++ b/AMBA/AXI/v4/AXI4Stream.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. diff --git a/AMBA/AXI/v4/AXI4Stream_Generic.vhdl b/AMBA/AXI/v4/AXI4Stream_Generic.vhdl index a5a5d51..fa7b735 100644 --- a/AMBA/AXI/v4/AXI4Stream_Generic.vhdl +++ b/AMBA/AXI/v4/AXI4Stream_Generic.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -41,5 +41,4 @@ package Axi4Stream_Generic is Keep(KEEP_BITS - 1 downto 0), User(USER_BITS - 1 downto 0) ); - end package; diff --git a/AMBA/AXI/v4/AXI4_Generic.vhdl b/AMBA/AXI/v4/AXI4_Generic.vhdl index 8b4689f..410379f 100644 --- a/AMBA/AXI/v4/AXI4_Generic.vhdl +++ b/AMBA/AXI/v4/AXI4_Generic.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. diff --git a/Avalon/v1/AvalonCommon.vhdl b/Avalon/v1/AvalonCommon.vhdl index 0beae7d..587a9ba 100644 --- a/Avalon/v1/AvalonCommon.vhdl +++ b/Avalon/v1/AvalonCommon.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -32,9 +32,9 @@ use IEEE.numeric_std.all; package AvalonCommon is -- Common types subtype Data_Type is std_ulogic_vector; - subtype Address_Type is unsigned; + subtype Address_Type is unresolved_unsigned; subtype ByteEnable_Type is std_ulogic_vector; - subtype BurstCount_Type is unsigned; + subtype BurstCount_Type is unresolved_unsigned; -- Avalon-MM Response subtype Response_Type is std_ulogic_vector(1 downto 0); @@ -47,5 +47,4 @@ package AvalonCommon is Clock : std_ulogic; Reset : std_ulogic; end record; - end package; diff --git a/Avalon/v1/AvalonMM.vhdl b/Avalon/v1/AvalonMM.vhdl index d911ae6..6e6dcc0 100644 --- a/Avalon/v1/AvalonMM.vhdl +++ b/Avalon/v1/AvalonMM.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -40,22 +40,22 @@ package AvalonMM is Write : std_ulogic; -- Write request WriteData : Data_Type; -- Write data ByteEnable : ByteEnable_Type; -- Byte enable - + -- Slave signals ReadData : Data_Type; -- Read data ReadDataValid : std_ulogic; -- Read data valid WaitRequest : std_ulogic; -- Wait request Response : Response_Type; -- Response - + -- Optional burst signals BurstCount : BurstCount_Type; -- Burst count - + -- Optional pipelining signals WriteResponseValid : std_ulogic; -- Write response valid - + -- Optional lock signal Lock : std_ulogic; -- Lock - + -- Optional debug signals DebugAccess : std_ulogic; -- Debug access end record; @@ -72,7 +72,7 @@ package AvalonMM is BurstCount : out; Lock : out; DebugAccess : out; - + -- Master inputs ReadData : in; ReadDataValid : in; @@ -81,5 +81,4 @@ package AvalonMM is WriteResponseValid : in; end view; alias AvalonMM_SlaveView is AvalonMM_MasterView'converse; - end package; diff --git a/Avalon/v1/AvalonMM_Generic.vhdl b/Avalon/v1/AvalonMM_Generic.vhdl index b046b3f..821aedc 100644 --- a/Avalon/v1/AvalonMM_Generic.vhdl +++ b/Avalon/v1/AvalonMM_Generic.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -52,5 +52,4 @@ package AvalonMM_Generic is ByteEnable(BYTEENABLE_BITS - 1 downto 0), BurstCount(BURSTCOUNT_BITS - 1 downto 0) ); - end package; diff --git a/Avalon/v1/AvalonMM_Minimal.vhdl b/Avalon/v1/AvalonMM_Minimal.vhdl index 80aef75..e9d96f8 100644 --- a/Avalon/v1/AvalonMM_Minimal.vhdl +++ b/Avalon/v1/AvalonMM_Minimal.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -40,7 +40,7 @@ package AvalonMM_Minimal is Write : std_ulogic; WriteData : Data_Type; ByteEnable : ByteEnable_Type; - + -- Slave signals ReadData : Data_Type; WaitRequest : std_ulogic; @@ -55,11 +55,10 @@ package AvalonMM_Minimal is Write : out; WriteData : out; ByteEnable : out; - + -- Master inputs (slave outputs) ReadData : in; WaitRequest : in; end view; alias AvalonMM_Minimal_SlaveView is AvalonMM_Minimal_MasterView'converse; - end package; diff --git a/Avalon/v1/AvalonMM_Minimal_Generic.vhdl b/Avalon/v1/AvalonMM_Minimal_Generic.vhdl index c178b27..d85519e 100644 --- a/Avalon/v1/AvalonMM_Minimal_Generic.vhdl +++ b/Avalon/v1/AvalonMM_Minimal_Generic.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -49,5 +49,4 @@ package AvalonMM_Minimal_Generic is ReadData(DATA_BITS - 1 downto 0), ByteEnable(BYTEENABLE_BITS - 1 downto 0) ); - end package; diff --git a/Avalon/v1/AvalonST.vhdl b/Avalon/v1/AvalonST.vhdl index 137bef5..731f78a 100644 --- a/Avalon/v1/AvalonST.vhdl +++ b/Avalon/v1/AvalonST.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -37,18 +37,18 @@ package AvalonST is -- Handshake signals Valid : std_ulogic; -- Valid Ready : std_ulogic; -- Ready - + -- Payload signals Data : Data_Type; -- Data - + -- Packet signals StartOfPacket : std_ulogic; -- Start of packet EndOfPacket : std_ulogic; -- End of packet Empty : std_ulogic_vector; -- Empty (number of empty symbols) - + -- Error signal Error : std_ulogic_vector; -- Error - + -- Channel signal Channel : std_ulogic_vector; -- Channel end record; @@ -64,10 +64,9 @@ package AvalonST is Empty : out; Error : out; Channel : out; - + -- Source inputs (sink outputs) Ready : in; end view; alias AvalonST_SinkView is AvalonST_SourceView'converse; - end package; diff --git a/Avalon/v1/AvalonST_Generic.vhdl b/Avalon/v1/AvalonST_Generic.vhdl index 63ea3e6..9d91168 100644 --- a/Avalon/v1/AvalonST_Generic.vhdl +++ b/Avalon/v1/AvalonST_Generic.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -49,5 +49,4 @@ package AvalonST_Generic is Error(ERROR_BITS - 1 downto 0), Channel(CHANNEL_BITS - 1 downto 0) ); - end package; diff --git a/Avalon/v1/AvalonST_Minimal.vhdl b/Avalon/v1/AvalonST_Minimal.vhdl index c3b70b7..c37958f 100644 --- a/Avalon/v1/AvalonST_Minimal.vhdl +++ b/Avalon/v1/AvalonST_Minimal.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -37,7 +37,7 @@ package AvalonST_Minimal is -- Source signals Data : Data_Type; Valid : std_ulogic; - + -- Sink signals Ready : std_ulogic; end record; @@ -48,10 +48,9 @@ package AvalonST_Minimal is -- Source outputs Data : out; Valid : out; - + -- Source inputs (sink outputs) Ready : in; end view; alias AvalonST_Minimal_SinkView is AvalonST_Minimal_SourceView'converse; - end package; diff --git a/Avalon/v1/AvalonST_Minimal_Generic.vhdl b/Avalon/v1/AvalonST_Minimal_Generic.vhdl index 315e771..c3fe6b3 100644 --- a/Avalon/v1/AvalonST_Minimal_Generic.vhdl +++ b/Avalon/v1/AvalonST_Minimal_Generic.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2025-2025 Open Source VHDL Group +-- Copyright 2025-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -40,5 +40,4 @@ package AvalonST_Minimal_Generic is subtype AvalonST_Minimal_SizedInterface_Vector is AvalonST_Minimal_Interface_Vector(open)( Data(DATA_BITS - 1 downto 0) ); - end package; diff --git a/IO/Common.vhdl b/IO/Common.vhdl index f4d229f..9f5e1f3 100644 --- a/IO/Common.vhdl +++ b/IO/Common.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -77,5 +77,4 @@ package Common is T : out; end view; alias Tristate_InView is Tristate_OutView'converse; - end package; diff --git a/IO/I2C.vhdl b/IO/I2C.vhdl index 008b61a..0f7a5ee 100644 --- a/IO/I2C.vhdl +++ b/IO/I2C.vhdl @@ -17,7 +17,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -66,5 +66,4 @@ package I2C is SDA : view Tristate_OutView; end view; alias I2C_IOBView is I2C_ControllerView'converse; - end package; diff --git a/IO/I2S.vhdl b/IO/I2S.vhdl index a80fdcc..ca7fcd9 100644 --- a/IO/I2S.vhdl +++ b/IO/I2S.vhdl @@ -13,7 +13,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -56,5 +56,4 @@ package I2S is SD : out; end view; alias I2S_DestSync_ReceiverView is I2S_DestSync_TransmitterView'converse; - end package; diff --git a/IO/JTAG.vhdl b/IO/JTAG.vhdl index 54980ee..7f0022c 100644 --- a/IO/JTAG.vhdl +++ b/IO/JTAG.vhdl @@ -15,7 +15,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -56,5 +56,4 @@ package JTAG is TDO : out; end view; alias JTAG_TesterView is JTAG_DeviceView'converse; - end package; diff --git a/IO/SPI.vhdl b/IO/SPI.vhdl index ce707ca..7395173 100644 --- a/IO/SPI.vhdl +++ b/IO/SPI.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -49,5 +49,4 @@ package SPI is SS_n : out; end view; alias SPI_SlaveView is SPI_MasterView'converse; - end package; diff --git a/IO/UART.vhdl b/IO/UART.vhdl index 9d69e89..f1b6d9d 100644 --- a/IO/UART.vhdl +++ b/IO/UART.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -43,5 +43,4 @@ package UART is RX : in; end view; alias UART_ReceiverView is UART_TransmitterView'converse; - end package; diff --git a/IO/Cages.vhdl b/Network/Cages.vhdl similarity index 98% rename from IO/Cages.vhdl rename to Network/Cages.vhdl index d16c9b1..3b580d0 100644 --- a/IO/Cages.vhdl +++ b/Network/Cages.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -94,5 +94,4 @@ package Cages is RX : view ( Differatial_InView ); end view; alias QSFP_CageView is QSFP_IcView'converse; - end package; diff --git a/IO/Ethernet.vhdl b/Network/Ethernet.vhdl similarity index 99% rename from IO/Ethernet.vhdl rename to Network/Ethernet.vhdl index 034ecea..024a229 100644 --- a/IO/Ethernet.vhdl +++ b/Network/Ethernet.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -173,5 +173,4 @@ package Ethernet is -- XAUI -- 4 lanes á 3.125 Gbps - end package; diff --git a/PoC/CSE.vhdl b/PoC/CSE.vhdl index 19b30f5..e71770a 100644 --- a/PoC/CSE.vhdl +++ b/PoC/CSE.vhdl @@ -10,7 +10,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -45,5 +45,4 @@ package CSE is Error : in; end view; alias CSE_InView is CSE_OutView'converse; - end package; diff --git a/README.md b/README.md index 4c7d800..8ec3620 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,36 @@ +[![Sourcecode on GitHub](https://img.shields.io/badge/VHDL-Interfaces-63bf7f?longCache=true&style=flat-square&longCache=true&logo=GitHub)](https://GitHub.com/VHDL/Interfaces) +[![Sourcecode License](https://img.shields.io/badge/code-Apache--2.0-green?longCache=true&style=flat-square&logo=Apache&logoColor=fff)](LICENSE.md) +[![Documentation](https://img.shields.io/website?longCache=true&style=flat-square&label=vhdl.github.io%2FInterfaces&logo=GitHub&logoColor=fff&up_color=blueviolet&up_message=Read%20now%20%E2%9E%9A&url=https%3A%2F%2Fvhdl.github.io%2FInterfaces%2Findex.html)](https://vhdl.github.io/Interfaces/) +[![Documentation License](https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true&style=flat-square&logo=CreativeCommons&logoColor=fff)](doc/Doc-License.rst) +[![GitHub Workflow - Build and Test Status](https://img.shields.io/github/actions/workflow/status/VHDL/Interfaces/Pipeline.yml?branch=main&longCache=true&style=flat-square&label=build%20and%20test&logo=GitHub%20Actions&logoColor=FFFFFF)](https://GitHub.com/VHDL/Interfaces/actions/workflows/Pipeline.yml) + # Interfaces + Interface definitions for VHDL-2019. + + +## Adopters + +* [Paebbels/BigDesign](https://github.com/Paebbels/BigDesign) + + +## Tests + +* VHDL-2019 syntax checked by [NVC](https://github.com/nickg/nvc). + See [test results](https://vhdl.github.io/Interfaces/tests/index.html). + +## Contributors + +* [Patrick Lehmann](https://GitHub.com/Paebbels) (Maintainer) +* [Parham Soltani](https://github.com/parhamsoltani) +* [and more...](https://GitHub.com/VHDL/Interfaces/graphs/contributors) + + +## License + +This VHDL packages (source code) are licensed under [Apache License 2.0](LICENSE.md). +The accompanying documentation is licensed under [Creative Commons - Attribution 4.0 (CC-BY 4.0)](doc/Doc-License.rst). + +------------------------- + +SPDX-License-Identifier: Apache-2.0 diff --git a/MIPI/C-PHY.vhdl b/Video/C-PHY.vhdl similarity index 99% rename from MIPI/C-PHY.vhdl rename to Video/C-PHY.vhdl index e387fca..8cfa4b6 100644 --- a/MIPI/C-PHY.vhdl +++ b/Video/C-PHY.vhdl @@ -47,5 +47,4 @@ package CPHY is type CPHYLane_Interface_Vector is array(natural range <>) of CPHYLane_Interface; - end package; diff --git a/MIPI/D-PHY.vhdl b/Video/D-PHY.vhdl similarity index 100% rename from MIPI/D-PHY.vhdl rename to Video/D-PHY.vhdl diff --git a/MIPI/M-PHY.vhdl b/Video/M-PHY.vhdl similarity index 99% rename from MIPI/M-PHY.vhdl rename to Video/M-PHY.vhdl index 2a4d0c9..5c41b6c 100644 --- a/MIPI/M-PHY.vhdl +++ b/Video/M-PHY.vhdl @@ -42,5 +42,4 @@ package MPHY is RX : view ( Differatial_InView ); end view; alias Differatial_InView is Differatial_OutView'converse; - end package; diff --git a/Video/VGA.vhdl b/Video/VGA.vhdl index 52c24f5..bbff113 100644 --- a/Video/VGA.vhdl +++ b/Video/VGA.vhdl @@ -12,7 +12,7 @@ -- -- License: -- ============================================================================= --- Copyright 2016-2025 Open Source VHDL Group +-- Copyright 2016-2026 Open Source VHDL Group -- -- Licensed under the Apache License, Version 2.0 (the "License"); -- you may not use this file except in compliance with the License. @@ -80,5 +80,4 @@ package VGA is alias VGA_ReceiverView is VGA_TransmitterView'converse; type VGA_Interface_Vector is array(natural range <>) of VGA_Interface; - end package; diff --git a/build.pro b/build.pro index d3f6f37..ec032b7 100644 --- a/build.pro +++ b/build.pro @@ -1,5 +1,5 @@ # ==================================================================================================================== # -# Copyright 2016-2025 Open Source VHDL Group # +# Copyright 2016-2026 Open Source VHDL Group # # # # Licensed under the Apache License, Version 2.0 (the "License"); # # you may not use this file except in compliance with the License. # @@ -33,7 +33,19 @@ analyze AMBA/AXI/v4/AXI4Lite.presized.vhdl analyze AMBA/AXI/v4/AXI4Stream.vhdl analyze AMBA/AXI/v4/AXI4Stream_Generic.vhdl +# Avalon interfaces +analyze Avalon/v1/AvalonCommon.vhdl +analyze Avalon/v1/AvalonMM.vhdl +analyze Avalon/v1/AvalonMM_Generic.vhdl +analyze Avalon/v1/AvalonMM_Minimal.vhdl +analyze Avalon/v1/AvalonMM_Minimal_Generic.vhdl +analyze Avalon/v1/AvalonST.vhdl +analyze Avalon/v1/AvalonST_Generic.vhdl +analyze Avalon/v1/AvalonST_Minimal.vhdl +analyze Avalon/v1/AvalonST_Minimal_Generic.vhdl + # Low-speed interfaces +#analyze IO/BiSS.vhdl analyze IO/I2C.vhdl analyze IO/SPI.vhdl analyze IO/I2S.vhdl @@ -41,25 +53,16 @@ analyze IO/JTAG.vhdl analyze IO/UART.vhdl # Ethernet -analyze IO/Ethernet.vhdl -analyze IO/Cages.vhdl - -# Video interfaces -analyze Video/VGA.vhdl -analyze MIPI/C-PHY.vhdl -analyze MIPI/D-PHY.vhdl -analyze MIPI/M-PHY.vhdl +analyze Network/Ethernet.vhdl +analyze Network/Cages.vhdl # Miscellaneous interfaces analyze PoC/CSE.vhdl -# Avalon interfaces -analyze Avalon/v1/AvalonCommon.vhdl -analyze Avalon/v1/AvalonMM.vhdl -analyze Avalon/v1/AvalonMM_Generic.vhdl -analyze Avalon/v1/AvalonMM_Minimal.vhdl -analyze Avalon/v1/AvalonMM_Minimal_Generic.vhdl -analyze Avalon/v1/AvalonST.vhdl -analyze Avalon/v1/AvalonST_Generic.vhdl -analyze Avalon/v1/AvalonST_Minimal.vhdl -analyze Avalon/v1/AvalonST_Minimal_Generic.vhdl +# Video interfaces +analyze Video/VGA.vhdl +analyze Video/C-PHY.vhdl +analyze Video/D-PHY.vhdl +analyze Video/M-PHY.vhdl + +# WishBone diff --git a/compileorder.list b/compileorder.list index 45c7902..4ddbda1 100644 --- a/compileorder.list +++ b/compileorder.list @@ -1,5 +1,5 @@ # ==================================================================================================================== # -# Copyright 2016-2025 Open Source VHDL Group # +# Copyright 2016-2026 Open Source VHDL Group # # # # Licensed under the Apache License, Version 2.0 (the "License"); # # you may not use this file except in compliance with the License. # @@ -31,7 +31,19 @@ AMBA/AXI/v4/AXI4Lite.presized.vhdl AMBA/AXI/v4/AXI4Stream.vhdl AMBA/AXI/v4/AXI4Stream_Generic.vhdl +# Avalon Memory-Mapped Interfaces +Avalon/v1/AvalonCommon.vhdl +Avalon/v1/AvalonMM.vhdl +Avalon/v1/AvalonMM_Generic.vhdl +Avalon/v1/AvalonMM_Minimal.vhdl +Avalon/v1/AvalonMM_Minimal_Generic.vhdl +Avalon/v1/AvalonST.vhdl +Avalon/v1/AvalonST_Generic.vhdl +Avalon/v1/AvalonST_Minimal.vhdl +Avalon/v1/AvalonST_Minimal_Generic.vhdl + # Low-speed interfaces +#IO/BiSS.vhdl IO/I2C.vhdl IO/SPI.vhdl IO/I2S.vhdl @@ -39,25 +51,16 @@ IO/JTAG.vhdl IO/UART.vhdl # Ethernet -IO/Ethernet.vhdl -IO/Cages.vhdl - -# Video interfaces -Video/VGA.vhdl -MIPI/C-PHY.vhdl -MIPI/D-PHY.vhdl -MIPI/M-PHY.vhdl +Network/Ethernet.vhdl +Network/Cages.vhdl # Miscellaneous interfaces PoC/CSE.vhdl -# Avalon Memory-Mapped Interfaces -Avalon/v1/AvalonCommon.vhdl -Avalon/v1/AvalonMM.vhdl -Avalon/v1/AvalonMM_Generic.vhdl -Avalon/v1/AvalonMM_Minimal.vhdl -Avalon/v1/AvalonMM_Minimal_Generic.vhdl -Avalon/v1/AvalonST.vhdl -Avalon/v1/AvalonST_Generic.vhdl -Avalon/v1/AvalonST_Minimal.vhdl -Avalon/v1/AvalonST_Minimal_Generic.vhdl +# Video interfaces +Video/VGA.vhdl +Video/C-PHY.vhdl +Video/D-PHY.vhdl +Video/M-PHY.vhdl + +# WishBone diff --git a/doc/AXI.rst b/doc/AXI.rst new file mode 100644 index 0000000..d72c1fe --- /dev/null +++ b/doc/AXI.rst @@ -0,0 +1,44 @@ +.. _AXI4: + +AXI - Advanced eXtensible Interface +################################### + +The *Advanced eXtensible Interface* (AXI) is an on-chip communication bus protocol and is part of the +*Advanced Microcontroller Bus Architecture* specification (AMBA). AXI is royalty-free and its specification is freely +available from ARM. + +:website: `developer.arm.com ⭢ AXI Protocol Overview `__ +:Wikipedia: :wiki:`Advanced_eXtensible_Interface` +:Versions: 3 - 2003 |br| + 4 - 2010 |br| + 5 - 2022 + +.. _AXI4/Full: + +AXI4 (Full) +*********** + +.. literalinclude:: ../AMBA/AXI/v4/AXI4.vhdl + :caption: AXI4.vhdl + :language: VHDL + :tab-width: 2 + +.. _AXI4/Lite: + +AXI4-Lite +********* + +.. todo:: + + AXI4-Lite: To be documented + + +.. _AXI4/Stream: + +AXI4-Stream +*********** + +.. todo:: + + AXI4-Stream: To be documented + diff --git a/doc/Avalon.rst b/doc/Avalon.rst new file mode 100644 index 0000000..8686ffc --- /dev/null +++ b/doc/Avalon.rst @@ -0,0 +1,44 @@ +.. _Avalon: + +Avalon +###### + +:Specification: `docs.altera.com ⭢ Avalon Interface Specifications `__ + +.. _Avalon/MM: + +Avalon-MM +********* + +.. todo:: + + Avalon-MM: To be documented + +.. _Avalon/MM-Minimal: + +Avalon-MM Minimal +***************** + +.. todo:: + + Avalon-MM Minimal: To be documented + + +.. _Avalon/ST: + +Avalon-ST +********* + +.. todo:: + + Avalon-ST: To be documented + + +.. _Avalon/ST-Minimal: + +Avalon-ST Minimal +***************** + +.. todo:: + + Avalon-ST Minimal: To be documented diff --git a/doc/license.rst b/doc/Code-License.rst similarity index 96% rename from doc/license.rst rename to doc/Code-License.rst index 1cd6d4b..fba66a2 100644 --- a/doc/license.rst +++ b/doc/Code-License.rst @@ -1,13 +1,15 @@ -.. _LICENSE: +.. _SRCLICENSE: -.. Note:: This is a local copy of the `Apache License Version 2.0 `_. +.. Note:: This is a local copy of the `Apache License Version 2.0 `__. + +.. Attention:: This **Apache License, 2.0** applies to all **source and configuration files of project**, **except documentation**. Apache License 2.0 ################## Version 2.0, January 2004 -**TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION** +:xlarge:`TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION` 1. Definitions. @@ -115,7 +117,7 @@ incurred by, or claims asserted against, such Contributor by reason of your acce ---------------------------------------------------------------------------------------------------------------------------------------------------------------- -**Appendix: How to apply the Apache License to your work** +:xlarge:`Appendix: How to apply the Apache License to your work` To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or diff --git a/doc/Doc-License.rst b/doc/Doc-License.rst new file mode 100644 index 0000000..ca0c256 --- /dev/null +++ b/doc/Doc-License.rst @@ -0,0 +1,353 @@ +.. _DOCLICENSE: + +.. note:: This is a local copy of the `Creative Commons - Attribution 4.0 International (CC BY 4.0) `__. + +.. attention:: This **CC BY 4.0** license applies only to the **documentation** of this project. + + +Creative Commons Attribution 4.0 International +############################################## + +Creative Commons Corporation (“Creative Commons”) is not a law firm and does not +provide legal services or legal advice. Distribution of Creative Commons public +licenses does not create a lawyer-client or other relationship. Creative Commons +makes its licenses and related information available on an “as-is” basis. +Creative Commons gives no warranties regarding its licenses, any material +licensed under their terms and conditions, or any related information. Creative +Commons disclaims all liability for damages resulting from their use to the +fullest extent possible. + +.. topic:: Using Creative Commons Public Licenses + + Creative Commons public licenses provide a standard set of terms and conditions + that creators and other rights holders may use to share original works of + authorship and other material subject to copyright and certain other rights + specified in the public license below. The following considerations are for + informational purposes only, are not exhaustive, and do not form part of our + licenses. + + * **Considerations for licensors:** Our public licenses are intended for use + by those authorized to give the public permission to use material in ways + otherwise restricted by copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms and conditions + of the license they choose before applying it. Licensors should also secure + all rights necessary before applying our licenses so that the public can reuse + the material as expected. Licensors should clearly mark any material not + subject to the license. This includes other CC-licensed material, or material + used under an exception or limitation to copyright. + `More considerations for licensors `__. + + * **Considerations for the public:** By using one of our public licenses, a + licensor grants the public permission to use the licensed material under + specified terms and conditions. If the licensor’s permission is not necessary + for any reason–for example, because of any applicable exception or limitation + to copyright–then that use is not regulated by the license. Our licenses grant + only permissions under copyright and certain other rights that a licensor has + authority to grant. Use of the licensed material may still be restricted for + other reasons, including because others have copyright or other rights in the + material. A licensor may make special requests, such as asking that all + changes be marked or described. Although not required by our licenses, you are + encouraged to respect those requests where reasonable. + `More considerations for the public `__. + +:xlarge:`Creative Commons Attribution 4.0 International Public License` + +By exercising the Licensed Rights (defined below), You accept and agree to be +bound by the terms and conditions of this Creative Commons Attribution 4.0 +International Public License ("Public License"). To the extent this Public +License may be interpreted as a contract, You are granted the Licensed Rights +in consideration of Your acceptance of these terms and conditions, and the +Licensor grants You such rights in consideration of benefits the Licensor +receives from making the Licensed Material available under these terms and +conditions. + +Section 1 – Definitions. +======================== + +a. **Adapted Material** means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material and in + which the Licensed Material is translated, altered, arranged, transformed, or + otherwise modified in a manner requiring permission under the Copyright and + Similar Rights held by the Licensor. For purposes of this Public License, + where the Licensed Material is a musical work, performance, or sound + recording, Adapted Material is always produced where the Licensed Material + is synched in timed relation with a moving image. + +b. **Adapter's License** means the license You apply to Your Copyright and + Similar Rights in Your contributions to Adapted Material in accordance with + the terms and conditions of this Public License. + +c. **Copyright and Similar Rights** means copyright and/or similar rights + closely related to copyright including, without limitation, performance, + broadcast, sound recording, and Sui Generis Database Rights, without regard + to how the rights are labeled or categorized. For purposes of this Public + License, the rights specified in Section 2(b)(1)-(2) are not Copyright and + Similar Rights. + +d. **Effective Technological Measures** means those measures that, in the + absence of proper authority, may not be circumvented under laws fulfilling + obligations under Article 11 of the WIPO Copyright Treaty adopted on + December 20, 1996, and/or similar international agreements. + +e. **Exceptions and Limitations** means fair use, fair dealing, and/or any + other exception or limitation to Copyright and Similar Rights that applies to + Your use of the Licensed Material. + +f. **Licensed Material** means the artistic or literary work, database, or + other material to which the Licensor applied this Public License. + +g. **Licensed Rights** means the rights granted to You subject to the terms + and conditions of this Public License, which are limited to all Copyright and + Similar Rights that apply to Your use of the Licensed Material and that the + Licensor has authority to license. + +h. **Licensor** means the individual(s) or entity(ies) granting rights under + this Public License. + +i. **Share** means to provide material to the public by any means or process + that requires permission under the Licensed Rights, such as reproduction, + public display, public performance, distribution, dissemination, + communication, or importation, and to make material available to the public + including in ways that members of the public may access the material from a + place and at a time individually chosen by them. + +j. **Sui Generis Database Rights** means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of the + Council of 11 March 1996 on the legal protection of databases, as amended + and/or succeeded, as well as other essentially equivalent rights anywhere + in the world. + +k. **You** means the individual or entity exercising the Licensed Rights + under this Public License. **Your** has a corresponding meaning. + +Section 2 – Scope. +================== + +a. **License grant.** + + 1. Subject to the terms and conditions of this Public License, the Licensor + hereby grants You a worldwide, royalty-free, non-sublicensable, + non-exclusive, irrevocable license to exercise the Licensed Rights in the + Licensed Material to: + + A. reproduce and Share the Licensed Material, in whole or in part; and + + B. produce, reproduce, and Share Adapted Material. + + 2. :underline:`Exceptions and Limitations.` For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public License does not + apply, and You do not need to comply with its terms and conditions. + + 3. :underline:`Term.` The term of this Public License is specified in Section 6(a). + + 4. :underline:`Media and formats`; :underline:`technical modifications allowed.` The Licensor + authorizes You to exercise the Licensed Rights in all media and formats + whether now known or hereafter created, and to make technical + modifications necessary to do so. The Licensor waives and/or agrees not to + assert any right or authority to forbid You from making technical + modifications necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective Technological + Measures. For purposes of this Public License, simply making modifications + authorized by this Section 2(a)(4) never produces Adapted Material. + + 5. :underline:`Downstream recipients.` + + A. :underline:`Offer from the Licensor – Licensed Material.` Every recipient of + the Licensed Material automatically receives an offer from the + Licensor to exercise the Licensed Rights under the terms and + conditions of this Public License. + + B. :underline:`No downstream restrictions.` You may not offer or impose any + additional or different terms or conditions on, or apply any Effective + Technological Measures to, the Licensed Material if doing so restricts + exercise of the Licensed Rights by any recipient of the Licensed + Material. + + 6. :underline:`No endorsement.` Nothing in this Public License constitutes or may + be construed as permission to assert or imply that You are, or that Your + use of the Licensed Material is, connected with, or sponsored, endorsed, + or granted official status by, the Licensor or others designated to + receive attribution as provided in Section 3(a)(1)(A)(i). + +b. **Other rights.** + + 1. Moral rights, such as the right of integrity, are not licensed under this + Public License, nor are publicity, privacy, and/or other similar + personality rights; however, to the extent possible, the Licensor waives + and/or agrees not to assert any such rights held by the Licensor to the + limited extent necessary to allow You to exercise the Licensed Rights, but + not otherwise. + + 2. Patent and trademark rights are not licensed under this Public License. + + 3. To the extent possible, the Licensor waives any right to collect royalties + from You for the exercise of the Licensed Rights, whether directly or + through a collecting society under any voluntary or waivable statutory or + compulsory licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + +Section 3 – License Conditions. +=============================== + +Your exercise of the Licensed Rights is expressly made subject to the following conditions. + +a. **Attribution.** + + 1. If You Share the Licensed Material (including in modified form), You must: + + A. retain the following if it is supplied by the Licensor with the + Licensed Material: + + i. identification of the creator(s) of the Licensed Material and any + others designated to receive attribution, in any reasonable manner + requested by the Licensor (including by pseudonym if designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of warranties; + + v. a URI or hyperlink to the Licensed Material to the extent reasonably + practicable; + + B. indicate if You modified the Licensed Material and retain an + indication of any previous modifications; and + + C. indicate the Licensed Material is licensed under this Public License, + and include the text of, or the URI or hyperlink to, this Public + License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner + based on the medium, means, and context in which You Share the Licensed + Material. For example, it may be reasonable to satisfy the conditions by + providing a URI or hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the information + required by Section 3(a)(1)(A) to the extent reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's License You apply + must not prevent recipients of the Adapted Material from complying with + this Public License. + +Section 4 – Sui Generis Database Rights. +======================================== + +Where the Licensed Rights include Sui Generis Database Rights that apply to Your +use of the Licensed Material: + +a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, + reuse, reproduce, and Share all or a substantial portion of the contents of + the database; + +b. if You include all or a substantial portion of the database contents in a + database in which You have Sui Generis Database Rights, then the database + in which You have Sui Generis Database Rights (but not its individual + contents) is Adapted Material; and + +c. You must comply with the conditions in Section 3(a) if You Share all or a + substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not replace +Your obligations under this Public License where the Licensed Rights include +other Copyright and Similar Rights. + +Section 5 – Disclaimer of Warranties and Limitation of Liability. +================================================================= + +a. **Unless otherwise separately undertaken by the Licensor, to the extent + possible, the Licensor offers the Licensed Material as-is and as-available, + and makes no representations or warranties of any kind concerning the + Licensed Material, whether express, implied, statutory, or other. This + includes, without limitation, warranties of title, merchantability, + fitness for a particular purpose, non-infringement, absence of latent or + other defects, accuracy, or the presence or absence of errors, whether or + not known or discoverable. Where disclaimers of warranties are not allowed + in full or in part, this disclaimer may not apply to You.** + +b. **To the extent possible, in no event will the Licensor be liable to You + on any legal theory (including, without limitation, negligence) or + otherwise for any direct, special, indirect, incidental, consequential, + punitive, exemplary, or other losses, costs, expenses, or damages arising + out of this Public License or use of the Licensed Material, even if the + Licensor has been advised of the possibility of such losses, costs, expenses, + or damages. Where a limitation of liability is not allowed in full or in + part, this limitation may not apply to You.** + +c. The disclaimer of warranties and limitation of liability provided above + shall be interpreted in a manner that, to the extent possible, most + closely approximates an absolute disclaimer and waiver of all liability. + +Section 6 – Term and Termination. +================================= + +a. This Public License applies for the term of the Copyright and Similar Rights + licensed here. However, if You fail to comply with this Public License, then + Your rights under this Public License terminate automatically. + +b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided it is cured + within 30 days of Your discovery of the violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any right the + Licensor may have to seek remedies for Your violations of this Public License. + +c. For the avoidance of doubt, the Licensor may also offer the Licensed Material + under separate terms or conditions or stop distributing the Licensed Material + at any time; however, doing so will not terminate this Public License. + +d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. + +Section 7 – Other Terms and Conditions. +======================================= + +a. The Licensor shall not be bound by any additional or different terms or + conditions communicated by You unless expressly agreed. + +b. Any arrangements, understandings, or agreements regarding the Licensed + Material not stated herein are separate from and independent of the terms + and conditions of this Public License. + +Section 8 – Interpretation. +=========================== + +a. For the avoidance of doubt, this Public License does not, and shall not be + interpreted to, reduce, limit, restrict, or impose conditions on any use of + the Licensed Material that could lawfully be made without permission under + this Public License. + +b. To the extent possible, if any provision of this Public License is deemed + unenforceable, it shall be automatically reformed to the minimum extent + necessary to make it enforceable. If the provision cannot be reformed, it + shall be severed from this Public License without affecting the + enforceability of the remaining terms and conditions. + +c. No term or condition of this Public License will be waived and no failure to + comply consented to unless expressly agreed to by the Licensor. + +d. Nothing in this Public License constitutes or may be interpreted as a + limitation upon, or waiver of, any privileges and immunities that apply to + the Licensor or You, including from the legal processes of any jurisdiction + or authority. + +------------------ + +Creative Commons is not a party to its public licenses. Notwithstanding, +Creative Commons may elect to apply one of its public licenses to material it +publishes and in those instances will be considered the “Licensor.” Except for +the limited purpose of indicating that material is shared under a Creative +Commons public license or as otherwise permitted by the Creative Commons +policies published at `creativecommons.org/policies `__, +Creative Commons does not authorize the use of the trademark “Creative Commons” +or any other trademark or logo of Creative Commons without its prior written +consent including, without limitation, in connection with any unauthorized +modifications to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For the +avoidance of doubt, this paragraph does not form part of the public licenses. + +Creative Commons may be contacted at `creativecommons.org `__ diff --git a/doc/IO.rst b/doc/IO.rst new file mode 100644 index 0000000..6ac15da --- /dev/null +++ b/doc/IO.rst @@ -0,0 +1,76 @@ +.. _IO: + +Low-Speed I/O Interfaces +######################## + +.. _IO/BiSS: + +BiSS - Bidirectional/Serial/Synchronous +*************************************** + +:Website: `biss-interface.com `__ +:Wikipedia: :wiki:`BiSS_interface` + +.. todo:: + + BiSS: To be documented + + +.. _IO/I2C: + +I²C - Inter-Integrated Circuit +****************************** + +:Wikipedia: :wiki:`I2C` + +.. todo:: + + I²C: To be documented + + +.. _IO/I2S: + +I²S - Inter-Integrated Circuit Sound +************************************ + +:Wikipedia: :wiki:`I2S` + +.. todo:: + + I²S: To be documented + + +.. _IO/JTAG: + +JTAG +**** + +:Wikipedia: :wiki:`JTAG` + +.. todo:: + + JTAG: To be documented + + +.. _IO/SPI: + +SPI - Serial Peripheral Interface +********************************* + +:Wikipedia: :wiki:`Serial_Peripheral_Interface` + +.. todo:: + + SPI: To be documented + + +.. _IO/UART: + +UART - universal asynchronous receiver-transmitter +************************************************** + +:Wikipedia: :wiki:`Universal_asynchronous_receiver-transmitter` + +.. todo:: + + UART: To be documented diff --git a/doc/Introduction.rst b/doc/Introduction.rst new file mode 100644 index 0000000..235ad5b --- /dev/null +++ b/doc/Introduction.rst @@ -0,0 +1,55 @@ +Introduction +############ + +Naming Convention +***************** + +Types +===== + +:``***_Interface``: All IC internal interface records are suffixed with ``_Interface``. +:``***_PcbInterface``: All IC external interface records are suffixed with ``_PcbInterface``. +:``***_Vector``: All arrays are suffixed with ``_Vector`` following the IEEE Std. 1076 naming scheme. |br| + An array of an interface is ``_Interface_Vector``. +:``***_***View``: All mode views are suffixed with ``_***View``, where \*\*\* is describing the point of view. + +Generics +======== + +:``***_BITS``: The number of bits. +:``***_COUNT``: The number of items. + + +Packages +******** + + + +Member Data Types +***************** + +* For IC internal interfaces, unresolved data types are used: + + * ``std_ulogic``, + * ``std_ulogic_vector``, + * ``unresolved_unsigned``, + * ``unresolved_signed``, + * ... + +* For IC external interfaces, resolved data types are used: + + * ``std_logic``, + * ``std_logic_vector``, + * ``unsigned``, + * ``signed``, + * ... + +* Data and control signals are implemented using ``std_(u)logic`` or ``std_(u)logic_vector`` data types. +* Addresses, counters, ... signals (with arithmetic/numeric meaning) are implemented using ``(unresolved_)unsigned`` or + ``(unresolved_)signed`` data types. +* Integer and real data types shouldn't be used in interfaces. +* Arrays of fixed sizes should use a previously defined constrained array subtype. +* Commands, status codes, return codes, ... where binary mapping is predefined, are implemented as constrained arrays. |br| + Each code should declare a set of constants. +* Status codes, return codes, ... where no binary mapping is defined by the standard, are implemented using + enumeration types. diff --git a/doc/Network.rst b/doc/Network.rst new file mode 100644 index 0000000..6c662a1 --- /dev/null +++ b/doc/Network.rst @@ -0,0 +1,69 @@ +.. _NET: + +Network +####### + +.. _NET/Ethernet: + +Ethernet +******** + +:Website: `www.ieee802.org/3 `__ +:Download: `IEEE Std. 802.3 `__ via *IEEE Get Program* +:Standard: IEEE Std. 802.3 +:Wikipedia: :wiki:`Ethernet` |br| + :wiki:`IEEE_802.3` + +.. _NET/Eth/MII: + +MII +=== + +.. todo:: + + MII: To be documented + + +.. _NET/Eth/GMII: + +GMII +==== + +.. todo:: + + GMII: To be documented + + +.. _NET/Eth/SGMII: + +SGMII +===== + +.. todo:: + + SGMII: To be documented + + +.. _NET/Cages: + +Cages +***** + +.. _NET/Cage/SFP: + +SFP +=== + +.. todo:: + + SFP: To be documented + + +.. _NET/Cage:QSFP: + +QSFP +==== + +.. todo:: + + QSFP: To be documented diff --git a/doc/PCIe.rst b/doc/PCIe.rst new file mode 100644 index 0000000..5a54ae8 --- /dev/null +++ b/doc/PCIe.rst @@ -0,0 +1,4 @@ +.. _PCIE: + +PCI Express +########### diff --git a/doc/PoC.rst b/doc/PoC.rst new file mode 100644 index 0000000..ffcfda6 --- /dev/null +++ b/doc/PoC.rst @@ -0,0 +1,30 @@ +.. _POC: + +The PoC-Library +############### + +:Website: :doc:`The PoC Library ` + + +.. _POC/CSE: + +CSE - Command-Status-Error +************************** + +:Protocol Description: :doc:`Command-Status-Error ` + +.. todo:: + + CSE: To be documented + + +.. _POC/FIFO: + +FIFO +**** + +:Protocol Description: :doc:`FIFO ` + +.. todo:: + + FIFO: To be documented diff --git a/doc/Usage.rst b/doc/Usage.rst new file mode 100644 index 0000000..97c1abf --- /dev/null +++ b/doc/Usage.rst @@ -0,0 +1,8 @@ +.. _USAGE: + +Usage +##### + +.. todo:: + + Usage: To be documented diff --git a/doc/Video.rst b/doc/Video.rst new file mode 100644 index 0000000..30eb715 --- /dev/null +++ b/doc/Video.rst @@ -0,0 +1,42 @@ +.. _VIDEO: + +Video +##### + +.. _VIDEO/MIPI: + +MIPI +**** + +.. _VIDEO/MIPI/CPHY: + +C-PHY +===== + +.. _VIDEO/MIPI/DPHY: + +D-PHY +===== + +.. _VIDEO/MIPI/MPHY: + +M-PHY +===== + + +.. _VIDEO/VESA: + +VESA +**** + +.. _VIDEO/VESA/VGA: + +VGA +=== + +:Wikipedia: :wiki:`Video_Graphics_Array` |br| + :wiki:`VGA_connector` + +.. todo:: + + VGA: To be documented diff --git a/doc/WishBone.rst b/doc/WishBone.rst new file mode 100644 index 0000000..b1c6002 --- /dev/null +++ b/doc/WishBone.rst @@ -0,0 +1,56 @@ +.. _WB: + +WishBone +######### + +.. _WB/OpenCores: + +OpenCores/Silicore +****************** + +:Website: `opencores.org ⭢ wishbone`__ +:Wikipedia: :wiki:`Wishbone_(computer_bus)` +:Versions: B.3 - 2002 |br| + B.4 - 2010 |br| + ??? - maintained by FOSSi + + +.. _WB/OpenCores/B3: + +WishBone B.3 +============ + +:Specification: `WishBone Specification B.3 `__ + +.. todo:: + + WishBone B.3: To be documented + + +.. _WB/OpenCores/B4: + +WishBone B.4 +============ + +:Specification: `WishBone Specification B.4 `__ + +.. todo:: + + WishBone B.4: To be documented + + +.. _WB/FOSSi: + +FOSSi Foundation +**************** + +.. _WB/FOSSi/WB: + +WishBone Interconnect +===================== + +:Specification: `wishbone-interconnect.readthedocs.io `__ + +.. todo:: + + FOSSi WishBone: To be documented diff --git a/doc/_static/css/override.css b/doc/_static/css/override.css new file mode 100644 index 0000000..675e2ad --- /dev/null +++ b/doc/_static/css/override.css @@ -0,0 +1,146 @@ +/* theme overrides */ +.rst-content h1, +.rst-content h2 { + margin-top: 24px; + margin-bottom: 6px; + text-decoration: underline; +} + +.rst-content h3, +.rst-content h4, +.rst-content h5, +.rst-content h6 { + margin-top: 12px; + margin-bottom: 6px; +} + +.rst-content p { + margin-bottom: 6px +} + +/* general overrides */ +html { + font-size: 15px; +} + +footer { + font-size: 95%; + text-align: center +} + +footer p { + margin-bottom: 0px /* 12px */; + font-size: 95% +} + +section > p, +.section p, +.simple li { + text-align: justify +} + +.rst-content .topic-title { + font-size: larger; + font-weight: 700; + text-decoration: underline; + margin-top: 18px; + margin-bottom: 6px; +} + +.rst-content p.rubric { + text-decoration: underline; + font-weight: 700; + margin-top: 18px; + margin-bottom: 16px; +} + +/* wyrm overrides */ +.wy-menu-vertical header, +.wy-menu-vertical p.caption { + color: #9b9b9b /* #55a5d9 */; + padding: 0 0.809em /* 0 1.618em */; + margin: 6px 0 0 0 /* 12px 0 0 */; + border-top: 1px solid #9b9b9b; +} + +.wy-side-nav-search { + margin-bottom: 0 /* .809em */; + background-color: #333333 /* #2980b9 */; + /* BTD: */ + /*color: #fcfcfc*/ +} + +.wy-side-nav-search input[type=text] { + border-radius: 0px /* 50px */; +} + +.wy-side-nav-search .wy-dropdown > a, .wy-side-nav-search > a { + /* BTD: */ + /*color: #fcfcfc;*/ + margin-bottom: 0.404em /* .809em */; +} + +.wy-side-nav-search > div.version { + margin: 0 0 6px 0; + /* BTD: */ + /*margin-top: -.4045em;*/ +} + +.wy-nav .wy-menu-vertical a:hover { + background-color: #333333 /* #2980b9 */; +} + +.wy-nav-content { + max-width: 1600px /* 800px */ ; +} + +.wy-nav-top { + background: #333333 /* #2980b9 */; +} + +/* Sphinx Design */ +.sd-tab-set { + margin: 0 +} + +.sd-tab-set > label { + padding-top: .5em; + padding-right: 1em; + padding-bottom: .5em; + padding-left: 1em +} + +.sd-container-fluid { + padding-left: 0; + padding-right: 0; +} + +.sd-container-fluid > .sd-row > .sd-col > p.rubric { + margin-bottom: 6px; +} + +.sd-container-fluid > .sd-row > .sd-col > ul.simple { + margin-bottom: 0px; +} + +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property { + display: inline; /* inline-block; */ +} + +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl.attribute:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { + border-left: 3px solid #6c6; /* #ccc; */ + background: #c6ecc6; /* #f0f0f0; */ + color: #555; +} + +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl.method:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { + border-left: 3px solid #c6f; + background: #e6b3ff; + color: #555; +} + +html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl.property:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt { + border-left: 3px solid #ff6 !important; + background: #ffffb3 !important; + color: #555; +} diff --git a/doc/_static/logo.png b/doc/_static/logo.png new file mode 100644 index 0000000..73b6341 Binary files /dev/null and b/doc/_static/logo.png differ diff --git a/doc/conf.py b/doc/conf.py index 6b6a366..85638d9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,97 +1,76 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -import os -import sys -sys.path.insert(0, os.path.abspath('.')) -sys.path.insert(0, os.path.abspath('..')) -#sys.path.insert(0, os.path.abspath('_extensions')) -#sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme')) +from sys import path as sys_path +from os.path import abspath +from pathlib import Path +from textwrap import dedent +from pyTooling.Versioning import SemanticVersion # ============================================================================== -# Project information +# Project configuration # ============================================================================== -project = 'VHDL Interfaces' -copyright = '2016-2020, Open Source VHDL Group, CC-BY 4.0' -author = 'OSVG - Open Source VHDL Group' +githubNamespace = "VHDL" +githubProject = "Interfaces" +githubVersion = "1.1.1" -# -- General configuration --------------------------------------------------- -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ -] +# ============================================================================== +# Project paths +# ============================================================================== +ROOT = Path(__file__).resolve().parent + +sys_path.insert(0, abspath(".")) +sys_path.insert(0, abspath("..")) + # ============================================================================== -# Versioning +# Project information and versioning # ============================================================================== # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -from subprocess import check_output - -def _IsUnderGitControl(): - return (check_output(["git", "rev-parse", "--is-inside-work-tree"], universal_newlines=True).strip() == "true") - -def _LatestTagName(): - return check_output(["git", "describe", "--abbrev=0", "--tags"], universal_newlines=True).strip() -# The full version, including alpha/beta/rc tags -version = "0.1" # The short X.Y version. -release = "0.1.0" # The full version, including alpha/beta/rc tags. -try: - if _IsUnderGitControl: - latestTagName = _LatestTagName()[1:] # remove prefix "v" - versionParts = latestTagName.split("-")[0].split(".") - - version = ".".join(versionParts[:2]) - release = latestTagName # ".".join(versionParts[:3]) -except: - pass +project = githubProject +author = "Patrick Lehmann" +copyright = "2016-2026 Open Source VHDL Group" +version = ".".join(githubVersion.split(".")[:2]) # e.g. 2.3 The short X.Y version. +release = githubVersion # ============================================================================== # Miscellaneous settings # ============================================================================== # The master toctree document. -master_doc = 'index' +master_doc = "index" # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ "_build", - "_themes", + "_theme", "Thumbs.db", ".DS_Store" ] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'stata-dark' +pygments_style = "manni" # ============================================================================== # Restructured Text settings # ============================================================================== -prologPath = "prolog.inc" +prologPath = Path("prolog.inc") try: - with open(prologPath, "r") as prologFile: - rst_prolog = prologFile.read() + with prologPath.open("r", encoding="utf-8") as fileHandle: + rst_prolog = fileHandle.read() except Exception as ex: - print("[ERROR:] While reading '{0!s}'.".format(prologPath)) + print(f"[ERROR:] While reading '{prologPath}'.") print(ex) rst_prolog = "" @@ -99,13 +78,26 @@ def _LatestTagName(): # ============================================================================== # Options for HTML output # ============================================================================== -# html_theme = 'alabaster' -html_theme = 'sphinx_rtd_theme' +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "logo_only": True, + "vcs_pageview_mode": 'blob', + "navigation_depth": 5, +} +html_css_files = [ + 'css/override.css', +] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] + +html_logo = str(Path(html_static_path[0]) / "logo.png") +html_favicon = str(Path(html_static_path[0]) / "icon.png") + +# Output file base name for HTML help builder. +htmlhelp_basename = f"{githubProject}Doc" # If not None, a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. @@ -116,46 +108,47 @@ def _LatestTagName(): # ============================================================================== # Options for LaTeX / PDF output # ============================================================================== -from textwrap import dedent - +latex_engine = "lualatex" +latex_use_xindy = False latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - 'papersize': 'a4paper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - 'preamble': dedent(r""" - % ================================================================================ - % User defined additional preamble code - % ================================================================================ - % Add more Unicode characters for pdfLaTeX. - % - Alternatively, compile with XeLaTeX or LuaLaTeX. - % - https://github.com/sphinx-doc/sphinx/issues/3511 - % - \ifdefined\DeclareUnicodeCharacter - \DeclareUnicodeCharacter{2265}{$\geq$} - \DeclareUnicodeCharacter{21D2}{$\Rightarrow$} - \fi - - - % ================================================================================ - """), - - # Latex figure (float) alignment - #'figure_align': 'htbp', + "papersize": "a4paper", # The paper size ('letterpaper' or 'a4paper'). + "pointsize": "10pt", # The font size ('10pt', '11pt' or '12pt'). + "inputenc": "", # Let LuaLaTeX handle input encoding + "utf8extra": "", + "fontenc": r"\usepackage{fontspec}", # Disable the default T1 font encoding (Essential for LuaLaTeX) + "fontpkg": dedent("""\ + \\usepackage{unicode-math} + + % Set the Text Fonts (Libertinus) + \\setmainfont{Libertinus Serif} + \\setsansfont{Libertinus Sans} + \\setmonofont{Libertinus Mono} + \\setmathfont{Libertinus Math} + + % Set Symbol font + \\usepackage{newunicodechar} + \\newfontfamily{\\emojifont}[Renderer=OpenType]{NotoColorEmoji.ttf} + \\usepackage{pytooling} + """), + "passoptionstopackages": dedent("""\ + \\PassOptionsToPackage{verbatimvisiblespace=\\ }{sphinx} + """), +# "sphinxsetup": "verbatimvisiblespace=\\textvisiblespace" +# "figure_align": "htbp", # Latex figure (float) alignment + "makeindex": r"\usepackage[columns=1]{idxlayout}\makeindex", + "printindex": r"\def\twocolumn[#1]{#1}\printindex", } + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, - 'VHDL-Interfaces.tex', - 'VHDL Interfaces', - 'Open Source VHDL Group', - 'manual' + f"{githubProject}.tex", + f"The {githubProject} Documentation", + "Patrick Lehmann", + "manual" ), ] @@ -164,36 +157,21 @@ def _LatestTagName(): # Extensions # ============================================================================== extensions = [ -# Sphinx theme - "sphinx_rtd_theme", - # Standard Sphinx extensions - 'sphinx.ext.extlinks', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.graphviz', - 'sphinx.ext.mathjax', - 'sphinx.ext.ifconfig', - 'sphinx.ext.viewcode', -# 'sphinx.ext.duration', - + "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.graphviz", + "sphinx.ext.mathjax", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", # SphinxContrib extensions -# 'sphinxcontrib.actdiag', -# 'sphinxcontrib.seqdiag', -# 'sphinxcontrib.textstyle', -# 'sphinxcontrib.spelling', -# 'changelog', - -# BuildTheDocs extensions - + "sphinxcontrib.mermaid", # Other extensions - 'sphinx_fontawesome', - -# local extensions (patched) -# 'autoapi.sphinx', - -# local extensions -# 'DocumentMember' + "sphinx_design", + "sphinx_copybutton", + "sphinx_reports", +# User defined extensions ] @@ -201,25 +179,22 @@ def _LatestTagName(): # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { -# 'python': ('https://docs.python.org/3', None), + "python": ("https://docs.python.org/3", None), + # "ghdl": ("https://setuptools.pypa.io/en/latest", None), + # "nvc": ("https://setuptools.pypa.io/en/latest", None), + "poc": ("https://vhdl.github.io/PoC", None), } -# ============================================================================== -# Sphinx.Ext.AutoDoc -# ============================================================================== -# see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration -autodoc_member_order = "bysource" # alphabetical, groupwise, bysource - - # ============================================================================== # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - 'issue': ('https://github.com/VHDL/Interfaces/issues/%s', 'issue #'), - 'pull': ('https://github.com/VHDL/Interfaces/pull/%s', 'pull request #'), - 'src': ('https://github.com/VHDL/Interfaces/blob/master/%s?ts=2', None), -# 'test': ('https://github.com/VHDL/Interfaces/blob/master/tests/%s?ts=2', None) + "gh": (f"https://GitHub.com/%s", "gh:%s"), + "ghissue": (f"https://GitHub.com/{githubNamespace}/{githubProject}/issues/%s", "issue #%s"), + "ghpull": (f"https://GitHub.com/{githubNamespace}/{githubProject}/pull/%s", "pull request #%s"), + "ghsrc": (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None), + "wiki": (f"https://en.wikipedia.org/wiki/%s", None), } @@ -229,6 +204,16 @@ def _LatestTagName(): graphviz_output_format = "svg" +# ============================================================================== +# SphinxContrib.Mermaid +# ============================================================================== +mermaid_cmd = "mmdc" +mermaid_cmd_shell = True +mermaid_params = [ + '--backgroundColor', 'transparent', +] +mermaid_verbose = True + # ============================================================================== # Sphinx.Ext.ToDo @@ -236,3 +221,20 @@ def _LatestTagName(): # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True todo_link_only = True + + +# ============================================================================== +# sphinx-reports +# ============================================================================== +report_unittest_testsuites = { + "src": { + "name": f"{githubProject}", + "xml_report": "../report/unit/Unittesting.xml", + } +} + + +# ============================================================================== +# Sphinx_Design +# ============================================================================== +# sd_fontawesome_latex = True diff --git a/doc/index.rst b/doc/index.rst index 14d3adf..a02d9f2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,26 +1,169 @@ VHDL Interfaces =============== -This repository will provide Interfaces (*mode views*) for VHDL-2019. +.. grid:: 3 + + .. grid-item:: + :columns: 8 + + This repository provides generic VHDL-2019 **Interfaces** (*mode views*) descriptions of commonly used interfaces + like UART, I²C, ..., AXI, WishBone, Avalon, ..., MII, GMII, SGMII, ... + + Interfaces are defined in 2 stages (see example to the right): + + 1. Define all necessary signals in a VHDL record type. If interfaces are more complicated and grouped in + sub-interfaces, records can be nested. If a record sub-element is an array, usually these sub-elements are + unconstrained, thus they can be constrained later. + 2. Define a ``view``, which defines *directions* (modes) for each record sub-element. Usually, the reverse + view is created by creating an alias using the ``'converse`` attribute. + + .. grid-item:: + :columns: 4 + + .. code-block:: vhdl + + library IEEE; + use IEEE.std_logic_1164.all; + + package JTAG is + type JTAG_Interface is record + TCK : std_logic; -- Test Clock + TRST : std_logic; -- Test Reset + TMS : std_logic; -- Test Mode Select + TDI : std_logic; -- Test Data In + TDO : std_logic; -- Test Data Out + end record; + + view JTAG_DeviceView of JTAG_Interface is + TCK : in; + TRST : in; + TMS : in; + TDI : in; + TDO : out; + end view; + alias JTAG_TesterView is JTAG_DeviceView'converse; + end package; + + +Supported Interfaces +******************** + +.. grid:: 4 + + .. grid-item-card:: AMBA + :columns: 3 + + * :doc:`AXI`: + + * :ref:`AXI4/Full` + * :ref:`AXI4/Lite` + * :ref:`AXI4/Stream` + + .. grid-item-card:: Avalon + :columns: 3 + + * :ref:`Avalon/MM` + * :ref:`Avalon/ST` + + .. grid-item-card:: WishBone + :columns: 3 + + * :ref:`WB/OpenCores` + + * :ref:`WB/OpenCores/B3` + * :ref:`WB/OpenCores/B4` + + * :ref:`WB/FOSSi` + + * :ref:`WB/FOSSi/WB` + + .. grid-item-card:: PoC Library + :columns: 3 + + * :ref:`POC/CSE` + * :ref:`POC/FIFO` + + .. grid-item-card:: I/O + :columns: 3 + + * :ref:`IO/BiSS` + * :ref:`IO/I2C` + * :ref:`IO/I2S` + * :ref:`IO/JTAG` + * :ref:`IO/SPI` + * :ref:`IO/UART` + + .. grid-item-card:: PCI Express + :columns: 3 + + * :ref:`PCIE` + + .. grid-item-card:: Network + :columns: 3 + + * Ethernet + + * MII + * RMII + * GMII + * RGMII + * SGMII + + * Cages: + + * SFP + * QSFP + + .. grid-item-card:: Video + :columns: 3 + + * MIPI: + + * :ref:`VIDEO/MIPI/CPHY` + * :ref:`VIDEO/MIPI/DPHY` + * :ref:`VIDEO/MIPI/MPHY` + + * VESA + + * :ref:`VIDEO/VESA/VGA` + + +.. _ADOPTERS: + +Adopters +******** + +* `Paebbels/BigDesign `__ +* ... (*Contact the maintainer to get listed.*) + + +.. _TESTS: + +Tests +***** + +* VHDL-2019 syntax checked by `NVC `__. |br| + See :ref:`test results `. + + +.. _CONTRIBUTORS: Contributors ************ -* `Patrick Lehmann `_ (Maintainer) +* `Patrick Lehmann `__ (Maintainer) +* `Parham Soltani `__ +* `and more... `__ + +.. _LICENSE: License ******* -This library is licensed under **Apache License, 2.0**. - ------------------------------------- - -.. |docdate| date:: %b %d, %Y - %H:%M - -.. only:: html +This VHDL library (source code) is licensed under :doc:`Apache License 2.0 `. |br| +The accompanying documentation is licensed under :doc:`Creative Commons - Attribution 4.0 (CC-BY 4.0) `. - This document was generated on |docdate|. .. # =========================================================================== # Table of Contents @@ -30,19 +173,27 @@ This library is licensed under **Apache License, 2.0**. :caption: Overview :hidden: - introduction - usage + Introduction + Usage .. toctree:: :caption: Interfaces :hidden: - io/index + AXI + Avalon + IO + Network + PCIe + PoC + Video + WishBone .. toctree:: :caption: Appendix :hidden: tests/index - license + Code-License + Doc-License genindex diff --git a/doc/introduction.rst b/doc/introduction.rst deleted file mode 100644 index 97e99dd..0000000 --- a/doc/introduction.rst +++ /dev/null @@ -1,3 +0,0 @@ -Introduction -############ - diff --git a/doc/io/index.rst b/doc/io/index.rst deleted file mode 100644 index a97a759..0000000 --- a/doc/io/index.rst +++ /dev/null @@ -1,3 +0,0 @@ -Low-Speed I/O Interfaces -######################## - diff --git a/doc/prolog.inc b/doc/prolog.inc index 7297d99..75463a8 100644 --- a/doc/prolog.inc +++ b/doc/prolog.inc @@ -9,6 +9,51 @@
+.. # define horizontal line for HTML .. |hr| raw:: html
+ +.. # define additional CSS based styles and ReST roles for HTML +.. raw:: html + + + +.. role:: bolditalic + :class: bolditalic + +.. role:: underline + :class: underline + +.. role:: strike + :class: strike + +.. role:: xlarge + :class: xlarge + +.. role:: red + :class: colorred +.. role:: green + :class: colorgreen +.. role:: blue + :class: colorblue +.. role:: purple + :class: colorpurple + +.. role:: deletion + :class: colorred strike +.. role:: addition + :class: colorgreen + +.. role:: pycode(code) + :language: python + :class: highlight diff --git a/doc/requirements.txt b/doc/requirements.txt index deabcd3..e675e5d 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,16 +1,15 @@ -#-r ../requirements.txt +# -r ../requirements.txt + # Enforce latest version on ReadTheDocs -sphinx>=3.1.1 +sphinx ~= 9.1 +#docutils ~= 0.22.0 +docutils_stubs ~= 0.0.22 -# Sphinx Themes -sphinx-rtd-theme>=0.5.0 +# ReadTheDocs Theme +sphinx_rtd_theme ~= 3.1 # Sphinx Extenstions -sphinx_fontawesome>=0.0.6 - -# changelog>=0.3.5 - -# BuildTheDocs Extensions (mostly patched Sphinx extensions) - -# Enforce newer version on ReadTheDocs (currently using 2.3.1) -Pygments>=2.6.1 +sphinxcontrib-mermaid ~= 2.0 +sphinx_design ~= 0.7.0 +sphinx-copybutton >= 0.5.2 +sphinx_reports ~= 0.10.0 diff --git a/doc/tests/index.rst b/doc/tests/index.rst index 5856fee..b4e748e 100644 --- a/doc/tests/index.rst +++ b/doc/tests/index.rst @@ -1,3 +1,13 @@ -Tests -##### +.. _RPT/Unittests: +Test Summary Report +################### + +.. report:unittest-summary:: + :reportid: src + :testsuite-summary-name: Interfaces + :no-assertions: + +---------- + +Test report generated a Bash script and visualized by `sphinx-reports `__. diff --git a/doc/usage.rst b/doc/usage.rst deleted file mode 100644 index 4b01e43..0000000 --- a/doc/usage.rst +++ /dev/null @@ -1,2 +0,0 @@ -Usage -##### diff --git a/scripts/NVC.sh b/scripts/NVC.sh index 482a05f..f0b492e 100755 --- a/scripts/NVC.sh +++ b/scripts/NVC.sh @@ -1,6 +1,6 @@ #!/bin/bash # ==================================================================================================================== # -# Copyright 2016-2025 Open Source VHDL Group # +# Copyright 2016-2026 Open Source VHDL Group # # # # Licensed under the Apache License, Version 2.0 (the "License"); # # you may not use this file except in compliance with the License. # @@ -25,8 +25,8 @@ exec 3>${UnittestSummaryFile} printf "%s\n" "Analyzing '${VHDLLibrary}' ..." -printf "\n" "1.0" "utf-8" >&3 -printf "\n" "%TIME%" >&3 +printf "\n" "1.0" "utf-8" >&3 +printf "\n" "${UnittestTestsuitename}" "%TIME%" >&3 printf " \n" "${UnittestTestsuitename}" "$(hostname -f)" "$(date --iso-8601=seconds)" "%TIME%" >&3 libraryBegin=$(date +%s%N)