diff --git a/AGENTS.md b/AGENTS.md index 54c70fea..0e0187f6 100644 --- a/AGENTS.md +++ b/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. diff --git a/tests/compat_bundle_version.py b/tests/compat_bundle_version.py new file mode 100644 index 00000000..2152dd65 --- /dev/null +++ b/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() diff --git a/tools/build.py b/tools/build.py index a7b525c1..72871ede 100644 --- a/tools/build.py +++ b/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]) diff --git a/tools/check_compat_version.py b/tools/check_compat_version.py new file mode 100644 index 00000000..fb905471 --- /dev/null +++ b/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') diff --git a/tools/test.py b/tools/test.py index 8217c70a..197782db 100644 --- a/tools/test.py +++ b/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)]