[v2,02/25] dt-bindings: arm: apple: Add bindings for Apple ARM platforms

This introduces bindings for all three 2020 Apple M1 devices:

* apple,j274 - Mac mini (M1, 2020)
* apple,j293 - MacBook Pro (13-inch, M1, 2020)
* apple,j313 - MacBook Air (M1, 2020)

Signed-off-by: Hector Martin <marcan@marcan.st>
---
 .../devicetree/bindings/arm/apple.yaml        | 36 +++++++++++++++++++
 MAINTAINERS                                   | 10 ++++++
 2 files changed, 46 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/apple.yaml

On Mon, Feb 15, 2021 at 09:16:50PM +0900, Hector Martin wrote:
> This introduces bindings for all three 2020 Apple M1 devices:
> 
> * apple,j274 - Mac mini (M1, 2020)
> * apple,j293 - MacBook Pro (13-inch, M1, 2020)
> * apple,j313 - MacBook Air (M1, 2020)
> 
> Signed-off-by: Hector Martin <marcan@marcan.st>
> ---
>  .../devicetree/bindings/arm/apple.yaml        | 36 +++++++++++++++++++
>  MAINTAINERS                                   | 10 ++++++
>  2 files changed, 46 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/arm/apple.yaml
> 
> diff --git a/Documentation/devicetree/bindings/arm/apple.yaml b/Documentation/devicetree/bindings/arm/apple.yaml
> new file mode 100644
> index 000000000000..e44d308d6bde
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/arm/apple.yaml
> @@ -0,0 +1,36 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/arm/apple.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Apple ARM Machine Device Tree Bindings
> +
> +maintainers:
> +  - Hector Martin <marcan@marcan.st>
> +
> +description: |
> +  Apple ARM ("Apple Silicon") platforms should contain compatible strings
> +  in the following format:
> +
> +  - apple,j274 (board/device ID)
> +  - apple,m1 (SoC name)
> +  - apple,arm-platform (Apple Silicon)

This description is irrelevant because the rules come from schema below.
Maybe instead write few words about the platform? Or describe how to get
the board/device ID if it is not obvious?

Best regards,
Krzysztof

On 16/02/2021 02.48, Krzysztof Kozlowski wrote:
> On Mon, Feb 15, 2021 at 09:16:50PM +0900, Hector Martin wrote:
>> +description: |
>> +  Apple ARM ("Apple Silicon") platforms should contain compatible strings
>> +  in the following format:
>> +
>> +  - apple,j274 (board/device ID)
>> +  - apple,m1 (SoC name)
>> +  - apple,arm-platform (Apple Silicon)
> 
> This description is irrelevant because the rules come from schema below.
> Maybe instead write few words about the platform? Or describe how to get
> the board/device ID if it is not obvious?

Good point. Actually, I've gone back and forth over this a few times,
but I'm going to change the SoC name. Apple calls these things by 5
different names, but the only two that make any sense to consider are
the marketing name ("m1") and the SoC name ("t8103"). I'm going to
switch to the latter (so `apple,t8103`).

In the past, Apple have dual-sourced SoCs with different IDs under the
same marketing name, and Apple themselves name most of their compatible
properties after the lowest-compatible SoC name, so I'm going to go with
that after all. This will save us grief in the future if they do that
again, and I think I get to pick the color of this bike shed :)

Given that, I expanded a bit on the description. Let me know what you think:

description: |
   ARM platforms using SoCs designed by Apple Inc., branded "Apple Silicon".

   This currently includes devices based on the "M1" SoC, starting with the
   three Mac models released in late 2020:

   - Mac mini (M1, 2020)
   - MacBook Pro (13-inch, M1, 2020)
   - MacBook Air (M1, 2020)

   The compatible property should follow this format:

   compatible = "apple,<targettype>", "apple,<socid>", "apple,arm-platform";

   <targettype> represents the board/device and comes from the `target-type`
   property of the root node of the Apple Device Tree, lowercased. It can be
   queried on macOS using the following command:

   $ ioreg -d2 -l | grep target-type

   <socid> is the lowercased SoC ID. Apple uses at least *five* different
   names for their SoCs:

   - Marketing name ("M1")
   - Internal name ("H13G")
   - Codename ("Tonga")
   - SoC ID ("T8103")
   - Package/IC part number ("APL1102")

   Devicetrees should use the the lowercased SoC ID, to avoid confusion if
   multiple SoCs share the same marketing name. This can be obtained from
   the `compatible` property of the arm-io node of the Apple Device Tree,
   which can be queried as follows on macOS:

   $ ioreg -n arm-io | grep compatible