chore: rebase aurora-wip and merge into integration

Documentation/PCI/controller/apple-t8140.rst

@@ -1,89 +1,39 @@
 .. SPDX-License-Identifier: GPL-2.0-only
 
 T8140/J700 experimental radio PCIe bootstrap
-============================================
+==========================================
 
 The J700 path trains port 0, validates a bounded PIODMA bootstrap request,
 and enables native ECAM for the MediaTek Wi-Fi and Bluetooth functions.
 The root bridge forwards their BARs and DART translates endpoint DMA.
 
-This is a bring-up implementation, not general T8140 PCIe support. Build
-``CONFIG_PCIE_APPLE_PIODMA_DIAG=y``; the Apple PCIe host driver may be a module.
-The bootstrap enables enumeration by default only on machines matching both
-``apple,j700`` and ``apple,t8140``, through the matching diagnostic and host
-device-tree nodes. No kernel argument is required. To leave the root-only
-diagnostic path closed, pass ``pcie_apple_piodma_diag.enumerate=0``.
-The read-only ``enumerate`` parameter reports the configured admission request,
-not whether the current machine is a Neo or its radios were admitted. Its
-default value is also visible on other Macs; the machine and DT checks decide
-whether it has any effect.
-
-The shared kernel can keep suspend, hibernation and kexec support enabled.
-Before the host creates PCI children, a short admission critical section
-acquires a kexec interlock and registers a PM notifier that refuses sleep
-transitions. Its device prepare callback provides a second veto. This also covers
-``/dev/snapshot`` files opened before the supplier probes: later image, restore
-and suspend ioctls enter device PM without repeating the prepare notifier.
-A kexec interlock refuses loading or executing a replacement kernel,
-including an already loaded crash kernel. Image unloading remains permitted.
-These interlocks apply only to the active J700 bootstrap; other machines do not
-acquire them. Merely probing its supplier does not block transitions. The device
-prepare callback also checks this guarded pre-publication window. Admission
-contention may defer only before PCI children exist; a later failure is a hard
-error. Pre-child contention schedules a delayed attachment of this matched
-host, so a long-running kexec loader does not require another driver to bind
-before admission can retry. Only renewed contention queues another attempt;
-successful admission and hardware publication end these retries. Shutdown
-blocks late admission. A failure before memory publication releases the guards. Once the
-bootstrap retains memory, the protection persists even if enumeration or either
-radio's firmware loading fails. Thus the block applies on every default J700
-boot which reaches retained radio admission, regardless of installed firmware.
-Failed or uncertain bootstrap state requires a full external hardware reset;
-there is no command retry.
-
-Sleep is not supported on the MacBook Neo yet. With radio support active
-(the default), the kernel refuses suspend: lid close and ``systemctl suspend``
-do not put it to sleep. Shut down before putting it in a bag. Booting with
-``pcie_apple_piodma_diag.enumerate=0`` removes this refusal and disables Wi-Fi
-and Bluetooth; sleep and wake remain unproven on this hardware without radios.
-
-Before either radio driver can bind, the host disables ASPM, all L1 substates
-and Clock PM on the validated radio endpoints' shared PCIe link through the
-PCI core. ``CONFIG_PCIEASPM=y`` is required. The global ASPM policy is unchanged;
-neither a performance-policy boot argument nor a sysfs policy write is needed.
-Booting with ``pcie_aspm=off`` prevents the PCI core from applying this restriction
-and radio admission fails closed.
-
-The supplier publishes radio admission only after both functions pass the
-host's identity, cold-state, memory-window and link-power checks. Both radio
-probes require that completed admission before accessing PCI or MMIO state;
-the host's downstream device-enable callback enforces the same gate for other
-drivers. This prevents a later generic rescan from enabling cached children of
-a failed admission. Each radio probe reapplies the link-power restriction, so
-a recreated ASPM link state cannot inherit an incompatible global policy.
-Privileged writes to the per-link PCI sysfs ASPM or Clock PM attributes can
-override the restriction; it is reapplied only at probe, not continuously.
-Do not enable those link power states while the Neo radios are admitted.
-
-The PIODMA arena remains allocated until external reset. Standard PCI sysfs
-``remove`` writes for the root port and radio functions return ``-EOPNOTSUPP``
-while the host has its retained supplier; the removal attributes remain present.
-The same hierarchy refuses userspace ``reset`` and ``reset_subordinate``
-writes, and its host does not hand native PCIe or SHPC slot hot-plug control
-to Linux. These restrictions leave other PCI hosts unchanged.
-VFIO assignment is refused on this host because it exposes reset operations
-outside PCI sysfs. Automatic native AER/DPC port recovery is also withheld:
-its bus or link reset has no qualified retained-memory contract here. A hardware
-fault requires external reset rather than guessed recovery.
-The host and activated Wi-Fi/Bluetooth modules are pinned until reset. Arbitrary
-platform-device removal, IOMMU teardown, forced module removal, memory reuse
-and arbitrary downstream devices remain unqualified. Do not remove the
-controller or its IOMMUs while this experiment is active.
+This is a bring-up implementation, not general T8140 PCIe support.
+Build ``CONFIG_PCIE_APPLE_PIODMA_DIAG=y``. The board device tree selects the
+bootstrap by pointing the host's ``apple,piodma`` property at the engine, and
+the kernel then runs it during the host probe. Passing
+``pcie_apple_piodma_diag.enumerate=0`` keeps the root-only diagnostic path,
+which rejects downstream configuration access. A kernel built without the
+option always uses that root-only path.
+Build the host and its DART in as well: the supplier retains published DMA
+and has no removal contract. Keeping the supplier and host built in avoids
+a module dependency on a provider whose lifetime cannot end at unload.
+
+Suspend-to-idle suspend retains the arena after checking the completed request,
+idle FIFO and command state. Resume restores the existing configuration
+banks without issuing a second bootstrap. Hibernation, deeper suspend and
+kexec are refused while admission or retained DMA ownership is active. The
+runtime kexec guard permits the kernel to support kexec on other machines.
+Host removal, sysfs reset, hotplug, VFIO assignment and native AER/DPC
+recovery are withheld on this retained hierarchy. Sleep is refused until
+radio admission completes; the existing suspend-to-idle path remains available
+after successful admission. Failed or uncertain bootstrap state
+requires a full external hardware reset; there is no command retry.
+
+The PIODMA arena remains allocated until external reset. Controller removal,
+teardown, memory reuse and arbitrary downstream devices are unqualified.
+Fresh hardware qualification must check both radio functions across sleep.
+Do not remove the controller or its IOMMU while this experiment is active.
 These lifecycle contracts require further work before production support.
