Various hardware, like the Type-C PHY or the Thunderbolt/USB4 NHI,
present on Apple SoCs need machine-specific tunables passed from our
bootloader m1n1 to the device tree. Add generic helpers so that we
don't have to duplicate this across multiple drivers.

Reviewed-by: Alyssa Rosenzweig <alyssa@rosenzweig.io>
Reviewed-by: Neal Gompa <neal@gompa.dev>
Signed-off-by: Sven Peter <sven@kernel.org>
---
 drivers/soc/apple/Kconfig         |  4 +++
 drivers/soc/apple/Makefile        |  3 ++
 drivers/soc/apple/tunable.c       | 71 +++++++++++++++++++++++++++++++++++++++
 include/linux/soc/apple/tunable.h | 60 +++++++++++++++++++++++++++++++++
 4 files changed, 138 insertions(+)

diff --git a/drivers/soc/apple/Kconfig b/drivers/soc/apple/Kconfig
index ad67368892311bed5a94d358288390a6fb8b3b4a..d0ff32182a2b4a10c98cb96c70a03bea8c650f84 100644
--- a/drivers/soc/apple/Kconfig
+++ b/drivers/soc/apple/Kconfig
@@ -38,6 +38,10 @@ config APPLE_SART
 
 	  Say 'y' here if you have an Apple SoC.
 
+config APPLE_TUNABLE
+	tristate
+	depends on ARCH_APPLE || COMPILE_TEST
+
 endmenu
 
 endif
diff --git a/drivers/soc/apple/Makefile b/drivers/soc/apple/Makefile
index 4d9ab8f3037b7159771d8817fa507ba29f99ae10..0b85ab61aefe131349a67d0aa80204edd8e89925 100644
--- a/drivers/soc/apple/Makefile
+++ b/drivers/soc/apple/Makefile
@@ -8,3 +8,6 @@ apple-rtkit-y = rtkit.o rtkit-crashlog.o
 
 obj-$(CONFIG_APPLE_SART) += apple-sart.o
 apple-sart-y = sart.o
