media: apple: avd: retain zero-copy H.264 pictures across frame operations

drivers/media/platform/apple/avd/H264-FRAME-OPS.rst

@@ -0,0 +1,48 @@
+H.264 picture preparation and ownership
+======================================
+
+H.264 exports CPU prepare/pack_cmd/retire operations. The queued open backend
+accepts its complete instruction program; the older open backend selects the
+legacy callbacks. Both paths collect slice descriptors and request-control
+snapshots until the final request of a HOLD_CAPTURE_BUF picture. Only metadata
+is copied. Each descriptor points at the OUTPUT DMA address plus data_offset
+and the emulation-prevention-aware slice-header offset.
+
+The core removes intermediate OUTPUTs from the scheduler without completing
+them. It transfers their ownership to the final frame and completes them after
+CAPTURE retirement. Incomplete pictures release their OUTPUTs and codec state
+on streamoff or preparation failure. Userspace must queue every slice of a
+picture before waiting for its OUTPUT buffers; it cannot recycle a held slice.
+The codec never operates mem2mem queues or MMIO in its frame callbacks.
+
+Each live picture owns independent scratch and a VP-to-PP instruction FIFO.
+Sixteen owners are cached per context, with reuse only after retirement. Motion
+vectors remain in their reference CAPTURE allocation. H.264 uses DEP_NONE.
+
+Apple layout boundary
+---------------------
+
+The public MIT eiln/avd avid/h264/fp.py and halv3.py describe Viola/V3. The
+packer writes its SPS/PPS/scaling, DPB, output, weights and slice fields, with
+600 separately bounded slice records. This public comparison does not establish
+the later LilyD layout selected by T6000 firmware. Match data must select a
+proved layout rather than infer one from the hardware register revision.
+
+Borage has an independent table with the command projection proved by SPEC 6.2.
+The exact +0x3c/+0x44 packed-address rules, both work-count bounds, and the full
+parser-compatible syntax layout remain unproved. These fields retain numeric
+source offsets and return EOPNOTSUPP; this draft cannot enable Apple decoding.
+T8112 and T8140 remain explicit per-SoC ledger TODO rows (t-3862). No later-class
+layout falls back to V3.
+
+Verification
+------------
+
+On a Linux build host run tests/run-host-tests.py. It compiles the production
+builder and parameter writer, compares 96 synthetic I/P/B 1/4-slice programs
+against the licensed frozen Linux builder, and exercises the actual prepare and
+retire functions across separate held requests and sixteen live pictures.
+Additional tests compile the core source-ownership helpers and check final
+completion, native/legacy partial abort, V3 field bounds and Borage projection.
+These are host tests, not target decode or GStreamer/ffmpeg conformance results.
+The encoded-stream comparison with eiln's decoder remains separate validation.

drivers/media/platform/apple/avd/Kconfig

@@ -24,8 +24,7 @@ config VIDEO_APPLE_AVD_KUNIT_TEST
 	default KUNIT_ALL_TESTS
 	help
 	  Build KUnit tests for the Apple video decoder. They exercise the
-	  checks that the H.264 path makes on the slices that userspace
-	  queues, such as finding the slice data after the slice header,
-	  at the limits and one past them.
+	  H.264 slice bounds, frame-slot ownership, and runtime power management,
+	  including suspend gating and resubmission after firmware resume.
 
 	  If unsure, say N.

drivers/media/platform/apple/avd/Makefile

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: GPL-2.0-only
 
-apple-avd-y := avd-drv.o avd-v4l2.o avd-hw.o avd-h264.o avd-vp9.o avd-hevc.o \
-	avd-av1.o avd-av1-entropymode.o
-apple-avd-$(CONFIG_VIDEO_APPLE_AVD_KUNIT_TEST) += avd-h264-test.o
+apple-avd-y := avd-drv.o avd-v4l2.o avd-hw.o avd-pm.o avd-h264.o avd-h264-fp.o avd-vp9.o \
+	avd-hevc.o avd-av1.o avd-av1-entropymode.o avd-queue.o avd-backend-open.o \
+	avd-backend-apple.o avd-backend-queue.o
+apple-avd-$(CONFIG_VIDEO_APPLE_AVD_KUNIT_TEST) += avd-h264-test.o avd-queue-test.o \
+	avd-pm-test.o
 obj-$(CONFIG_VIDEO_APPLE_AVD) += apple-avd.o

drivers/media/platform/apple/avd/avd-apple-protocol.h

