Nselvara/issue14

LICENSE-THIRD-PARTY.md

@@ -0,0 +1,17 @@
+# Third-Party Content Notice
+
+This repository contains references to external educational content from chipdev.io:
+
+- Problem descriptions and prompts for HDL design challenges
+- Referenced under fair use for non-commercial, educational, and illustrative purposes
+- Original content © chipdev.io – All rights reserved
+
+This repository is not affiliated with or endorsed by chipdev.io.
+All problem statements remain the intellectual property of chipdev.io.
+
+---
+
+The VHDL implementations, testbenches, and supporting infrastructure developed in this repository are licensed under:
+
+**GNU General Public License v3.0 (GPLv3)**
+See the main [LICENSE](./LICENSE) file for details.

README.md

@@ -122,19 +122,51 @@ These examples serve as a learning resource or starting point for building, simu
 34. **Mealy Finite State Machine (FSM)** – 🟢 Easy – 🏢 Google, Microsoft
     - FSM where outputs depend on both current state and input.
 
+## Implementation Notes
+
+> [!NOTE]
+> **Deviations from ChipDev.io Specifications**
+>
+> This repository makes two consistent changes across all implementations:
+>
+> 1. **Reset signal naming**: ChipDev.io uses various names (`resetn`, `reset_n`, `reset`). This repository uniformly uses **`rst_n`** for consistency.
+>
+> 2. **Generic parameters**: Some quests specify hardcoded bit widths. This repository adds **`DATA_WIDTH`** and similar generic parameters where appropriate to improve reusability.
+>
+> Some signal names from the original problems (e.g., port naming conventions) may not be optimal but were preserved to maintain alignment with the source material. Quest-specific deviations are documented in individual README files.
+
+## Testbench Methodology
+
+> [!NOTE]
+> **Professional Verification Approach**
+>
+> All testbenches follow industry-standard practices:
+>
+> - **VUnit framework**: Automated test execution with pass/fail reporting
+> - **OSVVM RandomPkg**: Constrained-random stimulus generation for better coverage than sequential patterns
+> - **Dual verification**: Checker procedures use different coding styles than the DUT to avoid systematic errors
+> - **Edge case testing**: Explicit tests for boundary conditions, resets, and corner cases
+> - **ModelSim .do files**: Pre-configured waveform views for debugging
+>
+> Test strategies typically include:
+>
+> 1. **Directed tests**: Exhaustive testing of all valid states/combinations
+> 2. **Random tests**: Hundreds of randomized inputs to catch unexpected corner cases
+> 3. **Reset testing**: Verify proper initialization and reset behavior
+
 ## Minimum System Requirements
 
 - **OS**: (Anything that can run the following)
