Legacy Artifacts to Clean Up

This document lists all legacy/ABI version artifacts found in the documentation that should be removed from both the documentation and the codebase.

IMPORTANT: These items violate the Atomic Updates philosophy. We do not maintain backward compatibility or multiple API versions.

Category: ABI Version References

File: docs/01-plugin-system.md

Item 1: API Version Macros

Location: Section “API Version Macros”

Content:

#define WAXED_PLUGIN_API_V5  0x05000000
#define WAXED_PLUGIN_API_V4  0x04000000

Reason: We do not maintain multiple API versions. Only the current API should exist.

Item 2: FrameHandle Structure (Legacy)

Location: Section “FrameHandle Structure (Legacy)”
Content: Full documentation of FrameHandle structure
Reason: FrameHandle is superseded by RenderTarget. Legacy structures should not be documented.

Item 3: v4 API Deprecation Notice

Location: “Plugins should implement the v5 API… The v4 API is deprecated.”
Reason: No deprecation - just remove old APIs immediately.

Item 4: ABI v5/v9 References

Location: Multiple sections mention “ABI v5”, “ABI v9”, “v9”
Content: References like “(ABI v5)”, “Ownership Model (v9)”, “Cursor handoff fields (ABI v9)”
Reason: There is only one ABI - the current one. No version qualifiers needed.

File: docs/02-atomic-updates.md

~~Item 5: Migration Examples with Old API~~ ~~Item 6: RenderTarget ABI v9~~ ~~Item 7: Migration Strategy Section~~ **Item 8: Version Smell Checkboxes”

STATUS: CLEANED - Document replaced entirely. Now documents current development status and notes that version compatibility decisions will be made when V1.0.0 approaches.

File: docs/03-core-api.md

Item 9: Migration Notes Section

Location: Section “Migration Notes” / “v4 to v5 API Changes”
Content: “New functions in v5:”, v4 to v5 migration information
Reason: Migration notes should not persist in final documentation.

File: docs/05-render-loop.md

Item 10: Deprecated State Variable

Location: State Variables table
Content: | fence_pending_ | bool | Fence waiting (deprecated) |
Reason: Deprecated variables should not be documented - they should be removed.

Item 23: Render Loop Documentation Issues

Issue: Multiple content and structure problems

Problems to Fix:

“ASCII Diagrams” reference is outdated - diagrams are now Mermaid
Diagrams without explanation - either add meaningful context or remove them
“File Locations” section - remove entirely (useless)
“Key Functions” section - remove (render loop is internal, not an API)
“State Variables” section - remove (render loop is internal, not an API)

Reason: The render loop is internal implementation, not a public API. Documentation should explain the architecture and flow, not list functions and variables.

File: docs/06-atomic-kms-output.md

Item 24: EBUSY Retry Logic

Location: EBUSY Retry Logic section
Issue: EBUSY retry logic exists in both documentation and code

Code Location Verified:

src/composer/atomic_kms_output.cpp - submit_frame() function
Has retry loop: MAX_EBUSY_RETRIES = 3, EBUSY_RETRY_DELAY_MS = 5ms
Retries drmModeAtomicCommit() on EBUSY with 5ms sleep

Action Required:

Remove EBUSY retry logic from documentation (docs/06-atomic-kms-output.md)
Remove EBUSY retry logic from code (src/composer/atomic_kms-output.cpp)
Remove related EBUSY mentions from other docs (04-display-manager.md, 07-triple-buffer-system.md, 05-render-loop.md)

Reason: The retry logic masks underlying timing issues. If EBUSY occurs, it indicates a real problem that should be addressed at the source, not papered over with retries.

Item 25: Async Cursor Position Updates - Clarification Needed

Location: “Async Cursor Position Updates” section
Issue: Current description may be unclear about the purpose

Clarification to Add: The cursor is updated on the hardware plane immediately. This means that at the next frame render, the most actual and recent cursor position is rendered. Without this async update, the cursor position could lag behind by as much as an entire frame in the worst case.

Action Required:

Update the section to clearly explain WHY async cursor updates matter
Emphasize the latency reduction benefit (preventing up to 1 frame of cursor lag)

Item 26: ABA Problem - Inconsistent Explanation

Issue: “ABA Problem” / “ABA Prevention” mentioned in multiple places but not consistently explained
Locations:
- docs/07-triple-buffer-system.md - HAS explanation (lines 112-130)
- docs/05-render-loop.md - mentions ABA but no explanation
- docs/21-frame-pipeline.md - mentions ABA but no explanation

Action Required (choose one):

Remove everywhere: Replace “ABA prevention” with descriptive text like “stale event prevention” or “generation counter validation”
Explain everywhere: Add the same explanation to every file that mentions ABA

