Check generated Compat dependency versions

AGENTS.md

@@ -35,6 +35,11 @@ when their work informed a change.
 ## Build and test
 
 Build with `python3 tools/build.py`; run CPU tests with `python3 tools/test.py`.
+The builder checks each generated Compat plist, including both DEBUG and RELEASE
+in CI. Existing output can be checked with `python3 tools/check_compat_version.py`
+and its build directory. Compat's release version and oldest compatible ABI are independent;
+do not raise the compatibility floor during an ordinary version bump. An ABI
+break requires coordinated Graphics client updates and final-pkg validation.
 Lilu.kext and MacKernelSDK are local ignored dependencies. Optional native replay
 requires the exact Apple drivers accepted by the tests. Do not commit generated
 payloads, Apple driver files, credentials or local machine state.

tests/compat_bundle_version.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+import plistlib
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'tools'))
+from check_compat_version import check
+
+
+class CompatVersionTests(unittest.TestCase):
+    def validate(self, current, minimum):
+        with tempfile.TemporaryDirectory() as temporary:
+            path = Path(temporary) / 'Info.plist'
+            path.write_bytes(plistlib.dumps({
+                'CFBundleIdentifier': 'org.b00t0x.AppleIntelTGLCompat',
+                'CFBundleVersion': current, 'OSBundleCompatibleVersion': minimum}))
+            check(path)
+
+    def test_release_bump_preserves_old_clients(self):
+        for current in ['0.5.0', '0.6.0', '0.7.0', '1.0.0']:
+            with self.subTest(current=current):
+                self.validate(current, '0.5.0')
+
+    def test_compatibility_floor_bump_rejects_old_clients(self):
+        with self.assertRaisesRegex(ValueError, 'no longer accepts'):
+            self.validate('0.6.0', '0.6.0')
+
+    def test_provider_too_old(self):
+        with self.assertRaisesRegex(ValueError, 'no longer accepts'):
+            self.validate('0.4.0', '0.4.0')
+
+
+if __name__ == '__main__':
+    unittest.main()

tools/build.py

@@ -2,6 +2,7 @@
 """Build the standalone x86_64 Lilu plugin and donor symbol provider."""
 import argparse,hashlib,json,plistlib,subprocess
 from pathlib import Path
+from check_compat_version import check as check_compat_version
 ROOT=Path(__file__).resolve().parents[1]
 def run(cmd): subprocess.run([str(x) for x in cmd],check=True,cwd=ROOT)
 def main():
@@ -45,6 +46,7 @@ def main():
    # Keep the native policy class, scoped to its Intel client and independent of SMBIOS.
    info['IOKitPersonalities']=plistlib.loads((ROOT/'AppleIntelTGLCompat/GraphicsPolicy.plist').read_bytes())
   (bundle/'Info.plist').write_bytes(plistlib.dumps(info))
+  if name=='AppleIntelTGLCompat':check_compat_version(bundle/'Info.plist')
   # Preserve DWARF before removing the linker's object-path records.
   if name=='WhateverXe':run(['xcrun','dsymutil',exe,'-o',out/(name+'.kext.dSYM')])
   run(['xcrun','strip','-S',exe])

tools/check_compat_version.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Check that built Compat bundles still accept the shipped framebuffer ABI."""
+import argparse
+import plistlib
+import re
+from pathlib import Path
+
+
+def version(value):
+    if not isinstance(value, str) or not re.fullmatch(r'\d+\.\d+\.\d+', value):
+        raise ValueError(f'unsupported Compat version: {value!r}')
+    return tuple(map(int, value.split('.')))
+
+
+def check(path):
+    info = plistlib.loads(path.read_bytes())
+    if info['CFBundleIdentifier'] != 'org.b00t0x.AppleIntelTGLCompat':
+        raise ValueError('wrong Compat bundle identifier')
+    # Existing Graphics framebuffer payloads request this ABI independently of
+    # the provider's release version. Changing it requires coordinated clients.
+    required = (0, 5, 0)
+    if not version(info['OSBundleCompatibleVersion']) <= required <= version(info['CFBundleVersion']):
+        raise ValueError('Compat no longer accepts the shipped framebuffer dependency 0.5.0')
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('builds', type=Path, nargs='+')
+    args = parser.parse_args()
+    for build in args.builds:
+        check(build / 'AppleIntelTGLCompat.kext/Contents/Info.plist')
+    print('PASS: built Compat bundles accept the shipped framebuffer dependency')

tools/test.py

@@ -8,7 +8,7 @@
 python_tests=['framebuffer_training_registration','framebuffer_common','display13_shared_registration','adlp_render','firmware_readout','display13_offline','adlp_fb_candidate','display13_tc_native','display13_ddc','adlp_load_only','small_gt_urb','display_backend_dispatch','tgl_agdc_port_status','display_contract_adapter','tgl_agdc_aux_observer','xe_data_access','adls_aux_parent','adls_lane_power','adls_clock_guard','adls_clock_runtime','adls_boot_runtime','xelp_mmio_bar','bigsur_pmap','tahoe_iosurface','tahoe_pmap','sequoia_pmap','sonoma_iosurface','sonoma_pmap','ventura_pmap','tgl_kernel_admission','monterey_pmap','xelp_forcewake_irq','boot_arguments','tgl_display_observers','tgl_stream_ack','tgl_transmitter_observer','tgl_transition_live','tgl_aux_live','tgl_bootstrap_host','tgl_clock_order','provider_binding','tgl_start_order','tgl_hdmi_wiring','tgl_bootstrap_aux','tgl_copy_routing','tgl_training_leases','tgl_wiring','tgl_boot_readout','tgl_pcode_gate','tgl_port_use','tgl_tc_cold','tgl_fia','tgl_port_map','tgl_dp_alt_fia','tgl_dp_mode_replace','tgl_phy_clock_gating','tgl_probe','dvmt','host_publication']
 jobs=[(p.stem,['clang++','-std=c++17','-O1','-g','-fsanitize=address,undefined','-fno-omit-frame-pointer','-I'+str(R/'WhateverXe'),str(p),'-o',str(O/p.stem)],[str(O/p.stem)]) for p in sorted((R/'tests').glob('*.cpp')) if not p.stem.endswith('_fixture')]
 python_tests += ['tgl_power_fuses', 'display13_boot_aux', 'display13_aux', 'display13_sst', 'display13_combo_clock', 'adls_panel_pwm', 'tgl_panel_timing', 'backlight_adapter', 'tgl_panel_power', 'tgl_edp_transcoder', 'tgl_training_pattern', 'tgl_combo_pll_write', 'tgl_sink_framing', 'tgl_combo_aux_gate', 'tgl_combo_signal_guard', 'tgl_combo_aux_lifetime', 'tgl_iosurface_compression', 'tgl_panel_depth_route', 'display13_tiling']
-python_tests += ['xelp_combo_clock_guard','display13_tc_preparation','display13_retirement','display13_port_wait','display13_agdc','display13_training_frontend','framebuffer_donor_runtime']
+python_tests += ['xelp_combo_clock_guard','display13_tc_preparation','display13_retirement','display13_port_wait','display13_agdc','display13_training_frontend','framebuffer_donor_runtime','compat_bundle_version']
 jobs += [(n,[sys.executable,str(R/'tests'/(n+'.py'))],None) for n in python_tests]
 if a.donor:jobs += [('display13_agdc_native',[sys.executable,str(R/'tests/display13_agdc.py'),str(a.donor.resolve())],None)]
 if a.donor:jobs += [('adls_ddi_power_native',[sys.executable,str(R/'tests/adls_ddi_power_native.py'),str(a.donor.resolve())],None)]