1use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
12
13#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
14use std::sync::OnceLock;
15
16#[cfg(test)]
17mod migration_contract_tests;
18mod reservation;
19pub use reservation::{GraphicsReservationError, VramReservation, VramResourceClass};
20
21#[cfg(feature = "gpu-runtime")]
25mod caps;
26#[cfg(all(
27 not(target_arch = "wasm32"),
28 feature = "gpu-runtime",
29 feature = "wgsl-forge"
30))]
31pub(crate) use caps::experimental_features_allowed;
32#[cfg(feature = "gpu-runtime")]
33pub(crate) use caps::requested_native_llm_features;
34#[cfg(all(feature = "gpu-runtime", not(target_arch = "wasm32")))]
35pub use caps::{
36 GpuAdapterCaps, GpuFeatureCaps, GpuLimitCaps, qualia_backend_override,
37 recommend_inference_backend,
38};
39#[cfg(all(feature = "gpu-runtime", target_arch = "wasm32"))]
40pub use caps::{GpuAdapterCaps, GpuFeatureCaps, GpuLimitCaps, recommend_inference_backend};
41
42#[cfg(feature = "gpu-runtime")]
43pub use etalon_agent::{
44 AccessRights as EtalonAccessRights, AccessRights, AllocationId as EtalonAllocationId,
45 AllocationId, BufferRegion as EtalonBufferRegion, BufferRegion,
46 CapabilityState as EtalonCapabilityState, CapabilityState,
47 HalComputeLane as EtalonHalComputeLane, HalComputeLane, MemoryTopology as EtalonMemoryTopology,
48 MemoryTopology, QualiaSlabAllocator as EtalonSlabAllocator, QualiaSlabAllocator,
49 QueueId as EtalonQueueId, QueueId, SiliconCapability as EtalonSiliconCapability,
50 SiliconCapability, SubmissionLease as EtalonSubmissionLease, SubmissionLease,
51 SubmissionToken as EtalonSubmissionToken, SubmissionToken,
52};
53
54#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
58pub mod device_registry;
59
60#[repr(u8)]
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
63pub enum OperationalMode {
64 #[default]
65 Full = 0,
66 Eco = 1,
67 Reserve = 2,
69}
70
71impl OperationalMode {
72 #[inline]
75 pub fn from_pressure(pressure: f32) -> Self {
76 if pressure >= 0.92 {
77 Self::Reserve
78 } else if pressure >= 0.72 {
79 Self::Eco
80 } else {
81 Self::Full
82 }
83 }
84
85 #[inline]
87 pub fn max_particles(self) -> u32 {
88 match self {
89 Self::Full => 50_000,
90 Self::Eco => 8_000,
91 Self::Reserve => 0,
92 }
93 }
94
95 #[inline]
97 pub fn bloom_enabled(self) -> bool {
98 matches!(self, Self::Full)
99 }
100
101 #[inline]
105 pub fn supports_3d(self) -> bool {
106 matches!(self, Self::Full)
107 }
108}
109
110#[repr(u8)]
112#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
113pub enum ComputeUniverse {
114 LlmInference = 0,
116 Tensor10D = 1,
118 Viewport = 2,
120 AcousticPlane = 3,
122}
123
124impl ComputeUniverse {
125 pub const ALL: [Self; 4] = [
126 Self::LlmInference,
127 Self::Tensor10D,
128 Self::Viewport,
129 Self::AcousticPlane,
130 ];
131
132 #[inline]
134 pub fn partition_index(self) -> usize {
135 match self {
136 Self::AcousticPlane => Self::Tensor10D as usize,
137 u => u as usize,
138 }
139 }
140
141 #[inline]
143 pub fn label(self) -> &'static str {
144 match self {
145 Self::LlmInference => "U0 LLM",
146 Self::Tensor10D => "U1 Tensor10D",
147 Self::Viewport => "U2 Viewport",
148 Self::AcousticPlane => "U3 AcousticPlane",
149 }
150 }
151
152 #[inline]
154 pub fn default_queue_lane(self) -> QueueLane {
155 match self {
156 Self::LlmInference => QueueLane::LlmCompute,
157 Self::Tensor10D => QueueLane::TensorCompute,
158 Self::Viewport | Self::AcousticPlane => QueueLane::ViewportRender,
159 }
160 }
161
162 #[inline]
164 pub fn ledger_slots(self) -> &'static [VramLedgerSlot] {
165 match self {
166 Self::LlmInference => &[VramLedgerSlot::LlmKvCache, VramLedgerSlot::LlmWeightStaging],
167 Self::Tensor10D | Self::AcousticPlane => &[VramLedgerSlot::Tensor10D],
168 Self::Viewport => &[VramLedgerSlot::Viewport],
169 }
170 }
171}
172
173#[repr(u8)]
175#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
176pub enum VramLedgerSlot {
177 LlmKvCache = 0,
178 LlmWeightStaging = 1,
179 Tensor10D = 2,
180 Viewport = 3,
181}
182
183#[repr(u8)]
185#[derive(Debug, Clone, Copy, PartialEq, Eq)]
186pub enum QueueLane {
187 LlmCompute = 0,
188 TensorCompute = 1,
189 ViewportRender = 2,
190}
191
192#[derive(Debug, Clone, Copy, PartialEq, Eq)]
194pub struct VramByteRange {
195 pub offset: u64,
196 pub size: u64,
197}
198
199impl VramByteRange {
200 #[inline]
202 pub const fn empty() -> Self {
203 Self { offset: 0, size: 0 }
204 }
205
206 #[inline]
208 pub fn end(&self) -> u64 {
209 self.offset.saturating_add(self.size)
210 }
211
212 #[inline]
214 pub fn contains(&self, alloc_offset: u64, alloc_size: u64) -> bool {
215 alloc_size == 0
216 || alloc_offset >= self.offset && alloc_offset.saturating_add(alloc_size) <= self.end()
217 }
218}
219
220#[derive(Debug, Clone, Copy)]
222pub struct UniversePartition {
223 pub universe: ComputeUniverse,
224 pub mode: OperationalMode,
225 pub vram_budget_bytes: u64,
227 pub ledger_range: VramByteRange,
229 pub queue_lane: QueueLane,
230}
231
232#[derive(Debug, Clone)]
234pub struct UniverseOrchestrator {
235 pub active_mode: OperationalMode,
236 pub partitions: [UniversePartition; 3],
237}
238
239impl UniverseOrchestrator {
240 #[inline]
242 pub fn budget_triplet(total_bytes: u64, mode: OperationalMode) -> (u64, u64, u64) {
243 match mode {
244 OperationalMode::Reserve => {
245 let u2 = total_bytes / 10;
246 let rem = total_bytes.saturating_sub(u2);
247 let u0 = rem / 2;
248 let u1 = rem.saturating_sub(u0);
249 (u0, u1, u2)
250 }
251 OperationalMode::Eco => {
252 let u2 = total_bytes / 4;
253 let rem = total_bytes.saturating_sub(u2);
254 let u0 = rem.saturating_mul(6) / 10;
255 let u1 = rem.saturating_sub(u0);
256 (u0, u1, u2)
257 }
258 OperationalMode::Full => {
259 let u0 = total_bytes.saturating_mul(55) / 100;
260 let u1 = total_bytes.saturating_mul(25) / 100;
261 let u2 = total_bytes.saturating_mul(15) / 100;
262 (u0, u1, u2)
263 }
264 }
265 }
266
267 fn partition_at_offset(
270 universe: ComputeUniverse,
271 mode: OperationalMode,
272 offset: u64,
273 size: u64,
274 ) -> UniversePartition {
275 UniversePartition {
276 universe,
277 mode,
278 vram_budget_bytes: size,
279 ledger_range: VramByteRange { offset, size },
280 queue_lane: universe.default_queue_lane(),
281 }
282 }
283
284 pub fn from_total_budget(total_bytes: u64, mode: OperationalMode) -> Self {
286 let (u0, u1, u2) = Self::budget_triplet(total_bytes, mode);
287 Self {
288 active_mode: mode,
289 partitions: [
290 Self::partition_at_offset(ComputeUniverse::LlmInference, mode, 0, u0),
291 Self::partition_at_offset(ComputeUniverse::Tensor10D, mode, u0, u1),
292 Self::partition_at_offset(
293 ComputeUniverse::Viewport,
294 mode,
295 u0.saturating_add(u1),
296 u2,
297 ),
298 ],
299 }
300 }
301
302 #[inline]
304 pub fn from_total_budget_full(total_bytes: u64) -> Self {
305 Self::from_total_budget(total_bytes, OperationalMode::Full)
306 }
307
308 #[inline]
311 pub fn partition(&self, universe: ComputeUniverse) -> &UniversePartition {
312 &self.partitions[universe.partition_index()]
313 }
314
315 #[inline]
317 pub fn effective_mode(
318 &self,
319 universe: ComputeUniverse,
320 global: OperationalMode,
321 ) -> OperationalMode {
322 match global {
323 OperationalMode::Full => OperationalMode::Full,
324 OperationalMode::Eco => match universe {
325 ComputeUniverse::Viewport | ComputeUniverse::AcousticPlane => OperationalMode::Eco,
326 _ => OperationalMode::Eco,
327 },
328 OperationalMode::Reserve => match universe {
329 ComputeUniverse::LlmInference => OperationalMode::Full,
330 ComputeUniverse::Tensor10D => OperationalMode::Eco,
331 ComputeUniverse::Viewport | ComputeUniverse::AcousticPlane => {
332 OperationalMode::Reserve
333 }
334 },
335 }
336 }
337
338 #[inline]
341 pub fn max_particles(&self, universe: ComputeUniverse, global: OperationalMode) -> u32 {
342 self.effective_mode(universe, global).max_particles()
343 }
344
345 #[inline]
348 pub fn bloom_enabled(&self, universe: ComputeUniverse, global: OperationalMode) -> bool {
349 universe == ComputeUniverse::Viewport
350 && self.effective_mode(universe, global).bloom_enabled()
351 }
352}
353
354#[inline]
356pub fn universe_orchestrator() -> UniverseOrchestrator {
357 let ledger = global_vram_ledger();
358 UniverseOrchestrator::from_total_budget(ledger.budget().max(1), ledger.mode())
359}
360
361#[inline]
363pub fn global_universe_orchestrator() -> UniverseOrchestrator {
364 universe_orchestrator()
365}
366
367#[inline]
369pub fn viewport_operational_mode() -> OperationalMode {
370 let ledger = global_vram_ledger();
371 universe_orchestrator().effective_mode(ComputeUniverse::Viewport, ledger.mode())
372}
373
374#[inline]
376pub fn ambient_draw_instances_for_mode(resident: u32, global: OperationalMode) -> u32 {
377 let cap = universe_orchestrator()
378 .effective_mode(ComputeUniverse::Viewport, global)
379 .max_particles();
380 resident.min(cap)
381}
382
383#[inline]
385pub fn ambient_draw_instances(resident: u32) -> u32 {
386 ambient_draw_instances_for_mode(resident, global_vram_ledger().mode())
387}
388
389#[derive(Debug, Default)]
391pub struct VramLedger {
392 budget_bytes: AtomicU64,
393 tensor_bytes: AtomicU64,
394 kv_cache_bytes: AtomicU64,
395 render_bytes: AtomicU64,
396 llm_weight_staging_bytes: AtomicU64,
397 graphics_reservations: etalon_resources::reservation::ReservationPool<6>,
399 mode: AtomicU32,
400}
401
402impl VramLedger {
403 pub const KV_CACHE_CAP_BYTES: u64 = 448 * 1024 * 1024;
405
406 #[inline]
408 fn load_slot(&self, slot: VramLedgerSlot) -> u64 {
409 match slot {
410 VramLedgerSlot::LlmKvCache => self.kv_cache_bytes.load(Ordering::Relaxed),
411 VramLedgerSlot::LlmWeightStaging => {
412 self.llm_weight_staging_bytes.load(Ordering::Relaxed)
413 }
414 VramLedgerSlot::Tensor10D => self.tensor_bytes.load(Ordering::Relaxed),
415 VramLedgerSlot::Viewport => self.render_bytes.load(Ordering::Relaxed),
416 }
417 }
418
419 #[inline]
422 fn store_slot(&self, slot: VramLedgerSlot, bytes: u64) {
423 let bytes = match slot {
424 VramLedgerSlot::LlmKvCache => bytes.min(Self::KV_CACHE_CAP_BYTES),
425 _ => bytes,
426 };
427 match slot {
428 VramLedgerSlot::LlmKvCache => self.kv_cache_bytes.store(bytes, Ordering::Relaxed),
429 VramLedgerSlot::LlmWeightStaging => self
430 .llm_weight_staging_bytes
431 .store(bytes, Ordering::Relaxed),
432 VramLedgerSlot::Tensor10D => self.tensor_bytes.store(bytes, Ordering::Relaxed),
433 VramLedgerSlot::Viewport => self.render_bytes.store(bytes, Ordering::Relaxed),
434 }
435 self.refresh_mode();
436 }
437
438 #[inline]
440 pub fn budget(&self) -> u64 {
441 self.budget_bytes.load(Ordering::Relaxed)
442 }
443
444 #[inline]
446 pub fn used_in_slot(&self, slot: VramLedgerSlot) -> u64 {
447 self.load_slot(slot)
448 }
449
450 #[inline]
453 pub fn record_slot(&self, slot: VramLedgerSlot, bytes: u64) {
454 self.store_slot(slot, bytes);
455 }
456
457 #[inline]
461 pub fn universe_used_bytes(&self, universe: ComputeUniverse) -> u64 {
462 let recorded = universe
463 .ledger_slots()
464 .iter()
465 .map(|s| self.load_slot(*s))
466 .fold(0u64, u64::saturating_add);
467 if universe == ComputeUniverse::Viewport {
468 recorded.saturating_add(self.graphics_reservations.total_bytes())
469 } else {
470 recorded
471 }
472 }
473
474 #[inline]
477 pub fn universe_pressure(
478 &self,
479 orchestrator: &UniverseOrchestrator,
480 universe: ComputeUniverse,
481 ) -> f32 {
482 let cap = orchestrator.partition(universe).vram_budget_bytes;
483 if cap == 0 {
484 return 0.0;
485 }
486 (self.universe_used_bytes(universe) as f32 / cap as f32).clamp(0.0, 1.25)
487 }
488
489 #[inline]
492 pub fn can_allocate_in_universe(
493 &self,
494 orchestrator: &UniverseOrchestrator,
495 universe: ComputeUniverse,
496 extra_bytes: u64,
497 ) -> bool {
498 let part = orchestrator.partition(universe);
499 let used = self.universe_used_bytes(universe);
500 if used.saturating_add(extra_bytes) > part.vram_budget_bytes {
501 return false;
502 }
503 part.ledger_range
504 .contains(part.ledger_range.offset.saturating_add(used), extra_bytes)
505 && self.can_allocate(extra_bytes)
506 }
507
508 #[inline]
510 pub fn slot_byte_offset(orchestrator: &UniverseOrchestrator, slot: VramLedgerSlot) -> u64 {
511 let universe = match slot {
512 VramLedgerSlot::LlmKvCache | VramLedgerSlot::LlmWeightStaging => {
513 ComputeUniverse::LlmInference
514 }
515 VramLedgerSlot::Tensor10D => ComputeUniverse::Tensor10D,
516 VramLedgerSlot::Viewport => ComputeUniverse::Viewport,
517 };
518 let used_before = match slot {
519 VramLedgerSlot::LlmWeightStaging => {
520 orchestrator
521 .partition(ComputeUniverse::LlmInference)
522 .ledger_range
523 .offset
524 + global_vram_ledger().used_in_slot(VramLedgerSlot::LlmKvCache)
525 }
526 _ => orchestrator.partition(universe).ledger_range.offset,
527 };
528 used_before
529 }
530
531 #[inline]
533 pub fn record_universe(&self, universe: ComputeUniverse, slot: VramLedgerSlot, bytes: u64) {
534 debug_assert!(universe.ledger_slots().contains(&slot));
535 self.store_slot(slot, bytes);
536 }
537
538 #[inline]
540 pub fn new(budget_bytes: u64) -> Self {
541 Self {
542 budget_bytes: AtomicU64::new(budget_bytes),
543 ..Default::default()
544 }
545 }
546
547 #[inline]
549 pub fn set_budget(&self, bytes: u64) {
550 self.budget_bytes.store(bytes, Ordering::Relaxed);
551 }
552
553 #[inline]
555 pub fn record_tensor(&self, bytes: u64) {
556 self.record_universe(ComputeUniverse::Tensor10D, VramLedgerSlot::Tensor10D, bytes);
557 }
558
559 #[inline]
561 pub fn record_kv_cache(&self, bytes: u64) {
562 self.record_universe(
563 ComputeUniverse::LlmInference,
564 VramLedgerSlot::LlmKvCache,
565 bytes,
566 );
567 }
568
569 #[inline]
571 pub fn record_render(&self, bytes: u64) {
572 self.record_universe(ComputeUniverse::Viewport, VramLedgerSlot::Viewport, bytes);
573 }
574
575 #[inline]
577 pub fn record_llm_staging(&self, bytes: u64) {
578 self.record_universe(
579 ComputeUniverse::LlmInference,
580 VramLedgerSlot::LlmWeightStaging,
581 bytes,
582 );
583 }
584
585 #[inline]
588 pub fn used_bytes(&self) -> u64 {
589 self.recorded_used_bytes()
590 .saturating_add(self.graphics_reservations.total_bytes())
591 }
592
593 #[inline]
596 fn recorded_used_bytes(&self) -> u64 {
597 self.tensor_bytes
598 .load(Ordering::Relaxed)
599 .saturating_add(self.kv_cache_bytes.load(Ordering::Relaxed))
600 .saturating_add(self.render_bytes.load(Ordering::Relaxed))
601 .saturating_add(self.llm_weight_staging_bytes.load(Ordering::Relaxed))
602 }
603
604 #[inline]
607 pub fn pressure(&self) -> f32 {
608 let budget = self.budget_bytes.load(Ordering::Relaxed);
609 if budget == 0 {
610 return 0.0;
611 }
612 (self.used_bytes() as f32 / budget as f32).clamp(0.0, 1.25)
613 }
614
615 #[inline]
618 pub fn mode(&self) -> OperationalMode {
619 match self.mode.load(Ordering::Relaxed) {
620 1 => OperationalMode::Eco,
621 2 => OperationalMode::Reserve,
622 _ => OperationalMode::Full,
623 }
624 }
625
626 #[inline]
628 pub fn refresh_mode(&self) {
629 let m = OperationalMode::from_pressure(self.pressure());
630 self.mode.store(m as u32, Ordering::Relaxed);
631 }
632
633 #[inline]
636 pub fn can_allocate(&self, extra_bytes: u64) -> bool {
637 let budget = self.budget_bytes.load(Ordering::Relaxed);
638 self.used_bytes()
639 .checked_add(extra_bytes)
640 .is_some_and(|required| required <= budget)
641 }
642}
643
644static LEDGER: std::sync::OnceLock<VramLedger> = std::sync::OnceLock::new();
646
647#[inline]
649pub fn global_vram_ledger() -> &'static VramLedger {
650 LEDGER.get_or_init(|| VramLedger::new(6 * 1024 * 1024 * 1024))
651}
652
653static LLM_HEAT_MILLI: AtomicU32 = AtomicU32::new(0);
656static LOGIC_FLASH_MILLI: AtomicU32 = AtomicU32::new(0);
657static BAKE_PULSE_MILLI: AtomicU32 = AtomicU32::new(0);
658static NETWORK_RIPPLE_MILLI: AtomicU32 = AtomicU32::new(0);
659static PRODUCER_CYCLE_MILLI: AtomicU32 = AtomicU32::new(0);
660static CONTEXT_RING_DROP_MILLI: AtomicU32 = AtomicU32::new(0);
661static DRAFT_ACCEPT_MILLI: AtomicU32 = AtomicU32::new(0);
662static DRAFT_LEN_CUR: AtomicU32 = AtomicU32::new(0);
663
664#[inline]
666fn pulse(atom: &AtomicU32, strength_milli: u32) {
667 let cur = atom.load(Ordering::Relaxed);
668 atom.store(cur.max(strength_milli), Ordering::Relaxed);
669}
670
671#[inline]
674fn sample_decay(atom: &AtomicU32, decay: u32) -> f32 {
675 let v = atom.load(Ordering::Relaxed);
676 atom.store(v.saturating_sub(decay), Ordering::Relaxed);
677 (v as f32 / 1000.0).clamp(0.0, 1.0)
678}
679
680#[inline]
682pub fn record_llm_decode_step() {
683 pulse(&LLM_HEAT_MILLI, 1000);
684}
685
686#[inline]
688pub fn record_logic_flash() {
689 pulse(&LOGIC_FLASH_MILLI, 900);
690}
691
692#[inline]
694pub fn record_bake_pulse() {
695 pulse(&BAKE_PULSE_MILLI, 850);
696 global_vram_ledger().refresh_mode();
697}
698
699#[inline]
701pub fn record_network_ripple() {
702 pulse(&NETWORK_RIPPLE_MILLI, 700);
703}
704
705#[inline]
707pub fn record_producer_cycle(pushed_tokens: u32) {
708 let strength = (500 + pushed_tokens.min(16) * 25).min(1000);
709 pulse(&PRODUCER_CYCLE_MILLI, strength);
710}
711
712#[inline]
714pub fn record_context_ring_drop() {
715 pulse(&CONTEXT_RING_DROP_MILLI, 800);
716}
717
718#[inline]
720pub fn record_draft_acceptance(accepted: u32, draft_len: u32) {
721 if draft_len > 0 {
722 let rate = ((accepted as u64) * 1000 / draft_len as u64).min(1000) as u32;
723 DRAFT_LEN_CUR.store(draft_len, Ordering::Relaxed);
724 pulse(&DRAFT_ACCEPT_MILLI, rate);
725 }
726}
727
728#[inline]
730pub fn sample_ambient_telemetry() -> [f32; 11] {
731 let ledger = global_vram_ledger();
732 [
733 ledger.pressure(),
734 sample_decay(&NETWORK_RIPPLE_MILLI, 25),
735 sample_decay(&BAKE_PULSE_MILLI, 20),
736 sample_decay(&LOGIC_FLASH_MILLI, 35),
737 sample_decay(&LLM_HEAT_MILLI, 30),
738 sample_decay(&PRODUCER_CYCLE_MILLI, 18),
739 sample_decay(&CONTEXT_RING_DROP_MILLI, 22),
740 0.08,
741 0.25,
742 ledger.pressure() * 0.5,
743 ledger.mode() as u32 as f32,
744 ]
745}
746
747#[cfg(feature = "gpu-runtime")]
750pub struct SharedGpuContext {
751 pub provider_lease: etalon_agent::device_lease::DeviceLease,
752 pub device: etalon::Device,
753 pub queue: etalon::Queue,
754 pub instance: etalon::Instance,
756 pub adapter: etalon::Adapter,
758 pub adapter_caps: GpuAdapterCaps,
760 pub enabled_features: GpuFeatureCaps,
762 pub timestamps_supported: bool,
765 pub timestamp_period_ns: f32,
767}
768
769#[cfg(feature = "gpu-runtime")]
770impl SharedGpuContext {
771 #[inline]
774 pub fn queue_for_lane(&self, lane: QueueLane) -> &etalon::Queue {
775 let _ = lane;
776 &self.queue
777 }
778
779 #[inline]
782 pub fn queue_for_universe(&self, universe: ComputeUniverse) -> &etalon::Queue {
783 self.queue_for_lane(universe.default_queue_lane())
784 }
785
786 pub fn create_etalon_hal_lane(&self) -> etalon_agent::HalComputeLane {
788 etalon_agent::HalComputeLane::new(
789 std::sync::Arc::new(self.device.clone()),
790 std::sync::Arc::new(self.queue.clone()),
791 etalon_agent::QueueId(0),
792 )
793 }
794
795 pub fn create_etalon_slab_allocator(
797 &self,
798 capacity_bytes: u64,
799 label: &str,
800 ) -> etalon_agent::QualiaSlabAllocator {
801 let _ = (&self.device, label);
802 etalon_agent::QualiaSlabAllocator::new(
803 capacity_bytes as usize,
804 etalon_agent::slab::DEFAULT_BINDING_ALIGNMENT,
805 )
806 }
807}
808
809#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
810static SHARED_GPU: OnceLock<Option<SharedGpuContext>> = OnceLock::new();
811
812#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
815std::thread_local! {
816 static WASM_SHARED_GPU: std::cell::Cell<Option<&'static SharedGpuContext>> =
817 const { std::cell::Cell::new(None) };
818}
819
820#[cfg(all(
829 not(target_arch = "wasm32"),
830 feature = "gpu-runtime",
831 feature = "gpu-native-dx12"
832))]
833fn resolve_dx12_compiler() -> etalon::Dx12Compiler {
834 if let Ok(p) = std::env::var("QUALIA_DXC_PATH") {
835 if !p.trim().is_empty() {
836 log::info!("shared_gpu|dx12_compiler|DynamicDxc(env)={p}");
837 return etalon::Dx12Compiler::DynamicDxc { dxc_path: p };
838 }
839 }
840 if let Ok(exe) = std::env::current_exe() {
841 if let Some(dir) = exe.parent() {
842 let dll = dir.join("dxcompiler.dll");
843 if dll.exists() {
844 log::info!(
845 "shared_gpu|dx12_compiler|DynamicDxc(vendored)={}",
846 dll.display()
847 );
848 return etalon::Dx12Compiler::DynamicDxc {
849 dxc_path: dll.to_string_lossy().into_owned(),
850 };
851 }
852 }
853 }
854 etalon::Dx12Compiler::Auto
855}
856
857#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
860async fn init_shared_gpu_async() -> Result<SharedGpuContext, String> {
861 let mut desc = etalon::InstanceDescriptor::new_without_display_handle();
873 #[cfg(feature = "gpu-native-dx12")]
874 {
875 let dx12_compiler = resolve_dx12_compiler();
876 desc.backend_options.dx12.shader_compiler = dx12_compiler;
877 }
878 if let Some(backends) = caps::qualia_backend_override() {
879 log::info!("shared_gpu|backend_override|QUALIA_WGPU_BACKEND={backends:?}");
880 desc.backends = backends;
881 } else if cfg!(target_os = "windows") {
882 #[cfg(feature = "gpu-native-dx12")]
883 {
884 desc.backends = etalon::Backends::DX12;
889 log::info!(
890 "shared_gpu|backend_default|windows->dx12 (override with QUALIA_WGPU_BACKEND=vulkan)"
891 );
892 }
893 #[cfg(not(feature = "gpu-native-dx12"))]
894 {
895 desc.backends = etalon::Backends::GL;
899 log::info!("shared_gpu|backend_default|windows->gles_portable_build");
900 }
901 }
902 let instance = etalon::Instance::new(desc);
903 let adapter = instance
904 .request_adapter(&etalon::RequestAdapterOptions {
905 power_preference: etalon::PowerPreference::HighPerformance,
906 ..Default::default()
907 })
908 .await
909 .map_err(|e| format!("Failed to find wgpu adapter: {e}"))?;
910
911 #[cfg(target_os = "windows")]
915 if let Ok(memory) = crate::directml_bridge::probe_best_adapter_memory() {
916 let total_local = memory
917 .local_budget_bytes
918 .max(memory.dedicated_vram_bytes)
919 .max(memory.available_local_bytes());
920 if total_local > 0 {
921 global_vram_ledger().set_budget(total_local);
922 }
923 }
924
925 init_shared_gpu_for_adapter(instance, adapter).await
926}
927
928#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
929pub(crate) use etalon_resources::device_caps::webgpu_minimum_limits;
930
931#[cfg(feature = "gpu-runtime")]
937pub(crate) async fn init_shared_gpu_for_adapter(
938 instance: etalon::Instance,
939 adapter: etalon::Adapter,
940) -> Result<SharedGpuContext, String> {
941 let adapter_caps = GpuAdapterCaps::from_adapter(&adapter);
942 log::info!(
943 "shared_gpu|adapter|{}|{}",
944 adapter_caps.summary_line(),
945 adapter_caps.llm_feature_line()
946 );
947 log::info!(
948 "shared_gpu|inference_backend|{}|recommend: {}",
949 adapter_caps.backend_label(),
950 caps::recommend_inference_backend(&adapter_caps)
951 );
952 if adapter_caps.is_integrated_gpu()
953 && std::env::var("QUALIA_LLM_ALLOW_IGPU").ok().as_deref() != Some("1")
954 {
955 log::warn!(
956 "shared_gpu|adapter|integrated_gpu_selected|set QUALIA_LLM_ALLOW_IGPU=1 to acknowledge this for native LLM runs"
957 );
958 }
959
960 let required_features = requested_native_llm_features(adapter.features());
965 let enabled_features = GpuFeatureCaps::from_features(required_features);
966 log::info!(
967 "shared_gpu|enabled_features|{}",
968 enabled_features.compact_flags()
969 );
970 if adapter_caps.features.cooperative_matrix && !enabled_features.cooperative_matrix {
971 log::info!(
972 "shared_gpu|cooperative_matrix_supported_but_disabled|set QUALIA_WGPU_EXPERIMENTAL_FEATURES=1 to request it"
973 );
974 }
975 let _ts_supported = enabled_features.timestamp_query;
976 let adapter_limits = {
984 #[cfg(target_arch = "wasm32")]
985 {
986 let _ = &adapter;
987 webgpu_minimum_limits()
988 }
989 #[cfg(not(target_arch = "wasm32"))]
990 {
991 adapter.limits()
992 }
993 };
994 let required_limits = etalon::Limits {
995 max_buffer_size: adapter_limits.max_buffer_size,
996 max_storage_buffer_binding_size: adapter_limits.max_storage_buffer_binding_size,
997 ..etalon::Limits::default()
998 };
999 let experimental_features = if required_features.intersects(
1000 etalon::Features::EXPERIMENTAL_COOPERATIVE_MATRIX | etalon::Features::EXPERIMENTAL_RAY_QUERY,
1001 ) {
1002 unsafe { etalon::ExperimentalFeatures::enabled() }
1006 } else {
1007 etalon::ExperimentalFeatures::disabled()
1008 };
1009 let context = etalon_agent::shared_device::DeviceContext::request(
1010 instance,
1011 adapter,
1012 &etalon::DeviceDescriptor {
1013 required_features,
1014 required_limits,
1015 experimental_features,
1016 ..Default::default()
1017 },
1018 )
1019 .await?;
1020 Ok(SharedGpuContext {
1021 provider_lease: context.lease,
1022 device: context.device,
1023 queue: context.queue,
1024 instance: context.instance,
1025 adapter: context.adapter,
1026 adapter_caps: context.adapter_caps,
1027 enabled_features: context.enabled_features,
1028 timestamps_supported: context.timestamps_supported,
1029 timestamp_period_ns: context.timestamp_period_ns,
1030 })
1031}
1032
1033#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1040pub fn try_shared_gpu() -> Option<&'static SharedGpuContext> {
1041 #[cfg(all(not(target_arch = "wasm32"), feature = "wgsl-forge"))]
1042 crate::wgsl_forge::install_device_policy();
1043 SHARED_GPU
1044 .get_or_init(|| {
1045 let handle = match tokio::runtime::Handle::try_current() {
1046 Ok(h) => h,
1047 Err(_) => match tokio::runtime::Runtime::new() {
1048 Ok(rt) => Box::leak(Box::new(rt)).handle().clone(),
1049 Err(_) => return None,
1050 },
1051 };
1052 tokio::task::block_in_place(|| handle.block_on(init_shared_gpu_async()).ok())
1053 })
1054 .as_ref()
1055}
1056
1057#[cfg(not(feature = "gpu-runtime"))]
1060pub fn try_shared_gpu() -> Option<&'static ()> {
1061 None
1062}
1063
1064#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1067pub async fn ensure_shared_gpu() -> Result<(), String> {
1068 if WASM_SHARED_GPU.with(|c| c.get().is_some()) {
1069 return Ok(());
1070 }
1071 etalon_wasm::readback::recover_browser_worker()
1072 .map_err(|error| format!("Browser device recovery: {error:?}"))?;
1073 let ctx = init_shared_gpu_wasm().await?;
1074 if WASM_SHARED_GPU.with(|c| c.get().is_some()) {
1076 return Ok(());
1077 }
1078 let leaked: &'static SharedGpuContext = Box::leak(Box::new(ctx));
1079 WASM_SHARED_GPU.with(|c| c.set(Some(leaked)));
1080 let owner_identity = leaked as *const SharedGpuContext as usize;
1081 let worker = etalon_wasm::readback::browser_worker();
1082 leaked.device.set_device_lost_callback(move |reason, message| {
1083 let retired = WASM_SHARED_GPU.with(|slot| {
1084 if slot.get().is_some_and(|current| current as *const SharedGpuContext as usize == owner_identity) {
1085 slot.set(None);
1086 true
1087 } else {
1088 false
1089 }
1090 });
1091 if retired {
1092 worker.lock().unwrap().notify_device_lost();
1093 crate::gguf_bridge::WASM_ENGINE_INSTANCE.with(|slot| {
1094 *slot.borrow_mut() = None;
1095 });
1096 log::warn!("shared_gpu|browser_device_lost|{reason:?}|{message}");
1097 }
1098 });
1099 Ok(())
1100}
1101
1102#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1105async fn init_shared_gpu_wasm() -> Result<SharedGpuContext, String> {
1106 let mut desc = etalon::InstanceDescriptor::new_without_display_handle();
1107 desc.backends = etalon::Backends::BROWSER_WEBGPU;
1108 let instance = etalon::Instance::new(desc);
1109 let adapter = match instance
1110 .request_adapter(&etalon::RequestAdapterOptions {
1111 power_preference: etalon::PowerPreference::HighPerformance,
1112 ..Default::default()
1113 })
1114 .await
1115 {
1116 Ok(a) => a,
1117 Err(high_err) => instance
1118 .request_adapter(&etalon::RequestAdapterOptions::default())
1119 .await
1120 .map_err(|e| {
1121 format!(
1122 "Failed to find WebGPU adapter (high-performance: {high_err}; default: {e})"
1123 )
1124 })?,
1125 };
1126 init_shared_gpu_for_adapter(instance, adapter).await
1127}
1128
1129#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1133pub fn try_shared_gpu() -> Option<&'static SharedGpuContext> {
1134 WASM_SHARED_GPU.with(|c| c.get())
1135}
1136
1137#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1140pub fn shared_gpu() -> &'static SharedGpuContext {
1141 try_shared_gpu().expect("shared wgpu init failed — call ensure_shared_gpu() first")
1142}
1143
1144#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1148pub fn shared_gpu() -> &'static SharedGpuContext {
1149 try_shared_gpu().expect("shared wgpu init failed")
1150}
1151
1152#[cfg(feature = "gpu-runtime")]
1155pub fn try_shared_etalon_hal_lane() -> Option<etalon_agent::HalComputeLane> {
1156 try_shared_gpu().map(|g| g.create_etalon_hal_lane())
1157}
1158
1159#[cfg(all(test, not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1160mod shared_gpu_robustness_tests {
1161 use super::*;
1162
1163 #[test]
1164 fn try_shared_gpu_never_panics_and_is_idempotent() {
1165 let first = try_shared_gpu().is_some();
1169 let second = try_shared_gpu().is_some();
1170 assert_eq!(first, second, "try_shared_gpu must be cached + consistent");
1171 }
1172}
1173
1174#[cfg(all(test, not(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))))]
1175mod try_shared_gpu_fail_closed_tests {
1176 use super::*;
1177
1178 #[test]
1179 fn try_shared_gpu_is_none_without_gpu_runtime() {
1180 assert!(try_shared_gpu().is_none());
1181 }
1182}
1183
1184#[cfg(test)]
1185mod tests {
1186 use super::*;
1187
1188 #[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1192 #[test]
1193 #[serial_test::serial(gpu)]
1194 fn report_inference_backend() {
1195 if !crate::wgsl_forge::test_gpu_available() {
1196 return;
1197 }
1198 let g = shared_gpu();
1199 eprintln!(
1200 "[inference-backend] selected = {} | recommend: {}",
1201 g.adapter_caps.backend_label(),
1202 recommend_inference_backend(&g.adapter_caps),
1203 );
1204 eprintln!("[inference-backend] {}", g.adapter_caps.summary_line());
1205 assert!(!g.adapter_caps.backend_label().is_empty());
1207 }
1208
1209 #[test]
1210 fn pressure_triggers_eco_and_reserve() {
1211 let ledger = VramLedger::new(1000);
1212 ledger.record_tensor(500);
1213 assert_eq!(ledger.mode(), OperationalMode::Full);
1214 ledger.record_kv_cache(300);
1215 assert_eq!(ledger.mode(), OperationalMode::Eco);
1216 ledger.record_render(200);
1217 assert_eq!(ledger.mode(), OperationalMode::Reserve);
1218 }
1219
1220 #[test]
1221 fn universe_partitions_sum_below_total() {
1222 let orch = UniverseOrchestrator::from_total_budget_full(10_000);
1223 let sum: u64 = orch.partitions.iter().map(|p| p.vram_budget_bytes).sum();
1224 assert!(sum <= 10_000);
1225 assert_eq!(
1226 orch.partition(ComputeUniverse::LlmInference)
1227 .vram_budget_bytes,
1228 5500
1229 );
1230 }
1231
1232 #[test]
1233 fn reserve_mode_caps_u2_at_ten_percent() {
1234 let orch = UniverseOrchestrator::from_total_budget(10_000, OperationalMode::Reserve);
1235 assert_eq!(
1236 orch.partition(ComputeUniverse::Viewport).vram_budget_bytes,
1237 1_000
1238 );
1239 assert_eq!(
1240 orch.partition(ComputeUniverse::LlmInference)
1241 .vram_budget_bytes,
1242 4_500
1243 );
1244 assert_eq!(orch.active_mode, OperationalMode::Reserve);
1245 }
1246
1247 #[test]
1248 fn ledger_ranges_are_consecutive_non_overlapping() {
1249 let orch = UniverseOrchestrator::from_total_budget(10_000, OperationalMode::Eco);
1250 let u0 = orch.partition(ComputeUniverse::LlmInference).ledger_range;
1251 let u1 = orch.partition(ComputeUniverse::Tensor10D).ledger_range;
1252 let u2 = orch.partition(ComputeUniverse::Viewport).ledger_range;
1253 assert_eq!(u0.offset, 0);
1254 assert_eq!(u1.offset, u0.end());
1255 assert_eq!(u2.offset, u1.end());
1256 assert!(u2.end() <= 10_000);
1257 }
1258
1259 #[test]
1260 fn u2_cannot_evict_u0_kv_under_reserve() {
1261 let orch = UniverseOrchestrator::from_total_budget_full(10_000);
1262 assert_eq!(
1263 orch.effective_mode(ComputeUniverse::LlmInference, OperationalMode::Reserve),
1264 OperationalMode::Full
1265 );
1266 assert_eq!(
1267 orch.effective_mode(ComputeUniverse::Viewport, OperationalMode::Reserve),
1268 OperationalMode::Reserve
1269 );
1270 }
1271
1272 #[test]
1273 fn universe_budget_isolated() {
1274 let ledger = VramLedger::new(10_000);
1275 let orch = UniverseOrchestrator::from_total_budget_full(10_000);
1276 ledger.record_render(2000);
1277 assert!(ledger.can_allocate_in_universe(&orch, ComputeUniverse::LlmInference, 5000));
1278 assert!(!ledger.can_allocate_in_universe(&orch, ComputeUniverse::Viewport, 2000));
1279 }
1280
1281 #[test]
1282 fn ambient_draw_instant_step_by_mode() {
1283 let orch =
1284 UniverseOrchestrator::from_total_budget(6 * 1024 * 1024 * 1024, OperationalMode::Full);
1285 assert_eq!(
1286 orch.max_particles(ComputeUniverse::Viewport, OperationalMode::Full),
1287 50_000
1288 );
1289 assert_eq!(
1290 orch.max_particles(ComputeUniverse::Viewport, OperationalMode::Eco),
1291 8_000
1292 );
1293 assert_eq!(
1294 orch.max_particles(ComputeUniverse::Viewport, OperationalMode::Reserve),
1295 0
1296 );
1297
1298 let resident = 50_000_u32;
1299 assert_eq!(
1300 ambient_draw_instances_for_mode(resident, OperationalMode::Full),
1301 50_000
1302 );
1303 assert_eq!(
1304 ambient_draw_instances_for_mode(resident, OperationalMode::Eco),
1305 8_000
1306 );
1307 assert_eq!(
1308 ambient_draw_instances_for_mode(resident, OperationalMode::Reserve),
1309 0
1310 );
1311 assert_eq!(
1312 ambient_draw_instances_for_mode(3_000, OperationalMode::Eco),
1313 3_000
1314 );
1315 }
1316}