Skip to content

Add documentation for FIFO queue component #434

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Nihal4777 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add documentation for FIFO queue component #434

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions docs/chapter4/6sequentialelements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ CircuitVerse features the following circuit elements in this category:
- [ROM](#rom)
- [RAM](#ram)
- [EEPROM](#eeprom)
- [FIFO Queue](#fifo-queue)

## D Flip Flop

Expand Down Expand Up @@ -586,3 +587,86 @@ You can verify the behavior of the EEPROM circuit element in the live circuit em
>
{" "}
</iframe>

## FIFO Queue

The **FIFO Queue** circuit element simulates a hardware queue that follows the *First-In-First-Out* principle. It temporarily stores input data and allows retrieval in the same order it was received. Users can enqueue (`ENQ`) and dequeue (`DEQ`) data values, reset the entire queue (`RST`), and monitor its current state via `EMP` (Empty) and `FULL` indicators.

> Properties that can be customized in the **PROPERTIES** panel include: **Direction, BitWidth, Depth**

### Functionality
The queue operation is clock-driven and updates happen on the rising edge of the `CLK` input:

- When `ENQ` is HIGH, the value on `D` is stored into the queue (if not full).
- When `DEQ` is HIGH, the next value is output from the queue (if not empty).
- If `RST` is HIGH during a clock edge, the queue is cleared.
- Output indicators reflect queue state (`EMP` = empty, `FULL` = full).

Comment on lines +599 to +604
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Document concurrent ENQ + DEQ behaviour

When both ENQ and DEQ are asserted on the same rising clock edge, what happens? Users will inevitably try this. Add one sentence clarifying whether the queue performs a “pass-through”, prioritises one action, or treats it as undefined.

🤖 Prompt for AI Agents 
In docs/chapter4/6sequentialelements.md around lines 599 to 604, add a sentence
explaining the behavior when both ENQ and DEQ are asserted simultaneously on the
same rising clock edge. Clarify if the queue performs a pass-through,
prioritizes one action over the other, or treats this condition as undefined to
guide users on expected behavior.

---

### Table: Pin Description of FIFO Queue

<table>
<tr>
<td><strong>Pin</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>D</td>
<td>Input data to be enqueued into the queue</td>
</tr>
<tr>
<td>ENQ</td>
<td>Trigger to enqueue current input (rising edge CLK)</td>
</tr>
<tr>
<td>DEQ</td>
<td>Trigger to dequeue and output next value (rising edge CLK)</td>
</tr>
<tr>
<td>RST</td>
<td>Resets and clears the entire queue</td>
</tr>
<tr>
<td>CLK</td>
<td>Clock input; operations occur on rising edge</td>
</tr>
<tr>
<td>Q</td>
<td>Output data from the front of the queue</td>
</tr>
<tr>
<td>EMP</td>
<td>High (1) when the queue is empty</td>
</tr>
<tr>
<td>FULL</td>
<td>High (1) when the queue is full</td>
</tr>
</table>

---

### Depth Property

The `Depth` property controls the **maximum number of entries** the queue can hold. It can be changed via the **PROPERTIES** panel.

> Default depth is `8`. You can set custom values as needed.

---

### Example

Below is a live example of the **FIFO Queue** in operation. Try toggling `ENQ`, `DEQ`, and `RST` inputs while observing the output (`Q`) and status flags (`EMP`, `FULL`):

<iframe
width="600px"
height="400px"
src="https://circuitverse.org/simulator/embed/<INSERT_PROJECT_ID>"
Comment on lines +662 to +665
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Replace the <INSERT_PROJECT_ID> placeholder or drop the iframe

Leaving the placeholder breaks the embed and renders a 404. Either supply a real public example ID or remove the iframe until one is available.

-src="https://circuitverse.org/simulator/embed/<INSERT_PROJECT_ID>"
+src="https://circuitverse.org/simulator/embed/REPLACE_WITH_VALID_PROJECT_ID"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<iframe
width="600px"
height="400px"
src="https://circuitverse.org/simulator/embed/<INSERT_PROJECT_ID>"
<iframe
width="600px"
height="400px"
src="https://circuitverse.org/simulator/embed/REPLACE_WITH_VALID_PROJECT_ID"
>
</iframe>
🤖 Prompt for AI Agents 
In docs/chapter4/6sequentialelements.md around lines 662 to 665, the iframe src
attribute contains a placeholder <INSERT_PROJECT_ID> which causes a 404 error
when rendered. Replace this placeholder with a valid public project ID from
circuitverse.org to ensure the embed works correctly, or remove the entire
iframe element if no valid project ID is available yet.

id="projectPreview"
scrolling="no"
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
>
</iframe>