Apple SoC suspend-to-RAM on T8140

.github/workflows/sep-source.yml

@@ -9,6 +9,12 @@ on:
       - 'drivers/soc/apple/**'
       - 'include/uapi/linux/apple-sep.h'
       - 'tools/aurora-sep/**'
+      - 'Kconfig'
+      - '**/Kconfig*'
+      - 'arch/arm64/configs/defconfig'
+      - 'drivers/usb/dwc3/**'
+      - 'include/linux/phy/apple-atc.h'
+      - 'scripts/ci/apple-dwc3-atc-compile.sh'
       - '.github/workflows/sep-source.yml'
 
 jobs:
@@ -116,3 +122,38 @@ jobs:
             --make_options LLVM=1 \
             --kunitconfig=drivers/soc/apple/sep.kunitconfig \
             --jobs="$(nproc)" --timeout=900 'apple_sep*'
+
+  dwc3-atc-compile:
+    name: DWC3/ATC ${{ matrix.profile }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        profile: [builtin-no-atc, modular-no-atc, builtin-modular-atc]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Install arm64 C build dependencies
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y -q clang-18 lld-18 llvm-18 libelf-dev libssl-dev \
+            flex bison bc pkg-config make perl
+          echo "/usr/lib/llvm-18/bin" >> "$GITHUB_PATH"
+      - name: Compile the Apple DWC3 object with the resolved PHY profile
+        env:
+          PROFILE: ${{ matrix.profile }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: scripts/ci/apple-dwc3-atc-compile.sh "$PROFILE"
+      - name: Keep configuration and compiler receipts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: dwc3-atc-${{ matrix.profile }}
+          path: ${{ runner.temp }}/dwc3-atc-${{ matrix.profile }}/artifacts/
+          retention-days: 14

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
@@ -145,6 +148,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

@@ -98,6 +98,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,64 @@ 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,restore-on-power-up:
+    type: boolean
+    description:
+      Reset and restore the DART, and write its address filter back, every
+      time it powers up, even where its registers still read as they were
+      left. For a DART that keeps its values through a sleep in which the
+      SoC's sleep engine runs its consumer, but whose address filter only
+      takes effect once written again.
+
+  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, after the DART's state is saved. Streams
+      they stop are started again at the restore. 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: >
@@ -168,6 +228,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:
           Later AOP setup-port mailboxes with the T8140 register layout.
         items:
@@ -142,6 +150,16 @@ properties:
     maxItems: 2
 
 allOf:
+  - if:
+      not:
+        properties:
+          compatible:
+            contains:
+              const: apple,secure-rtbuddy-proxy
+    then:
+      required:
+        - interrupts
+        - interrupt-names
   - if:
       properties:
         compatible:
@@ -220,8 +238,6 @@ allOf:
 required:
   - compatible
   - reg
-  - interrupts
-  - interrupt-names
   - "#mbox-cells"
 
 additionalProperties: false