Deep sleep (suspend-to-RAM) for the MacBook Neo (T8140) at EL2

Documentation/PCI/controller/apple-t8140.rst

@@ -64,6 +64,19 @@ recovery remain refused. Supporting these operations requires a proven engine
 teardown/reset and endpoint recovery contract first. Renaming the provider
 does not qualify those operations.
 
+Deep sleep keeps both functions bound and the radio powered, with its firmware
+running. Their drivers stop for it, the link goes through L2 and PERST#, and the SoC
+powers the engine off. On the way back the engine's whole register file must read as it
+did before the first command, the state the bootstrap checks for; if anything differs,
+the radios stay down. Only then does the retained state reopen for one more validated
+read, on the same memory, which the retrained link needs before native ECAM. The
+functions' configuration is then restored and their drivers resume, with no firmware
+load. If a driver finds that its side didn't survive, the host removes both functions,
+which resets the chip, and scans again, so that they probe and load their firmware as at
+boot. If the link didn't come back, the radio's rail is cycled first. An abandoned sleep
+never ran that power-off, so it replays nothing. This needs tunables
+from a loader that publishes them, and is refused otherwise.
+
 Suspend-to-idle is allowed only after radio admission, with no IRQ fault,
 idle command/FIFO checks and intact arena contents. Resume restores the
 configuration banks after genpd power restoration without submitting another

Documentation/devicetree/bindings/display/apple,dcp.yaml

@@ -78,11 +78,14 @@ properties:
     description: Optional host display-engine interrupt sources.
 
   mboxes:
-    maxItems: 1
+    minItems: 1
+    maxItems: 2
 
   mbox-names:
+    minItems: 1
     items:
       - const: mbox
+      - const: secure
 
   iommus:
     maxItems: 1
@@ -123,6 +126,13 @@ properties:
     items:
       pattern: '^(dp-phy|typec[0-9]+)$'
 
+  apple,display-power:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description:
+      A node whose ps, pwrgate and pmc-dcp registers hold the display power
+      words this coprocessor's driver writes around a firmware restart, such
+      as an apple,t8140-display-power node.
+
   apple,bw-scratch:
     $ref: /schemas/types.yaml#/definitions/phandle-array
     items:

Documentation/devicetree/bindings/display/apple,t8140-display-power.yaml

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/apple,t8140-display-power.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Apple T8140 display power words
+
+maintainers:
+  - Diljit Singh <hey@djdev.me>
+
+description:
+  The words a display coprocessor's driver writes to power its domains off
+  and on around a restart of its firmware, as macOS does. A display
+  coprocessor names this node in its apple,display-power property. The words
+  belong to the power manager and the display block, so no driver binds it.
+
+properties:
+  compatible:
+    const: apple,t8140-display-power
+
+  reg:
+    items:
+      - description: the display PMC word that counts the powered coprocessors
+      - description: the power manager's power state words
+      - description: the power manager's power gate words
+
+  reg-names:
+    items:
+      - const: pmc-dcp
+      - const: ps
+      - const: pwrgate
+
+required:
+  - compatible
+  - reg
+  - reg-names
+
+additionalProperties: false
+
+examples:
+  - |
+    soc {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        display-power@3028a9c14 {
+            compatible = "apple,t8140-display-power";
+            reg = <0x3 0x028a9c14 0x0 0x4>,
+                  <0x3 0x00700000 0x0 0x14000>,
+                  <0x3 0x00724000 0x0 0x1000>;
+            reg-names = "pmc-dcp", "ps", "pwrgate";
+        };
+    };

Documentation/devicetree/bindings/dma/apple,sio.yaml

@@ -82,6 +82,11 @@ allOf:
               reg:
                 minItems: 3
                 maxItems: 3
+              reg-names:
+                items:
+                  - const: asc
+                  - const: auxiliary
+                  - const: asc-tail
           else:
             if:
               properties:
@@ -137,6 +142,10 @@ properties:
 
   status: true
 