@@ -0,0 +1,141 @@
+/* SPDX-License-Identifier: GPL-2.0-only OR MIT */
+#ifndef AVD_APPLE_PROTOCOL_H_
+#define AVD_APPLE_PROTOCOL_H_
+
+#include <linux/errno.h>
+#include <linux/types.h>
+
+#include "avd-queue.h"
+
+#define AVD_APPLE_INBOX_BASE 0x01482cf8
+#define AVD_APPLE_COMMAND_SIZE 0x60
+#define AVD_APPLE_RESULT_WORDS 20
+#define AVD_APPLE_SHADOW_SIZE 64
+
+/*
+ * [C] Expected address notification, from the MIT V3 trace_avd.py precedent.
+ * Keep this rule in one place for correction by the Borage capture.
+ */
+#define AVD_APPLE_NOTIFY_BASE AVD_APPLE_INBOX_BASE
+
+/* SPEC 5.1: only these session opcodes have proved builders. */
+static inline int
+avd_apple_session_command(u32 cmd[24], u32 client, u32 opcode,
+			  u32 property, u32 value)
+{
+	unsigned int i;
+
+	if (client >= 1024 || (opcode != 0 && opcode != 2 && opcode != 5 && opcode != 6))
+		return -EINVAL;
+	for (i = 0; i < 24; i++)
+		cmd[i] = 0;
+	cmd[0] = opcode | (client << 16);
+	if (opcode == 6) {
+		cmd[1] = property;
+		cmd[2] = value;
+	}
+	return 0;
+}
+
+static inline int avd_apple_decode_prefix(struct avd_frame *f, u32 client,
+					  u32 selector, u32 work_sequence)
+{
+	unsigned int i;
+
+	if (f->idx >= AVD_MAX_FRAMES || client >= 1024 || selector >= 16 || work_sequence >= 4)
+		return -EINVAL;
+	for (i = 0; i < 24; i++)
+		f->cmd[i] = 0;
+	f->cmd[0] = 1 | (selector << 10) | (client << 22);
+	f->cmd[1] = f->idx | (work_sequence << 16);
+	f->cmd[3] = f->frame_num;
+	return 0;
+}
+
+struct avd_apple_reply_layout {
+	u8 type_word;
+	u8 type_shift;
+	u32 type_mask;
+	u8 client_word;
+	u8 client_shift;
+	u32 client_mask;
+	u8 frame_word;
+	u8 status_word;
+	u32 done_type;
+	bool verified;
+};
+
+struct avd_apple_reply {
+	u32 type;
+	u32 client;
+	u32 frame;
+	int status;
+};
+
+static inline int
+avd_apple_parse_reply(const u32 *record, size_t words,
+		      const struct avd_apple_reply_layout *layout,
+		      struct avd_apple_reply *reply)
+{
+	if (words != AVD_APPLE_RESULT_WORDS)
+		return -EMSGSIZE;
+	if (!layout->verified)
+		return -EOPNOTSUPP;
+	if (layout->type_word >= words || layout->client_word >= words ||
+	    layout->frame_word >= words || layout->status_word >= words ||
+	    layout->type_shift >= 32 || layout->client_shift >= 32 ||
+	    !layout->type_mask || !layout->client_mask || layout->done_type == 7)
+		return -EINVAL;
+	reply->type = (record[layout->type_word] >> layout->type_shift) & layout->type_mask;
+	reply->client = (record[layout->client_word] >> layout->client_shift) & layout->client_mask;
+	reply->frame = record[layout->frame_word];
+	/* SPEC 4.3: type 7 is parsing/VP done, never final buffer ownership. */
+	if (reply->type == 7)
+		return -EINPROGRESS;
+	if (reply->type != layout->done_type)
+		return -ENOMSG;
+	reply->status = record[layout->status_word] ? -EIO : 0;
+	return 0;
+}
+
+static inline u32 avd_apple_notification(unsigned int slot)
+{
+	return AVD_APPLE_NOTIFY_BASE + AVD_APPLE_COMMAND_SIZE * slot;
+}
+
+struct avd_apple_hw {
+	const char *fw_name;
+	/* All offsets below are relative to a DT-owned "apple" resource. */
+	u32 aperture_origin;
+	u32 imem;
+	u32 imem_size;
+	u32 version_offset;
+	u32 itcm_start;
+	u32 itcm_end;
+	u32 itcm_clear;
+	u32 itcm_clear_value;
+	u32 itcm_enable;
+	u32 itcm_enable_value;
+	u32 link_setup;
+	u32 link_setup_value;
+	u32 link_state;
+	u32 link_up;
+	u32 link_up_value;
+	u32 ready;
+	u32 notify;
+	u32 receive;
+	u32 receive_status;
+	u32 receive_pending;
+	u32 receive_ack;
+	u32 receive_ack_value;
+	u32 inbox_consumer;
+	u32 result_base;
+	struct avd_apple_reply_layout reply;
+	/* Match-data fact, never a module parameter or a userspace setting. */
+	bool verified;
+};
+
+extern const struct avd_apple_hw avd_borage_hw;
+extern const u8 avd_borage_config[64];
+
+#endif /* AVD_APPLE_PROTOCOL_H_ */

drivers/media/platform/apple/avd/avd-av1.c

@@ -1515,6 +1515,13 @@ static enum avd_image_fmt avd_av1_get_image_fmt(struct avd_ctx *ctx,
 #undef BIT_DEPTH
 }
 
+static unsigned int avd_av1_pp_kicks(struct avd_ctx *ctx)
+{
+	struct avd_av1_ctx *priv = ctx->priv;
+
+	return max_t(int, priv->submit_num, 1);
+}
+
 static void avd_av1_submit(struct avd_ctx *ctx)
 {
 	struct avd_av1_ctx *av1_ctx = ctx->priv;
@@ -1570,6 +1577,7 @@ const struct avd_coded_fmt_ops avd_av1_fmt_ops = {
 	.stop = avd_av1_stop,
 	.run = avd_av1_run,
 	.submit = avd_av1_submit,
+	.pp_kicks = avd_av1_pp_kicks,
 	.try_ctrl = avd_av1_try_ctrl,
 	.get_image_fmt = avd_av1_get_image_fmt,
 };