Re: [PATCH v2 02/11] dt-bindings: hwmon: Add Apple System Management Controller hwmon schema

Rob Herring
2025-08-29T16:40:58Z

On Wed, Aug 27, 2025 at 09:22:36PM +1000, James Calligeros wrote:
> Apple Silicon devices integrate a vast array of sensors, monitoring
> current, power, temperature, and voltage across almost every part of
> the system. The sensors themselves are all connected to the System
> Management Controller (SMC). The SMC firmware exposes the data
> reported by these sensors via its standard FourCC-based key-value
> API. The SMC is also responsible for monitoring and controlling any
> fans connected to the system, exposing them in the same way.
>
> For reasons known only to Apple, each device exposes its sensors with
> an almost totally unique set of keys. This is true even for devices
> which share an SoC. An M1 Mac mini, for example, will report its core
> temperatures on different keys to an M1 MacBook Pro. Worse still, the
> SMC does not provide a way to enumerate the available keys at runtime,
> nor do the keys follow any sort of reasonable or consistent naming
> rules that could be used to deduce their purpose. We must therefore
> know which keys are present on any given device, and which function
> they serve, ahead of time.
>
> Add a schema so that we can describe the available sensors for a given
> Apple Silicon device in the Devicetree.
>
> Signed-off-by: James Calligeros <jcalligeros99@gmail.com>
> ---
> .../bindings/hwmon/apple,smc-hwmon.yaml | 132 +++++++++++++++++++++++++
> .../bindings/mfd/apple,smc.yaml | 36 +++++++
> MAINTAINERS | 1 +
> 3 files changed, 169 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/hwmon/apple,smc-hwmon.yaml b/Documentation/devicetree/bindings/hwmon/apple,smc-hwmon.yaml
> new file mode 100644
> index 0000000000000000000000000000000000000000..08cc4f55f3a41ca8b3b428088f96240266fa42e8
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/hwmon/apple,smc-hwmon.yaml
> @@ -0,0 +1,132 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/hwmon/apple,smc-hwmon.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Apple SMC Hardware Monitoring
> +
> +description:
> + Apple's System Management Controller (SMC) exposes a vast array of
> + hardware monitoring sensors, including temperature probes, current and
> + voltage sense, power meters, and fan speeds. It also provides endpoints
> + to manually control the speed of each fan individually. Each Apple
> + Silicon device exposes a different set of endpoints via SMC keys. This
> + is true even when two machines share an SoC. The CPU core temperature
> + sensor keys on an M1 Mac mini are different to those on an M1 MacBook
> + Pro, for example.
> +
> +maintainers:
> + - James Calligeros <jcalligeros99@gmail.com>
> +
> +definitions:

$defs

definitions was convention. $defs is in json-schema spec now.

> + apple,key-id:
> + $ref: /schemas/types.yaml#/definitions/string
> + pattern: "^[A-Za-z0-9]{4}$"
> + description: The SMC FourCC key of the desired sensor.
> + Must match the node's suffix.
> +
> + label:
> + description: Human-readable name for the sensor
> +
> +properties:
> + compatible:
> + const: apple,smc-hwmon
> +
> +patternProperties:
> + "^current-[A-Za-z0-9]{4}$":
> + type: object
> + additionalProperties: false
> +
> + properties:
> + apple,key-id:
> + $ref: "#/definitions/apple,key-id"
> +
> + label:
> + $ref: "#/definitions/label"
> +
> + required:
> + - apple,key-id
> + - label

This should be something like this:

"^current-[A-Za-z0-9]{4}$":
$ref: "#/$defs/sensor"
unevaluatedProperties: false

With the $defs/sensor being:

$defs:
sensor:
type: object

properties:
apple,key-id:
$ref: /schemas/types.yaml#/definitions/string
pattern: "^[A-Za-z0-9]{4}$"
description:
The SMC FourCC key of the desired sensor. Must match the
node's suffix.

label:
description: Human-readable name for the sensor

required:
- apple,key-id
- label

Though in general, 'label' should never be required being just for human
convenience.

> +
> + "^fan-[A-Za-z0-9]{4}$":
> + type: object
> + additionalProperties: false

And this one the same as above, but with the additional fan properties
listed here.

> +
> + properties:
> + apple,key-id:
> + $ref: "#/definitions/apple,key-id"
> +
> + apple,fan-minimum:
> + $ref: /schemas/types.yaml#/definitions/string
> + pattern: "^[A-Za-z0-9]{4}$"
> + description: SMC key containing the fan's minimum speed
> +
> + apple,fan-maximum:
> + $ref: /schemas/types.yaml#/definitions/string
> + pattern: "^[A-Za-z0-9]{4}$"
> + description: SMC key containing the fan's maximum speed
> +
> + apple,fan-target:
> + $ref: /schemas/types.yaml#/definitions/string
> + pattern: "^[A-Za-z0-9]{4}$"
> + description: Writeable endpoint for setting desired fan speed
> +
> + apple,fan-mode:
> + $ref: /schemas/types.yaml#/definitions/string
> + pattern: "^[A-Za-z0-9]{4}$"
> + description: Writeable key to enable/disable manual fan control
> +
> + label:
> + $ref: "#/definitions/label"
> +
> + required:
> + - apple,key-id
> + - label
> +
> + "^power-[A-Za-z0-9]{4}$":
> + type: object
> + additionalProperties: false
> +
> + properties:
> + apple,key-id:
> + $ref: "#/definitions/apple,key-id"
> +
> + label:
> + $ref: "#/definitions/label"
> +
> + required:
> + - apple,key-id
> + - label
> +
> + "^temperature-[A-Za-z0-9]{4}$":
> + type: object
> + additionalProperties: false
> +
> + properties:
> + apple,key-id:
> + $ref: "#/definitions/apple,key-id"
> +
> + label:
> + $ref: "#/definitions/label"
> +
> + required:
> + - apple,key-id
> + - label
> +
> + "^voltage-[A-Za-z0-9]{4}$":
> + type: object
> + additionalProperties: false
> +
> + properties:
> + apple,key-id:
> + $ref: "#/definitions/apple,key-id"
> +
> + label:
> + $ref: "#/definitions/label"
> +
> + required:
> + - apple,key-id
> + - label
> +
> +additionalProperties: false