+  reg-names:
+    minItems: 1
+    maxItems: 3
+
   '#dma-cells':
     const: 1
     description:

Documentation/devicetree/bindings/gpu/apple,agx.yaml

@@ -95,6 +95,13 @@ properties:
       GFX supplier power cannot represent GPU work on firmware that keeps
       its coprocessor domain powered while the cores are idle.
 
+  apple,pmp-report-entry:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: |
+      PMP report entry that tells the PMP the GPU is in use. The driver withdraws
+      this request before it lowers the GPU's power state for a system sleep, and
+      makes it again after raising it.
+
   apple,idle-off-delay-ms:
     minimum: 2
     maximum: 1000

Documentation/devicetree/bindings/iommu/apple,dart.yaml

@@ -79,13 +79,15 @@ properties:
       - description: DART registers
       - description:
           Address filter (DAPF) registers, which restrict the physical
-          addresses the DART lets its masters reach
+          addresses the DART lets its masters reach, or the slice of the
+          fabric filter (GAPF) that protects the power state of the
+          coprocessor CPU behind this DART, cleared to power that CPU down
 
   reg-names:
     minItems: 1
     items:
       - const: dart
-      - enum: [dapf, auxiliary]
+      - enum: [dapf, gapf, auxiliary]
 
   interrupts:
     maxItems: 1
@@ -117,6 +119,54 @@ properties:
       may select a firmware-visible alias of the translation aperture.
       A consumer may further specify its own aperture in its binding.
 
+  apple,dapf-ranges:
+    $ref: /schemas/types.yaml#/definitions/uint64-matrix
+    items:
+      items:
+        - description: First address of a range
+        - description: Last address of a range
+    description:
+      The address filter the loader programs into the dapf registers, one
+      entry per range. A sleep that reaches the hardware clears it, and the
+      DART writes it back before its consumer's firmware starts again.
+
+  apple,dapf-r20:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    description:
+      The last word of each filter entry, one per range in apple,dapf-ranges.
+      1 where absent.
+
+  apple,sleep-prepare:
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    items:
+      items:
+        - description: Register offset
+        - description: Value
+    description:
+      Register writes before a consumer that gates itself is told about a
+      firmware-driven system suspend. Needs apple,sleep-restore.
+
+  apple,sleep-restore:
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    items:
+      items:
+        - description: Register offset
+        - description: Value
+    description:
+      Register writes after such a suspend, before the translations are put
+      back. With this, the consumer saves and restores the DART around the
+      suspend, as the order relative to its firmware's start matters.
+
+  apple,sleep-restore-late:
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    items:
+      items:
+        - description: Register offset
+        - description: Value
+    description:
+      Register writes after the translations are back and before the streams
+      are enabled.
+
   apple,dma-offset:
     $ref: /schemas/types.yaml#/definitions/uint64
     description: >
@@ -158,6 +208,18 @@ properties:
       Tree by the bootloader and required to initialize dynamically powered
       DART instances.
 
+  apple,resume-tunable:
+    $ref: /schemas/types.yaml#/definitions/uint32-matrix
+    items:
+      items:
+        - description: Register offset
+        - description: Mask to be applied to the register value
+        - description: Bits to be set after applying the mask
+    description: >
+      The same tuples for a DART whose bootloader has already applied them,
+      written back where a power-off lost them, before its consumer's
+      firmware starts again.
+
   apple,bypass-sids:
     $ref: /schemas/types.yaml#/definitions/uint32-array
     minItems: 1

Documentation/devicetree/bindings/mailbox/apple,mailbox.yaml

@@ -76,6 +76,14 @@ properties:
           AOP setup-port mailbox with a separate register layout.
         const: apple,t8140-aop-setup-mailbox
 
+      - description:
+          A coprocessor's secure RTBuddy port, the ADT's
+          iop,secure-rtbuddy-proxy. It is polled, with no interrupts described.
+        items:
+          - enum:
+              - apple,t8140-secure-rtbuddy-proxy
+          - const: apple,secure-rtbuddy-proxy
+
       - description:
           An older ASC mailbox interface found on T2 and A11 that is also
           used for the NVMe coprocessor and the system management
