sim_ring/lib.rs
1// Copyright (c) 2025 Graphcore Ltd. All rights reserved.
2
3//! Simulate a device comprising ring nodes.
4//!
5//! The model is constructed with as many ring nodes as specified by
6//! the user. Each ring node will receive Ethernet Frames from a source
7//! that should be routed all the way around the ring and end up at
8//! the node effectively to its left.
9//!
10//! Limiters and flow control pipes are added to model actual hardware
11//! limitations.
12//!
13//! The ring node contains an arbiter used to decide which frame to
14//! grant next; the next ring frame or a new frame from the source.
15//! The ring priority can be configured to demonstrate that incorrect
16//! priority will lead to deadlock.
17//!
18//! # Examples
19//!
20//! Running a ring node that will lock up:
21//! ```txt
22//! cargo run --bin sim-ring --release -- --kib-to-send 1024 --stdout
23//! ```
24//!
25//! But with increased ring priority the same model will pass:
26//! ```txt
27//! cargo run --bin sim-ring --release -- --kib-to-send 1024 --ring-priority 10 --stdout
28//! ```
29//!
30//! # Diagram
31//!
32//! ```text
33//! /------------------------------------------------------------\
34//! | |
35//! | +--------+ +--------+ |
36//! | | Source | | Source | |
37//! | +--------+ +--------+ |
38//! | | | |
39//! | v v |
40//! | +---------+ +---------+ |
41//! | | Limiter | | Limiter | |
42//! | +---------+ +---------+ |
43//! | | | |
44//! | v v |
45//! | +--------+ +--------+ |
46//! | | FcPipe | | FcPipe | |
47//! | +--------+ +--------+ |
48//! | | | |
49//! | v v |
50//! | +----------+ +---------+ +--------+ +----------+ |
51//! \->| RingNode |->| Limiter |->| FcPipe |->| RingNode | ... -/
52//! +----------+ +---------+ +--------+ +----------+
53//! | |
54//! v v
55//! +---------+ +---------+
56//! | Limiter | | Limiter |
57//! +---------+ +---------+
58//! | |
59//! v v
60//! +------+ +------+
61//! | Sink | | Sink |
62//! +------+ +------+
63//! ```
64
65pub mod frame_gen;
66pub mod ring_builder;