+
+obj-$(CONFIG_APPLE_TUNABLE) += apple-tunable.o
+apple-tunable-y = tunable.o
diff --git a/drivers/soc/apple/tunable.c b/drivers/soc/apple/tunable.c
new file mode 100644
index 0000000000000000000000000000000000000000..c54da8ef28cef16118c518c761f95e8dd9f78002
--- /dev/null
+++ b/drivers/soc/apple/tunable.c
@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: GPL-2.0-only OR MIT
+/*
+ * Apple Silicon hardware tunable support
+ *
+ * Each tunable is a list with each entry containing a offset into the MMIO
+ * region, a mask of bits to be cleared and a set of bits to be set. These
+ * tunables are passed along by the previous boot stages and vary from device
+ * to device such that they cannot be hardcoded in the individual drivers.
+ *
+ * Copyright (C) The Asahi Linux Contributors
+ */
+
+#include <linux/io.h>
+#include <linux/module.h>
+#include <linux/of.h>
+#include <linux/soc/apple/tunable.h>
+
+struct apple_tunable *devm_apple_tunable_parse(struct device *dev,
+					       struct device_node *np,
+					       const char *name)
+{
+	struct apple_tunable *tunable;
+	struct property *prop;
+	const __be32 *p;
+	size_t sz;
+	int i;
+
+	prop = of_find_property(np, name, NULL);
+	if (!prop)
+		return ERR_PTR(-ENOENT);
+
+	if (prop->length % (3 * sizeof(u32)))
+		return ERR_PTR(-EINVAL);
+	sz = prop->length / (3 * sizeof(u32));
+
+	tunable = devm_kzalloc(dev,
+			       sizeof(*tunable) + sz * sizeof(*tunable->values),
+			       GFP_KERNEL);
+	if (!tunable)
+		return ERR_PTR(-ENOMEM);
+	tunable->sz = sz;
+
+	for (i = 0, p = NULL; i < tunable->sz; ++i) {
+		p = of_prop_next_u32(prop, p, &tunable->values[i].offset);
+		p = of_prop_next_u32(prop, p, &tunable->values[i].mask);
+		p = of_prop_next_u32(prop, p, &tunable->values[i].value);
+	}
+
+	return tunable;
+}
+EXPORT_SYMBOL(devm_apple_tunable_parse);
+
+void apple_tunable_apply(void __iomem *regs, struct apple_tunable *tunable)
+{
+	size_t i;
+
+	for (i = 0; i < tunable->sz; ++i) {
+		u32 val, old_val;
+
+		val = old_val = readl_relaxed(regs + tunable->values[i].offset);
+		val &= ~tunable->values[i].mask;
+		val |= tunable->values[i].value;
+		if (val != old_val)
+			writel_relaxed(val, regs + tunable->values[i].offset);
+	}
+}
+EXPORT_SYMBOL(apple_tunable_apply);
+
+MODULE_LICENSE("Dual MIT/GPL");
+MODULE_AUTHOR("Sven Peter <sven@kernel.org>");
+MODULE_DESCRIPTION("Apple Silicon hardware tunable support");
diff --git a/include/linux/soc/apple/tunable.h b/include/linux/soc/apple/tunable.h
new file mode 100644
index 0000000000000000000000000000000000000000..7e74e81b32e56c9a8ce94cb64bb340b007bac8da
--- /dev/null
+++ b/include/linux/soc/apple/tunable.h
@@ -0,0 +1,60 @@
+/* SPDX-License-Identifier: GPL-2.0-only OR MIT */
+/*
+ * Apple Silicon hardware tunable support
+ *
+ * Each tunable is a list with each entry containing a offset into the MMIO
+ * region, a mask of bits to be cleared and a set of bits to be set. These
+ * tunables are passed along by the previous boot stages and vary from device
+ * to device such that they cannot be hardcoded in the individual drivers.
+ *
+ * Copyright (C) The Asahi Linux Contributors
+ */
+
+#ifndef _LINUX_SOC_APPLE_TUNABLE_H_
+#define _LINUX_SOC_APPLE_TUNABLE_H_
+
+#include <linux/device.h>
+#include <linux/types.h>
+
+/**
+ * Struct to store an Apple Silicon hardware tunable.
+ *
+ * Each tunable is a list with each entry containing a offset into the MMIO
+ * region, a mask of bits to be cleared and a set of bits to be set. These
+ * tunables are passed along by the previous boot stages and vary from device
+ * to device such that they cannot be hardcoded in the individual drivers.
+ *
+ * @param sz Number of [offset, mask, value] tuples stored in values.
+ * @param values [offset, mask, value] array.
+ */
+struct apple_tunable {
+	size_t sz;
+	struct {
+		u32 offset;
+		u32 mask;
+		u32 value;
+	} values[] __counted_by(sz);
+};
+
+/**
+ * Parse an array of hardware tunables from the device tree.
+ *
+ * @dev: Device node used for devm_kzalloc internally.
+ * @np: Device node which contains the tunable array.
+ * @name: Name of the device tree property which contains the tunables.
+ *
+ * @return: devres allocated struct on success or PTR_ERR on failure.
+ */
+struct apple_tunable *devm_apple_tunable_parse(struct device *dev,
+					       struct device_node *np,
+					       const char *name);
+
+/**
+ * Apply a previously loaded hardware tunable.
+ *
+ * @param regs: MMIO to which the tunable will be applied.
+ * @param tunable: Pointer to the tunable.
+ */
+void apple_tunable_apply(void __iomem *regs, struct apple_tunable *tunable);
+
+#endif

-- 
2.34.1

Hej,

