Merged
Conversation
…e including a webarchive link Fixes #14
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for IP modules (Quests 1-34) by creating individual README files with problem statements, descriptions, and licensing information. It also updates the main README with implementation notes and testbench methodology documentation, and adds a LICENSE-THIRD-PARTY file for proper attribution.
- Adds 34 README files documenting HDL design challenges from chipdev.io
- Updates main README with implementation notes, testbench methodology, and licensing sections
- Adds LICENSE-THIRD-PARTY.md for third-party content attribution
- Minor whitespace cleanup in testbench file
Reviewed changes
Copilot reviewed 37 out of 37 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| ip/34_Mealy_Finite_State_Machine/README.md | Documents Mealy FSM implementation with state tracking and gated outputs |
| ip/33_Bubble_Sort/README.md | Documents hardware bubble sort with O(n²) complexity |
| ip/32_Carry_Select_Adder/README.md | Documents carry-select adder architecture with parallel RCAs |
| ip/31_Configurable_LFSR/README.md | Documents configurable LFSR with runtime-programmable taps |
| ip/30_Two_Read_One_Write_Register_File/README.md | Documents dual-port register file with collision detection |
| ip/29_Thermometer_Code_Detector/README.md | Documents thermometer code validation logic |
| ip/28_Binary_to_Thermometer_Decoder/README.md | Documents binary-to-thermometer decoder |
| ip/27_Dot_Product/README.md | Documents sequential dot-product calculator |
| ip/26_Multi_Bit_FIFO/README.md | Documents two-deep shift-register FIFO |
| ip/25_Flip_Flop_Array/tb_flip_flop_array.vhd | Removes trailing whitespace and corrects comment spelling |
| ip/25_Flip_Flop_Array/README.md | Documents single-port memory array using flip-flops |
| ip/24_Ripple_Carry_Adder/README.md | Documents ripple-carry adder chain |
| ip/23_Basic_ALU/README.md | Documents combinational ALU with six parallel operations |
| ip/22_Full_Adder/README.md | Documents full adder implementations |
| ip/21_FizzBuzz/README.md | Documents hardware FizzBuzz counter with modulo logic |
| ip/20_Divide_by_Evens_Clock_Divider/README.md | Documents multiple clock divider implementation |
| ip/19_Programmable_Sequence_Detector/README.md | Documents runtime-programmable sequence detector |
| ip/18_Palindrome_Detector/README.md | Documents palindrome detection circuit |
| ip/17_Divisible_by_5/README.md | Documents divisibility-by-5 detector using FSM |
| ip/16_Divisible_by_3/README.md | Documents divisibility-by-3 detector using FSM |
| ip/15_Sequence_Detector/README.md | Documents parameterizable sequence detector |
| ip/14_Stopwatch_Timer/README.md | Documents stopwatch counter with start/stop/reset |
| ip/13_One_Hot_Detector/README.md | Documents one-hot encoding validator |
| ip/12_Trailing_Zeroes/README.md | Documents trailing zero counter |
| ip/11_Gray_Code_to_Binary/README.md | Documents Gray-to-binary decoder |
| ip/10_Counting_Ones/README.md | Documents population count circuit |
| ip/09_Fibonacci_Generator/README.md | Documents Fibonacci sequence generator |
| ip/08_Deserialiser/README.md | Documents serial-to-parallel deserializer |
| ip/07_Serialiser/README.md | Documents parallel-to-serial serializer |
| ip/06_Edge_Detector/README.md | Documents rising edge detector |
| ip/05_Gray_Code_Converter/README.md | Documents Gray code converter (has title/description mismatch) |
| ip/04_Bit_Reverser/README.md | Documents bit reverser (has title/description mismatch) |
| ip/03_Rounding_Division/README.md | Documents power-of-2 divider with rounding |
| ip/02_Second_Largest/README.md | Documents second-largest value tracker |
| ip/01_Simple_Router/README.md | Documents combinational 1:4 router |
| README.md | Adds implementation notes, testbench methodology, and licensing sections |
| LICENSE-THIRD-PARTY.md | Adds third-party content attribution notice |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `a` - First operand input word | ||
| `b` - Second operand input word | ||
| `sum` - Output word corresponding to a plus b operation (note that sum has DATA_WIDTH+1 bits to account for the carry-out/overflow bit) | ||
| `cout_int` - Internal carry-out nets, ouputs of the full adder instances |
There was a problem hiding this comment.
The word "ouputs" is misspelled. It should be "outputs".
Suggested change
| `cout_int` - Internal carry-out nets, ouputs of the full adder instances | |
| `cout_int` - Internal carry-out nets, outputs of the full adder instances |
|
|
||
| Thermometer (a.k.a. unary) coding is frequently used in digital systems applications to represent a natural number. In a thermometer code, a `N`-bit binary number is represented by a `(2 ** N)`-bit digital word, which has `m` zeros followed by `(N - m)` ones or vice-versa. | ||
|
|
||
| Implement a thermometer code detector. The module has two ports, `codeIn` and `isThermemeter`. The former is a `DATA_WIDTH`-bit unsigned binary word, and the latter is the signal that indicates whether or not the input is a thermometer code. The circuit must support both types of thermometer representations. For instance, for an input word that is `N`-bit long, the detector must detect thermometer representations that use `m` zeros followed by `(N - m)` ones or `m` ones followed by `(N - m)` zeros. Output `isThermemeter` is one when a thermometer word is detected at the input and zero otherwise. |
There was a problem hiding this comment.
The word "isThermemeter" is misspelled. It should be "isThermometer".
Comment on lines
+1
to
+12
| # 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 |
There was a problem hiding this comment.
The title "Quest 5 - Reversing Bits" does not match the file content. The description discusses Gray Code conversion, but the title suggests bit reversal. This appears to be incorrectly copied from another quest.
Suggested change
| # 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 | |
| # Quest 5 - Gray Code Converter | |
| ## Original Problem Statement | |
| ### Prompt | |
| Implement a sequential Gray code counter that outputs the Gray code representation of an internal binary count value. | |
| ### Input and Output Signals | |
| `clk` - Clock input | |
| `rst` - Synchronous or asynchronous reset (implementation-specific) | |
| `dout` - Gray-coded output value corresponding to the current counter state |
| @@ -0,0 +1,46 @@ | |||
| # Quest 4 - Gray Code Counter | |||
There was a problem hiding this comment.
The title "Quest 4 - Gray Code Counter" does not match the file content. The description discusses bit reversal, but the title suggests Gray code counting. This appears to be incorrectly copied from another quest.
Suggested change
| # Quest 4 - Gray Code Counter | |
| # Quest 4 - Bit Reverser |
Comment on lines
+20
to
+22
| 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. |
There was a problem hiding this comment.
The description section contradicts the prompt. The prompt asks to "Reverse the bits of an input value's binary representation" but the description discusses "Sequential Gray code counter" which is unrelated to bit reversal.
Suggested change
| 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. | |
| Combinational circuit that reverses the bit order of the input word. | |
| For an N-bit input `din[N-1:0]`, the output `dout[N-1:0]` is defined by `dout[i] = din[N-1-i]` for all valid bit indices. | |
| This operation is a pure bit permutation (no arithmetic): the most significant bit of `din` becomes the least significant bit of `dout`, and so on for all bits. |
|
|
||
| Use the solutions to questions 22 & 24 (Full Adder and Ripper Carry Adder, respectively) to implement a 24-bit Carry Select Adder (CSA). CSAs commonly employ two Ripple Carry Adders (RCAs) which compute `a + b + cin`, where `cin = 0` in one computation, and `cin = 1` in the other. The final result is obtained by selecting the correct partial sum, based on the `cout` bit of the previous stage. | ||
|
|
||
| In this question, implement a 24-bit Carry Select Adder (CSA) using multiple parallel RCAs and multiplexers. The CSA module takes two unsigned integers `a` and `b`, and produces an output word `sum`, corresponding to `a + b` operation. The number of RCA stages in the CSA can be chosen by the designer, e.g., 3 stages of 8-bit RCAs, 4 stages of 6-bit RCAs, etc. Bonus: Can you design a parametric number of stage 24-bit CSA? Test your design with various number of RCA stages. |
There was a problem hiding this comment.
The word "correpond" is misspelled. It should be "correspond".
|
|
||
| Upon assertion of `resetn` (active-low), the FIFO is reset to zero and the `empty` signal is set to logic high to indicate the FIFO is empty. Once `resetn` is unpressed, the operation starts. The FIFO has a two-entry bank of flip-flops that can be written to by using inputs `din` (data in) and `wr` (write-enable). If `wr` is set to logic low, the input `din` does not get written to the FIFO. | ||
|
|
||
| As the FIFO is being written to, its output port `dout` should imediatelly reflect the first-in data, i.e., there should be no latency between inputs and outputs. Once all entries are written to, the FIFO should output `full = 1` in order to indicate it is full. Writing to a full FIFO is a valid operation and the output `full` must be set to one. |
There was a problem hiding this comment.
The word "imediatelly" is misspelled. It should be "immediately".
Suggested change
| As the FIFO is being written to, its output port `dout` should imediatelly reflect the first-in data, i.e., there should be no latency between inputs and outputs. Once all entries are written to, the FIFO should output `full = 1` in order to indicate it is full. Writing to a full FIFO is a valid operation and the output `full` must be set to one. | |
| As the FIFO is being written to, its output port `dout` should immediately reflect the first-in data, i.e., there should be no latency between inputs and outputs. Once all entries are written to, the FIFO should output `full = 1` in order to indicate it is full. Writing to a full FIFO is a valid operation and the output `full` must be set to one. |
|
|
||
| ### Prompt | ||
|
|
||
| Design a simple 1-read/write (1RW) register file (RF) by using a multidimentional array of flip-flops in Verilog. |
There was a problem hiding this comment.
The word "multidimentional" is misspelled. It should be "multidimensional".
Suggested change
| Design a simple 1-read/write (1RW) register file (RF) by using a multidimentional array of flip-flops in Verilog. | |
| Design a simple 1-read/write (1RW) register file (RF) by using a multidimensional array of flip-flops in Verilog. |
Comment on lines
+36
to
+37
| 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. |
There was a problem hiding this comment.
The description section contradicts the prompt. The prompt asks to "Build a circuit that generates a Gray code sequence" but the description discusses "Combinational bit-reversal circuit" which is unrelated to Gray code generation.
Suggested change
| 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. | |
| Synchronous Gray code counter that advances to the next Gray code value on each rising edge of `clk`. | |
| When `resetn` is asserted low, the counter synchronously resets so that `out` returns to 0 and the standard Gray code sequence restarts from the beginning. |
| * **Script execution environment**: | ||
| - **VHDL Simulator**: (Anything that supports **VHDL-2008**): | ||
| - **Script execution environment**: | ||
| - `Python 3.11.4` to automatise testing via **VUnit** |
There was a problem hiding this comment.
The word "automatise" should be "automate" in American English, which is the standard used throughout the rest of the documentation.
Suggested change
| - `Python 3.11.4` to automatise testing via **VUnit** | |
| - `Python 3.11.4` to automate testing via **VUnit** |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #14