Merge pull request #1072 from bittide/lucas/add-component-diagrams

Add diagrams and mdbook entries fo s/g units and calendar

Author: lmbollen

docs/SUMMARY.md

@@ -13,3 +13,7 @@ SPDX-License-Identifier: Apache-2.0
 - [Soft UGN Demo](sections/soft-ugn-demo.md)
 - [Switch Demo with ASIC](sections/switch-demo-asic.md)
 - [Switch Demo with GPPE](sections/switch-demo-gppe.md)
+- [Components](sections/components.md)
+  - [Calendar](sections/components/calendar.md)
+  - [Scatter Unit](sections/components/scatter-unit.md)
+  - [Gather Unit](sections/components/gather-unit.md)

docs/diagrams/components.drawio

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2025 Google LLC
+
+SPDX-License-Identifier: CC0-1.0

docs/diagrams/components.drawio.license

@@ -0,0 +1,16 @@
+<!--
+SPDX-FileCopyrightText: 2025 Google LLC
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Components
+
+This section provides an overview of the main hardware components in the Bittide system. Each component plays a specific role in enabling efficient, synchronized, and flexible operation of the hardware platform.
+
+## Available Components
+
+- [Calendar](components/calendar.md)
+- [Scatter Unit](components/scatter-unit.md)
+- [Gather Unit](components/gather-unit.md)
+- [Switch](components/switch.md)

docs/sections/components.md

@@ -0,0 +1,38 @@
+<!--
+SPDX-FileCopyrightText: 2025 Google LLC
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+## Calendar
+
+The Calendar component is a programmable state machine that drives the configuration of other components (like the Scatter Unit, Gather Unit, or Switch) on a cycle-by-cycle basis. It allows for time-division multiplexing of resources by cycling through a sequence of pre-programmed configurations.
+
+### Architecture
+
+{{#drawio path="diagrams/components.drawio" page=2}}
+
+The Calendar consists of two memories (buffers) to allow for double-buffering: an **active** calendar and a **shadow** calendar.
+- The **active** calendar drives the output signals to the target component.
+- The **shadow** calendar can be reconfigured via the Wishbone interface without interrupting the operation of the active calendar.
+
+The active and shadow calendars can be swapped at the end of a **metacycle**. A metacycle is one full iteration through the active calendar's entries, including all repetitions.
+
+### Operation
+
+Each entry in the calendar consists of:
+1.  **Configuration Data**: The actual control signals for the target component.
+2.  **Repetition Count**: The number of additional cycles this configuration should remain active.
+    - `0`: The entry is valid for 1 cycle.
+    - `N`: The entry is valid for `N + 1` cycles.
+
+The Calendar iterates through the entries in the active buffer. When it reaches the end of the active buffer (determined by the configured depth), it loops back to the beginning, completing a metacycle.
+
+### Double Buffering and Swapping
+
+To update the schedule:
+1.  Software writes new entries into the **shadow** calendar using the Wishbone interface.
+2.  Software configures the depth of the shadow calendar.
+3.  Software arms the swap mechanism by writing to the `swapActive` register.
+
+The swap does not happen immediately. It occurs only when the active calendar completes its current metacycle. This ensures that the schedule is always switched at a deterministic point, preventing glitches or partial schedules.

docs/sections/components/calendar.md

@@ -0,0 +1,36 @@
+<!--
+SPDX-FileCopyrightText: 2025 Google LLC
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+## Gather Unit
+
+The Gather Unit is a hardware component designed to transmit data frames over a Bittide link. It uses a double-buffered memory architecture and a configurable **Calendar** to determine which data to send in each cycle. This ensures deterministic data transmission.
+
+### Architecture
+
+{{#drawio path="diagrams/components.drawio" page=1}}
+
+The Gather Unit consists of:
+-   **Double-Buffered Memory**: Two memory buffers (Active and Shadow).
+    -   **Active Buffer**: Provides data to the Bittide link.
+    -   **Shadow Buffer**: Can be written to by the CPU via the Wishbone interface.
+-   **Calendar**: Determines the read address in the Active Buffer for each outgoing frame.
+-   **Wishbone Interface**: Allows the CPU to write data to be transmitted and monitor metacycle progress.
+
+### Operation
+
+1.  **Data Transmission**:
+    -   Each clock tick, the **Calendar** provides the read address for the Active Buffer.
+    -   The data at that address is read from the Active Buffer and sent over the Bittide link.
+
+2.  **Buffer Swapping**:
+    -   The Active and Shadow buffers are swapped at end of each **metacycle**.
+    -   A metacycle is defined by the Calendar's schedule.
+    -   After the swap, the data that was written by the CPU becomes the active data being transmitted.
+
+3.  **CPU Access**:
+    -   The CPU writes the data to the Shadow Buffer using the Wishbone interface.
+    -   **Byte Enables**: The Wishbone interface is 32-bit, but the Gather Unit memory is 64-bit. The hardware uses the byte enables to allow writing to the upper or lower 32 bits of the 64-bit memory words.
+    -   To ensure data consistency, the CPU can synchronize with the metacycle using the stalling mechanism.

docs/sections/components/gather-unit.md

@@ -0,0 +1,35 @@
+<!--
+SPDX-FileCopyrightText: 2025 Google LLC
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+## Scatter Unit
+
+The Scatter Unit is a hardware component designed to receive data frames from a Bittide link and store them into a local memory. It uses a double-buffered memory architecture and a configurable **Calendar** to determine the write address for each incoming frame. This allows for cycle-accurate, deterministic data reception.
+
+### Architecture
+
+{{#drawio path="diagrams/components.drawio" page=0}}
+
+The Scatter Unit consists of:
+-   **Double-Buffered Memory**: Two memory buffers (Active and Shadow).
+    -   **Active Buffer**: Receives data from the Bittide link.
+    -   **Shadow Buffer**: Can be read by the CPU via the Wishbone interface.
+-   **Calendar**: Determines the write address in the Active Buffer for each incoming frame.
+-   **Wishbone Interface**: Allows the CPU to read received data and monitor metacycle progress.
+
+### Operation
+
+1.  **Data Reception**:
+    -   In each cycle, if a valid frame arrives from the Bittide link, the **Calendar** provides the write address for the Active Buffer.
+    -   The frame is written to the Active Buffer at that address.
+
+2.  **Buffer Swapping**:
+    -   The Active and Shadow buffers are swapped at end of each **metacycle**.
+    -   A metacycle is defined by the Calendar's schedule.
+    -   After the swap, the data that was just received becomes available in the Shadow Buffer for the CPU to read.
+
+3.  **CPU Access**:
+    -   The CPU reads the data from the Shadow Buffer using the Wishbone interface.
+    -   To ensure data consistency, the CPU can synchronize with the metacycle using the stalling mechanism.