On Sun, Oct 26, 2025 at 01:52:01PM +0000, Sven Peter wrote:
> Various hardware, like the Type-C PHY or the Thunderbolt/USB4 NHI,
> present on Apple SoCs need machine-specific tunables passed from our
> bootloader m1n1 to the device tree. Add generic helpers so that we
> don't have to duplicate this across multiple drivers.
> 
> Reviewed-by: Alyssa Rosenzweig <alyssa@rosenzweig.io>
> Reviewed-by: Neal Gompa <neal@gompa.dev>
> Signed-off-by: Sven Peter <sven@kernel.org>
> ---
>  drivers/soc/apple/Kconfig         |  4 +++
>  drivers/soc/apple/Makefile        |  3 ++
>  drivers/soc/apple/tunable.c       | 71 +++++++++++++++++++++++++++++++++++++++
>  include/linux/soc/apple/tunable.h | 60 +++++++++++++++++++++++++++++++++
>  4 files changed, 138 insertions(+)
> 
> diff --git a/drivers/soc/apple/Kconfig b/drivers/soc/apple/Kconfig
> index ad67368892311bed5a94d358288390a6fb8b3b4a..d0ff32182a2b4a10c98cb96c70a03bea8c650f84 100644
> --- a/drivers/soc/apple/Kconfig
> +++ b/drivers/soc/apple/Kconfig
> @@ -38,6 +38,10 @@ config APPLE_SART
>  
>  	  Say 'y' here if you have an Apple SoC.
>  
> +config APPLE_TUNABLE
> +	tristate
> +	depends on ARCH_APPLE || COMPILE_TEST
> +
>  endmenu
>  
>  endif
> diff --git a/drivers/soc/apple/Makefile b/drivers/soc/apple/Makefile
> index 4d9ab8f3037b7159771d8817fa507ba29f99ae10..0b85ab61aefe131349a67d0aa80204edd8e89925 100644
> --- a/drivers/soc/apple/Makefile
> +++ b/drivers/soc/apple/Makefile
> @@ -8,3 +8,6 @@ apple-rtkit-y = rtkit.o rtkit-crashlog.o
>  
>  obj-$(CONFIG_APPLE_SART) += apple-sart.o
>  apple-sart-y = sart.o
> +
> +obj-$(CONFIG_APPLE_TUNABLE) += apple-tunable.o
> +apple-tunable-y = tunable.o
> diff --git a/drivers/soc/apple/tunable.c b/drivers/soc/apple/tunable.c
> new file mode 100644
> index 0000000000000000000000000000000000000000..c54da8ef28cef16118c518c761f95e8dd9f78002
> --- /dev/null
> +++ b/drivers/soc/apple/tunable.c
> @@ -0,0 +1,71 @@
> +// SPDX-License-Identifier: GPL-2.0-only OR MIT
> +/*
> + * Apple Silicon hardware tunable support
> + *
> + * Each tunable is a list with each entry containing a offset into the MMIO
> + * region, a mask of bits to be cleared and a set of bits to be set. These
> + * tunables are passed along by the previous boot stages and vary from device
> + * to device such that they cannot be hardcoded in the individual drivers.
> + *
> + * Copyright (C) The Asahi Linux Contributors
> + */
> +
> +#include <linux/io.h>
> +#include <linux/module.h>
> +#include <linux/of.h>
> +#include <linux/soc/apple/tunable.h>
> +
> +struct apple_tunable *devm_apple_tunable_parse(struct device *dev,
> +					       struct device_node *np,
> +					       const char *name)
> +{
> +	struct apple_tunable *tunable;
> +	struct property *prop;
> +	const __be32 *p;
> +	size_t sz;
> +	int i;
> +
> +	prop = of_find_property(np, name, NULL);
> +	if (!prop)
> +		return ERR_PTR(-ENOENT);
> +
> +	if (prop->length % (3 * sizeof(u32)))
> +		return ERR_PTR(-EINVAL);
> +	sz = prop->length / (3 * sizeof(u32));
> +
> +	tunable = devm_kzalloc(dev,
> +			       sizeof(*tunable) + sz * sizeof(*tunable->values),

There is a struct_size macro in linux/overflow.h for this calculation.
We do not have to care about overflows as as struct property.length
remains (signed) int. I would expect there is a much smaller limit for of
properties in place anyway. The macro looks nicer though:

struct_size(tunable, values, sz)

> +			       GFP_KERNEL);
> +	if (!tunable)
> +		return ERR_PTR(-ENOMEM);
> +	tunable->sz = sz;
> +
> +	for (i = 0, p = NULL; i < tunable->sz; ++i) {
> +		p = of_prop_next_u32(prop, p, &tunable->values[i].offset);

Does it make sense to add an size argument either here or in
apple_tunable_apply() to check that the offset is within the expect MMIO
region? Not really important but might catch a bug someday.

> +		p = of_prop_next_u32(prop, p, &tunable->values[i].mask);
> +		p = of_prop_next_u32(prop, p, &tunable->values[i].value);
> +	}
> +
> +	return tunable;
> +}
> +EXPORT_SYMBOL(devm_apple_tunable_parse);
> +
> +void apple_tunable_apply(void __iomem *regs, struct apple_tunable *tunable)
> +{
> +	size_t i;
> +
> +	for (i = 0; i < tunable->sz; ++i) {
> +		u32 val, old_val;
> +
> +		val = old_val = readl_relaxed(regs + tunable->values[i].offset);
> +		val &= ~tunable->values[i].mask;
> +		val |= tunable->values[i].value;
> +		if (val != old_val)
> +			writel_relaxed(val, regs + tunable->values[i].offset);
> +	}
> +}
> +EXPORT_SYMBOL(apple_tunable_apply);
> +
> +MODULE_LICENSE("Dual MIT/GPL");
> +MODULE_AUTHOR("Sven Peter <sven@kernel.org>");
> +MODULE_DESCRIPTION("Apple Silicon hardware tunable support");
> diff --git a/include/linux/soc/apple/tunable.h b/include/linux/soc/apple/tunable.h
> new file mode 100644
> index 0000000000000000000000000000000000000000..7e74e81b32e56c9a8ce94cb64bb340b007bac8da
> --- /dev/null
> +++ b/include/linux/soc/apple/tunable.h
> @@ -0,0 +1,60 @@
> +/* SPDX-License-Identifier: GPL-2.0-only OR MIT */
> +/*
> + * Apple Silicon hardware tunable support
> + *
> + * Each tunable is a list with each entry containing a offset into the MMIO
> + * region, a mask of bits to be cleared and a set of bits to be set. These
> + * tunables are passed along by the previous boot stages and vary from device
> + * to device such that they cannot be hardcoded in the individual drivers.
> + *
> + * Copyright (C) The Asahi Linux Contributors
> + */
> +
> +#ifndef _LINUX_SOC_APPLE_TUNABLE_H_
> +#define _LINUX_SOC_APPLE_TUNABLE_H_
> +
> +#include <linux/device.h>
> +#include <linux/types.h>
> +
> +/**
> + * Struct to store an Apple Silicon hardware tunable.
> + *
> + * Each tunable is a list with each entry containing a offset into the MMIO
> + * region, a mask of bits to be cleared and a set of bits to be set. These
> + * tunables are passed along by the previous boot stages and vary from device
> + * to device such that they cannot be hardcoded in the individual drivers.
> + *
> + * @param sz Number of [offset, mask, value] tuples stored in values.
> + * @param values [offset, mask, value] array.
> + */
> +struct apple_tunable {
> +	size_t sz;
> +	struct {
> +		u32 offset;
> +		u32 mask;
> +		u32 value;
> +	} values[] __counted_by(sz);
> +};
> +
> +/**
> + * Parse an array of hardware tunables from the device tree.
> + *
> + * @dev: Device node used for devm_kzalloc internally.
> + * @np: Device node which contains the tunable array.
> + * @name: Name of the device tree property which contains the tunables.
> + *
> + * @return: devres allocated struct on success or PTR_ERR on failure.
> + */
> +struct apple_tunable *devm_apple_tunable_parse(struct device *dev,
> +					       struct device_node *np,
> +					       const char *name);
> +
> +/**
> + * Apply a previously loaded hardware tunable.
> + *
> + * @param regs: MMIO to which the tunable will be applied.
> + * @param tunable: Pointer to the tunable.
> + */
> +void apple_tunable_apply(void __iomem *regs, struct apple_tunable *tunable);
> +
> +#endif

