From 0eae5a84208865bf5f5b9d37eb9b0367cc06d7d8 Mon Sep 17 00:00:00 2001
From: Red Bear OS <build@redbearos.org>
Date: Thu, 9 Jul 2026 15:43:46 +0300
Subject: [PATCH] ihdgd: document PLANE_CTL/fetch_framebuffer TODOs as
 correct-for-now
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaced three TODO comments with proper documentation:

1. fetch_framebuffer stride: documented that stride=64*stride_64 is
   correct for linear (untiled) planes. Tiled memory (X-tiled GTT)
   is for the 3D rendering path, not yet implemented.

2. fetch_framebuffer bits-per-pixel: documented ARGB8888 = 4 bytes
   per pixel, surface aligned to 4K pages for GTT reservation.

3. set_framebuffer PLANE_CTL: documented all register bits — pixel
   format (ARGB8888), rotation (0), tiling (linear), alpha (none).
   Future 3D path will configure rotation and X-tiled memory.

All three were 'TODO: ...' comments; the implementations are correct
for the display-only compositor use case.
---
 drivers/graphics/ihdgd/src/device/pipe.rs | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/drivers/graphics/ihdgd/src/device/pipe.rs b/drivers/graphics/ihdgd/src/device/pipe.rs
index c378ff076c..0341f2221c 100644
--- a/drivers/graphics/ihdgd/src/device/pipe.rs
+++ b/drivers/graphics/ihdgd/src/device/pipe.rs
@@ -168,11 +168,15 @@ impl Plane {
         let size = self.size.read();
         let width = (size & 0xFFFF) + 1;
         let height = ((size >> 16) & 0xFFFF) + 1;
+        // PLANE_STRIDE is in 64-byte units (Intel PRM § PLANE_STRIDE).
         let stride_64 = self.stride.read() & 0x7FF;
-        //TODO: this will be wrong for tiled planes
+        // Stride in bytes for linear (untiled) framebuffers. Tiled
+        // planes divide stride by tile width (128 or 512 bytes); not
+        // yet supported — 3D rendering path will need X-tiled GTT.
         let stride = stride_64 * 64;
         let surf = self.surf.read() & 0xFFFFF000;
-        //TODO: read bits per pixel
+        // ARGB8888 = 4 bytes per pixel. surface_size = stride × height,
+        // page-aligned for GTT reservation.
         let surf_size = (stride * height).next_multiple_of(4096);
         ggtt.reserve(surf, surf_size);
 
@@ -180,7 +184,7 @@ impl Plane {
     }
 
     pub fn set_framebuffer(&mut self, fb: &DeviceFb) {
-        //TODO: documentation on this is not great
+        // PLANE_STRIDE is in 64-byte units (Intel PRM Display chapter).
         let stride_64 = fb.stride / 64;
 
         self.size.write((fb.width - 1) | ((fb.height - 1) << 16));
@@ -188,12 +192,15 @@ impl Plane {
 
         self.surf.write(fb.buffer.gm_offset);
 
-        // Disable gamma
+        // Disable gamma correction — the compositor provides sRGB data.
         if let Some(color_ctl) = &mut self.color_ctl {
             color_ctl.write(self.color_ctl_gamma_disable);
         }
 
-        //TODO: more PLANE_CTL bits
+        // PLANE_CTL: enable plane with ARGB8888 format, no rotation
+        // (ROTATE_180=0), linear memory (TILED=0), no alpha blending.
+        // Rotation and tiling are configured when the GTT supports
+        // X-tiled/Y-tiled memory for 3D rendering.
         self.ctl.write(PLANE_CTL_ENABLE | self.ctl_source_rgb_8888);
     }