use super::interconnect::InterconnectTopology;
use crate::device::substrate::{Substrate, SubstrateCapability, SubstrateType};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransferStrategy {
PeerToPeer,
HostBounce,
None,
}
#[derive(Debug, Clone)]
pub struct StageWorkload {
pub name: String,
pub required_capabilities: Vec<SubstrateCapability>,
}
impl StageWorkload {
pub fn new(name: impl Into<String>, caps: Vec<SubstrateCapability>) -> Self {
Self {
name: name.into(),
required_capabilities: caps,
}
}
}
#[derive(Debug)]
pub struct PipelineStage {
pub name: String,
pub workload: StageWorkload,
pub output_bytes: u64,
pub fallback: FallbackPolicy,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FallbackPolicy {
Degrade,
Skip,
Fail,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StageResolution {
Optimal,
Degraded,
Skipped,
}
#[derive(Debug)]
pub struct ResolvedStage<'a> {
pub stage: &'a PipelineStage,
pub substrate: Option<&'a Substrate>,
pub transfer: TransferStrategy,
pub transfer_cost_us: u64,
pub reason: StageResolution,
}
#[derive(Debug)]
pub struct SubstratePipeline {
pub name: String,
pub stages: Vec<PipelineStage>,
}
#[derive(Debug)]
pub struct ResolvedPipeline<'a> {
pub name: &'a str,
pub stages: Vec<ResolvedStage<'a>>,
pub total_transfer_us: u64,
pub fully_optimal: bool,
}
impl SubstratePipeline {
pub fn new(name: impl Into<String>) -> Self {
Self {
name: name.into(),
stages: Vec::new(),
}
}
#[must_use]
pub fn stage(mut self, stage: PipelineStage) -> Self {
self.stages.push(stage);
self
}
#[must_use]
pub fn plan<'a>(
&'a self,
substrates: &'a [Substrate],
topology: &InterconnectTopology,
) -> ResolvedPipeline<'a> {
let mut resolved_stages = Vec::with_capacity(self.stages.len());
let mut total_transfer_us = 0u64;
let mut fully_optimal = true;
let mut prev_substrate_idx: Option<usize> = None;
for stage in &self.stages {
let (substrate, reason) = match route_workload(&stage.workload, substrates) {
Some((idx, sub)) => {
let _ = idx;
(Some(sub), StageResolution::Optimal)
}
None => match stage.fallback {
FallbackPolicy::Degrade => {
let degraded = find_cpu_fallback(substrates);
if degraded.is_some() {
fully_optimal = false;
}
(degraded, StageResolution::Degraded)
}
FallbackPolicy::Skip => {
fully_optimal = false;
(None, StageResolution::Skipped)
}
FallbackPolicy::Fail => (None, StageResolution::Optimal),
},
};
let (transfer, transfer_cost) =
if let (Some(prev_idx), Some(sub)) = (prev_substrate_idx, substrate) {
let curr_idx = substrates
.iter()
.position(|s| std::ptr::eq(s, sub))
.unwrap_or(0);
if prev_idx == curr_idx {
(TransferStrategy::None, 0)
} else {
let prev_output = resolved_stages
.last()
.map_or(0, |rs: &ResolvedStage<'_>| rs.stage.output_bytes);
let link = topology.best_link(prev_idx, curr_idx);
let cost = link.map_or(0, |l| l.tier.transfer_time_us(prev_output));
let strategy = link.map_or(TransferStrategy::HostBounce, |l| {
if l.tier.is_peer_to_peer() {
TransferStrategy::PeerToPeer
} else {
TransferStrategy::HostBounce
}
});
(strategy, cost)
}
} else {
(TransferStrategy::None, 0)
};
total_transfer_us += transfer_cost;
if let Some(sub) = substrate {
prev_substrate_idx = substrates.iter().position(|s| std::ptr::eq(s, sub));
}
resolved_stages.push(ResolvedStage {
stage,
substrate,
transfer,
transfer_cost_us: transfer_cost,
reason,
});
}
ResolvedPipeline {
name: &self.name,
stages: resolved_stages,
total_transfer_us,
fully_optimal,
}
}
}
impl PipelineStage {
pub fn new(name: impl Into<String>, workload: StageWorkload, output_bytes: u64) -> Self {
Self {
name: name.into(),
workload,
output_bytes,
fallback: FallbackPolicy::Degrade,
}
}
#[must_use]
pub const fn with_fallback(mut self, policy: FallbackPolicy) -> Self {
self.fallback = policy;
self
}
}
impl ResolvedPipeline<'_> {
#[must_use]
pub fn all_assigned(&self) -> bool {
self.stages.iter().all(|s| s.substrate.is_some())
}
#[must_use]
pub fn p2p_transfer_count(&self) -> usize {
self.stages
.iter()
.filter(|s| s.transfer == TransferStrategy::PeerToPeer)
.count()
}
#[must_use]
pub fn degraded_count(&self) -> usize {
self.stages
.iter()
.filter(|s| s.reason == StageResolution::Degraded)
.count()
}
pub fn print_summary(&self) {
tracing::info!("Pipeline: {}", self.name);
tracing::info!(
" Stages: {} | Transfer overhead: {}µs | Optimal: {}",
self.stages.len(),
self.total_transfer_us,
self.fully_optimal,
);
for (i, rs) in self.stages.iter().enumerate() {
let sub_name = rs.substrate.map_or("(skipped)", |s| s.name.as_str());
let transfer_str = match rs.transfer {
TransferStrategy::PeerToPeer => "←P2P←",
TransferStrategy::HostBounce => "←HOST←",
TransferStrategy::None => "",
};
tracing::info!(
" [{i}] {:<30} → {:<20} {transfer_str} ({:?})",
rs.stage.name,
sub_name,
rs.reason,
);
}
}
}
fn route_workload<'a>(
workload: &StageWorkload,
substrates: &'a [Substrate],
) -> Option<(usize, &'a Substrate)> {
let mut best: Option<(usize, &Substrate, u32)> = None;
for (idx, sub) in substrates.iter().enumerate() {
if workload
.required_capabilities
.iter()
.all(|cap| sub.has(cap))
{
let priority = match sub.substrate_type {
SubstrateType::DiscreteGpu => 100,
SubstrateType::IntegratedGpu => 80,
SubstrateType::Npu => 70,
SubstrateType::Cpu => 10,
SubstrateType::Other => 5,
};
if best.as_ref().is_none_or(|(_, _, p)| priority > *p) {
best = Some((idx, sub, priority));
}
}
}
best.map(|(idx, sub, _)| (idx, sub))
}
fn find_cpu_fallback(substrates: &[Substrate]) -> Option<&Substrate> {
substrates
.iter()
.find(|s| s.substrate_type == SubstrateType::Cpu)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::device::substrate::SubstrateCapability;
fn gpu_sub() -> Substrate {
Substrate {
substrate_type: SubstrateType::DiscreteGpu,
name: "Test GPU".to_string(),
backend: "Vulkan".to_string(),
index: 0,
capabilities: vec![
SubstrateCapability::F64Compute,
SubstrateCapability::ShaderDispatch,
SubstrateCapability::ScalarReduce,
],
}
}
fn npu_sub() -> Substrate {
Substrate {
substrate_type: SubstrateType::Npu,
name: "BrainChip AKD1000".to_string(),
backend: "PCIe".to_string(),
index: 0,
capabilities: vec![
SubstrateCapability::QuantizedInference { bits: 8 },
SubstrateCapability::BatchInference { max_batch: 8 },
],
}
}
fn cpu_sub() -> Substrate {
Substrate {
substrate_type: SubstrateType::Cpu,
name: "Test CPU".to_string(),
backend: "native".to_string(),
index: 0,
capabilities: vec![
SubstrateCapability::F64Compute,
SubstrateCapability::F32Compute,
],
}
}
#[test]
fn pipeline_plans_npu_then_gpu() {
let subs = vec![gpu_sub(), npu_sub(), cpu_sub()];
let topo = InterconnectTopology::infer(&subs);
let pipeline = SubstratePipeline::new("NPU classify → GPU refine")
.stage(PipelineStage::new(
"NPU classify",
StageWorkload::new(
"classify",
vec![SubstrateCapability::QuantizedInference { bits: 8 }],
),
1024,
))
.stage(PipelineStage::new(
"GPU Lyapunov",
StageWorkload::new(
"lyapunov",
vec![
SubstrateCapability::F64Compute,
SubstrateCapability::ShaderDispatch,
],
),
8192,
));
let resolved = pipeline.plan(&subs, &topo);
assert!(resolved.all_assigned());
assert_eq!(resolved.stages.len(), 2);
assert_eq!(
resolved.stages[0].substrate.unwrap().substrate_type,
SubstrateType::Npu
);
assert_eq!(
resolved.stages[1].substrate.unwrap().substrate_type,
SubstrateType::DiscreteGpu
);
}
#[test]
fn pipeline_degrades_when_npu_missing() {
let subs = vec![gpu_sub(), cpu_sub()];
let topo = InterconnectTopology::infer(&subs);
let pipeline = SubstratePipeline::new("degrade test").stage(
PipelineStage::new(
"NPU classify",
StageWorkload::new(
"classify",
vec![SubstrateCapability::QuantizedInference { bits: 8 }],
),
1024,
)
.with_fallback(FallbackPolicy::Degrade),
);
let resolved = pipeline.plan(&subs, &topo);
assert!(resolved.all_assigned());
assert_eq!(resolved.degraded_count(), 1);
assert_eq!(
resolved.stages[0].substrate.unwrap().substrate_type,
SubstrateType::Cpu
);
}
#[test]
fn pipeline_skips_when_policy_is_skip() {
let subs = vec![cpu_sub()];
let topo = InterconnectTopology::infer(&subs);
let pipeline = SubstratePipeline::new("skip test").stage(
PipelineStage::new(
"GPU work",
StageWorkload::new(
"gpu_only",
vec![
SubstrateCapability::F64Compute,
SubstrateCapability::ShaderDispatch,
],
),
4096,
)
.with_fallback(FallbackPolicy::Skip),
);
let resolved = pipeline.plan(&subs, &topo);
assert!(!resolved.all_assigned());
assert!(resolved.stages[0].substrate.is_none());
assert_eq!(resolved.stages[0].reason, StageResolution::Skipped);
}
#[test]
fn pipeline_fully_optimal_when_all_match() {
let subs = vec![gpu_sub(), cpu_sub()];
let topo = InterconnectTopology::infer(&subs);
let pipeline = SubstratePipeline::new("optimal").stage(PipelineStage::new(
"GPU work",
StageWorkload::new(
"compute",
vec![
SubstrateCapability::F64Compute,
SubstrateCapability::ShaderDispatch,
],
),
4096,
));
let resolved = pipeline.plan(&subs, &topo);
assert!(resolved.fully_optimal);
}
#[test]
fn empty_pipeline_plans_ok() {
let subs = vec![cpu_sub()];
let topo = InterconnectTopology::infer(&subs);
let pipeline = SubstratePipeline::new("empty");
let resolved = pipeline.plan(&subs, &topo);
assert!(resolved.all_assigned());
assert!(resolved.fully_optimal);
assert_eq!(resolved.total_transfer_us, 0);
}
#[test]
fn same_substrate_no_transfer() {
let subs = vec![gpu_sub(), cpu_sub()];
let topo = InterconnectTopology::infer(&subs);
let pipeline = SubstratePipeline::new("GPU→GPU")
.stage(PipelineStage::new(
"first",
StageWorkload::new(
"a",
vec![
SubstrateCapability::F64Compute,
SubstrateCapability::ShaderDispatch,
],
),
4096,
))
.stage(PipelineStage::new(
"second",
StageWorkload::new(
"b",
vec![
SubstrateCapability::F64Compute,
SubstrateCapability::ShaderDispatch,
],
),
4096,
));
let resolved = pipeline.plan(&subs, &topo);
assert_eq!(resolved.stages[1].transfer, TransferStrategy::None);
assert_eq!(resolved.stages[1].transfer_cost_us, 0);
}
}