Reviewed-by: Janne Grunau <j@jannau.net>

Janne

Hi,

On 29.10.25 20:21, Janne Grunau wrote:
> Hej,
> 
> On Sun, Oct 26, 2025 at 01:52:01PM +0000, Sven Peter wrote:
>> Various hardware, like the Type-C PHY or the Thunderbolt/USB4 NHI,
>> present on Apple SoCs need machine-specific tunables passed from our
>> bootloader m1n1 to the device tree. Add generic helpers so that we
>> don't have to duplicate this across multiple drivers.
>>
>> Reviewed-by: Alyssa Rosenzweig <alyssa@rosenzweig.io>
>> Reviewed-by: Neal Gompa <neal@gompa.dev>
>> Signed-off-by: Sven Peter <sven@kernel.org>

[...]

>> +
>> +	tunable = devm_kzalloc(dev,
>> +			       sizeof(*tunable) + sz * sizeof(*tunable->values),
> 
> There is a struct_size macro in linux/overflow.h for this calculation.
> We do not have to care about overflows as as struct property.length
> remains (signed) int. I would expect there is a much smaller limit for of
> properties in place anyway. The macro looks nicer though:
> 
> struct_size(tunable, values, sz)

Nice, I'll use that!

> 
>> +			       GFP_KERNEL);
>> +	if (!tunable)
>> +		return ERR_PTR(-ENOMEM);
>> +	tunable->sz = sz;
>> +
>> +	for (i = 0, p = NULL; i < tunable->sz; ++i) {
>> +		p = of_prop_next_u32(prop, p, &tunable->values[i].offset);
> 
> Does it make sense to add an size argument either here or in
> apple_tunable_apply() to check that the offset is within the expect MMIO
> region? Not really important but might catch a bug someday.

I would've usually said this was overkill but given that we just found a 
bug in our bootloader which caused us to copy random memory as tunables 
a week or two ago because of a stale fdt node id I'll add some sanity 
checks here.

> 
>> +		p = of_prop_next_u32(prop, p, &tunable->values[i].mask);
>> +		p = of_prop_next_u32(prop, p, &tunable->values[i].value);

[...]

>> +/**
>> + * Apply a previously loaded hardware tunable.
>> + *
>> + * @param regs: MMIO to which the tunable will be applied.
>> + * @param tunable: Pointer to the tunable.
>> + */
>> +void apple_tunable_apply(void __iomem *regs, struct apple_tunable *tunable);
>> +
>> +#endif
> 
> Reviewed-by: Janne Grunau <j@jannau.net>

thanks!


Sven