@@ -134,6 +142,16 @@ properties:
     maxItems: 2
 
 allOf:
+  - if:
+      not:
+        properties:
+          compatible:
+            contains:
+              const: apple,secure-rtbuddy-proxy
+    then:
+      required:
+        - interrupts
+        - interrupt-names
   - if:
       properties:
         compatible:
@@ -212,8 +230,6 @@ allOf:
 required:
   - compatible
   - reg
-  - interrupts
-  - interrupt-names
   - "#mbox-cells"
 
 additionalProperties: false

Documentation/devicetree/bindings/pci/apple,pcie.yaml

@@ -175,6 +175,30 @@ properties:
     $ref: '#/$defs/tunable'
     description: Initialization tuples for the oe-fabric register region.
 
+  apple,tunable-axi2af:
+    $ref: '#/$defs/tunable'
+    description: Initialization tuples for the shared PHY block's AXI bridge.
+
+  apple,tunable-cio3pll:
+    $ref: '#/$defs/tunable'
+    description: Initialization tuples for the shared PHY block's PLL.
+
+  apple,tunable-clkgen:
+    $ref: '#/$defs/tunable'
+    description: Initialization tuples for the shared PHY block's clock generator.
+
+  apple,tunable-phy:
+    $ref: '#/$defs/tunable'
+    description: Initialization tuples for the shared PHY block.
+
+  apple,tunable-phy-ip-pll:
+    $ref: '#/$defs/tunable'
+    description: PLL settings of the shared PHY, relative to its phy-ip registers.
+
+  apple,tunable-phy-ip-auspma:
+    $ref: '#/$defs/tunable'
+    description: Lane settings of the shared PHY, relative to its phy-ip registers.
+
   apple,piodma:
     $ref: /schemas/types.yaml#/definitions/phandle
     description:
@@ -420,8 +444,9 @@ allOf:
             properties:
               reg:
                 minItems: 8
-                maxItems: 8
+                maxItems: 13
               reg-names:
+                minItems: 8
                 items:
                   - const: config
                   - const: rc
@@ -431,6 +456,11 @@ allOf:
                   - const: phy0
                   - const: phy1
                   - const: phy2
+                  - const: axi2af
+                  - const: cio3pll
+                  - const: clkgen
+                  - const: phy-block
+                  - const: phy-ip
               interrupts:
                 maxItems: 3
           else:

Documentation/devicetree/bindings/phy/apple,atcphy.yaml

@@ -125,6 +125,10 @@ allOf:
               - description: USB2 PHY specific controls
               - description: USB3 PIPE interface controls
               - description: Secondary eUSB2 PHY register bank (T8140)
+              - description:
+                  Power and hibernation control of the USB controller the PHY
+                  serves (T8140). The PHY drives that controller's reset and
+                  takes it through hibernation for a system sleep.
           reg-names:
             minItems: 5
             items:
@@ -134,6 +138,7 @@ allOf:
               - const: usb2phy
               - const: pipehandler
               - const: usb2phy-reg
+              - const: pwrctl
         required:
           - power-domains
   - if:

Documentation/devicetree/bindings/power/apple,pmgr-pwrstate.yaml

@@ -23,6 +23,7 @@ allOf:
       properties:
         apple,firmware-owned: false
         apple,sleep-retained: false
+        apple,sleep-driver-owned: false
         apple,always-on: false
         apple,min-state: false
         apple,force-disable: false
@@ -135,6 +136,13 @@ properties:
       system sleep. Runtime power management is unaffected.
     type: boolean
 
+  apple,sleep-driver-owned:
+    description:
+      The driver behind this domain lowers it before a system sleep and brings
+      it back afterwards, in an order its hardware needs. The power controller
+      leaves it alone after a wake.
+    type: boolean
+
   apple,firmware-owned:
     description:
       The boot loader hands over active hardware whose power domain remains