Recommended: Option 1 - Remove the jargon. Use clear descriptive language instead of “ABA” which requires domain knowledge to understand.

File: docs/08-vulkan-raii.md

Item 27: Remove Entire File

Action: Delete docs/08-vulkan-raii.md entirely
Reason: Vulkan RAII usage is a coding guideline, not a Waxed-specific system or architecture. It belongs in CLAUDE.md or a coding standards document, not as a standalone architecture document.

File: docs/09-shared-vulkan-device.md

Item 28: Remove Entire File

Action: Delete docs/09-shared-vulkan-device.md entirely
Reason: The Vulkan provider pattern is simple and self-explanatory. It doesn’t warrant a dedicated architecture document.

File: docs/10-texture-streamer.md

Item 29: Texture Streamer Documentation Fixes

Issues: Multiple problems in this file

Problems to Fix:

Remove “File Locations” block with file paths (useless)
Fix “Worker Loop Flow” section - Mermaid diagram has errors with “Unsupported markdown: list”

Action Required:

Remove the file locations section
Review and fix the Mermaid diagram syntax in Worker Loop Flow

File: docs/09-shared-vulkan-device.md

Item 11: Legacy Compatibility Layer

Location: Section about Vulkan Provider system
Content: “The Vulkan Provider system is a legacy compatibility layer maintained for transitioning plugins.”
Reason: Legacy compatibility layers violate atomic updates philosophy.

File: docs/21-frame-pipeline.md

Item 12: Multiple ABI Version References

Location: Throughout the document
Content:
- “Core-owned swapchain buffers (ABI v5)”
- “In ABI v5, the core owns the DMA-BUF…”
- “buffer_id (ABI v4)”, “generation (ABI v4)”
- “RenderTarget Structure (ABI v5)”
- “Cursor handoff fields (ABI v9)”
- “RenderTarget Ownership Model (v9)”
- “Core-Owned Buffers (ABI v5)”
- “v5 Render API Flow”
- “waxed_plugin_render_v5()”
Reason: All ABI version qualifiers should be removed. There is only one API.

File: docs/VULKAN_RAAI_REFACTORING_PLAN.md

Item 13: Entire Migration Plan Document

Location: Full file
Reason: This is a migration plan that should be deleted once the migration is complete. It is not documentation.

Category: Codebase Artifacts (Not in Docs)

The following should also be cleaned up in the codebase:

v4/v5 API versioning in plugin headers - should only have current API
FrameHandle structure if superseded by RenderTarget
Legacy compatibility layers for transitioning plugins
Deprecated state variables like fence_pending_
Any _v2, _v3, _old, _deprecated function names
#ifdef LEGACY guards or version guards

Cleanup Action Items

Remove API version macros (WAXED_PLUGIN_API_V4, WAXED_PLUGIN_API_V5)
Remove FrameHandle documentation section (or merge into RenderTarget if needed)
Remove all “(ABI vX)” qualifiers from documentation
Remove Migration Notes sections
Remove deprecated state variable documentation
Remove Vulkan Provider legacy compatibility documentation
Delete VULKAN_RAAI_REFACTORING_PLAN.md
Rename waxed_plugin_render_v5 to just be the current render function
Update all docs to use present tense without version qualifiers

Files Requiring Cleanup

File	Items to Remove/Update
01-plugin-system.md	API macros, FrameHandle section, v4 references, ABI qualifiers
02-atomic-updates.md	Migration examples with old API, version references
03-core-api.md	Migration Notes section
05-render-loop.md	Deprecated fence_pending_ variable
09-shared-vulkan-device.md	Legacy compatibility layer reference
21-frame-pipeline.md	All ABI version qualifiers
VULKAN_RAAI_REFACTORING_PLAN.md	Delete entire file

Category: Terminology Consistency

Item 17: Display Server Naming

Issue: Inconsistent naming of the core project
Find: “Waxed compositor core”, “Waxed compositor”, “compositor”
Replace with: “Waxed Display Server” (or just “Waxed” when context is clear)
Scope: Project-wide (documentation, code comments, log messages)
Reason: Consistent terminology improves clarity and professionalism

Item 18: Background → Texture Refactoring

Issue: “Background” is a misnomer - it’s just texture loading, not background-specific
Scope: Core API, classes, documentation

API Functions to Remove:

set_background() → Remove entirely (superseded by DMA-BUF version)
set_background_video() → Remove entirely
get_background_descriptor() → Remove from CoreAPI
is_background_ready() → Remove from CoreAPI

API Function to Keep and Rename:

