Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
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 {

Copy link
Copy Markdown
Member

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.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

It would help to state here that pop() does not check readiness and callers must check ready(cycle) before a timed departure. The class describes that protocol, but this method's only listed precondition is non-emptiness, and pop() will also return an entry before its ready cycle. Making the caller's responsibility explicit beside the operation would clarify the timing contract without changing the API.

/// @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
2 changes: 2 additions & 0 deletions emulation/rocjitsu/tests/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -412,6 +412,8 @@ add_executable(
sparse_memory_test.cpp
cpu_dispatch_pool_test.cpp
simdojo_sim_test.cpp
simdojo_pipe_latch_test.cpp
simdojo_issue_queue_test.cpp
partitioning_test.cpp
simulated_kfd_test.cpp
kfd_events_test.cpp
Expand Down
66 changes: 66 additions & 0 deletions emulation/rocjitsu/tests/simdojo_issue_queue_test.cpp
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();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Please spell out std::unique_ptr<int> value = queue.pop(); here. This makes the move-only result type visible at the assertion and follows docs/style.md's rule against function-return auto when the type is not apparent on the same line.

ASSERT_NE(value, nullptr);
EXPECT_EQ(*value, 3);
}

} // namespace
135 changes: 135 additions & 0 deletions emulation/rocjitsu/tests/simdojo_pipe_latch_test.cpp
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();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

It would be good to add an unread-value replacement test: write(1); clock(); write(2); clock(); should make take() return 2. The current tests cover a bubble replacing an unread value, but consume the old value before testing replacement with another value. A scratch mutation that retained the old value when both slots were populated still passed all five latch tests. The implementation is correct; this test would protect its documented overwrite behavior.

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
Loading