Legacy Driver Separation in Mesa: A Step-by-Step Guide to Git Branching

Overview

In the Mesa graphics driver ecosystem, maintaining support for older GPUs while advancing modern OpenGL and Vulkan drivers creates tension. Recently, Valve Linux graphics team member Mike Blumenkrantz proposed a solution: shifting some older GPU drivers—including ATI/AMD R300 and R600—into a separate legacy Git branch. This guide details how such a branching strategy works, why it is considered, and how developers can implement it. By isolating legacy code, the mainline Mesa codebase can be cleaned and optimized without risking breakage for older hardware users.

Prerequisites

• Familiarity with the Mesa 3D Graphics Library codebase and its driver architecture.
• Working knowledge of Git, especially branching, rebasing, and cherry-picking.
• Understanding of OpenGL and Vulkan driver development processes.
• Access to a Mesa development environment (e.g., Linux, build tools, hardware for testing).
• Basic comprehension of the driver lifecycle: maintenance, deprecation, and removal.

Step-by-Step Instructions

1. Identify Candidates for the Legacy Branch

Begin by listing all Mesa drivers that are no longer actively developed or are based on outdated hardware architectures. In the current discussion, the ATI/AMD R300 (Radeon 9500–X1950 series) and R600 (Radeon HD 2000–6000 series) have been flagged, along with several smaller drivers for older GPUs. Document each driver’s state:

• Number of active users and bug reports.
• Frequency of changes in the last 12 months.
• Integration dependencies with common Mesa infrastructure (e.g., Gallium, state trackers).

2. Create the Legacy Git Branch

Using the main Mesa repository, create a new branch (e.g., legacy-drivers-2025) from the current stable release tag. This branch will act as the long-term home for legacy drivers, receiving only critical fixes.

git checkout -b legacy-drivers-2025 <stable-tag>
git push origin legacy-drivers-2025

3. Remove Legacy Drivers from Mainline

On the main development branch (e.g., main), delete the directories and build files related to the identified legacy drivers. For example, for R300 and R600:

git rm -r src/gallium/drivers/r300
  src/gallium/drivers/r600
  src/mesa/drivers/dri/r300
  src/mesa/drivers/dri/r600
git commit -m "Remove legacy R300 and R600 drivers to mainline"
git push origin main

4. Update Build System and Dependencies

Modify meson.build files to remove references to those drivers. Disable related Gallium targets and ensure meson options no longer include them. Update CI configuration to skip building legacy branch drivers on mainline.

5. Integrate Legacy Branch into the Workflow

Set up a merge strategy for security and critical bug fixes. For each fix that affects both branches, cherry-pick the commit from mainline into the legacy branch, or vice versa, according to the origin of the change. Document the procedure in a LEGACY_BRANCH.md file.

6. Communicate with the Community

Publish a notice on the Mesa mailing list and GitLab explaining the change. Provide a timeline for the transition, and instructions for users or downstream packagers who need to bundle the legacy drivers. Offer a simple one-liner to clone the legacy branch:

git clone -b legacy-drivers-2025 https://gitlab.freedesktop.org/mesa/mesa.git

Common Mistakes

• Breaking CI: Removing drivers without adjusting CI pipelines can cause test failures. Always test the main branch after removal.
• Forgetting Reverse Dependencies: Some legacy drivers share common code (e.g., shader compilers). Ensure those files are copied or retained in the legacy branch.
• Skipping Documentation: Without clear documentation, downstream users may struggle to find the legacy code. Update docs/relnotes/ and add a README.
• Irreversible Deletion: Some legacy hardware is still in use. Consider a deprecation period before complete removal from mainline, as proposed by Blumenkrantz.

Summary

This guide outlined a Git branching strategy for isolating older Mesa GPU drivers, using the proposed R300/R600 split as an example. By creating a dedicated legacy branch, developers can clean the mainline codebase and accelerate modern OpenGL/Vulkan features without sacrificing support for legacy hardware. The steps include driver identification, branching, code removal, build system updates, and community communication. Avoiding common pitfalls like broken CI and incomplete documentation ensures a smooth transition.