Patch Detail
Show a patch.
GET /api/patches/19684/?format=api
{ "id": 19684, "url": "https://patchwork.libcamera.org/api/patches/19684/?format=api", "web_url": "https://patchwork.libcamera.org/patch/19684/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20240312105851.243780-2-alexander.gordeev@opensynergy.com>", "date": "2024-03-12T10:58:51", "name": "[RFC,v9,1/1] virtio-video: Add virtio video device specification", "commit_ref": null, "pull_url": null, "state": "not-applicable", "archived": false, "hash": "1c2f1ab77cf2db406987c73790e547618eb38961", "submitter": { "id": 167, "url": "https://patchwork.libcamera.org/api/people/167/?format=api", "name": "Alexander Gordeev", "email": "Alexander.Gordeev@opensynergy.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/19684/mbox/", "series": [ { "id": 4216, "url": "https://patchwork.libcamera.org/api/series/4216/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=4216", "date": "2024-03-12T10:58:50", "name": "Virtio video device specification", "version": 9, "mbox": "https://patchwork.libcamera.org/series/4216/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/19684/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/19684/checks/", "tags": {}, "headers": { "Return-Path": "<libcamera-devel-bounces@lists.libcamera.org>", "X-Original-To": "parsemail@patchwork.libcamera.org", "Delivered-To": "parsemail@patchwork.libcamera.org", "Received": [ "from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 94B01C32A3\n\tfor <parsemail@patchwork.libcamera.org>;\n\tTue, 12 Mar 2024 11:29:03 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 242A462C8D;\n\tTue, 12 Mar 2024 12:29:03 +0100 (CET)", "from repost01.tmes.trendmicro.eu (repost01.tmes.trendmicro.eu\n\t[18.185.115.111])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 00E6D62C80\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 12 Mar 2024 11:59:59 +0100 (CET)", "from 104.47.11.169_.trendmicro.com (unknown [172.21.191.80])\n\tby repost01.tmes.trendmicro.eu (Postfix) with SMTP id 9BE2A10001350; \n\tTue, 12 Mar 2024 10:59:58 +0000 (UTC)", "from DEU01-FR2-obe.outbound.protection.outlook.com (unknown\n\t[104.47.11.169])\n\tby repre01.tmes.trendmicro.eu (Trend Micro Email Security) with\n\tESMTPS id 74DA810045DFD; Tue, 12 Mar 2024 10:59:56 +0000 (UTC)" ], "Authentication-Results": "lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (2048-bit key;\n\tunprotected) header.d=opensynergy.com header.i=@opensynergy.com\n\theader.b=\"DT3ipt7m\"; dkim-atps=neutral", "X-TM-MAIL-RECEIVED-TIME": "1710241196.478000", "X-TM-MAIL-UUID": "51c44f9c-2b1a-4080-8455-66d1ae3b3c82", "ARC-Seal": "i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none;\n\tb=bYjviGQVKjA6YAPRz6szHYz7VFmRegLZKhwbGSAOnVoZPjef5seZNp/c/P04i+/ElJlTVJQuT9kbRrO6cc7/iuyoaSERNsZ6fyjYpRM3FbLuzE8JjwX4aLKLE0Xt+lOXlNDVZhuNbPK2+Iuk6LOdDPGEuCCHBvNOYFLcXRF23no/Re9xkX522Eq7a5QpBelgUEakLN9A8VVUjouo2q9ExPkQLbngsBu6KIs0LkosdLXxKb32E/HqEh8Jt82byFv1z7Zq8/gyNNhDr8gNryEsjMj8SQL5UM5kq+0JCunSf54byNKCIuXoHmca/rxt0NlvllWMTdno0PiK1sr9VE6RQg==", "ARC-Message-Signature": "i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com;\n\ts=arcselector9901;\n\th=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1;\n\tbh=gNvtYPe7W/t4ouV2SIozFOI5B2f26aBgOcplPrhuozg=;\n\tb=THyqw60apDtFLAXdB6tSmXzYK0sFJFiY2KqXu66RYFLlCf9sifF25FlBqwW8F1N1rfa2KM3Mxryc6Rj58wwhyV2FioIpQ16Q9dn/9DP8/ly5f/BJn8vEmddWPEmivTkwxo43dGn6pTBIKVeKi5QrkdPNOwq46QIuEWSSzlxjQUGoGOnCPlqNVUQ89waw871exOloTxZMMx+pQ4AjTNjNV1PSOnWNw4z7KRG51rfin2Scgn1ltKnuQrOhsdYCKuhucrcdkk3BS/De9exb7TV3Pqz+E1wb4/S64bCznrWmte2NQhoVqiCP6owD2l5qmN9SWkRa6eyirtceE5X0g4tyyw==", "ARC-Authentication-Results": "i=1; mx.microsoft.com 1; spf=pass (sender ip is\n\t217.66.60.4) smtp.rcpttodomain=chromium.org\n\tsmtp.mailfrom=opensynergy.com; \n\tdmarc=pass (p=reject sp=reject pct=100) action=none\n\theader.from=opensynergy.com; dkim=none (message not signed);\n\tarc=none (0)", "X-MS-Exchange-Authentication-Results": "spf=pass (sender IP is 217.66.60.4)\n\tsmtp.mailfrom=opensynergy.com; dkim=none (message not signed)\n\theader.d=none;dmarc=pass action=none header.from=opensynergy.com;", "Received-SPF": "Pass (protection.outlook.com: domain of opensynergy.com\n\tdesignates 217.66.60.4 as permitted sender)\n\treceiver=protection.outlook.com; \n\tclient-ip=217.66.60.4; helo=SR-MAIL-03.open-synergy.com; pr=C", "From": "Alexander Gordeev <alexander.gordeev@opensynergy.com>", "To": "virtio-comment@lists.oasis-open.org", "Subject": "[RFC PATCH v9 1/1] virtio-video: Add virtio video device\n\tspecification", "Date": "Tue, 12 Mar 2024 11:58:51 +0100", "Message-Id": "<20240312105851.243780-2-alexander.gordeev@opensynergy.com>", "X-Mailer": "git-send-email 2.40.1", "In-Reply-To": "<20240312105851.243780-1-alexander.gordeev@opensynergy.com>", "References": "<20240312105851.243780-1-alexander.gordeev@opensynergy.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-EOPAttributedMessage": "0", "X-MS-PublicTrafficType": "Email", "X-MS-TrafficTypeDiagnostic": "AM2PEPF0001C70C:EE_|BE1P281MB1601:EE_", "Content-Type": "text/plain", "X-MS-Office365-Filtering-Correlation-Id": "0cf0497d-86cd-4993-25e7-08dc4283877b", "X-MS-Exchange-SenderADCheck": "1", "X-MS-Exchange-AntiSpam-Relay": "0", "X-Microsoft-Antispam": "BCL:0;", "X-Microsoft-Antispam-Message-Info": "dHbr/yjpKz2XZUjb9VvybOuSoANt0GEIuUgSiqPCj1oT0lkCNuDOO4AZwzSVbB2BJgSz+cMKEMQ6vDrPARLV8H0AqIKe+YC10eV4OCpK1HJwU3WcRr1mEb4L+Xy+8nVy/RribHiqpWne/e6fG33miioVd3iQwUkS2V/47HF07RlTIwK2sGlVA5qaOMmew8h+1qGT2JebCoiWesiSW2bIV9Abgrro8R1InWbwjIOIENkYl5kiYUEeXSVQCdzQrSXiZzgKlo6oBpIuFILUa3wIBaB9oJmP5c3TAN5N73r7iO2I56Ql9vaHKvytmVN4H/CbrBFyygHqhj6k3y/gI1VbdnrP9CRAUTYTOFHSROAKIdtAqp7jyafXGduyoWGW/hVBDoxUskbj4Ha7XXO+J/JrzJQ18QhDqzAVYQzCjNIFhEgCXfxjItxdVwdRxzA6Rp5m3n70IXGliaLMwGGOH/GZlvNgNeD9X2VKpi2qBWXH2r5sRnxMUo975sDeVqtu78EfZobL/J6x7U29qxCcU92kdrSZLTmDSyTI2pBah1bcHMU8Jh2HDXPNEBFqBHH5irOnTK/vnhGNt2+Mxc6xDTsbxqE1AI6cNssOKf/+sSu40rWmKZ2JFqIi7lTJrNpmSuvicVyADZ8NstHrJcDwGRTN8dgxV9QqEejemtxwHHOIS0zKF00B25Zqo1119WawWl5gORCI8G7aX/5U+Puuo7Gl5w==", "X-Forefront-Antispam-Report": "CIP:217.66.60.4; CTRY:DE; LANG:en; SCL:1; SRV:; \n\tIPV:NLI; SFV:NSPM; H:SR-MAIL-03.open-synergy.com;\n\tPTR:InfoDomainNonexistent; CAT:NONE;\n\tSFS:(13230031)(36860700004)(82310400014)(1800799015)(376005)(7416005);\n\tDIR:OUT; SFP:1102; ", "X-OriginatorOrg": "opensynergy.com", "X-MS-Exchange-CrossTenant-OriginalArrivalTime": "12 Mar 2024 10:59:46.0286\n\t(UTC)", "X-MS-Exchange-CrossTenant-Network-Message-Id": "0cf0497d-86cd-4993-25e7-08dc4283877b", "X-MS-Exchange-CrossTenant-Id": "800fae25-9b1b-4edc-993d-c939c4e84a64", "X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp": "TenantId=800fae25-9b1b-4edc-993d-c939c4e84a64;\n\tIp=[217.66.60.4]; \n\tHelo=[SR-MAIL-03.open-synergy.com]", "X-MS-Exchange-CrossTenant-AuthSource": "AM2PEPF0001C70C.eurprd05.prod.outlook.com", "X-MS-Exchange-CrossTenant-AuthAs": "Anonymous", "X-MS-Exchange-CrossTenant-FromEntityHeader": "HybridOnPrem", "X-MS-Exchange-Transport-CrossTenantHeadersStamped": "BE1P281MB1601", "X-TM-AS-ERS": "104.47.11.169-0.0.0.0", "X-TMASE-Version": "StarCloud-1.3-9.1.1015-28246.006", "X-TMASE-Result": "10--41.833700-4.000000", "X-TMASE-MatchedRID": "29kHMs2vf06UP+0hdpOx0icOunEIf0eXTY6J9vkpk6+EnIovOLzQ+rHq\n\tN6eNokKxnQvVnz410DyLO9h/kZ7mQnkHMxUIdlxL+DE5zr5ahdzc7b6k5+X69zAsn09lQFCFm7W\n\tYZnTau36ijVoxG5GMcAfoZhqt/FSE2J61hi7qqbLWcxHsnT13T+A4l73CwysLkZ43711Uirfnq/\n\tQ0Vm6yzXjkOsl2UmOSiOO4tRkG+50b0MvbS2k7/eR7n8NfvzbHvNWH1xH0HJtCSStXJecWpqk73\n\tTBcweln5uI/VJsBA/hExbsPAe7Yjzvv52pVtNiYCffN9El9NwMosWoVRearYZdigZi17dHqHzZm\n\t1Hzj3+Fdie35NvhswcBWIW6nmI08MK27Xb4wVhOzG+AMitSoBtZEjr6xrP/hVV0tOmM6MuUuyl+\n\tjDPCXAfPnifRvmQy1B8319zW9MLOQp7NCXsBS+l7l57ki0S38OIFiXs8CLoD/3DIK042wZLrylm\n\tp4boDebw2fK1xPVt7llG8yMplaAcCLq7uH3ByiS74sGh2G9bE0Tq4Urggo7JkRPHajPHqatNyYt\n\tAwOOd2NtHAU2Mk7UMZeKXZtwaKG291v80oF4q0JZ2Q97L+53YB1tSnIvF1DgWl+IkIeOg/tYJju\n\t2kuG605bjv09fgQoXs7OigGavd08sPiw3NkQIsd/DBuOH903CNLxQtZwZZ7hNUTwqg92ewysycy\n\tI3i9jmwx80ewIrMJ4NHx5qU6pwpafJafBs564uEKZe9OwaKzZv6jwU9E4EMw7GXc6vsdDDaw9SU\n\tr2HHwHXgi6SJ/1VYeBCZoD0SpTxeMj5nlDF9ERLjqoJJt/9Ye8/oJiio9KA3+iPIxcfrYMSiYZT\n\tF5wqnGDuy8y1qkuImxnQvgkai0i4mJ41W/O+n7cGd19dSFd", "X-TM-Deliver-Signature": "DC3F628AA3E39F5887E8D0900A8F709A", "X-TM-Addin-Auth": "mZbmNjHjVzSRep9LSR4DzNZXWazkbvIo3K+s5/K7MzP+Ulq0LBFv+/o00ZR\n\tp4W0Y4xstYwbWF3BBjNXszwmob9DLhfzQostu+t+ZtCj+qokiNjstwiLxLgO+CdXAPRUwZwOxQ/\n\t8V/Uez5vfvM80pGRfwAJvXay57+QXXTKVd6xfjFw4WnSs26TMhgraB/HCob5yemWfreyfNrR74/\n\tWo15Jq6VskzWHfjs/t0tE77/aod36Cy6RHcgvTtSn3wfZr6pqLcZmesbBIGb3mItBKQZ6WXv4vp\n\tDyYCcQxh12D4AshlII0c6xs8Jr+ovqgbCZx6.GroW5dxBB5Qj4XVRRAvhez1fP8Ao4aiBmjmhNF\n\tjA7stuMintPEJBhNarMeDws54Xw0XB2qjkB70yadGsMJNto6Fly2y2QgPhZY4MQ34yD9HSOmqi8\n\tG8QnykfgiBlXdl2suvL8070g0kehejbJhqNPkG8uZkutSdXHym/seew3QG5B0ztTgcTdEQPgs9a\n\t94ogMivaFBgFVpkfvmtU2NtGoQlRDaHjTjd5Jk3dbzVgIea60SUXz5sFXohr+OnsvsJszCnOYj5\n\t+smophD6cikqJRWF6rWZ5MnbMOFVtiqqJDib3Cx9anJldayVM8/IueuDqCd+38E5rbUfgIMuAZe\n\tzT5A==", "X-TM-Addin-ProductCode": "EMS", "DKIM-Signature": "v=1; a=rsa-sha256; c=simple/simple; d=opensynergy.com;\n\ts=TM-DKIM-20210503141657; t=1710241198;\n\tbh=3mxKMsgV0sHgC8qSMkaCAuv8HyaCCq9r928nW47Qdoc=; l=81486;\n\th=From:To:Date;\n\tb=DT3ipt7mnWVlFnFYOwQ/2s2VwbiRIqDbOvdvm6MDlFtwHtMrsLv4DCgsCDDr8NVAu\n\tcDxm/oJ+jlQOyYM0FHANNzZoilDHjNOxISpwHWClG712BSbVn+g/TFBatHnRsH75wj\n\tYzPd6ZAfHIKOVq7eiE9n2KuB+QcTGiVVnCQ8sA4KJYGoU6bIC55Wi4YFQu/1iUDy0M\n\tg/bubBVPUZRjXSdb2kjBOkV7BDIuylZIusn87svDjSwxktYfuKWsllOyw8JB/AgKAV\n\tPARm/JO5N3JHWR23M6YPTOKWyrhX7DAXlNRc+Brj+mYDB8CFfnssiJ7C0DqRry6wzM\n\tvttlsJNSbuzmw==", "X-Mailman-Approved-At": "Tue, 12 Mar 2024 12:29:00 +0100", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "Cc": "Albert Esteve <aesteve@redhat.com>, hmazur@google.com,\n\t\"Michael S . Tsirkin\" <mst@redhat.com>,\n\tDaniel Almeida <daniel.almeida@collabora.com>,\n\tMarcin Wojtas <mwojtas@google.com>,\n\tAndrii Cherniavskyi <andrii.cherniavskyi@opensynergy.com>,\n\tlibcamera-devel@lists.libcamera.org, bgrzesik@google.com,\n\tAndrew Gazizov <andrew.gazizov@opensynergy.com>,\n\tEnric Balletbo i Serra <eballetb@redhat.com>,\n\tGustavo Padovan <gustavo.padovan@collabora.com>,\n\tKeiichi Watanabe <keiichiw@chromium.org>, zyta@google.com,\n\tlinux-media@vger.kernel.org,\n\tAlexander Gordeev <alexander.gordeev@opensynergy.com>,\n\talex.bennee@linaro.org, \n\tmikrawczyk@google.com, Matti.Moell@opensynergy.com,\n\tAlexandre Courbot <acourbot@chromium.org>,\n\tCornelia Huck <cohuck@redhat.com>, bag@semihalf.com, srosek@google.com,\n\tNicolas Dufresne <nicolas.dufresne@collabora.com>,\n\tEnrico Granata <egranata@google.com>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "From: Alexander Gordeev <Alexander.Gordeev@opensynergy.com>\n\nAdd the specification of the video decoder and encoder devices, which\ncan be used to provide host-accelerated video operations to the guest.\n\nSigned-off-by: Alexander Gordeev <alexander.gordeev@opensynergy.com>\nCo-authored-by: Keiichi Watanabe <keiichiw@chromium.org>\nCo-authored-by: Alexandre Courbot <acourbot@chromium.org>\n---\n conformance.tex | 4 +\n content.tex | 1 +\n device-types/video/description.tex | 1607 +++++++++++++++++++++\n device-types/video/device-conformance.tex | 22 +\n device-types/video/driver-conformance.tex | 20 +\n introduction.tex | 21 +\n 6 files changed, 1675 insertions(+)\n create mode 100644 device-types/video/description.tex\n create mode 100644 device-types/video/device-conformance.tex\n create mode 100644 device-types/video/driver-conformance.tex", "diff": "diff --git a/conformance.tex b/conformance.tex\nindex dc00e84..56cdade 100644\n--- a/conformance.tex\n+++ b/conformance.tex\n@@ -34,6 +34,7 @@ \\section{Conformance Targets}\\label{sec:Conformance / Conformance Targets}\n \\ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance},\n \\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance} or\n \\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}.\n+\\ref{sec:Conformance / Driver Conformance / Video Driver Conformance},\n \n \\item Clause \\ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.\n \\end{itemize}\n@@ -61,6 +62,7 @@ \\section{Conformance Targets}\\label{sec:Conformance / Conformance Targets}\n \\ref{sec:Conformance / Device Conformance / SCMI Device Conformance},\n \\ref{sec:Conformance / Device Conformance / GPIO Device Conformance} or\n \\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}.\n+\\ref{sec:Conformance / Device Conformance / Video Device Conformance},\n \n \\item Clause \\ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}.\n \\end{itemize}\n@@ -152,6 +154,7 @@ \\section{Conformance Targets}\\label{sec:Conformance / Conformance Targets}\n \\input{device-types/scmi/driver-conformance.tex}\n \\input{device-types/gpio/driver-conformance.tex}\n \\input{device-types/pmem/driver-conformance.tex}\n+\\input{device-types/video/driver-conformance.tex}\n \n \\conformance{\\section}{Device Conformance}\\label{sec:Conformance / Device Conformance}\n \n@@ -238,6 +241,7 @@ \\section{Conformance Targets}\\label{sec:Conformance / Conformance Targets}\n \\input{device-types/scmi/device-conformance.tex}\n \\input{device-types/gpio/device-conformance.tex}\n \\input{device-types/pmem/device-conformance.tex}\n+\\input{device-types/video/device-conformance.tex}\n \n \\conformance{\\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}\n A conformant implementation MUST be either transitional or\ndiff --git a/content.tex b/content.tex\nindex 0a62dce..b6469b7 100644\n--- a/content.tex\n+++ b/content.tex\n@@ -767,6 +767,7 @@ \\chapter{Device Types}\\label{sec:Device Types}\n \\input{device-types/scmi/description.tex}\n \\input{device-types/gpio/description.tex}\n \\input{device-types/pmem/description.tex}\n+\\input{device-types/video/description.tex}\n \n \\chapter{Reserved Feature Bits}\\label{sec:Reserved Feature Bits}\n \ndiff --git a/device-types/video/description.tex b/device-types/video/description.tex\nnew file mode 100644\nindex 0000000..8ec28d3\n--- /dev/null\n+++ b/device-types/video/description.tex\n@@ -0,0 +1,1607 @@\n+\\section{Video Device}\n+\\label{sec:Device Types / Video Device}\n+\n+The virtio video encoder and decoder devices provide support for\n+host-accelerated video encoding and decoding. Despite being different\n+device types, they use the same protocol and general flow.\n+\n+\\subsection{Device ID}\n+\\label{sec:Device Types / Video Device / Device ID}\n+\n+\\begin{description}\n+\\item[30]\n+ encoder device\n+\\item[31]\n+ decoder device\n+\\end{description}\n+\n+\\subsection{Virtqueues}\n+\\label{sec:Device Types / Video Device / Virtqueues}\n+\n+\\begin{description}\n+\\item[0]\n+ mainq - high-priority driver commands\n+\\item[1]\n+ eventq - device delayed responses to commands and standalone device events\n+\\item[2] inputq0 - stream 0 input driver commands\n+\\item[3] outputq0 - stream 0 output driver commands\n+\\item[\\ldots]\n+\\item[2N] inputqN-1 - stream N-1 input driver commands\n+\\item[2N+1] outputqN-1 - stream N-1 output driver commands\n+\\end{description}\n+\n+\\subsection{Feature bits}\n+\\label{sec:Device Types / Video Device / Feature bits}\n+\n+\\begin{description}\n+\\item[VIRTIO_VIDEO_F_RESOURCE_GUEST_PAGES (0)]\n+ Guest pages can be used as the backing memory of resources.\n+\\item[VIRTIO_VIDEO_F_RESOURCE_NON_CONTIG (1)]\n+ The device can use non-contiguous guest memory as the backing memory of\n+ resources. Only meaningful if VIRTIO_VIDEO_F_RESOURCE_GUEST_PAGES is also\n+ set.\n+\\item[VIRTIO_VIDEO_F_RESOURCE_VIRTIO_OBJECT (2)]\n+ Objects exported by another virtio device can be used as the backing memory\n+ of resources.\n+\\item[VIRTIO_VIDEO_F_RESOURCE_DYNAMIC (3)]\n+ The device supports re-attaching memory to resources while streaming.\n+% TODO: this flag is not used anywhere at the moment. Might be necessary with\n+% Android. To be sorted out when the driver and the device are updated.\n+\\end{description}\n+\n+\\devicenormative{\\subsubsection}{Feature bits}{Device Types / Video Device / Feature bits}\n+\n+The device MUST set at least one of VIRTIO_VIDEO_F_RESOURCE_GUEST_PAGES or\n+VIRTIO_VIDEO_F_RESOURCE_VIRTIO_OBJECT, since the absence of both bits would\n+mean that no memory can be used at all for resources.\n+\n+The device MUST NOT set VIRTIO_VIDEO_F_RESOURCE_NON_CONTIG unless it also sets\n+VIRTIO_VIDEO_F_RESOURCE_GUEST_PAGES.\n+\n+\\drivernormative{\\subsubsection}{Feature bits}{Device Types / Video Device / Feature bits}\n+\n+The driver MUST negotiate at least one of the\n+VIRTIO_VIDEO_F_RESOURCE_GUEST_PAGES and VIRTIO_VIDEO_F_RESOURCE_VIRTIO_OBJECT\n+features.\n+\n+If VIRTIO_VIDEO_F_RESOURCE_GUEST_PAGES has been negotiated, but not\n+VIRTIO_VIDEO_F_RESOURCE_NON_CONTIG, the driver MUST use physically\n+contiguous memory for all the buffers it allocates.\n+\n+\\subsection{Device configuration layout}\n+\\label{sec:Device Types / Video Device / Device configuration layout}\n+\n+The video device configuration space uses the following layout:\n+\n+\\begin{lstlisting}\n+struct virtio_video_config {\n+ le32 max_streams;\n+ le32 caps_length;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{max_streams}]\n+ is the maximum number of concurrent streams the device supports.\n+\\item[\\field{caps_length}]\n+ is the minimum length in bytes that a device-writable buffer must have\n+ in order to receive the response to VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS, see\n+ \\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}.\n+\\end{description}\n+\n+\\devicenormative{\\subsubsection}{Device configuration layout}{Device Types / Video Device / Device configuration layout}\n+\n+\\field{max_streams} MUST be positive.\n+\n+\\field{caps_length} MUST be set to the response size of\n+VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS.\n+\n+\\subsection{Device Initialization}\n+\\label{sec:Device Types / Video Device / Device Initialization}\n+\\begin{enumerate}\n+\\item\n+ The driver reads the feature bits and negotiates the features it needs.\n+\\item\n+ The driver sets up the mainq and the eventq.\n+\\item\n+ The driver reads the \\field{max_streams} field of the configuration\n+ space and sets up input and output queues.\n+\\item\n+ The driver reads the \\field{caps_length} field of the configuration\n+ space, prepares a buffer of at least that size and sends the buffer on the\n+ mainq with the VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS command.\n+\\item\n+ The driver receives the response from the device, and parses its capabilities.\n+\\end{enumerate}\n+\n+\\subsection{Device Operation}\n+\\label{sec:Device Types / Video Device / Device Operation}\n+\n+The mainq is used by the driver to open streams using\n+VIRTIO_VIDEO_CMD_STREAM_OPEN commands, close the streams using\n+VIRTIO_VIDEO_CMD_STREAM_CLOSE commands, to reset stream queues using\n+VIRTIO_VIDEO_CMD_QUEUE_RESET commands, to set some of the stream parameters out\n+of band with high priority using VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS commands.\n+Each stream has two dedicated virtqueues: inputqX and outputqX, where X is the\n+stream id. The driver uses both queues to set their parameters using\n+VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS commands and queue input or output\n+resources using VIRTIO_VIDEO_CMD_RESOURCE_QUEUE commands.\n+The driver can ask the device to complete processing of all queued input\n+resources and make the resulting output resources available to the driver by\n+queueing a VIRTIO_VIDEO_CMD_STREAM_DRAIN command to inputqX.\n+The device sends responses to all the driver commands via used descriptors\n+provided with the commands.\n+The eventq is used by the device to send the device's delayed responses to\n+commands and the device's standalone events.\n+All the commands sent within an opened stream start background operations,\n+return the actual results using delayed responses over eventq and use the\n+command responses to establish links between the commands and the\n+delayed responses.\n+\n+Parameters allow the driver to configure the stream including setting up the\n+resources. Available parameters depend on the device type, see\n+\\ref{sec:Device Types / Video Device / Device capabilities and parameters}.\n+\n+A resource is a set of memory buffers that contain a unit of data that\n+the device can process or produce. Most resources will only have one\n+buffer (like coded data and single-planar raw frames), but frames using a\n+multi-planar format can have several.\n+Input resources are filled by the driver with compressed (coded) video data\n+for a decoder and raw frames for an encoder, output resources are filled by\n+the device as the result of processing the input resources with decoded raw\n+frames for a decoder and compressed (encoded) data for an encoder.\n+Resources from inputqX and outputqX are consumed independently, not in pairs.\n+One input resource can result in zero to many produced output resources.\n+A decoder device dequeues the output decoded frames in presentation order.\n+An encoder device dequeues the output decoded frames in decoding order.\n+The driver can reuse a queued resource after receiving a corresponding delayed\n+response. Dequeued output resources can still be used by the device as\n+reference frames, so the driver can't write to them.\n+\n+% TODO: maybe add a second delayed response, when the dequeued output resource\n+% is not used by the device anymore and therefore becomes writeable?\n+\n+The device can detect standalone stream-related events: errors and dynamic\n+parameters changes that require intervention from the driver (e.g.\n+reallocating backing memory of output resources to fit the new parameters).\n+The events are signalled on the eventq, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Standalone Events}.\n+\n+\\devicenormative{\\subsubsection}{Device Operation}{Device Types / Video Device / Device Operation}\n+\n+The device MUST NOT access inputqX or outputqX before it receives a\n+VIRTIO_VIDEO_CMD_STREAM_OPEN command with \\field{stream_id} set to X or after\n+a delayed response to VIRTIO_VIDEO_CMD_STREAM_CLOSE with the same\n+\\field{stream_id} is sent.\n+\n+The device MUST set to zero all unused, disabled or padding bits in its\n+responses.\n+\n+\\subsubsection{Device Operation: Command Virtqueues}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+\n+This section details the commands that can be sent by the driver to mainq,\n+stream input and output queues and the device's responses.\n+\n+Different structures are used for each command and response. A command\n+structure starts with the requested command code, defined as follows:\n+\n+\\begin{lstlisting}\n+/* Device */\n+#define VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS 0x100\n+\n+/* Stream */\n+#define VIRTIO_VIDEO_CMD_STREAM_OPEN 0x200\n+#define VIRTIO_VIDEO_CMD_STREAM_CLOSE 0x201\n+#define VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS 0x202\n+#define VIRTIO_VIDEO_CMD_STREAM_GET_PARAMS VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS\n+#define VIRTIO_VIDEO_CMD_STREAM_DRAIN 0x203\n+\n+/* Queue */\n+#define VIRTIO_VIDEO_CMD_QUEUE_RESET 0x300\n+#define VIRTIO_VIDEO_CMD_RESOURCE_QUEUE 0x301\n+\\end{lstlisting}\n+\n+A response structure starts with the result of the requested command,\n+defined as follows:\n+\n+\\begin{lstlisting}\n+/* Success */\n+#define VIRTIO_VIDEO_RESULT_OK 0x000\n+#define VIRTIO_VIDEO_RESULT_OK_DELAYED 0x001\n+\n+/* Error */\n+#define VIRTIO_VIDEO_RESULT_ERR_INVALID_COMMAND 0x100\n+#define VIRTIO_VIDEO_RESULT_ERR_INVALID_OPERATION 0x101\n+#define VIRTIO_VIDEO_RESULT_ERR_INVALID_STREAM_ID 0x102\n+#define VIRTIO_VIDEO_RESULT_ERR_INVALID_RESOURCE_ID 0x103\n+#define VIRTIO_VIDEO_RESULT_ERR_INVALID_ARGUMENT 0x104\n+#define VIRTIO_VIDEO_RESULT_ERR_OUT_OF_MEMORY 0x105\n+\\end{lstlisting}\n+\n+For response structures carrying an error code, the rest of the\n+structure is considered invalid.\n+\n+For all commands returning delayed responses over eventq, the command response\n+is defined as follows:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_VIDEO_STANDALONE_EVENT_ID 0xffffffff\n+\n+struct virtio_video_command_resp_delayed_common {\n+ le32 result; /* VIRTIO_VIDEO_RESULT_* */\n+ le32 delayed_response_id;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{result}]\n+ is\n+\n+ \\begin{description}\n+ \\item[VIRTIO_VIDEO_RESULT_OK_DELAYED]\n+ if the command started the desired background operation successfully,\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_INVALID_STREAM_ID]\n+ if the mentioned stream ID does not exist,\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_INVALID_RESOURCE_ID]\n+ if the mentioned resource ID does not exist,\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_INVALID_ARGUMENT]\n+ if other command parameters are not valid, e.g. not within the device's\n+ capabilities,\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_INVALID_OPERATION]\n+ if the command is performed at a time when it is not valid.\n+ \\end{description}\n+\\item[\\field{delayed_response_id}]\n+ is an ID of the future delayed response provided by the device, that allows\n+ to relate it to the command.\n+\\end{description}\n+\n+\\devicenormative{\\paragraph}{Device Operation: Command Virtqueues}{Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+\n+Responses to a command MUST be written by the device in the first\n+device-writable descriptor of the descriptor chain from which the\n+command came.\n+\n+The device MUST return VIRTIO_VIDEO_RESULT_ERR_INVALID_COMMAND to\n+any command code it does not recognize.\n+\n+\\field{delayed_response_id} MUST be set to a stream-unique identifier that\n+remains valid as long as the background operation hasn't finished.\n+\n+\\drivernormative{\\paragraph}{Device Operation: Command Virtqueues}{Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+\n+Descriptor chains sent to the command queues by the driver MUST include at\n+least one device-writable descriptor of a size sufficient to receive the\n+response to the queued command.\n+\n+The driver MUST NOT interpret the rest of a response whose result is not\n+VIRTIO_VIDEO_RESULT_OK or VIRTIO_VIDEO_RESULT_OK_DELAYED.\n+\n+\\subsubsection{Device Operation: Event Virtqueue}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}\n+\n+The eventq is used by the device to send delayed responses to commands queued\n+by the driver on other queues and standalone events. Stream errors and dynamic\n+parameters changes are caused by changes in the device's state, not by\n+commands, still they are delivered as VIRTIO_VIDEO_DELAYED_RESP_STREAM_CLOSE\n+and VIRTIO_VIDEO_DELAYED_RESP_STREAM_SET_PARAMS, respectively.\n+\n+The supported events are defined as follows:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_VIDEO_DELAYED_RESP_STREAM_CLOSE 1\n+#define VIRTIO_VIDEO_DELAYED_RESP_STREAM_SET_PARAMS 2\n+#define VIRTIO_VIDEO_DELAYED_RESP_STREAM_DRAIN 3\n+#define VIRTIO_VIDEO_DELAYED_RESP_QUEUE_RESET 4\n+#define VIRTIO_VIDEO_DELAYED_RESP_RESOURCE_QUEUE 5\n+\n+#define VIRTIO_VIDEO_EVENT_FLAG_CANCELED (1 << 0)\n+\n+struct virtio_video_event {\n+ le32 event_type; /* VIRTIO_VIDEO_DELAYED_RESP_* */\n+ le32 stream_id;\n+ le32 delayed_response_id;\n+ le32 event_flags; /* Bitmask of VIRTIO_VIDEO_EVENT_FLAG_* */\n+ union {\n+ struct virtio_video_stream_set_params_delayed_resp set_params;\n+ struct virtio_video_resource_queue_delayed_resp queue;\n+ };\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{event_type}]\n+ is the type of the event.\n+\\item[\\field{stream_id}]\n+ is the ID of a valid stream.\n+\\item[\\field{delayed_response_id}]\n+ is an ID of the delayed response, that allows to relate it to a previously\n+ submitted command. If it is set to VIRTIO_VIDEO_STANDALONE_EVENT_ID, then\n+ this is a standalone event, see\n+ \\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Standalone Events}.\n+\\item[\\field{event_flags}]\n+ is a bitmask of VIRTIO_VIDEO_EVENT_FLAG_* flags\n+\n+ \\begin{description}\n+ \\item[VIRTIO_VIDEO_EVENT_FLAG_CANCELED]\n+ is set if the command has been canceled by another command, that has\n+ higher priority. Doesn't make sense for standalone events.\n+ \\end{description}\n+\\end{description}\n+\n+The particular member of the union is selected according to the\n+\\field{event_type} for some of the types.\n+\n+\\drivernormative{\\paragraph}{Device Operation: Event Virtqueue}{Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}\n+\n+The driver MUST at any time have at least one descriptor with a used\n+buffer large enough to contain a \\field{struct virtio_video_event}\n+queued on the eventq.\n+\n+The driver MUST NOT put device-readable descriptors into the eventq.\n+\n+The driver MUST account for the fact that the delayed responses to commands\n+might come out-of-order (i.e. after other commands sent to the device),\n+and that some of them can be cancelled.\n+\n+The driver SHOULD wait for a delayed response of command A, that caused\n+cancellation of command B, before queueing the command B again.\n+\n+\\subsubsection{Device Operation: TLV format}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: TLV format}\n+\n+Both VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS and VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS\n+commands represent device parameters and corresponding device capabilities\n+in the form of TLV (Type-Length-Value):\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv {\n+ le32 type;\n+ le32 length;\n+ u8 value[length];\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{type}]\n+ specifies the type of data in \\field{value}.\n+\\item[\\field{length}]\n+ specifies the \\field{value} size in bytes aligned to 8.\n+\\item[\\field{value}]\n+ contains the data according to the type.\n+\\end{description}\n+\n+The following TLV types are defined:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_VIDEO_TLV_CODED_SET 1\n+#define VIRTIO_VIDEO_TLV_RAW_SET 2\n+#define VIRTIO_VIDEO_TLV_LINK 3\n+#define VIRTIO_VIDEO_TLV_CODED_FORMAT 4\n+#define VIRTIO_VIDEO_TLV_RAW_FORMAT 5\n+#define VIRTIO_VIDEO_TLV_CODED_RESOURCES 6\n+#define VIRTIO_VIDEO_TLV_RAW_RESOURCES 7\n+#define VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES 8\n+#define VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT 9\n+#define VIRTIO_VIDEO_TLV_CROP 10\n+#define VIRTIO_VIDEO_TLV_V4L2_CONTROLS 11\n+\\end{lstlisting}\n+\n+Some TLVs are used only as containers for sequences of nested TLVs:\n+\n+\\begin{description}\n+\\item[\\field{VIRTIO_VIDEO_TLV_CODED_SET}]\n+ groups various parameters or capabilities related to a particular coded\n+ format.\n+\\item[\\field{VIRTIO_VIDEO_TLV_RAW_SET}]\n+ groups various parameters or capabilities related to a particular raw\n+ format.\n+\\item[\\field{VIRTIO_VIDEO_TLV_V4L2_CONTROLS}]\n+ contains V4L2 controls represented in the TLV format. Within this container\n+ only selected V4L2 control identifiers (V4L2_CID_*) are allowed to be used\n+ in the TLV \\field{type} field, see\n+ \\ref{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS}.\n+\\end{description}\n+\n+TLV with type VIRTIO_VIDEO_TLV_LINK is a special one used to define relations\n+between sets of capabilities, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}.\n+\n+For each of the remaining TLV types two different contained data formats are\n+defined: one for the capabilities and one for the specific parameter values.\n+\n+\\field{struct virtio_video_range} is used to represent a range of values in\n+some TLVs:\n+\n+\\begin{lstlisting}\n+struct virtio_video_range {\n+ le32 min;\n+ le32 max;\n+ le32 step;\n+ u8 padding[4];\n+};\n+\\end{lstlisting}\n+\n+An integer \\(x\\) is within the range \\field{r} if\n+\\(\\field{r.min} \\le x \\le \\field{r.max}\\) holds and \\(x\\) equals to\n+\\((\\field{min} + \\field{step} * n)\\) for some integer \\(n\\).\n+\n+\\devicenormative{\\paragraph}{Device Operation: TLV format}{Device Types / Video Device / Device Operation / Device Operation: TLV format}\n+\n+\\field{min}, \\field{step} and \\field{max} MUST be positive.\n+\n+\\field{min} MUST be less then or equal to \\field{max} within the same range.\n+\n+\\subsubsection{Device Operation: Device Commands}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Device Commands}\n+\n+This command allows retrieving the device capabilities.\n+\n+\\paragraph{VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}\n+\n+Retrieve device capabilities for all available stream parameters (for example,\n+the range of values).\n+\n+The driver sends this command with\n+\\field{struct virtio_video_device_query_caps}:\n+\n+\\begin{lstlisting}\n+struct virtio_video_device_query_caps {\n+ le32 cmd_type; /* VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS */\n+};\n+\\end{lstlisting}\n+\n+The device responds with\n+\\field{struct virtio_video_device_query_caps_resp}:\n+\n+\\begin{lstlisting}\n+struct virtio_video_device_query_caps_resp {\n+ le32 result; /* VIRTIO_VIDEO_RESULT_* */\n+ u8 padding[4];\n+ /**\n+ * Followed by a sequence of TLVs up to caps_length\n+ * counted in bytes from the beginning of the struct.\n+ */\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{result}]\n+ is\n+\n+ \\begin{description}\n+ \\item[VIRTIO_VIDEO_RESULT_OK]\n+ if the operation succeeded,\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_OUT_OF_MEMORY]\n+ if the descriptor was smaller than the defined \\field{caps_length} in\n+ the video device configuration.\n+ \\end{description}\n+\\end{description}\n+\n+The sequence of TLVs consists of TLV containers VIRTIO_VIDEO_TLV_CODED_SET\n+and VIRTIO_VIDEO_TLV_RAW_SET defining sets of possible coded, or respectively\n+raw formats, including the corresponding parameters (e.g. profiles, levels\n+or format modifiers, resolutions), that are supported by the device. For the\n+details see\n+\\ref{sec:Device Types / Video Device / Device capabilities and parameters}.\n+The last TLV in the sequence with type VIRTIO_VIDEO_TLV_LINK establishes\n+relations between the two groups. If there is a link, then the device supports\n+decoding from the specified coded set to the specified raw set, or encoding in\n+the opposite direction. The value format is defined as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_link {\n+ le64 links[n_coded * (n_raw + 63) / 64];\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{n_coded}]\n+ is the number of VIRTIO_VIDEO_TLV_CODED_SET containers.\n+\\item[\\field{n_raw}]\n+ is the number of VIRTIO_VIDEO_TLV_RAW_SET containers.\n+\\item[\\field{links}]\n+ is a bitset establishing links between coded and raw sets. For \\field{i}-th\n+ coded and \\field{j}-th raw sets counted from zero bit \\field{(j \\% 64)} in\n+ \\field{links[i * (n_raw + 63) / 64 + j / 64]} defines the link if it is set.\n+\\end{description}\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}{Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}\n+\n+The device MUST include into the response at least one\n+VIRTIO_VIDEO_TLV_CODED_SET and at least one VIRTIO_VIDEO_TLV_RAW_SET TLV\n+containers, and exactly one VIRTIO_VIDEO_TLV_LINK TLV, that defines links\n+between the coded and raw sets. The VIRTIO_VIDEO_TLV_LINK TLV MUST be the\n+last one in the sequence.\n+\n+Each VIRTIO_VIDEO_TLV_CODED_SET and VIRTIO_VIDEO_TLV_RAW_SET MUST take part\n+in at least one defined link in the VIRTIO_VIDEO_TLV_LINK.\n+\n+Each VIRTIO_VIDEO_TLV_CODED_SET MUST contain exactly one\n+VIRTIO_VIDEO_TLV_CODED_FORMAT TLV, exactly one\n+VIRTIO_VIDEO_TLV_CODED_RESOURCES TLV and at most one TLV of other types.\n+\n+Each VIRTIO_VIDEO_TLV_RAW_SET MUST contain exactly one\n+VIRTIO_VIDEO_TLV_RAW_FORMAT TLV, exactly one VIRTIO_VIDEO_TLV_RAW_RESOURCES\n+TLV and at most one TLV of other types.\n+\n+VIRTIO_VIDEO_TLV_RAW_SET containers SHOULD be ordered according to raw format\n+preferences of the device from preferred to not preferred ones.\n+\n+The total size of the response MUST be equal to \\field{caps_length}\n+bytes, as reported by the device configuration.\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}{Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}\n+\n+VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS MUST be sent to mainq.\n+\n+\\subsubsection{Device Operation: Stream commands}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands}\n+\n+Stream commands allow to open, close and control the flow of a stream.\n+\n+\\paragraph{VIRTIO_VIDEO_CMD_STREAM_OPEN}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_OPEN}\n+\n+Open a stream using the device.\n+\n+The driver sends this command with\n+\\field{struct virtio_video_stream_open}:\n+\n+\\begin{lstlisting}\n+struct virtio_video_stream_open {\n+ le32 cmd_type; /* VIRTIO_VIDEO_CMD_STREAM_OPEN */\n+ le32 stream_id;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{stream_id}]\n+ is the ID of the stream to be opened.\n+\\end{description}\n+\n+The device responds with \\field{struct virtio_video_stream_open_resp}:\n+\n+\\begin{lstlisting}\n+struct virtio_video_stream_open_resp {\n+ le32 result; /* VIRTIO_VIDEO_RESULT_* */\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{result}]\n+ is\n+\n+ \\begin{description}\n+ \\item[VIRTIO_VIDEO_RESULT_OK]\n+ if the operation succeeded,\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_INVALID_STREAM_ID]\n+ if the \\field{stream_id} is out of limits specified by the device.\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_INVALID_OPERATION]\n+ if the stream is already open or cannot be opened due to an unexpected\n+ device issue.\n+ \\item[VIRTIO_VIDEO_RESULT_ERR_OUT_OF_MEMORY]\n+ if the limit of simultaneous streams has been reached by the device and\n+ no more can be opened.\n+ \\end{description}\n+\\end{description}\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_OPEN}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_OPEN}\n+\n+The device MUST ensure that the \\field{stream_id} is within limits and that\n+the corresponding stream is not open.\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_OPEN}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_OPEN}\n+\n+VIRTIO_VIDEO_CMD_STREAM_OPEN MUST be sent to mainq.\n+\n+\\paragraph{VIRTIO_VIDEO_CMD_STREAM_CLOSE}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_CLOSE}\n+\n+% CLOSE has to be more like RESET, not DRAIN, because it is called, for\n+% example, when the guest user-space app closes a file descriptor. So there\n+% is no sense in continuing the processing.\n+\n+Close a video stream. Any activity on the stream is halted and all resources\n+are released by the time the delayed response is received by the driver.\n+\n+The driver sends this command with\n+\\field{struct virtio_video_stream_close}:\n+\n+\\begin{lstlisting}\n+struct virtio_video_stream_close {\n+ le32 cmd_type; /* VIRTIO_VIDEO_CMD_STREAM_CLOSE */\n+ le32 stream_id;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{stream_id}]\n+ is the ID of the stream to be closed.\n+\\end{description}\n+\n+The device responds as described in\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+and begins a background CLOSE operation, that consists of RESET operations on\n+inputqX and outputqX, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_QUEUE_RESET},\n+and detaching all the resources.\n+\n+When the CLOSE operation is completed the device sends the\n+VIRTIO_VIDEO_DELAYED_RESP_STREAM_CLOSE delayed response, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}.\n+The same delayed response can also come after an unrecoverable stream error,\n+see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Standalone Events / Error Event}.\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_CLOSE}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_CLOSE}\n+\n+Before the device sends a delayed response to VIRTIO_VIDEO_CMD_STREAM_CLOSE,\n+it MUST reset inputqX and outputqX and detach all the resources.\n+\n+After VIRTIO_VIDEO_CMD_STREAM_CLOSE is queued, the device MUST reply with\n+VIRTIO_VIDEO_RESULT_ERR_INVALID_STREAM_ID to any subsequently queued command\n+with this stream ID except VIRTIO_VIDEO_CMD_STREAM_OPEN.\n+\n+The CLOSE operation MUST NOT be canceled.\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_CLOSE}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_CLOSE}\n+\n+\\field{stream_id} MUST be set to a valid stream ID of an open stream.\n+\n+VIRTIO_VIDEO_CMD_STREAM_CLOSE MUST be sent to mainq.\n+\n+The driver MAY release descriptors of inputqX and outputqX where X equals\n+\\field{stream_id} after receiving the delayed response to this command.\n+\n+\\paragraph{VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}\n+\n+Set selected parameters of inputqX or outputqX of a given stream and receive\n+back the current values of all parameters supported by the device for the\n+queue as reported by\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}.\n+Coded parameters within a VIRTIO_VIDEO_TLV_CODED_SET container belong to\n+inputqX of a decoder and to outputqX of an encoder. Raw parameters within a\n+VIRTIO_VIDEO_TLV_RAW_SET container belong to outputqX of a decoder and to\n+inputqX of an encoder.\n+\n+The driver sends this command with\n+\\field{struct virtio_video_stream_set_params}:\n+\n+\\begin{lstlisting}\n+struct virtio_video_stream_set_params {\n+ le32 cmd_type; /* VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS */\n+ le32 stream_id;\n+ /**\n+ * Followed by a single VIRTIO_VIDEO_TLV_CODED_SET or\n+ * VIRTIO_VIDEO_TLV_RAW_SET TLV container with the parameters.\n+ */\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{stream_id}]\n+ is the ID of the stream we want to set a parameter for.\n+\\end{description}\n+\n+The operation can be queued to:\n+\n+\\begin{itemize}\n+\\item[\\field{inputqX}]\n+ The parameters are set after all commands previously queued on the inputqX\n+ are processed. Both inputqX and outputqX parameters can be changed\n+ separately. Any changes to formats or resource numbers trigger the following\n+ sequence:\n+ \\begin{enumerate}\n+ \\item\n+ an implicit DRAIN operation, see\n+ \\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_DRAIN};\n+ \\item\n+ only for changes to outputqX parameters: an implicit RESET operation on\n+ the outputqX, see\n+ \\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_QUEUE_RESET};\n+ \\item\n+ all resources of the affected queue are detached.\n+ \\end{enumerate}\n+\\item[\\field{outputqX}]\n+ The parameters are set after all commands previously queued on the outputqX\n+ are processed. Only outputqX parameters can be changed. Changes to the\n+ format or the resource number are allowed only after opening the stream or\n+ after a outputqX RESET operation on outputqX before any resources are\n+ queued.\n+\\item[\\field{mainq}]\n+ The parameters are set without waiting for other commands queued on inputqX\n+ and outputqX to be processed. Both inputqX and outputqX parameters can be\n+ changed separately. Changes to formats or resources parameters are not\n+ allowed.\n+\\end{itemize}\n+% TODO: list use-cases?\n+\n+% Use-case: for the decoder, resolution can be set manually by the driver\n+% (useful for codecs that do not embed this information, like MPEG-2).\n+% The processing sequence should look similar to the dynamic parameters\n+% change case.\n+\n+Only the parameters returned in one of the corresponding sets in the device\n+capabilities can be set, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}.\n+The device checks and applies the parameter changes, responds as described in\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+and sends the VIRTIO_VIDEO_DELAYED_RESP_STREAM_SET_PARAMS\n+delayed response, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}.\n+The delayed response can also come in case of a dynamic parameters change, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Standalone Events / Dynamic Parameters Change Event}.\n+\n+The command-specific delayed response\n+\\field{struct virtio_video_stream_set_params_delayed_resp} is defined\n+as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_video_stream_set_params_delayed_resp {\n+ /**\n+ * A VIRTIO_VIDEO_TLV_CODED_SET or VIRTIO_VIDEO_TLV_RAW_SET\n+ * TLV container with all parameters supported by the device.\n+ */\n+};\n+\\end{lstlisting}\n+\n+The TLV container in the response is of the same type as in the request and it\n+contains the actual values of all the corresponding parameters supported by the\n+device. The values set by the device can differ from the requested values\n+depending on the device's capabilities. \\textbf{Note:} lengths of the\n+VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES and\n+VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT TLVs are always 8 in the device's\n+response in order to save memory and make eventq descriptor size more\n+predictable, i.e. they include only the \\field{resource_id} fields. Missing\n+TLV for a resource means that it is not attached.\n+\n+TLV containers in the request can be empty. In this case the command doesn't\n+set any parameters, still all the parameters are received in the response.\n+The driver can use an alias command type VIRTIO_VIDEO_CMD_STREAM_GET_PARAMS to\n+distinguish this case.\n+\n+The backing memory for resources can only be attached when there is no chance\n+for it to be simultaneously used by the device: when the resource is not\n+attached or haven't been queued after opening the stream, after a RESET\n+operation on the corresponding queue, after a DRAIN operation.\n+% TODO: to be clarified\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}\n+\n+The device MUST initialize each parameter to a valid default value.\n+\n+The device MUST allow each parameter to be read even without the driver\n+explicitly setting a value for them beforehand.\n+\n+The device MAY adjust any received parameter to a closest supported\n+value if the received one is not supported with the current settings.\n+\n+The parameters received and returned by the device MUST fit together into a\n+pair of linked sets returned in\n+\\field{struct virtio_video_device_query_caps_resp}.\n+\n+The parameters MUST be applied in the order of appearance in the TLV\n+container.\n+The device MUST return an error code as soon as it encounters an invalid not\n+correctable input and stop processing the TLVs afterwards.\n+All the received parameters MUST be validated before the command response is\n+sent.\n+\n+The device MUST process parameters changes, that are embedded in the input\n+stream, in the same way as if there is a VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS\n+command queued into inputqX changing the outputqX parameters. A standalone DPC\n+event MUST be sent in place of the command's delayed response in this case.\n+\n+The device MUST return all the available inputqX or outputqX parameters in the\n+delayed response.\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}\n+\n+\\field{stream_id} MUST be set to a valid stream ID of an open stream.\n+\n+VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS MUST be sent to mainq or inputqX or\n+outputqX where X equals \\field{stream_id}.\n+\n+The driver MUST put exactly one TLV container to the request with type\n+selected according to the queue type.\n+\n+The driver MUST check the actual values of the parameters as set by the\n+device and work with these values, or try to set different ones if it\n+cannot, or fail properly.\n+\n+After creating a new stream, the initial value of all parameters is\n+undefined to the driver. Thus, the driver MUST NOT assume the default\n+value of any parameter and MAY use VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS\n+in order to get the values of the parameters it needs.\n+\n+If some of the resources were detached as a result of this command the driver\n+SHOULD reattach the backing memories of these resources and queue them again\n+to resume the device operation.\n+\n+The same type of backing memories (either guest pages, or virtio objects)\n+MUST be used for all resources within a queue.\n+\n+\\paragraph{VIRTIO_VIDEO_CMD_STREAM_DRAIN}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_DRAIN}\n+\n+Complete processing of all input resources queued before this command\n+and make the resulting output resources available to the driver.\n+\n+The driver sends this command with\n+\\field{struct virtio_video_stream_drain}:\n+\n+\\begin{lstlisting}\n+struct virtio_video_stream_drain {\n+ le32 cmd_type; /* VIRTIO_VIDEO_CMD_STREAM_DRAIN */\n+};\n+\\end{lstlisting}\n+\n+The device responds as described in\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+and begins the background DRAIN operation.\n+\n+When the background DRAIN operation is completed the device sends the\n+VIRTIO_VIDEO_DELAYED_RESP_STREAM_DRAIN delayed response, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}.\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_DRAIN}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_DRAIN}\n+\n+Before the device sends the response, it MUST process and respond to all\n+the VIRTIO_VIDEO_CMD_RESOURCE_QUEUE commands on the inputqX that\n+were sent before the drain command, and make all the corresponding\n+output resources available to the driver with delayed responses to their\n+VIRTIO_VIDEO_CMD_RESOURCE_QUEUE commands.\n+\n+The device MUST be able to accept input work while a DRAIN operation\n+is ongoing, but any resulting delayed responses MUST NOT be sent before\n+the delayed response to the command, that started the DRAIN operation.\n+\n+If the command is interrupted with a RESET operation on inputqX or a CLOSE\n+operation, the device MUST send the delayed response with\n+VIRTIO_VIDEO_EVENT_FLAG_CANCELED flag set.\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_CMD_STREAM_DRAIN}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_DRAIN}\n+\n+VIRTIO_VIDEO_CMD_STREAM_DRAIN MUST be sent to inputqX where X is a valid\n+stream ID of an open stream.\n+\n+The driver MUST keep queueing output resources until it gets the\n+response to this command or cancels it using\n+VIRTIO_VIDEO_CMD_QUEUE_RESET or\n+VIRTIO_VIDEO_CMD_STREAM_CLOSE. Failure to do so may result in the\n+device stalling as it waits for output resources to write into.\n+\n+The driver MUST send a VIRTIO_VIDEO_CMD_STREAM_DRAIN command when it does not\n+have any further input to ensure it receives all the output.\n+\n+\\paragraph{VIRTIO_VIDEO_CMD_QUEUE_RESET}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_QUEUE_RESET}\n+\n+Immediately cancel all queued resources in inputqX or outputqX without\n+processing them and discard any processing results, that are not yet dequeued.\n+This command is useful for decoders that need to quickly jump to another point\n+in the stream (i.e. for seeking), or in order to clear the queue as quickly as\n+possible.\n+\n+The driver sends this command with\n+\\field{struct virtio_video_queue_reset}:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_VIDEO_QUEUE_TYPE_INPUT 0\n+#define VIRTIO_VIDEO_QUEUE_TYPE_OUTPUT 1\n+\n+struct virtio_video_queue_reset {\n+ le32 cmd_type; /* VIRTIO_VIDEO_CMD_QUEUE_RESET */\n+ le32 stream_id;\n+ le32 queue_type; /* VIRTIO_VIDEO_QUEUE_TYPE_* */\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{stream_id}]\n+ is the ID of the stream to reset.\n+\\item[\\field{queue_type}]\n+ is the direction of the queue to reset.\n+\\end{description}\n+\n+The device responds as described in\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+and begins the background RESET operation.\n+\n+When the background RESET operation is completed the device sends the\n+VIRTIO_VIDEO_DELAYED_RESP_QUEUE_RESET delayed response, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}.\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_CMD_QUEUE_RESET}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_QUEUE_RESET}\n+\n+The device MUST send delayed responses with VIRTIO_VIDEO_EVENT_FLAG_CANCELED\n+flag set for all active or pending commands in the selected queue before\n+sending the delayed response to this command.\n+\n+The device MUST interrupt operation as quickly as possible. Doing a RESET of\n+inputqX MUST NOT depend on output resources being queued by the driver.\n+\n+% If the device must accept more input after the beginning of the RESET\n+% like it was required in the previous versions of the specification, then\n+% some more measures are necessary because these are different queues now.\n+% For example, adding a \"generation\" field into the commands. At the moment\n+% this doesn't look like a problem.\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_CMD_QUEUE_RESET}{Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_QUEUE_RESET}\n+\n+\\field{stream_id} MUST be set to a valid stream ID of an open stream.\n+\n+VIRTIO_VIDEO_CMD_QUEUE_RESET MUST be sent to mainq.\n+\n+\\subsubsection{Device Operation: Resource Commands}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Resource Commands}\n+\n+This command queues an individual resource for the device to process.\n+\n+\\paragraph{VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Resource Commands / VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}\n+\n+Provide an input or output resource to the device for processing.\n+\n+\\begin{lstlisting}\n+#define VIRTIO_VIDEO_MAX_PLANES 8\n+\n+#define VIRTIO_VIDEO_ENQUEUE_FLAG_FORCE_KEY_FRAME (1 << 0)\n+\n+struct virtio_video_resource_queue {\n+ le32 cmd_type; /* VIRTIO_VIDEO_CMD_RESOURCE_QUEUE */\n+ le32 resource_id;\n+ le32 flags; /* Bitmask of VIRTIO_VIDEO_ENQUEUE_FLAG_* */\n+ u8 padding[4];\n+ le64 timestamp;\n+ le32 offsets[VIRTIO_VIDEO_MAX_PLANES];\n+ le32 data_sizes[VIRTIO_VIDEO_MAX_PLANES];\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{resource_id}]\n+ is the ID of the resource to be queued.\n+\\item[\\field{flags}]\n+ is a bitmask of VIRTIO_VIDEO_ENQUEUE_FLAG_* values.\n+\n+ \\begin{description}\n+ \\item[\\field{VIRTIO_VIDEO_ENQUEUE_FLAG_FORCE_KEY_FRAME}]\n+ The submitted frame is to be encoded as a key frame. Only valid for the\n+ encoder's inputqX.\n+ \\end{description}\n+\\item[\\field{timestamp}]\n+ is an abstract sequence counter that can be used on the inputqX for\n+ synchronization. Resources produced on the output queue will carry the\n+ \\field{timestamp} of the first input resource they have been produced\n+ from.\n+\\item[\\field{offsets}]\n+ is the starting offset for the data in the buffer for each plane.\n+ The number of planes depends on the format. Set by the driver for input\n+ resources.\n+\\item[\\field{data_sizes}]\n+ is number of data bytes used for each plane. Set by the driver for input\n+ resources.\n+\\end{description}\n+\n+The device responds as described in\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+and uses the resource in the video processing. When the processing of the\n+resource is completed the device sends the\n+VIRTIO_VIDEO_DELAYED_RESP_RESOURCE_QUEUE delayed response, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}.\n+\n+The command-specific delayed response\n+\\field{struct virtio_video_resource_queue_delayed_resp} is defined\n+as follows:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_VIDEO_DEQUEUE_FLAG_ERR (1 << 0)\n+/* Encoder only */\n+#define VIRTIO_VIDEO_DEQUEUE_FLAG_KEY_FRAME (1 << 1)\n+#define VIRTIO_VIDEO_DEQUEUE_FLAG_P_FRAME (1 << 2)\n+#define VIRTIO_VIDEO_DEQUEUE_FLAG_B_FRAME (1 << 3)\n+\n+struct virtio_video_resource_queue_delayed_resp {\n+ le32 flags;\n+ u8 padding[4];\n+ le64 timestamp;\n+ le32 offsets[VIRTIO_VIDEO_MAX_PLANES];\n+ le32 data_sizes[VIRTIO_VIDEO_MAX_PLANES];\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{flags}]\n+ is a bitmask of VIRTIO_VIDEO_DEQUEUE_FLAG_* flags.\n+\n+ \\begin{description}\n+ \\item[VIRTIO_VIDEO_DEQUEUE_FLAG_ERR]\n+ is set on resources when a non-fatal processing error has happened and\n+ the data contained by the resource is likely to be corrupted,\n+ \\item[VIRTIO_VIDEO_DEQUEUE_FLAG_KEY_FRAME]\n+ is set on output resources when the resource contains an encoded key\n+ frame (only for encoders).\n+ \\item[VIRTIO_VIDEO_DEQUEUE_FLAG_P_FRAME]\n+ is set on output resources when the resource contains only differences\n+ to a previous key frame (only for encoders).\n+ \\item[VIRTIO_VIDEO_DEQUEUE_FLAG_B_FRAME]\n+ is set on output resources when the resource contains only the\n+ differences between the current frame and both the preceding and\n+ following key frames (only for encoders).\n+ \\end{description}\n+\\item[\\field{timestamp}]\n+ is set on output resources to the \\field{timestamp} value of the first input\n+ resource that produced the resource.\n+\\item[\\field{offsets}]\n+ is set on output resources to the starting offset for the data in the\n+ buffer for each plane.\n+\\item[\\field{data_sizes}]\n+ is set on output resources to the amount of data written by the device,\n+ for each plane.\n+\\end{description}\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}{Device Types / Video Device / Device Operation / Device Operation: Resource Commands / VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}\n+\n+The device MUST return VIRTIO_VIDEO_RESULT_ERR_INVALID_OPERATION if\n+the resource has not been attached prior to queueing it or for an\n+attempt to queue a resources that is still processed in background.\n+\n+The device MUST mark resources that might contain corrupted content due to\n+an error with the VIRTIO_VIDEO_BUFFER_FLAG_ERR flag.\n+\n+For output resources, the device MUST copy the \\field{timestamp}\n+parameter of the first input resource that produced it into the delayed\n+response.\n+When many output resources are produced from a single input resource, the\n+device MUST copy the timestamp of the input resource to all of the output\n+resources.\n+\n+In case of encoder, the device MUST mark each output resource with one of\n+VIRTIO_VIDEO_DEQUEUE_FLAG_KEY_FRAME, VIRTIO_VIDEO_DEQUEUE_FLAG_P_FRAME, or\n+VIRTIO_VIDEO_DEQUEUE_FLAG_B_FRAME.\n+\n+If the processing of a resource was stopped due to a stream event, a\n+VIRTIO_VIDEO_CMD_QUEUE_RESET, or a VIRTIO_VIDEO_CMD_STREAM_CLOSE,\n+the device MUST send the corresponding delayed responses with\n+VIRTIO_VIDEO_EVENT_FLAG_CANCELED flag set.\n+\n+When starting or resuming processing after a RESET or a DRAIN operation, the\n+device MAY skip input data until it finds a point that allows it to resume\n+operation properly (e.g. until a keyframe is found in the input stream of a\n+decoder).\n+\n+The device MUST properly handle the case when a dequeued but still referenced\n+resource is queued again.\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}{Device Types / Video Device / Device Operation / Device Operation: Resource Commands / VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}\n+\n+VIRTIO_VIDEO_CMD_RESOURCE_QUEUE MUST be sent to inputqX or outputqX where X\n+is a valid stream ID of an open stream.\n+\n+\\field{resource_id} MUST be an ID of a resource, that is both allocated and\n+attached for the queue.\n+\n+The driver MUST be able to handle the output resources in decoding order in\n+encoder case, i.e. with timestamps out of order.\n+\n+\\subsubsection{Device Operation: Standalone Events}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Standalone Events}\n+\n+These events are caused by state changes in the device, not as a delayed\n+response to any command.\n+\n+\\paragraph{Error Event}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Standalone Events / Error Event}\n+\n+The error event is sent by the device when an unrecoverable error occurs\n+during processing a stream. The device operation is exactly the same as when\n+it receives a VIRTIO_VIDEO_CMD_STREAM_CLOSE command, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_CLOSE}.\n+Note that this is different from dequeued resources carrying the\n+VIRTIO_VIDEO_DEQUEUE_FLAG_ERR flag. This flag indicates that the\n+particular output frame might be corrupted, but the stream still exists\n+and can recover.\n+\n+\\paragraph{Dynamic Parameters Change Event}\n+\\label{sec:Device Types / Video Device / Device Operation / Device Operation: Standalone Events / Dynamic Parameters Change Event}\n+\n+A Dynamic Parameters Change (or DPC) event is sent by a decoder device when it\n+detects that the parameters of the stream being decoded have changed.\n+The device operation is exactly the same as if it receives a\n+VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS command in the inputqX at the exact same\n+point in the stream, that changes outputqX parameters, see\n+\\ref{sec:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}.\n+\n+% TODO add QoS events and overall think about quotas. Codecs are normally\n+% limited by bandwidth/macroblocks per second. How can we accommodate this?\n+\n+\\subsection{Device capabilities and parameters}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters}\n+\n+\\subsubsection{VIRTIO_VIDEO_TLV_CODED_SET}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET}\n+\n+These parameters are defined for the coded parameter sets.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_CODED_FORMAT}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_CODED_FORMAT}\n+\n+The following coded formats are defined:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_VIDEO_CODED_FORMAT_MPEG2 1 /* MPEG-2 Part 2 (V4L2_PIX_FMT_MPEG2) */\n+#define VIRTIO_VIDEO_CODED_FORMAT_MPEG4 2 /* MPEG-4 Part 2 (V4L2_PIX_FMT_MPEG4) */\n+#define VIRTIO_VIDEO_CODED_FORMAT_H264 3 /* H.264 (V4L2_PIX_FMT_H264) */\n+#define VIRTIO_VIDEO_CODED_FORMAT_HEVC 4 /* HEVC aka H.265 (V4L2_PIX_FMT_HEVC) */\n+#define VIRTIO_VIDEO_CODED_FORMAT_VP8 5 /* VP8 (V4L2_PIX_FMT_VP8) */\n+#define VIRTIO_VIDEO_CODED_FORMAT_VP9 6 /* VP9 (V4L2_PIX_FMT_VP9) */\n+#define VIRTIO_VIDEO_CODED_FORMAT_FWHT 7 /* FWHT (V4L2_PIX_FMT_FWHT) */\n+\\end{lstlisting}\n+\n+The coded formats and the expected data units per buffer are documented in\n+\\hyperref[intro:V4L2]{V4L2 header} and\n+\\hyperref[intro:V4L2 compressed]{V4L2 compressed formats documentation}.\n+\n+\\field{struct virtio_video_tlv_coded_format} represents both the coded format\n+in a coded set of capabilities and the specific parameter values:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_coded_format {\n+ le32 format; /* VIRTIO_VIDEO_CODED_FORMAT_* */\n+};\n+\\end{lstlisting}\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_CODED_RESOURCES}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_CODED_RESOURCES}\n+\n+Setup common coded resources parameters.\n+\n+\\field{struct virtio_video_tlv_coded_resources_caps} represents capabilities:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_coded_resources_caps {\n+ struct virtio_video_range num_resources_range;\n+ struct virtio_video_range resource_size_range;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{num_resources_range}]\n+ is the supported range of resources number of a particular coded set.\n+\\item[\\field{resource_size_range}]\n+ is the supported range of resource sizes.\n+\\end{description}\n+\n+\\field{struct virtio_video_tlv_resources_val} represents the parameter values:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_resources_val {\n+ le32 num_resources;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{num_resources}]\n+ is the number of resources that can be addressed for the queue, numbered\n+ from \\(0\\) to \\(num\\_resources - 1\\). Setting this parameter to zero is\n+ allowed even when \\field{num_resources_range.min} is positive, this results\n+ in detaching all the resources.\n+\\end{description}\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}\n+\n+This TLV is defined in the same way as for the VIRTIO_VIDEO_TLV_RAW_SET, see\n+\\ref{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}.\n+Note, that a coded resource can only have a single buffer, so only the first\n+element of \\field{num_entries} is not zero.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}\n+\n+This TLV is defined in the same way as for the VIRTIO_VIDEO_TLV_RAW_SET, see\n+\\ref{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}.\n+Note, that a coded resource can only have a single buffer, so\n+\\field{num_objects} is always 1.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_V4L2_CONTROLS}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS}\n+\n+Inside this TLV container only selected V4L2 control IDs are allowed to be\n+used as TLV types. The subset is listed in subsections below. Values of the\n+V4L2 controls can be converted to TLVs by taking their representation as\n+\\hyperref[intro:V4L2 ext ctrls]{struct v4l2_ext_control} and replacing the\n+pointers with values. Capabilities of the V4L2 controls can't be converted to\n+TLVs as easily, so they are described below. This is mostly useful for\n+encoders. Most relevant V4L2 controls are codec-specific. All definitions\n+related to V4L2 controls can be found in\n+\\hyperref[intro:V4L2 controls]{V4L2 controls header}, their descriptions\n+can be found in \\hyperref[intro:V4L2 codec controls]{V4L2 documentation}.\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_TLV_V4L2_CONTROLS}{Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS}\n+\n+The device MUST NOT advertise codec-specific parameters not corresponding to\n+the coded format of the particular coded set.\n+\n+\\subparagraph{V4L2 controls: 32 bit integers}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS / V4L2 controls: Enumerations}\n+\n+Integer V4L2 controls are signed by default, but this specification doesn't\n+define any signed integer types, see \\ref{sec:Structure Specifications}, so\n+not every integer V4L2 control could be used directly. Still for many of them\n+negative values don't make sense, so these controls are allowed in the range\n+from 0 to INT32_MAX:\n+\n+\\begin{itemize}\n+\\item V4L2_CID_MPEG_VIDEO_BITRATE: bitrate in bits per second\n+\\end{itemize}\n+\n+For capabilities the TLV value is defined as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_v4l2_int_caps {\n+ struct virtio_video_range range;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{range}]\n+ is a range of possible values of the control.\n+\\end{description}\n+\n+For the control values the TLV value is defined as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_v4l2_int_val {\n+ le32 value;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{value}]\n+ is one of the supported control values.\n+\\end{description}\n+\n+\\drivernormative{\\subparagraph}{V4L2 controls: 32 bit integers}{Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS / V4L2 controls: 32 bit integers}\n+\n+The integer V4L2 control values MUST be in the range from 0 to INT32_MAX.\n+\n+\\subparagraph{V4L2 controls: Enumerations}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS / V4L2 controls: Enumerations}\n+\n+The following V4L2 controls with values defined as enums are allowed:\n+\\begin{itemize}\n+\\item V4L2_CID_MPEG_VIDEO_MPEG2_PROFILE\n+% enum v4l2_mpeg_video_mpeg2_profile: V4L2_MPEG_VIDEO_MPEG2_PROFILE_*\n+\\item V4L2_CID_MPEG_VIDEO_MPEG2_LEVEL\n+% enum v4l2_mpeg_video_mpeg2_level: V4L2_MPEG_VIDEO_MPEG2_LEVEL_*\n+\\item V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE\n+% enum v4l2_mpeg_video_mpeg4_profile: V4L2_MPEG_VIDEO_MPEG4_PROFILE_*\n+\\item V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL\n+% enum v4l2_mpeg_video_mpeg4_level: V4L2_MPEG_VIDEO_MPEG4_LEVEL_*\n+\\item V4L2_CID_MPEG_VIDEO_H264_PROFILE\n+% enum v4l2_mpeg_video_h264_profile: V4L2_MPEG_VIDEO_H264_PROFILE_*\n+\\item V4L2_CID_MPEG_VIDEO_H264_LEVEL\n+% enum v4l2_mpeg_video_h264_level: V4L2_MPEG_VIDEO_H264_LEVEL_*\n+\\item V4L2_CID_MPEG_VIDEO_HEVC_PROFILE\n+% enum v4l2_mpeg_video_hevc_profile: V4L2_MPEG_VIDEO_HEVC_PROFILE_*\n+\\item V4L2_CID_MPEG_VIDEO_HEVC_LEVEL\n+% enum v4l2_mpeg_video_hevc_level: V4L2_MPEG_VIDEO_HEVC_LEVEL_*\n+\\item V4L2_CID_MPEG_VIDEO_VP8_PROFILE\n+% enum v4l2_mpeg_video_vp8_profile: V4L2_MPEG_VIDEO_VP8_PROFILE_*\n+\\item V4L2_CID_MPEG_VIDEO_VP9_PROFILE\n+% enum v4l2_mpeg_video_vp9_profile: V4L2_MPEG_VIDEO_VP9_PROFILE_*\n+\\item V4L2_CID_MPEG_VIDEO_VP9_LEVEL\n+% enum v4l2_mpeg_video_vp9_level: V4L2_MPEG_VIDEO_VP9_LEVEL_*\n+\\end{itemize}\n+\n+For capabilities the TLV value is defined as follows:\n+\n+\\begin{lstlisting}\n+#define MASK(x) (1 << (x))\n+\n+struct virtio_video_tlv_v4l2_enum_caps {\n+ le32 bitmask; /* Bitmask of MASK(<enum value>) */\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{bitmask}]\n+ is a bitmask of supported enum values used as bit numbers, see\n+ \\hyperref[intro:V4L2 controls]{V4L2 controls header}.\n+\\end{description}\n+\n+For the control values the TLV value is defined as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_v4l2_enum_val {\n+ u8 value; /* <enum value> */\n+ u8 padding[3];\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{value}]\n+ is one of the supported enum values, see\n+ \\hyperref[intro:V4L2 controls]{V4L2 controls header}.\n+\\end{description}\n+\n+\\subsubsection{VIRTIO_VIDEO_TLV_RAW_SET}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET}\n+\n+These parameters are defined for the raw parameter sets.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_RAW_FORMAT}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RAW_FORMAT}\n+\n+DRM fourcc format definitions and DRM format modifiers are used to represent\n+raw formats capabilities and values. The layouts of raw formats are documented\n+in \\hyperref[intro:DRM formats]{DRM} and \\hyperref[intro:V4L2]{V4L2} headers,\n+as well as in \\hyperref[intro:V4L2 RGB]{V4L2 RGB} and\n+\\hyperref[intro:V4L2 YUV]{planar YUV} formats documentation.\n+\n+% Some DRM and V4L2 formats can be matched with this table:\n+% DRM_FORMAT_ARGB8888 = V4L2_PIX_FMT_ABGR32\n+% DRM_FORMAT_BGRA8888 = V4L2_PIX_FMT_ARGB32\n+% DRM_FORMAT_RGBA8888 = V4L2_PIX_FMT_BGRA32\n+% DRM_FORMAT_NV12 = V4L2_PIX_FMT_NV12\n+% DRM_FORMAT_YUV420 = V4L2_PIX_FMT_YUV420\n+% DRM_FORMAT_YVU420 = V4L2_PIX_FMT_YVU420\n+% DRM_FORMAT_YUYV = V4L2_PIX_FMT_YUYV\n+\n+\\field{struct virtio_video_tlv_raw_format_caps} is used to describe the\n+capabilities:\n+\n+\\begin{lstlisting}\n+enum virtio_video_planes_layout {\n+ VIRTIO_VIDEO_PLANES_LAYOUT_SINGLE_BUFFER = 1,\n+ VIRTIO_VIDEO_PLANES_LAYOUT_MULTI_BUFFERS = 2,\n+};\n+\n+struct virtio_video_tlv_raw_format_caps {\n+ le32 planes_layout_mask; /* Bitmask of VIRTIO_VIDEO_PLANES_LAYOUT_* */\n+ le32 fourcc; /* DRM_FORMAT_* */\n+ le64 modifier; /* DRM_FORMAT_MOD_* */\n+ struct virtio_video_range width_range;\n+ struct virtio_video_range height_range;\n+ le32 stride_align_mask;\n+ le32 height_align_mask;\n+ le32 plane_align_mask;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{planes_layout_mask}]\n+ is a bitmask of supported planes layout types according to\n+ \\field{enum virtio_video_planes_layout}.\n+\\item[\\field{fourcc}]\n+ specifies the raw format, to which these capabilities apply.\n+\\item[\\field{modifier}]\n+ specifies the raw format modifier.\n+\\item[\\field{width_range}]\n+ is a range of widths in pixels.\n+\\item[\\field{height_range}]\n+ is a range of heights in pixels.\n+\\item[\\field{stride_align_mask}]\n+ is a bitmask of all supported power of two alignments of the distance in\n+ bytes between two lines of data (stride).\n+\\item[\\field{height_align_mask}]\n+ is a bitmask of all supported power of two height alignments in pixels.\n+\\item[\\field{plane_align_mask}]\n+ is a bitmask of all supported power of two alignments in bytes of planes\n+ within a buffer. This field is valid only if \\field{planes_layout_mask} has\n+ the \\field{VIRTIO_VIDEO_PLANES_LAYOUT_SINGLE_BUFFER} bit set.\n+\\end{description}\n+\n+\\field{struct virtio_video_tlv_raw_format_val} is used to describe the\n+values:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_raw_format_val {\n+ le32 planes_layout; /* VIRTIO_VIDEO_PLANES_LAYOUT_* */\n+ le32 fourcc; /* DRM_FORMAT_* */\n+ le64 modifier; /* DRM_FORMAT_MOD_* */\n+ le32 width;\n+ le32 height;\n+ le32 stride_align;\n+ le32 height_align;\n+ le32 plane_align;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{planes_layout}]\n+ is the actual layout of the planes.\n+\\item[\\field{fourcc}]\n+ specifies the raw format.\n+\\item[\\field{modifier}]\n+ specifies the raw format modifier.\n+\\item[\\field{width}]\n+ is the width in pixels of the stream frames.\n+\\item[\\field{height}]\n+ is the height in pixels of the stream frames.\n+\\item[\\field{stride_align}]\n+ is the power of two stride alignment in bytes.\n+\\item[\\field{height_align}]\n+ is the power of two height alignment in pixels.\n+\\item[\\field{plane_align}]\n+ is the power of two alignment in bytes of planes within a buffer. This field\n+ is valid only if \\field{planes_layout} has the\n+ \\field{VIRTIO_VIDEO_PLANES_LAYOUT_SINGLE_BUFFER} bit set.\n+\\end{description}\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_TLV_RAW_FORMAT}{Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RAW_FORMAT}\n+\n+The device MUST set \\field{VIRTIO_VIDEO_PLANES_LAYOUT_SINGLE_BUFFER} bit in\n+\\field{planes_layout_mask} if the plane layout with planes of a frame laid out\n+one after another in the same buffer is supported.\n+\n+The device MUST set \\field{VIRTIO_VIDEO_PLANES_LAYOUT_MULTI_BUFFERS} bit in\n+\\field{planes_layout_mask} if the plane layout with planes of a frame laid out\n+in separate buffers is supported.\n+\n+% TODO: not sure if !VIRTIO_VIDEO_F_RESOURCE_NON_CONTIG should be compatible\n+% with VIRTIO_VIDEO_PLANES_LAYOUT_MULTI_BUFFERS or not.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_RAW_RESOURCES}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RAW_RESOURCES}\n+\n+\\field{struct virtio_video_tlv_raw_resources_caps} represents capabilities:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_raw_resources_caps {\n+ struct virtio_video_range num_resources_range;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{num_resources_range}]\n+ is the supported range of resources number of a particular raw set.\n+\\end{description}\n+\n+\\field{struct virtio_video_tlv_resources_val} represents the parameter values,\n+see\n+\\ref{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_CODED_RESOURCES}.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}\n+\n+Setup guest pages as backing memory of a resource.\n+\n+The parameter capabilities are empty. The empty TLV with zero length indicates\n+the support for attaching guest pages to resources.\n+\n+\\field{struct virtio_video_tlv_resource_guest_pages} represents the parameter\n+values:\n+\n+\\begin{lstlisting}\n+struct virtio_video_resource_sg_entry {\n+ le64 addr;\n+ le32 length;\n+ u8 padding[4];\n+};\n+\n+struct virtio_video_tlv_resource_guest_pages {\n+ le32 resource_id;\n+ u8 padding[4];\n+ le32 num_entries[VIRTIO_VIDEO_MAX_PLANES];\n+ struct virtio_video_resource_sg_entry entries[];\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{resource_id}]\n+ is the ID of the resource.\n+\\item[\\field{num_entries}]\n+ is the number of scatter-gather list entries in each of the separate buffers\n+ forming together the resource according to currently set format. Unused\n+ array elements are set to 0. Sum of the array is the length of the\n+ \\field{entries} array.\n+\\item[\\field{entries}]\n+ is an array of the scatter-gather list entries:\n+\n+ \\begin{description}\n+ \\item[\\field{addr}]\n+ is a guest physical address of the start of the SG entry aligned to\n+ the physical guest pages size.\n+ \\item[\\field{length}]\n+ is the length of the SG entry in bytes aligned to the physical guest\n+ pages size.\n+ \\end{description}\n+\\end{description}\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}{Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}\n+\n+\\field{resource_id} MUST be an integer within the range of resource IDs\n+currently allocated for the queue.\n+\n+The memory regions identified by the elements of the \\field{entries} array\n+MUST NOT overlap.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}\n+\n+Setup virtio objects as backing memory to a resource.\n+\n+The parameter capabilities are empty. The empty TLV with zero length indicates\n+the support for attaching virtio objects to resources.\n+\n+\\field{struct virtio_video_tlv_resource_virtio_object} represents the parameter\n+values:\n+\n+\\begin{lstlisting}\n+struct virtio_video_resource_object {\n+ u8 uuid[16];\n+};\n+\n+struct virtio_video_tlv_resource_virtio_object {\n+ le32 resource_id;\n+ le32 num_objects; /* Up to VIRTIO_VIDEO_MAX_PLANES */\n+ struct virtio_video_resource_object objects[num_objects];\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{resource_id}]\n+ is the ID of the resource.\n+\\item[\\field{num_objects}]\n+ is the length of the \\field{objects} array according to currently set\n+ format.\n+\\item[\\field{object}]\n+ is an array of objects exported from another virtio device, see\n+ \\ref{sec:Basic Facilities of a Virtio Device / Exporting Objects}.\n+\n+ \\begin{description}\n+ \\item[uuid]\n+ is a version 4 UUID specified by \\hyperref[intro:rfc4122]{[RFC4122]}.\n+ \\end{description}\n+\\end{description}\n+\n+\\drivernormative{\\subparagraph}{VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}{Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}\n+\n+\\field{resource_id} MUST be an integer within the range of resource IDs\n+currently allocated for the queue.\n+\n+\\paragraph{VIRTIO_VIDEO_TLV_CROP}\n+\\label{sec:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_CROP}\n+\n+% TODO There is no reason in doing crop if it doesn't affect the output.\n+% So the output frames have to be smaller, than the full size. In the decoder\n+% case this means, that the buffers can't be used as a reference. So when crop\n+% is enabled, the decoder probably has to have some intermediate buffers.\n+% Is it reasonable to reallocate output buffers then? It could be. So it has\n+% to be decided (probably in the same way it is usually done in V4L2). In the\n+% encoder case this is not a problem.\n+% Is setting compose rectangles useful at all?\n+\n+This parameter sets a rectangle covering the visible area of the frame.\n+\n+The parameter capabilities are empty. The empty TLV with zero length indicates\n+the support for cropping.\n+\n+The parameter value is defined as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_video_tlv_crop_val {\n+ le32 left;\n+ le32 top;\n+ le32 width;\n+ le32 height;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{left, top}]\n+ are coordinates of top left corner of the crop rectangle in pixels.\n+\\item[\\field{width, height}]\n+ are dimensions of the crop rectangle in pixels.\n+\\end{description}\n+\n+\\devicenormative{\\subparagraph}{VIRTIO_VIDEO_TLV_CROP}{Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_CROP}\n+\n+The crop rectangle MUST be reset to full frame size on every resolution\n+change.\ndiff --git a/device-types/video/device-conformance.tex b/device-types/video/device-conformance.tex\nnew file mode 100644\nindex 0000000..d13486f\n--- /dev/null\n+++ b/device-types/video/device-conformance.tex\n@@ -0,0 +1,22 @@\n+\\conformance{\\subsection}{Video Device Conformance}\n+\\label{sec:Conformance / Device Conformance / Video Device Conformance}\n+\n+A video device MUST conform to the following normative statements:\n+\n+\\begin{itemize}\n+\\item \\ref{devicenormative:Device Types / Video Device / Feature bits}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device configuration layout}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: TLV format}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_OPEN}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_CLOSE}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_DRAIN}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_QUEUE_RESET}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device Operation / Device Operation: Resource Commands / VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RAW_FORMAT}\n+\\item \\ref{devicenormative:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_CROP}\n+\\end{itemize}\ndiff --git a/device-types/video/driver-conformance.tex b/device-types/video/driver-conformance.tex\nnew file mode 100644\nindex 0000000..4576e41\n--- /dev/null\n+++ b/device-types/video/driver-conformance.tex\n@@ -0,0 +1,20 @@\n+\\conformance{\\subsection}{Video Driver Conformance}\n+\\label{sec:Conformance / Driver Conformance / Video Driver Conformance}\n+\n+A video driver MUST conform to the following normative statements:\n+\n+\\begin{itemize}\n+\\item \\ref{drivernormative:Device Types / Video Device / Feature bits}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Command Virtqueues}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Event Virtqueue}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Device Commands / VIRTIO_VIDEO_CMD_DEVICE_QUERY_CAPS}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_OPEN}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_CLOSE}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_SET_PARAMS}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_STREAM_DRAIN}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Stream commands / VIRTIO_VIDEO_CMD_QUEUE_RESET}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device Operation / Device Operation: Resource Commands / VIRTIO_VIDEO_CMD_RESOURCE_QUEUE}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_CODED_SET / VIRTIO_VIDEO_TLV_V4L2_CONTROLS / V4L2 controls: 32 bit integers}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_GUEST_PAGES}\n+\\item \\ref{drivernormative:Device Types / Video Device / Device capabilities and parameters / VIRTIO_VIDEO_TLV_RAW_SET / VIRTIO_VIDEO_TLV_RESOURCE_VIRTIO_OBJECT}\n+\\end{itemize}\ndiff --git a/introduction.tex b/introduction.tex\nindex cfa6633..41a7476 100644\n--- a/introduction.tex\n+++ b/introduction.tex\n@@ -101,6 +101,15 @@ \\section{Normative References}\\label{sec:Normative References}\n \t\\phantomsection\\label{intro:SEC1}\\textbf{[SEC1]} &\n Standards for Efficient Cryptography Group(SECG), ``SEC1: Elliptic Cureve Cryptography'', Version 1.0, September 2000.\n \t\\newline\\url{https://www.secg.org/sec1-v2.pdf}\\\\\n+\t\\phantomsection\\label{intro:V4L2}\\textbf{[V4L2]} &\n+\tLinux V4L2 interface.\n+\t\\newline\\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/videodev2.h}\\\\\n+\t\\phantomsection\\label{intro:V4L2 controls}\\textbf{[V4L2 Controls]} &\n+\tLinux V4L2 controls definitions.\n+\t\\newline\\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/v4l2-controls.h}\\\\\n+\t\\phantomsection\\label{intro:DRM formats}\\textbf{[DRM Formats]} &\n+\tLinux DRM format definitions.\n+\t\\newline\\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_fourcc.h}\\\\\n \n \t\\phantomsection\\label{intro:rfc2784}\\textbf{[RFC2784]} &\n Generic Routing Encapsulation. This protocol is only specified for IPv4 and used as either the payload or delivery protocol.\n@@ -153,6 +162,18 @@ \\section{Non-Normative References}\n \t\\phantomsection\\label{intro:Virtio PCI Draft}\\textbf{[Virtio PCI Draft]} &\n \tVirtio PCI Draft Specification\n \t\\newline\\url{http://ozlabs.org/~rusty/virtio-spec/virtio-0.9.5.pdf}\\\\\n+\t\\phantomsection\\label{intro:V4L2 compressed}\\textbf{[V4L2 compressed formats]} &\n+\tDetailed descriptions of V4L2 compressed formats\n+\t\\newline\\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst}\\\\\n+\t\\phantomsection\\label{intro:V4L2 RGB}\\textbf{[V4L2 RGB formats]} &\n+\tDetailed descriptions of V4L2 RGB formats\n+\t\\newline\\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst}\\\\\n+\t\\phantomsection\\label{intro:V4L2 YUV}\\textbf{[V4L2 planar YUV formats]} &\n+\tDetailed descriptions of V4L2 planar YUV formats\n+\t\\newline\\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst}\\\\\n+\t\\phantomsection\\label{intro:V4L2 codec controls}\\textbf{[V4L2 codec controls]} &\n+\tDetailed descriptions of V4L2 controls\n+\t\\newline\\url{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst}\\\\\n \\end{longtable}\n \n \\section{Terminology}\\label{Terminology}\n", "prefixes": [ "RFC", "v9", "1/1" ] }