Merge pull request #110264 from stuartcarnie/109846/metal_version

Metal: Ensure baked Metal binaries can be loaded on the minimum target OS

Author: clayjohn

drivers/metal/metal_device_properties.h

@@ -143,11 +143,15 @@ class API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0)) MetalDeviceProperties {
 private:
 	void init_features(id<MTLDevice> p_device);
 	void init_limits(id<MTLDevice> p_device);
+	void init_os_props();
 
 public:
 	MetalFeatures features;
 	MetalLimits limits;
 
+	// maj * 10000 + min * 100 + patch
+	uint32_t os_version;
+
 	SampleCount find_nearest_supported_sample_count(RenderingDevice::TextureSamples p_samples) const;
 
 	MetalDeviceProperties(id<MTLDevice> p_device);

drivers/metal/metal_device_properties.mm

@@ -311,9 +311,15 @@
 #endif
 }
 
+void MetalDeviceProperties::init_os_props() {
+	NSOperatingSystemVersion ver = NSProcessInfo.processInfo.operatingSystemVersion;
+	os_version = (uint32_t)ver.majorVersion * 10000 + (uint32_t)ver.minorVersion * 100 + (uint32_t)ver.patchVersion;
+}
+
 MetalDeviceProperties::MetalDeviceProperties(id<MTLDevice> p_device) {
 	init_features(p_device);
 	init_limits(p_device);
+	init_os_props();
 }
 
 MetalDeviceProperties::~MetalDeviceProperties() {

drivers/metal/metal_utils.h

@@ -103,6 +103,11 @@ extern os_log_t LOG_DRIVER;
 // Used for dynamic tracing.
 extern os_log_t LOG_INTERVALS;
 
-_FORCE_INLINE_ static uint32_t make_msl_version(uint32_t major, uint32_t minor = 0, uint32_t patch = 0) {
-	return (major * 10000) + (minor * 100) + patch;
+_FORCE_INLINE_ static uint32_t make_msl_version(uint32_t p_major, uint32_t p_minor = 0, uint32_t p_patch = 0) {
+	return (p_major * 10000) + (p_minor * 100) + p_patch;
+}
+
+_FORCE_INLINE_ static void parse_msl_version(uint32_t p_version, uint32_t &r_major, uint32_t &r_minor) {
+	r_major = p_version / 10000;
+	r_minor = (p_version % 10000) / 100;
 }

drivers/metal/rendering_device_driver_metal.mm

@@ -1135,12 +1135,17 @@ static BindingInfo from_binding_info_data(const RenderingShaderContainerMetal::B
 	// We need to regenerate the shader if the cache is moved to an incompatible device.
 	ERR_FAIL_COND_V_MSG(device_properties->features.argument_buffers_tier < MTLArgumentBuffersTier2 && mtl_reflection_data.uses_argument_buffers(),
 			RDD::ShaderID(),
-			"Shader was generated with argument buffers, but device has limited support");
+			"Shader was compiled with argument buffers enabled, but this device does not support them");
 
 	uint32_t msl_version = make_msl_version(device_properties->features.mslVersionMajor, device_properties->features.mslVersionMinor);
 	ERR_FAIL_COND_V_MSG(msl_version < mtl_reflection_data.msl_version,
 			RDD::ShaderID(),
-			"Shader was compiled with a newer version of Metal than is available on the device.");
+			"Shader was compiled for a newer version of Metal");
+
+	MTLGPUFamily compiled_gpu_family = static_cast<MTLGPUFamily>(mtl_reflection_data.profile.gpu);
+	ERR_FAIL_COND_V_MSG(device_properties->features.highestFamily < compiled_gpu_family,
+			RDD::ShaderID(),
+			"Shader was generated for a newer Apple GPU");
 
 	MTLCompileOptions *options = [MTLCompileOptions new];
 	uint32_t major = mtl_reflection_data.msl_version / 10000;
@@ -1181,6 +1186,9 @@ static BindingInfo from_binding_info_data(const RenderingShaderContainerMetal::B
 
 		MDLibrary *library = nil;
 		if (shader_data.library_size > 0) {
+			ERR_FAIL_COND_V_MSG(mtl_reflection_data.os_min_version > device_properties->os_version,
+					RDD::ShaderID(),
+					"Metal shader binary was generated for a newer target OS");
 			dispatch_data_t binary = dispatch_data_create(decompressed_code.ptr() + shader_data.source_size, shader_data.library_size, dispatch_get_main_queue(), DISPATCH_DATA_DESTRUCTOR_DEFAULT);
 			library = [MDLibrary newLibraryWithCacheEntry:cd
 												   device:device

drivers/metal/rendering_shader_container_metal.h

@@ -41,6 +41,25 @@ const uint32_t VIEW_MASK_BUFFER_INDEX = 24;
 
 class RenderingShaderContainerFormatMetal;
 
+class MinOsVersion {
+	uint32_t version;
+
+public:
+	String to_compiler_os_version() const;
+	bool is_null() const { return version == UINT32_MAX; }
+	bool is_valid() const { return version != UINT32_MAX; }
+
+	MinOsVersion(const String &p_version);
+	explicit MinOsVersion(uint32_t p_version) :
+			version(p_version) {}
+	MinOsVersion() :
+			version(UINT32_MAX) {}
+
+	bool operator>(uint32_t p_other) {
+		return version > p_other;
+	}
+};
+
 /// @brief A minimal structure that defines a device profile for Metal.
 ///
 /// This structure is used by the `RenderingShaderContainerMetal` class to
@@ -53,17 +72,20 @@ struct MetalDeviceProfile {
 		iOS = 1,
 	};
 
-	/// @brief The GPU family.
+	/*! @brief The GPU family.
+	 *
+	 * NOTE: These values match Apple's MTLGPUFamily
+	 */
 	enum class GPU : uint32_t {
-		Apple1,
-		Apple2,
-		Apple3,
-		Apple4,
-		Apple5,
-		Apple6,
-		Apple7,
-		Apple8,
-		Apple9,
+		Apple1 = 1001,
+		Apple2 = 1002,
+		Apple3 = 1003,
+		Apple4 = 1004,
+		Apple5 = 1005,
+		Apple6 = 1006,
+		Apple7 = 1007,
+		Apple8 = 1008,
+		Apple9 = 1009,
 	};
 
 	enum class ArgumentBuffersTier : uint32_t {
@@ -108,6 +130,13 @@ class RenderingShaderContainerMetal : public RenderingShaderContainer {
 		/// The Metal language version specified when compiling SPIR-V to MSL.
 		/// Format is major * 10000 + minor * 100 + patch.
 		uint32_t msl_version = UINT32_MAX;
+		/*! @brief The minimum supported OS version for shaders baked to a `.metallib`.
+		 *
+		 * NOTE: This property is only valid when shaders are baked to a .metalllib
+		 *
+		 * Format is major * 10000 + minor * 100 + patch.
+		 */
+		MinOsVersion os_min_version;
 		uint32_t flags = NONE;
 
 		/// @brief Returns `true` if the shader is compiled with multi-view support.
@@ -210,9 +239,23 @@ class RenderingShaderContainerMetal : public RenderingShaderContainer {
 	HeaderData mtl_reflection_data; // compliment to reflection_data
 	Vector<StageData> mtl_shaders; // compliment to shaders
 
+private:
+	struct ToolchainProperties {
+		MinOsVersion os_version_min_required;
+		uint32_t metal_version = UINT32_MAX;
+
+		_FORCE_INLINE_ bool is_null() const { return os_version_min_required.is_null() || metal_version == UINT32_MAX; }
+		_FORCE_INLINE_ bool is_valid() const { return !is_null(); }
+	};
+
+	ToolchainProperties compiler_props;
+
+	void _initialize_toolchain_properties();
+
 private:
 	const MetalDeviceProfile *device_profile = nullptr;
 	bool export_mode = false;
+	MinOsVersion min_os_version;
 
 	Vector<UniformData> mtl_reflection_binding_set_uniforms_data; // compliment to reflection_binding_set_uniforms_data
 	Vector<SpecializationData> mtl_reflection_specialization_data; // compliment to reflection_specialization_data
@@ -224,6 +267,7 @@ class RenderingShaderContainerMetal : public RenderingShaderContainer {
 
 	void set_export_mode(bool p_export_mode) { export_mode = p_export_mode; }
 	void set_device_profile(const MetalDeviceProfile *p_device_profile) { device_profile = p_device_profile; }
+	void set_min_os_version(const MinOsVersion p_min_os_version) { min_os_version = p_min_os_version; }
 
 	struct MetalShaderReflection {
 		Vector<Vector<UniformData>> uniform_sets;
@@ -253,13 +297,14 @@ class RenderingShaderContainerMetal : public RenderingShaderContainer {
 
 class RenderingShaderContainerFormatMetal : public RenderingShaderContainerFormat {
 	bool export_mode = false;
+	MinOsVersion min_os_version;
 
 	const MetalDeviceProfile *device_profile = nullptr;
 
 public:
 	virtual Ref<RenderingShaderContainer> create_container() const override;
 	virtual ShaderLanguageVersion get_shader_language_version() const override;
 	virtual ShaderSpirvVersion get_shader_spirv_version() const override;
-	RenderingShaderContainerFormatMetal(const MetalDeviceProfile *p_device_profile, bool p_export = false);
+	RenderingShaderContainerFormatMetal(const MetalDeviceProfile *p_device_profile, bool p_export = false, const MinOsVersion p_min_os_version = MinOsVersion());
 	virtual ~RenderingShaderContainerFormatMetal() = default;
 };