set_background_dma_buf() → Rename to load_texture_dma_buf() or similar
Add flag to indicate image vs video source, OR auto-detect from file extension

Class Renames Required:

BackgroundService → TextureService or similar
BackgroundDescriptor → TextureDescriptor or similar
BackgroundDmaBuf → TextureDmaBuf or similar
BackgroundMode → TextureMode or similar

Architectural Change:

Texture loading becomes plugin-internal logic
Core provides generic texture utilities (load image/video, export DMA-BUF, etc.)
Plugins decide how to use textures (background, sprites, UI elements, etc.)
This removes domain-specific assumptions from the core

Reason: The core should not have “background” as a first-class concept. Textures are general-purpose; “background” is just one use case that plugins handle.

Category: API Documentation to Extract

The following sections contain API-level documentation that should be moved to dedicated API reference documentation. The current documents should link to these references instead of duplicating the information.

File: docs/03-core-api.md

Item 14: Full CoreAPI Function Reference

Location: Entire document
Content: Detailed function signatures for all CoreAPI functions
Action: This IS the canonical API documentation. Already properly structured. Removed Migration Notes section. Other docs should link to this for CoreAPI details.

File: docs/14-ipc-protocol.md

Item 15: IPC Command/Response Structures

Location: Binary Protocol section, Text Protocol section
Content: Detailed packet structures, enums, field layouts
Action: This IS the protocol documentation. Keep as-is but ensure proper cross-references from waxedctl documentation.

File: docs/21-frame-pipeline.md

Item 16: RenderTarget Structure Details

Location: RenderTarget Structure section
Content: Field-by-field documentation of RenderTarget
Action: Should be in a shared API types reference. Plugin system doc and frame pipeline doc should both link to it.

File: docs/03-core-api.md

Item 19: BREAKING CHANGE Warnings

Location: Various function descriptions (e.g., get_display_config)
Content: “BREAKING CHANGE: Plugins MUST use this API…”
Reason: No breaking changes during development - the API is unstable by default. These warnings are redundant.
Action: Remove all “BREAKING CHANGE” notes from documentation.

Item 20: notify_cursor_shape_changed - Potentially Redundant

Location: CoreAPI, PluginManager
Content: notify_cursor_shape_changed() function
Reason: The cursor provider callback already returns the current cursor buffer. The core may be able to just call the callback on every frame or when needed, making the explicit notification redundant.
Action: Investigate whether this notification is truly needed. If the cursor buffer is checked every frame anyway, remove this function. If it provides a performance benefit by avoiding unnecessary refreshes, document why it exists.

Category: Documentation Quality

File: docs/04-display-manager.md

Item 21: VRR Section Cleanup

Issue: VRR documentation has issues
Location: VRR Support section

Problems:

“VRR Logging” subsection shows example log lines - documentation should not include log output examples
VRR detection lists multiple property names (vrr_capable, adaptive_sync, VRR_CAPABLE, etc.) that may be outdated or incorrect
VRR detection logic may need rework to be more robust

Action Required:

Remove “VRR Logging” subsection entirely
Review and update VRR property detection logic
Verify which DRM properties are actually used vs. documented
Consider simplifying the VRR detection documentation to describe the approach rather than listing every property variant

Category: Broken/Unused Features to Remove

Item 22: Frame Dumping Logic

Issue: Frame dumping is broken and should be removed entirely
Scope: Multiple files across codebase

Files to Delete:

src/core/frame_dumper.cpp
include/waxed/frame_dumper.h
tests/unit/test_frame_dumping.cpp
tests/unit/test_fence_handler_dump_sync.cpp
tests/unit/FRAME_DUMP_SYNC_TEST_SUMMARY.md

Code to Remove:

dump_ref_count field in BufferSlot (include/waxed/composer/buffer_slot.h)
Frame dumping logic in RenderLoop (src/composer/render_loop.cpp, include/waxed/composer/render_loop.h)
--dump-frames CLI option (src/core/cli.cpp, include/waxed/cli.h)
Frame dumping references in main.cpp
Frame dumping tests from CMakeLists.txt (src/CMakeLists.txt, tests/unit/CMakeLists.txt)

Documentation to Update:

Remove dump_ref_count references from docs/07-triple-buffer-system.md
Remove frame dumping mentions from docs/05-render-loop.md
Remove frame dumping mentions from docs/21-frame-pipeline.md
Update TESTING.md and COMPILING.md if they reference frame dumping

Reason: The feature is broken and unused. Removing it simplifies the codebase.

Action Required

Create api-reference.md or similar for shared data structures (RenderTarget, DisplayConfig, etc.)
Ensure 03-core-api.md is the canonical reference for CoreAPI functions
Update other documents to link to these references instead of duplicating