Repository navigation
feat(rocjitsu): Add a pipeline latch and IssueQueue for clocked components #14308
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.
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| // Copyright (c) 2026 Advanced Micro Devices, Inc. | ||
| // SPDX-License-Identifier: MIT | ||
|
|
||
| /// @file issue_queue.h | ||
| /// @brief In-order queue whose entries leave once their ready cycle arrives. | ||
|
|
||
| #pragma once | ||
|
|
||
| #include <cassert> | ||
| #include <cstdint> | ||
| #include <deque> | ||
| #include <utility> | ||
|
|
||
| namespace simdojo { | ||
|
|
||
| /// @brief Entries that wait, in order, until the cycle each becomes ready. | ||
| /// | ||
| /// @details A producer push()es an entry with the first cycle it may leave; | ||
| /// the consumer pop()s the oldest entry once ready() says that cycle has | ||
| /// arrived. An entry never overtakes an older one. Cycles count the owning | ||
| /// component's clock and never decrease. | ||
| /// | ||
| /// @code | ||
| /// producer -- push(value, ready_cycle) --> [ oldest ... youngest ] -- pop() --> consumer | ||
| /// ^ ready(cycle) | ||
| /// @endcode | ||
| /// | ||
| /// A fixed-latency pipeline pushes each entry with the current cycle plus its | ||
| /// latency. An entry pushed with a later ready cycle than the current one is | ||
| /// not visible in the current cycle, so the stages of one cycle may run in | ||
| /// any order. | ||
| /// | ||
| /// @tparam T Entry type. It must be movable. | ||
| template <typename T> class IssueQueue { | ||
| public: | ||
| /// @brief Add @p value behind every entry already queued; it may leave from @p ready_cycle. | ||
| void push(T value, uint64_t ready_cycle) { entries_.push_back({std::move(value), ready_cycle}); } | ||
|
|
||
| /// @brief Whether the oldest entry may leave in @p cycle. | ||
| bool ready(uint64_t cycle) const { | ||
| return !entries_.empty() && entries_.front().ready_cycle <= cycle; | ||
| } | ||
|
|
||
| /// @brief Remove and return the oldest entry. | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It would help to state here that |
||
| /// @pre The queue is not empty. | ||
| T pop() { | ||
| assert(!entries_.empty() && "issue queue is empty"); | ||
| T value = std::move(entries_.front().value); | ||
| entries_.pop_front(); | ||
| return value; | ||
| } | ||
|
|
||
| /// @brief Whether no entry is queued. | ||
| bool empty() const { return entries_.empty(); } | ||
|
|
||
| private: | ||
| struct Entry { | ||
| T value; | ||
| uint64_t ready_cycle; | ||
| }; | ||
| std::deque<Entry> entries_; | ||
| }; | ||
|
|
||
| } // namespace simdojo | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| // Copyright (c) 2026 Advanced Micro Devices, Inc. | ||
| // SPDX-License-Identifier: MIT | ||
|
|
||
| /// @file pipe_latch.h | ||
| /// @brief Pipeline latch between the stages of a clocked component. | ||
|
|
||
| #pragma once | ||
|
|
||
| #include <cassert> | ||
| #include <optional> | ||
| #include <utility> | ||
|
|
||
| namespace simdojo { | ||
|
|
||
| /// @brief A pipeline register between two stages of a clocked component. | ||
| /// | ||
| /// @details The producer stage write()s during a cycle; the owning component | ||
| /// calls clock() on the clock edge, after every stage has run; the consumer | ||
| /// stage take()s the value in the next cycle. | ||
| /// | ||
| /// @code | ||
| /// producer -- write() --> [ next ] -- clock() --> [ current ] -- take() --> consumer | ||
| /// @endcode | ||
| /// | ||
| /// Nothing written in a cycle is visible before the clock edge, so the stages | ||
| /// of one cycle may run in any order. clock() replaces whatever the consumer | ||
| /// did not take. | ||
| /// | ||
| /// @tparam T Value type. It must be movable. | ||
| template <typename T> class PipeLatch { | ||
| public: | ||
| /// @brief Write the value the latch captures on the next clock edge. | ||
| void write(T value) { next_ = std::move(value); } | ||
|
|
||
| /// @brief Whether a value latched on the last clock edge is waiting. | ||
| bool valid() const { return current_.has_value(); } | ||
|
|
||
| /// @brief Consume and return the latched value. | ||
| /// @pre valid(). | ||
| T take() { | ||
| assert(valid() && "pipe latch has no value for the consumer"); | ||
| T value = std::move(*current_); | ||
| current_.reset(); | ||
| return value; | ||
| } | ||
|
|
||
| /// @brief The clock edge: latch the value written this cycle. | ||
| void clock() { | ||
| current_ = std::move(next_); | ||
| next_.reset(); | ||
| } | ||
|
|
||
| /// @brief Whether no value is written or latched. | ||
| bool empty() const { return !current_ && !next_; } | ||
|
|
||
| private: | ||
| std::optional<T> next_; | ||
| std::optional<T> current_; | ||
| }; | ||
|
|
||
| } // namespace simdojo |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| // Copyright (c) 2026 Advanced Micro Devices, Inc. | ||
| // SPDX-License-Identifier: MIT | ||
|
|
||
| /// @file simdojo_issue_queue_test.cpp | ||
| /// @brief Tests for simdojo::IssueQueue: ready cycles and in-order departure. | ||
|
|
||
| #include "simdojo/components/issue_queue.h" | ||
|
|
||
| #include <gtest/gtest.h> | ||
|
|
||
| #include <cstdint> | ||
| #include <memory> | ||
| #include <utility> | ||
| #include <vector> | ||
|
|
||
| using namespace simdojo; | ||
|
|
||
| namespace { | ||
|
|
||
| TEST(IssueQueueTest, EntryLeavesFromItsReadyCycle) { | ||
| IssueQueue<int> queue; | ||
| EXPECT_TRUE(queue.empty()); | ||
| queue.push(7, 4); | ||
| EXPECT_FALSE(queue.empty()); | ||
| EXPECT_FALSE(queue.ready(3)); | ||
| ASSERT_TRUE(queue.ready(4)); | ||
| EXPECT_TRUE(queue.ready(5)); | ||
| EXPECT_EQ(queue.pop(), 7); | ||
| EXPECT_TRUE(queue.empty()); | ||
| EXPECT_FALSE(queue.ready(5)); | ||
| } | ||
|
|
||
| TEST(IssueQueueTest, FixedLatencySustainsOneEntryPerCycle) { | ||
| constexpr uint64_t kLatency = 3; | ||
| IssueQueue<int> queue; | ||
| std::vector<std::pair<uint64_t, int>> left; | ||
| for (uint64_t cycle = 0; cycle < 8; ++cycle) { | ||
| if (queue.ready(cycle)) | ||
| left.emplace_back(cycle, queue.pop()); | ||
| queue.push(static_cast<int>(cycle), cycle + kLatency); | ||
| } | ||
| const std::vector<std::pair<uint64_t, int>> expected{{3, 0}, {4, 1}, {5, 2}, {6, 3}, {7, 4}}; | ||
| EXPECT_EQ(left, expected); | ||
| } | ||
|
|
||
| TEST(IssueQueueTest, YoungerEntryWaitsBehindAnOlderOne) { | ||
| IssueQueue<int> queue; | ||
| queue.push(1, 10); | ||
| queue.push(2, 5); | ||
| EXPECT_FALSE(queue.ready(5)); | ||
| ASSERT_TRUE(queue.ready(10)); | ||
| EXPECT_EQ(queue.pop(), 1); | ||
| ASSERT_TRUE(queue.ready(10)); | ||
| EXPECT_EQ(queue.pop(), 2); | ||
| } | ||
|
|
||
| TEST(IssueQueueTest, CarriesMoveOnlyEntries) { | ||
| IssueQueue<std::unique_ptr<int>> queue; | ||
| queue.push(std::make_unique<int>(3), 1); | ||
| ASSERT_TRUE(queue.ready(1)); | ||
| auto value = queue.pop(); | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please spell out |
||
| ASSERT_NE(value, nullptr); | ||
| EXPECT_EQ(*value, 3); | ||
| } | ||
|
|
||
| } // namespace | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,135 @@ | ||
| // Copyright (c) 2026 Advanced Micro Devices, Inc. | ||
| // SPDX-License-Identifier: MIT | ||
|
|
||
| /// @file simdojo_pipe_latch_test.cpp | ||
| /// @brief Tests for simdojo::PipeLatch: the clock edge, and use between the | ||
| /// stages of a clocked component. | ||
|
|
||
| #include "simdojo/components/pipe_latch.h" | ||
| #include "simdojo/sim/clock_domain.h" | ||
| #include "simdojo/sim/clocked.h" | ||
| #include "simdojo/sim/simulation.h" | ||
|
|
||
| #include <gtest/gtest.h> | ||
|
|
||
| #include <cstdint> | ||
| #include <memory> | ||
| #include <string> | ||
| #include <utility> | ||
| #include <vector> | ||
|
|
||
| using namespace simdojo; | ||
|
|
||
| namespace { | ||
|
|
||
| TEST(PipeLatchTest, WrittenValueIsValidAfterTheClockEdge) { | ||
| PipeLatch<int> latch; | ||
| EXPECT_TRUE(latch.empty()); | ||
| latch.write(7); | ||
| EXPECT_FALSE(latch.valid()); | ||
| EXPECT_FALSE(latch.empty()); | ||
| latch.clock(); | ||
| ASSERT_TRUE(latch.valid()); | ||
| EXPECT_EQ(latch.take(), 7); | ||
| EXPECT_FALSE(latch.valid()); | ||
| EXPECT_TRUE(latch.empty()); | ||
| } | ||
|
|
||
| TEST(PipeLatchTest, EdgeWithoutAWriteLatchesNothing) { | ||
| PipeLatch<int> latch; | ||
| latch.write(1); | ||
| latch.clock(); | ||
| latch.clock(); | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It would be good to add an unread-value replacement test: |
||
| EXPECT_FALSE(latch.valid()); | ||
| EXPECT_TRUE(latch.empty()); | ||
| } | ||
|
|
||
| TEST(PipeLatchTest, WriteAndTakeInTheSameCycle) { | ||
| PipeLatch<int> latch; | ||
| latch.write(1); | ||
| latch.clock(); | ||
| latch.write(2); | ||
| EXPECT_EQ(latch.take(), 1); | ||
| EXPECT_FALSE(latch.valid()); | ||
| latch.clock(); | ||
| EXPECT_EQ(latch.take(), 2); | ||
| } | ||
|
|
||
| TEST(PipeLatchTest, CarriesMoveOnlyValues) { | ||
| PipeLatch<std::unique_ptr<int>> latch; | ||
| latch.write(std::make_unique<int>(3)); | ||
| latch.clock(); | ||
| auto value = latch.take(); | ||
| ASSERT_NE(value, nullptr); | ||
| EXPECT_EQ(*value, 3); | ||
| } | ||
|
|
||
| /// A three-stage pipeline (source -> double -> sink) built from two latches. | ||
| /// Each stage runs once per cycle, front-to-back or back-to-front, and the | ||
| /// latches are clocked after all of them. | ||
| class ThreeStagePipeline : public Clocked<Component> { | ||
| public: | ||
| ThreeStagePipeline(const ClockDomain &domain, int count, bool back_to_front) | ||
| : Clocked<Component>("pipeline", domain), count_(count), back_to_front_(back_to_front) {} | ||
|
|
||
| bool advance(Tick) override { | ||
| if (back_to_front_) { | ||
| sink(); | ||
| double_stage(); | ||
| source(); | ||
| } else { | ||
| source(); | ||
| double_stage(); | ||
| sink(); | ||
| } | ||
| source_to_double_.clock(); | ||
| double_to_sink_.clock(); | ||
| ++cycle_; | ||
| return next_ < count_ || !source_to_double_.empty() || !double_to_sink_.empty(); | ||
| } | ||
|
|
||
| std::vector<std::pair<uint64_t, int>> arrivals; ///< (cycle, value) at the sink. | ||
|
|
||
| private: | ||
| void source() { | ||
| if (next_ < count_) | ||
| source_to_double_.write(next_++); | ||
| } | ||
| void double_stage() { | ||
| if (source_to_double_.valid()) | ||
| double_to_sink_.write(2 * source_to_double_.take()); | ||
| } | ||
| void sink() { | ||
| if (double_to_sink_.valid()) | ||
| arrivals.emplace_back(cycle_, double_to_sink_.take()); | ||
| } | ||
|
|
||
| PipeLatch<int> source_to_double_; | ||
| PipeLatch<int> double_to_sink_; | ||
| int count_; | ||
| int next_ = 0; | ||
| uint64_t cycle_ = 0; | ||
| bool back_to_front_; | ||
| }; | ||
|
|
||
| std::vector<std::pair<uint64_t, int>> run_pipeline(int count, bool back_to_front) { | ||
| ClockDomain domain("clk", 1'000'000'000); | ||
| SimulationEngine engine({.num_threads = 1}); | ||
| auto root = std::make_unique<CompositeComponent>("root"); | ||
| auto *pipeline = static_cast<ThreeStagePipeline *>( | ||
| root->add_child(std::make_unique<ThreeStagePipeline>(domain, count, back_to_front))); | ||
| engine.topology().set_root(std::move(root)); | ||
| engine.create(); | ||
| const ExitStatus exit = engine.run(); | ||
| EXPECT_EQ(exit.reason, ExitReason::COMPLETED); | ||
| return pipeline->arrivals; | ||
| } | ||
|
|
||
| TEST(PipeLatchTest, ClockedPipelineMovesOneStagePerCycleInEitherOrder) { | ||
| // Written in cycle c, a value is doubled in c + 1 and sunk in c + 2. | ||
| const std::vector<std::pair<uint64_t, int>> expected{{2, 0}, {3, 2}, {4, 4}, {5, 6}}; | ||
| EXPECT_EQ(run_pipeline(4, false), expected); | ||
| EXPECT_EQ(run_pipeline(4, true), expected); | ||
| } | ||
|
|
||
| } // namespace | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should name this for its timed FIFO behavior, for example
DelayQueue. It releases entries in insertion order using a fixed ready-cycle stamp; it does not select among ready instructions or track later changes to a wave's readiness. A behavior-based name would make its role clearer for execution delays and memory returns, and distinguish it from the CU's scheduling policy before the follow-up PRs adopt it.