-  * **IDE**:
+  - **IDE**:
     - [`VSCode latest`](https://code.visualstudio.com/download) with following plugins:
       - [`Python`](https://marketplace.visualstudio.com/items?itemName=ms-python.python) by Microsoft
       - [`Pylance`](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) by Microsoft
       - [`Draw.io`](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) by Henning Dieterichs
       - [`Draw.io Integration: WaveDrom plugin`](https://marketplace.visualstudio.com/items?itemName=nopeslide.vscode-drawio-plugin-wavedrom) by nopeslide
       - [`TerosHDL`](https://marketplace.visualstudio.com/items?itemName=teros-technology.teroshdl) by Teros Technology
       - [`VHDL-LS`](https://marketplace.visualstudio.com/items?itemName=hbohlin.vhdl-ls) by Henrik Bohlin (Deactivate the one provided by TerosHDL)
-  * **VHDL Simulator**: (Anything that supports **VHDL-2008**):
-  * **Script execution environment**:
+  - **VHDL Simulator**: (Anything that supports **VHDL-2008**):
+  - **Script execution environment**:
     - `Python 3.11.4` to automatise testing via **VUnit**
 
 ## Initial Setup
@@ -260,3 +292,17 @@ run_all_testbenches_lib(
     xunit_xml="./test/res.xml"    # Output file for test results
 )
 ```
+
+## License
+
+All VHDL source code, testbenches, and scripts in this repository are licensed under the GNU General Public License v3.0 (GPLv3).
+See the [LICENSE](./LICENSE) file for full details.
+
+> [!NOTE]
+> Problem statements and task descriptions referenced from [chipdev.io](https://chipdev.io) are **not** part of this license.
+> They are © chipdev.io and are used under fair use for educational purposes only.
+> This repository is not affiliated with or endorsed by chipdev.io.
+> This file and the accompanying VHDL code are licensed under GPLv3.
+
+> [!NOTE]
+> See [LICENSE-THIRD-PARTY](./LICENSE-THIRD-PARTY.md) for more.

ip/01_Simple_Router/README.md

@@ -0,0 +1,38 @@
+# Quest 1 - Simple Router
+
+## Original Problem Statement
+
+### Prompt
+
+Build a router circuit which forwards data from the input (din) to one of four outputs (dout0, dout1, dout2, or dout3), specified by the address input (addr).
+
+The address is a two bit value whose decimal representation determines which output value to use. Append to dout the decimal representation of addr to get the output signal name. For example, if addr=b11 then the decimal representation of addr is 3, so the output signal name is dout3.
+
+The input has an enable signal (din_en), which allows the input to be forwarded to an output when enabled. If an output is not currently being driven to, then it should be set to 0.
+
+### Input and Output Signals
+
+`din` - Input data
+`din_en` - Enable signal for din. Forwards data from input to an output if 1, does not forward data otherwise
+`addr` - Two bit destination address. For example addr = b11 = 3 indicates din should be forwarded to output value 3 (dout3)
+`dout0` - Output 0. Corresponds to addr = b00
+`dout1` - Output 1. Corresponds to addr = b01
+`dout2` - Output 2. Corresponds to addr = b10
+`dout3` - Output 3. Corresponds to addr = b11
+
+> [!NOTE]
+> For the complete problem description, please visit:
+> <https://chipdev.io/question/1>
+
+## Description
+
+Combinational router using a `case` statement to decode the 2-bit address and route input data to one of four outputs. All outputs default to zero, then the selected output is conditionally assigned when `din_en` is high. Synthesises to a simple 4:1 demultiplexer with AND gates gating the enable signal.
+
+## Source
+
+This quest is from [chipdev.io](https://chipdev.io/question/1).
+
+The problem description above is used under fair use for educational purposes.
+For licensing information, see [LICENSE-THIRD-PARTY.md](../../LICENSE-THIRD-PARTY.md).
+
+**Webarchive link:** <https://web.archive.org/web/https://chipdev.io/question/1>

ip/02_Second_Largest/README.md

@@ -0,0 +1,45 @@
+# Quest 2 – Second Largest
+
+## Original Problem Statement
+
+### Prompt
+
+Given a clocked sequence of unsigned values, output the second-largest value seen so far in the sequence. If only one value is seen, then the output (dout) should equal 0. Note that repeated values are treated as separate candidates for being the second largest value.
+
+When the reset-low signal (`resetn`) goes low, all previous values seen in the input sequence should no longer be considered for the calculation of the second largest value, and the output dout should restart from 0 on the next cycle.
+
+### Input and Output Signals
+
+`clk` - Clock signal
+`resetn` - Synchronous reset-low signal
+`din` - Input data sequence
+`dout` - Second-largest value seen so far
+
+### Output signals during reset
+
+`dout` - 0 when resetn is active
+
+> [!NOTE]
+> For the complete problem description, please visit:
+> <https://chipdev.io/question/2>
+
+## Description
+
+Design a sequential circuit that monitors a stream of unsigned values and continuously outputs the **second-largest value** observed so far. If only a single value has been seen, then the output (`dout`) must remain `0`.
+
+Each value, even if repeated, should be treated as a distinct observation. That means duplicates are still valid inputs when determining the second largest.
+
+If the active-low reset (`resetn`) signal is asserted, any previously observed values must be discarded, and the calculation of the second-largest value starts fresh. In this reset state, `dout` should immediately return to `0`.
+
+---
+
+## Source Reference
+
+This task is inspired by the "Second Largest" problem available at [chipdev.io](https://chipdev.io).
+The description here has been paraphrased for clarity and adapted under fair use for educational and research purposes.
+
+Please refer to [LICENSE.third_party.md](../LICENSE.third_party.md) for licensing information.
+
+This quest is from [chipdev.io](https://chipdev.io/question/2).
+
+**Webarchive link:** <https://web.archive.org/web/https://chipdev.io/question/2>

ip/03_Rounding_Division/README.md

@@ -0,0 +1,32 @@
+# Quest 3 - Rounding Division
+
+## Original Problem Statement
+
+### Prompt
+
+Divide an input number by a power of two and round the result to the nearest integer. The power of two is calculated using 2^DIV_LOG2 where DIV_LOG2 is a module parameter. Remainders of 0.5 or greater should be rounded up to the nearest integer. If the output were to overflow, then the result should be saturated instead.
+
+### Input and Output Signals
+
+`din` - Input number
+`dout` - Rounded result
+
+> [!NOTE]
+> For the complete problem description, please visit:
+> <https://chipdev.io/question/3>
+
+## Description
+
+Divider that performs power-of-2 division with rounding.
+The division is accomplished via right-shift by `DIV_LOG2` positions.
+The rounding logic examines the bit at position `DIV_LOG2-1` (representing the 0.5 threshold) - if this bit is set, it adds 1 to the quotient.
+The `resize()` function handles saturation when the result overflows the output width.
+
+## Source
+
+This quest is from [chipdev.io](https://chipdev.io/question/3).
+
+The problem description above is used under fair use for educational purposes.
+For licensing information, see [LICENSE-THIRD-PARTY.md](../../LICENSE-THIRD-PARTY.md).
+
+**Webarchive link:** <https://web.archive.org/web/https://chipdev.io/question/3>

ip/04_Bit_Reverser/README.md

@@ -0,0 +1,46 @@
+# Quest 4 - Gray Code Counter
+
+## Original Problem Statement
+
+### Prompt
+
+Build a circuit that generates a Gray code sequence starting from 0 on the output (dout).
+
+Gray code is an ordering of binary numbers such that two successive values only have one bit difference between them. For example, a Gray code sequence for a two bit value could be:
+
+b00
+b01
+b11
+b10
+
+The Gray code sequence should use the standard encoding. In the standard encoding the least significant bit follows a repetitive pattern of 2 on, 2 off ( ... 11001100 ... ); the next digit a pattern of 4 on, 4 off ( ... 1111000011110000 ... ); the nth least significant bit a pattern of 2n on 2n off.
+
+When the reset-low signal (resetn) goes to 0, the Gray code sequence should restart from 0.
+
+### Input and Output Signals
+
+`clk` - Clock signal
+`resetn` - Synchronous reset-low signal
+`out` - Gray code counter value
+
+### Output signals during reset
+
+`out` - 0 when resetn is active
+
+> [!NOTE]
+> For the complete problem description, please visit:
+> <https://chipdev.io/question/4>
+
+## Description
+
+Combinational bit-reversal circuit using a loop that maps `dout(i) <= din(din'high - i)` to mirror the input vector.
+Synthesises to pure wiring with no logic gates required.
+
+## Source
+
+This quest is from [chipdev.io](https://chipdev.io/question/4).
+
+The problem description above is used under fair use for educational purposes.
+For licensing information, see [LICENSE-THIRD-PARTY.md](../../LICENSE-THIRD-PARTY.md).
+
+**Webarchive link:** <https://web.archive.org/web/https://chipdev.io/question/4>

ip/05_Gray_Code_Converter/README.md

@@ -0,0 +1,31 @@
+# Quest 5 - Reversing Bits
+
+## Original Problem Statement
+
+### Prompt
+
+Reverse the bits of an input value's binary representation.
+
+### Input and Output Signals
+
+`din` - Input value
+`dout` - Bitwise reversed value
+
+> [!NOTE]
+> For the complete problem description, please visit:
+> <https://chipdev.io/question/5>
+
+## Description
+
+Sequential Gray code counter implemented as a binary counter with conversion output.
+Each clock cycle increments a binary counter variable, then converts it to Gray code using the standard formula: `gray = count XOR shift_right(count, 1)`.
+This produces the characteristic Gray code property where consecutive values differ by only one bit.
+
+## Source
+
+This quest is from [chipdev.io](https://chipdev.io/question/5).
+
+The problem description above is used under fair use for educational purposes.
+For licensing information, see [LICENSE-THIRD-PARTY.md](../../LICENSE-THIRD-PARTY.md).
+
+**Webarchive link:** <https://web.archive.org/web/https://chipdev.io/question/5>

ip/06_Edge_Detector/README.md

@@ -0,0 +1,38 @@
+# Quest 6 – Edge Detector
+
+## Original Problem Statement
+
+### Prompt
+
+Build a circuit that pulses `dout` one cycle after the rising edge of `din`. A pulse is defined as writing a single-cycle `1` as shown in the examples below. When `resetn` is asserted, the value of `din` should be treated as `0`.
+
+Bonus - can you enhance your design to pulse `dout` on the same cycle as the rising edge? Note that this enhancement will not pass our test suite, but is still a useful exercise.
+
+### Input and Output Signals
+
+`clk` - Clock signal
+`resetn` - Synchronous reset-low signal
+`din` - Input signal
+`dout` - Output signal
+
+### Output signals during reset
+
+`dout` - `0` when `resetn` is active
+
+> [!NOTE]
+> For the complete problem description, please visit:
+> <https://chipdev.io/question/6>
+
+## Description
+
+Rising edge detector that registers the previous input value each clock cycle and outputs a single-cycle pulse when `din='1'` and differs from the registered value.
+The comparison `din /= din_reg` detects the transition, while the `din = '1'` check ensures it's specifically a rising edge.
+
+## Source
+
+This quest is from [chipdev.io](https://chipdev.io/question/6).
+
+The problem description above is used under fair use for educational purposes.
+For licensing information, see [LICENSE-THIRD-PARTY.md](../../LICENSE-THIRD-PARTY.md).
+
+**Webarchive link:** <https://web.archive.org/web/https://chipdev.io/question/6>

ip/07_Serialiser/README.md

@@ -0,0 +1,49 @@
+# Quest 7 – Serialiser
+
+## Original Problem Statement
+
+### Prompt
+
+Build a circuit that takes the multi-bit input (`din`) and shifts the input value's least significant bit (rightmost bit) to the single-bit output (`dout`) one bit at a time.
+
+The circuit should begin shifting the input's least significant bit when the the input enable signal (`din_en`) goes high. In other words, the input enable signal going high indicates that this circuit should start shifting the current input signal from it's least significant bit, regardless of which bits the circuit has already shifted.
+
+If all the input's bits have been shifted to the output so that there are no more bits to shift, the output must output `0`.
+
+When reset (`resetn`) is active, the input value that is being shifted is treated as `0`. Even when reset goes back to being inactive, the input value will still be treated as `0`, unless the input enable signal makes the circuit begin shifting from the input again.
+
+### Input and Output Signals
+
+`clk` - Clock signal
+`resetn` - Synchronous reset-low signal
+`din` - Input signal
+`din_en` - Enable signal for input data
+`dout` - Output signal
+
+### Output signals during reset
+
+`dout` - `0` when `resetn` is active
+
+> [!NOTE]
+> For the complete problem description, please visit:
+> <https://chipdev.io/question/7>
+
+> [!NOTE]
+> **Implementation Deviation**
+>
+> This implementation adds a `DATA_WIDTH` generic parameter for configurability, though the original problem doesn't specify a particular bit width.
+
+## Description
+
+Serializer that captures a parallel input word when `din_en` asserts and shifts it out LSB-first over subsequent clock cycles.
+A `bit_index` counter tracks which bit to output, incrementing from 0 to `DATA_WIDTH-1`.
+The captured data remains in `din_reg` until the entire word is transmitted, then zeros out.
+
+## Source
+
+This quest is from [chipdev.io](https://chipdev.io/question/7).
+
+The problem description above is used under fair use for educational purposes.
+For licensing information, see [LICENSE-THIRD-PARTY.md](../../LICENSE-THIRD-PARTY.md).
+
+**Webarchive link:** <https://web.archive.org/web/https://chipdev.io/question/7>