/* SPDX-License-Identifier: GPL-2.0-or-later WITH Linux-syscall-note */
/*
 * daedalus-v4l2 — kernel ↔ daemon wire protocol.
 *
 * Shared header used by both the kernel module
 * (drivers/daedalus_v4l2_chardev.c) and the userspace daemon
 * (daemon/src/main.c).  ABI: pre-1.0 — no stability guarantees
 * until DAEDALUS_PROTO_VERSION reaches 1.
 *
 * Transport: a single-instance chardev at /dev/daedalus-v4l2.
 * The userspace daemon opens the chardev O_RDWR, then drives a
 * blocking read() / write() loop:
 *
 *   write(): submit a response to a prior request (RESP_*).
 *   read():  block until the next request from the kernel
 *            (REQ_*) is available.
 *
 * Each message is a `struct daedalus_msg_hdr` followed by an
 * optional variable-length payload of `hdr.payload_len` bytes.
 *
 * Phase 8.2 (chardev bridge): only PING/PONG implemented.
 * Phase 8.4 (VP9 end-to-end): adds DECODE_FRAME request,
 * FRAME_READY response.
 */
#ifndef DAEDALUS_V4L2_PROTO_H
#define DAEDALUS_V4L2_PROTO_H

#include <linux/types.h>

#define DAEDALUS_PROTO_MAGIC		0x44303456u	/* 'D04V' */
#define DAEDALUS_PROTO_VERSION		0u		/* pre-1.0 */

/**
 * enum daedalus_msg_type - wire-protocol message types
 * @DAEDALUS_MSG_PING:		request: payload is opaque echo data
 * @DAEDALUS_MSG_PONG:		response: payload echoes the matching ping
 * @DAEDALUS_MSG_HELLO:		response: daemon announces itself on connect
 *
 * Phase 8.2 implements PING / PONG / HELLO.  Later phases add
 * REQ_DECODE / RESP_FRAME / etc.
 *
 * Request types (kernel → daemon) live in 0x0000_0000..0x7fff_ffff.
 * Response types (daemon → kernel) live in 0x8000_0000..0xffff_ffff.
 */
enum daedalus_msg_type {
	DAEDALUS_MSG_PING	= 0x00000001u,
	DAEDALUS_MSG_HELLO	= 0x80000001u,
	DAEDALUS_MSG_PONG	= 0x80000002u,
};

/**
 * struct daedalus_msg_hdr - on-the-wire message header
 * @magic:	must be DAEDALUS_PROTO_MAGIC; rejects gibberish
 * @version:	protocol version (DAEDALUS_PROTO_VERSION)
 * @type:	one of enum daedalus_msg_type
 * @cookie:	caller-supplied identifier; copied verbatim into
 *		the matching response so the daemon can pair
 *		response with request
 * @payload_len: number of bytes immediately following this
 *		struct (max DAEDALUS_PROTO_MAX_PAYLOAD)
 * @reserved:	must be zero for future use
 */
struct daedalus_msg_hdr {
	__u32 magic;
	__u32 version;
	__u32 type;
	__u32 cookie;
	__u32 payload_len;
	__u32 reserved;
};

#define DAEDALUS_PROTO_MAX_PAYLOAD	(64u * 1024u)	/* 64 KiB */

#endif /* DAEDALUS_V4L2_PROTO_H */