From: Sasha Finkelstein <fnkl.kernel@gmail.com>
Add bindings for the GPU present in Apple SoCs
Signed-off-by: Sasha Finkelstein <fnkl.kernel@gmail.com>
---
Documentation/devicetree/bindings/gpu/apple,agx.yaml | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
MAINTAINERS | 1 +
2 files changed, 96 insertions(+)
diff --git a/Documentation/devicetree/bindings/gpu/apple,agx.yaml b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..23df3ebd689b1e885eb99ca573343fe7f2d09dc4
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/gpu/apple,agx.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple SoC GPU
+
+maintainers:
+ - Sasha Finkelstein <fnkl.kernel@gmail.com>
+
+properties:
+ compatible:
+ oneOf:
+ - items:
+ - const: apple,agx-g13g
+ - items:
+ - enum:
+ - apple,agx-g13s
+ - apple,agx-g13c
+ - apple,agx-g13d
+ - const: apple,agx-g13x
+ - items:
+ - const: apple,agx-g14g
+ reg:
+ items:
+ - description: ASC coprocessor control
+ - description: GPU block MMIO registers
+
+ reg-names:
+ items:
+ - const: asc
+ - const: sgx
+
+ power-domains:
+ maxItems: 1
+
+ mboxes:
+ maxItems: 1
+
+ memory-region:
+ items:
+ - description: Region containing GPU MMU TTBs
+ - description: Region containing GPU MMU page tables
+ - description:
+ Region containing a shared handoff structure for VM
+ management coordination
+ - description: Driver-opaque calibration blob
+ - description: Calibration blob
+ - description: Shared global variables with GPU firmware
+
+ memory-region-names:
+ items:
+ - const: ttbs
+ - const: pagetables
+ - const: handoff
+ - const: hw-cal-a
+ - const: hw-cal-b
+ - const: globals
+
+ apple,firmware-compat:
+ $ref: /schemas/types.yaml#/definitions/uint32-array
+ minItems: 3
+ description:
+ MacOS version the current firmware is paired with, used to pick
+ the version of firmware ABI to be used.
+ Bootloader will overwrite this
+
+required:
+ - compatible
+ - reg
+ - mboxes
+ - memory-region
+ - apple,firmware-compat
+
+additionalProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/interrupt-controller/apple-aic.h>
+ gpu@6400000 {
+ compatible = "apple,agx-g13g";
+ reg = <0x6400000 0x40000>,
+ <0x4000000 0x1000000>;
+ reg-names = "asc", "sgx";
+ mboxes = <&agx_mbox>;
+ power-domains = <&ps_gfx>;
+ memory-region = <&uat_ttbs>, <&uat_pagetables>, <&uat_handoff>,
+ <&gpu_hw_cal_a>, <&gpu_hw_cal_b>, <&gpu_globals>;
+ memory-region-names = "ttbs", "pagetables", "handoff",
+ "hw-cal-a", "hw-cal-b", "globals";
+
+ apple,firmware-compat = <0 0 0>;
+ };
+...
diff --git a/MAINTAINERS b/MAINTAINERS
index a92290fffa163f9fe8fe3f04bf66426f9a894409..2a32c9c4ee355a1109a3e2031ea3663c39cc8c68 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2331,6 +2331,7 @@ F: Documentation/devicetree/bindings/arm/apple/*
F: Documentation/devicetree/bindings/clock/apple,nco.yaml
F: Documentation/devicetree/bindings/cpufreq/apple,cluster-cpufreq.yaml
F: Documentation/devicetree/bindings/dma/apple,admac.yaml
+F: Documentation/devicetree/bindings/gpu/apple,agx.yaml
F: Documentation/devicetree/bindings/i2c/apple,i2c.yaml
F: Documentation/devicetree/bindings/input/touchscreen/apple,z2-multitouch.yaml
F: Documentation/devicetree/bindings/interrupt-controller/apple,*
--
2.49.0On Wed, Jun 11, 2025 at 12:32 PM Sasha Finkelstein via B4 Relay
<devnull+fnkl.kernel.gmail.com@kernel.org> wrote:
>
> From: Sasha Finkelstein <fnkl.kernel@gmail.com>
>
> Add bindings for the GPU present in Apple SoCs
>
> Signed-off-by: Sasha Finkelstein <fnkl.kernel@gmail.com>
> ---
> Documentation/devicetree/bindings/gpu/apple,agx.yaml | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> MAINTAINERS | 1 +
> 2 files changed, 96 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/gpu/apple,agx.yaml b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
> new file mode 100644
> index 0000000000000000000000000000000000000000..23df3ebd689b1e885eb99ca573343fe7f2d09dc4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
> @@ -0,0 +1,95 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/gpu/apple,agx.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Apple SoC GPU
> +
> +maintainers:
> + - Sasha Finkelstein <fnkl.kernel@gmail.com>
> +
> +properties:
> + compatible:
> + oneOf:
> + - items:
> + - const: apple,agx-g13g
> + - items:
> + - enum:
> + - apple,agx-g13s
> + - apple,agx-g13c
> + - apple,agx-g13d
> + - const: apple,agx-g13x
I'm assuming the 'x' is a wildcard. The preferred thing to do make one
of the 3 actual devices the fallback. Typically, the oldest one is
used.
> + - items:
> + - const: apple,agx-g14g
This and the 1st entry can be a single enum.
> + reg:
> + items:
> + - description: ASC coprocessor control
> + - description: GPU block MMIO registers
Seems odd that the main GPU registers are not first in the list, but
either way is fine.
> +
> + reg-names:
> + items:
> + - const: asc
> + - const: sgx
> +
> + power-domains:
> + maxItems: 1
> +
> + mboxes:
> + maxItems: 1
> +
> + memory-region:
> + items:
> + - description: Region containing GPU MMU TTBs
> + - description: Region containing GPU MMU page tables
> + - description:
> + Region containing a shared handoff structure for VM
> + management coordination
> + - description: Driver-opaque calibration blob
> + - description: Calibration blob
> + - description: Shared global variables with GPU firmware
> +
> + memory-region-names:
> + items:
> + - const: ttbs
> + - const: pagetables
> + - const: handoff
> + - const: hw-cal-a
> + - const: hw-cal-b
> + - const: globals
> +
> + apple,firmware-compat:
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + minItems: 3
> + description:
> + MacOS version the current firmware is paired with, used to pick
> + the version of firmware ABI to be used.
> + Bootloader will overwrite this
> +
> +required:
> + - compatible
> + - reg
> + - mboxes
> + - memory-region
> + - apple,firmware-compat
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + #include <dt-bindings/interrupt-controller/apple-aic.h>
> + gpu@6400000 {
> + compatible = "apple,agx-g13g";
> + reg = <0x6400000 0x40000>,
> + <0x4000000 0x1000000>;
> + reg-names = "asc", "sgx";
> + mboxes = <&agx_mbox>;
> + power-domains = <&ps_gfx>;
> + memory-region = <&uat_ttbs>, <&uat_pagetables>, <&uat_handoff>,
> + <&gpu_hw_cal_a>, <&gpu_hw_cal_b>, <&gpu_globals>;
> + memory-region-names = "ttbs", "pagetables", "handoff",
> + "hw-cal-a", "hw-cal-b", "globals";
> +
> + apple,firmware-compat = <0 0 0>;
> + };
> +...
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a92290fffa163f9fe8fe3f04bf66426f9a894409..2a32c9c4ee355a1109a3e2031ea3663c39cc8c68 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2331,6 +2331,7 @@ F: Documentation/devicetree/bindings/arm/apple/*
> F: Documentation/devicetree/bindings/clock/apple,nco.yaml
> F: Documentation/devicetree/bindings/cpufreq/apple,cluster-cpufreq.yaml
> F: Documentation/devicetree/bindings/dma/apple,admac.yaml
> +F: Documentation/devicetree/bindings/gpu/apple,agx.yaml
> F: Documentation/devicetree/bindings/i2c/apple,i2c.yaml
> F: Documentation/devicetree/bindings/input/touchscreen/apple,z2-multitouch.yaml
> F: Documentation/devicetree/bindings/interrupt-controller/apple,*
>
> --
> 2.49.0
>
>
> > + - apple,agx-g13s > > + - apple,agx-g13c > > + - apple,agx-g13d > > + - const: apple,agx-g13x > > I'm assuming the 'x' is a wildcard. The preferred thing to do make one > of the 3 actual devices the fallback. Typically, the oldest one is > used. Yeah, it's something of a family. G13X is an apple codename for these three chips. We can do `apple,agx-g13d, apple,agx-g13s` as the compatible list and omit the g13x compatible. I'm not sure if that's actually better since we'd continue to use the G13X naming in the driver itself but it's a minor point either way.
Hi,
I think there's a "gpu: " missing in the subject.
On 11.06.25 19:32, Sasha Finkelstein via B4 Relay wrote:
> From: Sasha Finkelstein <fnkl.kernel@gmail.com>
>
> Add bindings for the GPU present in Apple SoCs
>
> Signed-off-by: Sasha Finkelstein <fnkl.kernel@gmail.com>
> ---
> Documentation/devicetree/bindings/gpu/apple,agx.yaml | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> MAINTAINERS | 1 +
> 2 files changed, 96 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/gpu/apple,agx.yaml b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
> new file mode 100644
> index 0000000000000000000000000000000000000000..23df3ebd689b1e885eb99ca573343fe7f2d09dc4
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/gpu/apple,agx.yaml
> @@ -0,0 +1,95 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/gpu/apple,agx.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Apple SoC GPU
> +
> +maintainers:
> + - Sasha Finkelstein <fnkl.kernel@gmail.com>
> +
> +properties:
> + compatible:
> + oneOf:
> + - items:
> + - const: apple,agx-g13g
> + - items:
> + - enum:
> + - apple,agx-g13s
> + - apple,agx-g13c
> + - apple,agx-g13d
> + - const: apple,agx-g13x
> + - items:
> + - const: apple,agx-g14g
> + reg:
> + items:
> + - description: ASC coprocessor control
Apple calls these co-processors ASC but I'm not sure that's really
helpful to describe them. Maybe just "GPU coprocessor control registers"?
> + - description: GPU block MMIO registers
> +
> + reg-names:
> + items:
> + - const: asc
> + - const: sgx
> +
> + power-domains:
> + maxItems: 1
> +
> + mboxes:
> + maxItems: 1
> +
> + memory-region:
> + items:
> + - description: Region containing GPU MMU TTBs
> + - description: Region containing GPU MMU page tables
> + - description:
> + Region containing a shared handoff structure for VM
> + management coordination
> + - description: Driver-opaque calibration blob
> + - description: Calibration blob
Like Alyssa mentioned, this description also raises more questions than
it answers for me. Do we know what these two blobs contain or why they
are two separate blobs?
> + - description: Shared global variables with GPU firmware
> +
> + memory-region-names:
> + items:
> + - const: ttbs
> + - const: pagetables
> + - const: handoff
> + - const: hw-cal-a
> + - const: hw-cal-b
> + - const: globals
> +
> + apple,firmware-compat:
Nit: I'd prefer something like apple,firmware-abi here.
> + $ref: /schemas/types.yaml#/definitions/uint32-array
> + minItems: 3
> + description:
> + MacOS version the current firmware is paired with, used to pick
> + the version of firmware ABI to be used.
> + Bootloader will overwrite this
> +
> +required:
> + - compatible
> + - reg
> + - mboxes
> + - memory-region
> + - apple,firmware-compat
> +
> +additionalProperties: false
> +
> +examples:
> + - |
> + #include <dt-bindings/interrupt-controller/apple-aic.h>
No need for the include for this example.
> + gpu@6400000 {
> + compatible = "apple,agx-g13g";
> + reg = <0x6400000 0x40000>,
> + <0x4000000 0x1000000>;
> + reg-names = "asc", "sgx";
> + mboxes = <&agx_mbox>;
> + power-domains = <&ps_gfx>;
> + memory-region = <&uat_ttbs>, <&uat_pagetables>, <&uat_handoff>,
> + <&gpu_hw_cal_a>, <&gpu_hw_cal_b>, <&gpu_globals>;
> + memory-region-names = "ttbs", "pagetables", "handoff",
> + "hw-cal-a", "hw-cal-b", "globals";
> +
> + apple,firmware-compat = <0 0 0>;
> + };
> +...
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a92290fffa163f9fe8fe3f04bf66426f9a894409..2a32c9c4ee355a1109a3e2031ea3663c39cc8c68 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2331,6 +2331,7 @@ F: Documentation/devicetree/bindings/arm/apple/*
> F: Documentation/devicetree/bindings/clock/apple,nco.yaml
> F: Documentation/devicetree/bindings/cpufreq/apple,cluster-cpufreq.yaml
> F: Documentation/devicetree/bindings/dma/apple,admac.yaml
> +F: Documentation/devicetree/bindings/gpu/apple,agx.yaml
> F: Documentation/devicetree/bindings/i2c/apple,i2c.yaml
> F: Documentation/devicetree/bindings/input/touchscreen/apple,z2-multitouch.yaml
> F: Documentation/devicetree/bindings/interrupt-controller/apple,*
>
Best,
Sven
On Wed, 11 Jun 2025 at 20:44, Sven Peter <sven@kernel.org> wrote: > > + - description: Driver-opaque calibration blob > > + - description: Calibration blob > > Like Alyssa mentioned, this description also raises more questions than > it answers for me. Do we know what these two blobs contain or why they > are two separate blobs? At some point in the gpu initialization process we give the firmware a bag of pointers to various stuff it needs. HwCalA and HwCalB are separate pointers, and they use separate gpu allocations. We do not fully know what is in there, but we know what some of the fields do and how to create the blobs based on data from apple device tree.
On 11.06.25 21:06, Sasha Finkelstein wrote: > On Wed, 11 Jun 2025 at 20:44, Sven Peter <sven@kernel.org> wrote: >>> + - description: Driver-opaque calibration blob >>> + - description: Calibration blob >> >> Like Alyssa mentioned, this description also raises more questions than >> it answers for me. Do we know what these two blobs contain or why they >> are two separate blobs? > > At some point in the gpu initialization process we give the firmware a bag > of pointers to various stuff it needs. HwCalA and HwCalB are separate > pointers, and they use separate gpu allocations. We do not fully know > what is in there, but we know what some of the fields do and how to > create the blobs based on data from apple device tree. I looked at the driver itself and there are two comments related to these: HwDataA: This mostly contains power-related configuration. HwDataB: This mostly contains GPU-related configuration. Are they still accurate our just outdated leftovers from an early version? If they're accurate I'd include them in the description here as well. Best, Sven
> + - description: Driver-opaque calibration blob > + - description: Calibration blob ... > + - const: hw-cal-a > + - const: hw-cal-b For me these descriptions raise more questions than what they're meant to describe... Maybe "First hardware calibration blob" and "Second hardware calibration blob" or something. I don't fully get why A is opaque and B is not, I don't think there's really such a distinction in reality. > + description: > + MacOS version the current firmware is paired with, used to pick macOS
© 2016 - 2025 Red Hat, Inc.