-They protect against accidental teardown and are not a security boundary.
-Root can still reset through raw configuration writes, including secondary-bus
-reset, FLR and Link Disable, change per-link ASPM controls or unbind the root
-port's ``pcieport`` driver. Do not perform these operations on an admitted Neo.
 
 J700's ``wifi0`` alias and PCI endpoint node allow the public bootloader to
 pass the unit's own Wi-Fi address through ``local-mac-address``. The zero

Documentation/admin-guide/media/apple-ave.rst

@@ -0,0 +1,63 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Experimental T8140 video encoding
+================================
+
+The J700 AVE driver exposes a root-only debugfs firmware transport for
+hardware encoding experiments. It is not a V4L2 encoder, has no stable
+userspace ABI, and does not make an FFmpeg encoder available. The initial
+scope is the existing fixed 320x240 NV12 H.264/HEVC protocol experiment.
+
+Build ``CONFIG_VIDEO_APPLE_AVE_EXPERIMENTAL=m`` on a 16 KiB-page Apple kernel
+with debugfs and translated DMA. Suspend, hibernation and kexec must be off.
+Load with ``modprobe apple-ave enable=1``; probing is disabled otherwise.
+
+Firmware and boot requirements
+------------------------------
+
+Use the public Aurora m1n1 J700 AVE handoff. It reserves the firmware already
+loaded by iBoot, fills the device's ``memory-region`` references and exports
+``aurora,ave-text-crc32`` and ``aurora,ave-data-crc32`` strings under
+``/chosen``. No firmware file is included or requested by this driver.
+The current transport requires the qualified 25G76 two-segment layout:
+0x14c000 text bytes and 0x130000 data bytes, mapped starting at IOVA
+0x10000000000. Every mapping and both content CRCs are checked before use.
+Text CRCs are restricted to the two inspected 9003.78.0 images (0x2ce7359e
+and 0x69c54454). These checks detect build drift, not firmware authenticity.
+Different firmware is unsupported, even if the device has the same SoC.
+
+The driver holds the DMA, pipe4, pipe5, me0 and me1 power domains and owns
+the IPC, queue, log and firmware-requested heap allocations. Debugfs lives
+under ``/sys/kernel/debug/285100000.video-codec``:
+
+* ``ave-status`` reports mappings, protocol phase and reply counters.
+* ``ave-start-once`` accepts one explicit firmware start per boot.
+* ``ave-command`` accepts one bounded packet and returns a framed reply.
+* ``ave-arena`` stages image/reference/output surfaces within owned memory.
+* ``ave-poll`` drains later firmware replies without another submission.
+
+Writes require ``CAP_SYS_RAWIO``. Command packets must come from a trusted,
+matching local protocol experiment with all embedded surface addresses
+relocated into this boot's owned arena. Root access does not make arbitrary
+firmware packets valid. Binary command captures are supplied separately and
+are not included in this contribution.
+
+Lifecycle and verification
+--------------------------
+
+After the start attempt, the module, DMA buffers and power references remain
+pinned until an external hardware reset, including after failure. Do not
+force-unload, unbind the DARTs, reuse uncertain buffers or retry a failed
+command. Firmware quiescence and normal production teardown are unfinished.
+
+A transport acknowledgement is not an encoded frame. For physical tests,
+record the exact kernel/module, DT and firmware hashes; submit changing
+images; validate each codec reply; independently decode the current DMA
+output; check every frame's dimensions and quality; then verify Stop/Close,
+kernel health and the existing desktop/radio stack. Keep the generated
+inputs, bitstreams, decoded pixels, logs and hashes as a repeatable artifact.
+
+The prior implementation was authored by Ace (Acelogic). This contribution
+ports that existing GPL work. Arbitrary resolutions, standard media APIs,
+throughput, concurrent clients and other codecs or SoCs are outside this
+experiment.

Documentation/admin-guide/media/index.rst

@@ -43,6 +43,7 @@ Documentation/process/debugging/media_specific_debugging_guide.rst
 
 	v4l-drivers
 	dvb-drivers
+	apple-ave
 
 **Copyright** |copy| 1999-2020 : LinuxTV Developers