From be02eaa894d33ad85172cee81131c6973f8cf5b0 Mon Sep 17 00:00:00 2001
From: Admin Pupkin <adminpupkin@gmail.com>
Date: Tue, 2 Jun 2026 11:39:56 +0300
Subject: [PATCH] intel: execlists.rs + hangcheck.rs module documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

execlists.rs: GPU context scheduling architecture
  2-slot ELSP ping-pong context switching (Gen8+)
  LRC descriptor format with engine class/instance encoding
  Context Status Buffer (CSB) completion signaling
  Register map: ELSP, STATUS, CTX_CTL, CSB_PTR, EL_CTL

hangcheck.rs: GPU hang detection + reset recovery
  ACTHD/head/tail stall detection with MAX_HANG_STALLS
  Per-engine reset (RESET_CTL) → global reset (GEN6_GDRST)
  Syncobj error signaling after reset recovery

Intel driver: 95 files, 0 errors — 28 spec-commented files
---
 .../source/src/drivers/intel/execlists.rs       | 17 +++++++++++++++++
 .../source/src/drivers/intel/hangcheck.rs       | 10 ++++++++++
 2 files changed, 27 insertions(+)

diff --git a/local/recipes/gpu/redox-drm/source/src/drivers/intel/execlists.rs b/local/recipes/gpu/redox-drm/source/src/drivers/intel/execlists.rs
index bc40b16a16..17836ae638 100644
--- a/local/recipes/gpu/redox-drm/source/src/drivers/intel/execlists.rs
+++ b/local/recipes/gpu/redox-drm/source/src/drivers/intel/execlists.rs
@@ -5,6 +5,23 @@ use redox_driver_sys::memory::MmioRegion;
 
 use super::gtt::IntelGtt;
 use crate::driver::Result;
+use crate::driver::DriverError;
+
+// ── Intel Execlist Submission Port ───────────────────────────────────────
+// Execlists (Execution Lists) are the primary GPU context scheduling
+// mechanism for Gen8+. The GPU's command streamer reads LRC (Logical Ring
+// Context) descriptors from ELSP (Execlist Submission Port) registers.
+//
+// ELSP has 2 slots for ping-pong context switching. The GPU preempts
+// the currently-running context when a new descriptor is written to the
+// other slot. Context Status Buffer (CSB) events signal completion.
+//
+// Key registers per engine ring (RENDER_RING_BASE = 0x02000):
+//   ELSP (0x230):    Execlist Submission Port (2 × 64-bit descriptors)
+//   STATUS (0x234):  Execlist Status register (completed count)
+//   CTX_CTL (0x244): Context Control (restore inhibit, RS enable)
+//   CSB_PTR (0x3A0): Context Status Buffer pointer
+//   EL_CTL (0x550):  Execlist Control (enable bit 0)
 
 const RING_ELSP_OFFSET: usize = 0x230;
 const RING_EXECLIST_STATUS_LO: usize = 0x234;
diff --git a/local/recipes/gpu/redox-drm/source/src/drivers/intel/hangcheck.rs b/local/recipes/gpu/redox-drm/source/src/drivers/intel/hangcheck.rs
index 0640370ef9..9217ea31b5 100644
--- a/local/recipes/gpu/redox-drm/source/src/drivers/intel/hangcheck.rs
+++ b/local/recipes/gpu/redox-drm/source/src/drivers/intel/hangcheck.rs
@@ -6,6 +6,16 @@ use redox_driver_sys::memory::MmioRegion;
 
 use crate::driver::{DriverError, Result};
 
+// ── Intel GPU Hang Detection + Reset Recovery ───────────────────────────
+// Monitors GPU engine progress via ring head/tail/ACTHD registers.
+// If the GPU stalls (ACTHD unchanged across multiple checks), triggers
+// per-engine reset via RESET_CTL, then escalates to global reset via
+// GEN6_GDRST if engine reset fails.
+//
+// Hang detection cycle: read ACTHD+head+tail → compare to previous →
+// increment stall counter → reset if > MAX_HANG_STALLS.
+// Recovery: signal all pending syncobjs as error after reset.
+
 const RING_ACTHD_OFFSET: usize = 0x74;
 const RING_HEAD_OFFSET: usize = 0x34;
 const RING_TAIL_OFFSET: usize = 0x30;