Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-11.8 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING,SIGNED_OFF_BY,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9535CC43381 for ; Fri, 22 Mar 2019 08:25:57 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 375EB21873 for ; Fri, 22 Mar 2019 08:25:57 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="b0qESuF/" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727724AbfCVIZ4 (ORCPT ); Fri, 22 Mar 2019 04:25:56 -0400 Received: from mail-lf1-f67.google.com ([209.85.167.67]:40209 "EHLO mail-lf1-f67.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726667AbfCVIZ4 (ORCPT ); Fri, 22 Mar 2019 04:25:56 -0400 Received: by mail-lf1-f67.google.com with SMTP id u68so779565lff.7 for ; Fri, 22 Mar 2019 01:25:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to:content-transfer-encoding:content-language; bh=8XcWU5yS5T9mw3e0kKPJ8aDLJ3yCQTA4UZe4qF3gZ/E=; b=b0qESuF/BD+/WPC8FzqeGGCwOwvCyAxHU+2SUxcN9HBfBvBB31l0FOFLlRrM4OYwtQ gjj0GmTQk2bvMgjBSon+jJYTS0gS1dnxTuCfTpAO7ECGJxZokwDZyEalx6rdfZ584DYR Nrcl25FrOXKftegl9POe1mAPCmkned/HYw51nQM+6LL6F/ZVbGGiLD/GoXp5Tk0Kkfdr /u783EzgHq08Y/mQ8v9wopFLtW5jaIu0KMqzQUYSfRfXi4JU2GKTKvTaSAZbVPgpetVU ExBQlwOXobREf4bFv1JQ9etsAJqUcLOQ/Nye/b2y1tZyEdWtISPSJ2zwfn/W/cN7HRfm EpVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-transfer-encoding :content-language; bh=8XcWU5yS5T9mw3e0kKPJ8aDLJ3yCQTA4UZe4qF3gZ/E=; b=Zo7BIz98kPrPP7tTyRcv8I6TFAlMf/kpIrCvxMjpjb7Xu1GZYkcZ2hT+ahtNF24KzM x1Nt7tAwGztGUWxgMbAW0095yBWbG1r7OCzXe2J/s5AWzFgLqqkUGnH/CpSgOG3zs18D Edw2w9BEV2PnKJHtrA0hB3io6cP/mL4dnE852EeqgKlRlGbL7+9DP26O1l2EgC8wMphQ zETu1Idj09FTmDOFCSSCC5G6gQseb6DYKJ91YbexTKgSIzYQNDO9aEDGkC1jKj438YrO 877133loJPV3bVcK2hvPwhCowLUKllNdevg2qDOCOpLgAaWk2ZTvX3uxGP85gZaYWdRl q5hg== X-Gm-Message-State: APjAAAU//QyfmApOm0nROVKcoD4MQgYTLgOX+GYCav+dYbtnmT/uDO9A HxJqU3iUfgbE0GQab+X3cfA= X-Google-Smtp-Source: APXvYqyA8mkwyskenAtxcbJ+NOjpPB2d0G3crrzcnmiyDLwu6UEEdYz8vmynffnGdL1Z/XgofhZEWg== X-Received: by 2002:a19:f81a:: with SMTP id a26mr4420292lff.34.1553243149869; Fri, 22 Mar 2019 01:25:49 -0700 (PDT) Received: from [10.17.182.20] (ll-74.141.223.85.sovam.net.ua. [85.223.141.74]) by smtp.gmail.com with ESMTPSA id 2sm1400881ljh.41.2019.03.22.01.25.48 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 22 Mar 2019 01:25:49 -0700 (PDT) Subject: Re: [Xen-devel][PATCH v6 1/1] cameraif: add ABI for para-virtual camera To: Hans Verkuil , "Oleksandr_Andrushchenko@epam.com" , xen-devel@lists.xenproject.org, konrad.wilk@oracle.com, jgross@suse.com, boris.ostrovsky@oracle.com, mchehab@kernel.org, linux-media@vger.kernel.org, sakari.ailus@linux.intel.com, koji.matsuoka.xm@renesas.com References: <20190322073742.14639-1-andr2000@gmail.com> <20190322073742.14639-2-andr2000@gmail.com> From: Oleksandr Andrushchenko Message-ID: Date: Fri, 22 Mar 2019 10:25:47 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.5.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Content-Language: en-US Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org On 3/22/19 10:22 AM, Hans Verkuil wrote: > On 3/22/19 8:37 AM, Oleksandr Andrushchenko wrote: >> From: Oleksandr Andrushchenko >> >> This is the ABI for the two halves of a para-virtualized >> camera driver which extends Xen's reach multimedia capabilities even >> farther enabling it for video conferencing, In-Vehicle Infotainment, >> high definition maps etc. >> >> The initial goal is to support most needed functionality with the >> final idea to make it possible to extend the protocol if need be: >> >> 1. Provide means for base virtual device configuration: >> - pixel formats >> - resolutions >> - frame rates >> 2. Support basic camera controls: >> - contrast >> - brightness >> - hue >> - saturation >> 3. Support streaming control >> >> Signed-off-by: Oleksandr Andrushchenko > Looks good! > > Reviewed-by: Hans Verkuil > > Thank you for all your work on this. This was possible with your great help and support! I do appreciate this very much! Thank you > > Regards, > > Hans > >> --- >> xen/include/public/io/cameraif.h | 1374 ++++++++++++++++++++++++++++++ >> 1 file changed, 1374 insertions(+) >> create mode 100644 xen/include/public/io/cameraif.h >> >> diff --git a/xen/include/public/io/cameraif.h b/xen/include/public/io/cameraif.h >> new file mode 100644 >> index 000000000000..acbcbf3bd411 >> --- /dev/null >> +++ b/xen/include/public/io/cameraif.h >> @@ -0,0 +1,1374 @@ >> +/****************************************************************************** >> + * cameraif.h >> + * >> + * Unified camera device I/O interface for Xen guest OSes. >> + * >> + * Permission is hereby granted, free of charge, to any person obtaining a copy >> + * of this software and associated documentation files (the "Software"), to >> + * deal in the Software without restriction, including without limitation the >> + * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or >> + * sell copies of the Software, and to permit persons to whom the Software is >> + * furnished to do so, subject to the following conditions: >> + * >> + * The above copyright notice and this permission notice shall be included in >> + * all copies or substantial portions of the Software. >> + * >> + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR >> + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, >> + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE >> + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER >> + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING >> + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER >> + * DEALINGS IN THE SOFTWARE. >> + * >> + * Copyright (C) 2018-2019 EPAM Systems Inc. >> + * >> + * Author: Oleksandr Andrushchenko >> + */ >> + >> +#ifndef __XEN_PUBLIC_IO_CAMERAIF_H__ >> +#define __XEN_PUBLIC_IO_CAMERAIF_H__ >> + >> +#include "ring.h" >> +#include "../grant_table.h" >> + >> +/* >> + ****************************************************************************** >> + * Protocol version >> + ****************************************************************************** >> + */ >> +#define XENCAMERA_PROTOCOL_VERSION "1" >> + >> +/* >> + ****************************************************************************** >> + * Feature and Parameter Negotiation >> + ****************************************************************************** >> + * >> + * Front->back notifications: when enqueuing a new request, sending a >> + * notification can be made conditional on xencamera_req (i.e., the generic >> + * hold-off mechanism provided by the ring macros). Backends must set >> + * xencamera_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()). >> + * >> + * Back->front notifications: when enqueuing a new response, sending a >> + * notification can be made conditional on xencamera_resp (i.e., the generic >> + * hold-off mechanism provided by the ring macros). Frontends must set >> + * xencamera_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()). >> + * >> + * The two halves of a para-virtual camera driver utilize nodes within >> + * XenStore to communicate capabilities and to negotiate operating parameters. >> + * This section enumerates these nodes which reside in the respective front and >> + * backend portions of XenStore, following the XenBus convention. >> + * >> + * All data in XenStore is stored as strings. Nodes specifying numeric >> + * values are encoded in decimal. Integer value ranges listed below are >> + * expressed as fixed sized integer types capable of storing the conversion >> + * of a properly formatted node string, without loss of information. >> + * >> + ****************************************************************************** >> + * Example configuration >> + ****************************************************************************** >> + * >> + * This is an example of backend and frontend configuration: >> + * >> + *--------------------------------- Backend ----------------------------------- >> + * >> + * /local/domain/0/backend/vcamera/1/0/frontend-id = "1" >> + * /local/domain/0/backend/vcamera/1/0/frontend = "/local/domain/1/device/vcamera/0" >> + * /local/domain/0/backend/vcamera/1/0/state = "4" >> + * /local/domain/0/backend/vcamera/1/0/versions = "1,2" >> + * >> + *--------------------------------- Frontend ---------------------------------- >> + * >> + * /local/domain/1/device/vcamera/0/backend-id = "0" >> + * /local/domain/1/device/vcamera/0/backend = "/local/domain/0/backend/vcamera/1" >> + * /local/domain/1/device/vcamera/0/state = "4" >> + * /local/domain/1/device/vcamera/0/version = "1" >> + * /local/domain/1/device/vcamera/0/be-alloc = "1" >> + * >> + *---------------------------- Device 0 configuration ------------------------- >> + * >> + * /local/domain/1/device/vcamera/0/max-buffers = "3" >> + * /local/domain/1/device/vcamera/0/controls = "contrast,hue" >> + * /local/domain/1/device/vcamera/0/formats/YUYV/640x480/frame-rates = "30/1,15/1" >> + * /local/domain/1/device/vcamera/0/formats/YUYV/1920x1080/frame-rates = "15/2" >> + * /local/domain/1/device/vcamera/0/formats/BGRA/640x480/frame-rates = "15/1,15/2" >> + * /local/domain/1/device/vcamera/0/formats/BGRA/1200x720/frame-rates = "15/2" >> + * /local/domain/1/device/vcamera/0/unique-id = "0" >> + * /local/domain/1/device/vcamera/0/req-ring-ref = "2832" >> + * /local/domain/1/device/vcamera/0/req-event-channel = "15" >> + * /local/domain/1/device/vcamera/0/evt-ring-ref = "387" >> + * /local/domain/1/device/vcamera/0/evt-event-channel = "16" >> + * >> + *---------------------------- Device 1 configuration ------------------------- >> + * >> + * /local/domain/1/device/vcamera/1/max-buffers = "8" >> + * /local/domain/1/device/vcamera/1/controls = "brightness,saturation,hue" >> + * /local/domain/1/device/vcamera/1/formats/YUYV/640x480/frame-rates = "30/1,15/2" >> + * /local/domain/1/device/vcamera/1/formats/YUYV/1920x1080/frame-rates = "15/2" >> + * /local/domain/1/device/vcamera/1/unique-id = "1" >> + * /local/domain/1/device/vcamera/1/req-ring-ref = "2833" >> + * /local/domain/1/device/vcamera/1/req-event-channel = "17" >> + * /local/domain/1/device/vcamera/1/evt-ring-ref = "388" >> + * /local/domain/1/device/vcamera/1/evt-event-channel = "18" >> + * >> + ****************************************************************************** >> + * Backend XenBus Nodes >> + ****************************************************************************** >> + * >> + *----------------------------- Protocol version ------------------------------ >> + * >> + * versions >> + * Values: >> + * >> + * List of XENCAMERA_LIST_SEPARATOR separated protocol versions supported >> + * by the backend. For example "1,2,3". >> + * >> + ****************************************************************************** >> + * Frontend XenBus Nodes >> + ****************************************************************************** >> + * >> + *-------------------------------- Addressing --------------------------------- >> + * >> + * dom-id >> + * Values: >> + * >> + * Domain identifier. >> + * >> + * dev-id >> + * Values: >> + * >> + * Device identifier. >> + * >> + * /local/domain//device/vcamera//... >> + * >> + *----------------------------- Protocol version ------------------------------ >> + * >> + * version >> + * Values: >> + * >> + * Protocol version, chosen among the ones supported by the backend. >> + * >> + *------------------------- Backend buffer allocation ------------------------- >> + * >> + * be-alloc >> + * Values: "0", "1" >> + * >> + * If value is set to "1", then backend will be the buffer >> + * provider/allocator for this domain during XENCAMERA_OP_BUF_CREATE >> + * operation. >> + * If value is not "1" or omitted frontend must allocate buffers itself. >> + * >> + *------------------------------- Camera settings ----------------------------- >> + * >> + * unique-id >> + * Values: >> + * >> + * After device instance initialization each camera is assigned a >> + * unique ID, so it can be identified by the backend by this ID. >> + * This can be UUID or such. >> + * >> + * max-buffers >> + * Values: >> + * >> + * Maximum number of camera buffers this frontend may use. >> + * >> + * controls >> + * Values: >> + * >> + * List of supported camera controls separated by XENCAMERA_LIST_SEPARATOR. >> + * Camera controls are expressed as a list of string values w/o any >> + * ordering requirement. >> + * >> + * formats >> + * Values: >> + * >> + * Formats are organized as a set of directories one per each >> + * supported pixel format. The name of the directory is the >> + * corresponding FOURCC string label. The next level of >> + * the directory under represents supported resolutions. >> + * If the format represents a big-endian variant of a little >> + * endian format, then the "-BE" suffix must be added. E.g. 'AR15' vs >> + * 'AR15-BE'. >> + * If FOURCC string label has spaces then those are only allowed to >> + * be at the end of the label and must be trimmed, for example >> + * 'Y16' and 'Y16-BE' will be trimmed. >> + * >> + * resolution >> + * Values: x >> + * >> + * Resolutions are organized as a set of directories one per each >> + * supported resolution under corresponding directory. >> + * The name of the directory is the supported width and height >> + * of the camera resolution in pixels. >> + * >> + * frame-rates >> + * Values: / >> + * >> + * List of XENCAMERA_FRAME_RATE_SEPARATOR separated supported frame rates >> + * of the camera expressed as numerator and denominator of the >> + * corresponding frame rate. >> + * >> + *------------------- Camera Request Transport Parameters --------------------- >> + * >> + * This communication path is used to deliver requests from frontend to backend >> + * and get the corresponding responses from backend to frontend, >> + * set up per virtual camera device. >> + * >> + * req-event-channel >> + * Values: >> + * >> + * The identifier of the Xen camera's control event channel >> + * used to signal activity in the ring buffer. >> + * >> + * req-ring-ref >> + * Values: >> + * >> + * The Xen grant reference granting permission for the backend to map >> + * a sole page of camera's control ring buffer. >> + * >> + *-------------------- Camera Event Transport Parameters ---------------------- >> + * >> + * This communication path is used to deliver asynchronous events from backend >> + * to frontend, set up per virtual camera device. >> + * >> + * evt-event-channel >> + * Values: >> + * >> + * The identifier of the Xen camera's event channel >> + * used to signal activity in the ring buffer. >> + * >> + * evt-ring-ref >> + * Values: >> + * >> + * The Xen grant reference granting permission for the backend to map >> + * a sole page of camera's event ring buffer. >> + */ >> + >> +/* >> + ****************************************************************************** >> + * STATE DIAGRAMS >> + ****************************************************************************** >> + * >> + * Tool stack creates front and back state nodes with initial state >> + * XenbusStateInitialising. >> + * Tool stack creates and sets up frontend camera configuration >> + * nodes per domain. >> + * >> + *-------------------------------- Normal flow -------------------------------- >> + * >> + * Front Back >> + * ================================= ===================================== >> + * XenbusStateInitialising XenbusStateInitialising >> + * o Query backend device identification >> + * data. >> + * o Open and validate backend device. >> + * | >> + * | >> + * V >> + * XenbusStateInitWait >> + * >> + * o Query frontend configuration >> + * o Allocate and initialize >> + * event channels per configured >> + * camera. >> + * o Publish transport parameters >> + * that will be in effect during >> + * this connection. >> + * | >> + * | >> + * V >> + * XenbusStateInitialised >> + * >> + * o Query frontend transport parameters. >> + * o Connect to the event channels. >> + * | >> + * | >> + * V >> + * XenbusStateConnected >> + * >> + * o Create and initialize OS >> + * virtual camera as per >> + * configuration. >> + * | >> + * | >> + * V >> + * XenbusStateConnected >> + * >> + * XenbusStateUnknown >> + * XenbusStateClosed >> + * XenbusStateClosing >> + * o Remove virtual camera device >> + * o Remove event channels >> + * | >> + * | >> + * V >> + * XenbusStateClosed >> + * >> + *------------------------------- Recovery flow ------------------------------- >> + * >> + * In case of frontend unrecoverable errors backend handles that as >> + * if frontend goes into the XenbusStateClosed state. >> + * >> + * In case of backend unrecoverable errors frontend tries removing >> + * the virtualized device. If this is possible at the moment of error, >> + * then frontend goes into the XenbusStateInitialising state and is ready for >> + * new connection with backend. If the virtualized device is still in use and >> + * cannot be removed, then frontend goes into the XenbusStateReconfiguring state >> + * until either the virtualized device is removed or backend initiates a new >> + * connection. On the virtualized device removal frontend goes into the >> + * XenbusStateInitialising state. >> + * >> + * Note on XenbusStateReconfiguring state of the frontend: if backend has >> + * unrecoverable errors then frontend cannot send requests to the backend >> + * and thus cannot provide functionality of the virtualized device anymore. >> + * After backend is back to normal the virtualized device may still hold some >> + * state: configuration in use, allocated buffers, client application state etc. >> + * In most cases, this will require frontend to implement complex recovery >> + * reconnect logic. Instead, by going into XenbusStateReconfiguring state, >> + * frontend will make sure no new clients of the virtualized device are >> + * accepted, allow existing client(s) to exit gracefully by signaling error >> + * state etc. >> + * Once all the clients are gone frontend can reinitialize the virtualized >> + * device and get into XenbusStateInitialising state again signaling the >> + * backend that a new connection can be made. >> + * >> + * There are multiple conditions possible under which frontend will go from >> + * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS >> + * specific. For example: >> + * 1. The underlying OS framework may provide callbacks to signal that the last >> + * client of the virtualized device has gone and the device can be removed >> + * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue) >> + * to periodically check if this is the right time to re-try removal of >> + * the virtualized device. >> + * 3. By any other means. >> + * >> + ****************************************************************************** >> + * REQUEST CODES >> + ****************************************************************************** >> + */ >> +#define XENCAMERA_OP_CONFIG_SET 0x00 >> +#define XENCAMERA_OP_CONFIG_GET 0x01 >> +#define XENCAMERA_OP_CONFIG_VALIDATE 0x02 >> +#define XENCAMERA_OP_FRAME_RATE_SET 0x03 >> +#define XENCAMERA_OP_BUF_GET_LAYOUT 0x04 >> +#define XENCAMERA_OP_BUF_REQUEST 0x05 >> +#define XENCAMERA_OP_BUF_CREATE 0x06 >> +#define XENCAMERA_OP_BUF_DESTROY 0x07 >> +#define XENCAMERA_OP_BUF_QUEUE 0x08 >> +#define XENCAMERA_OP_BUF_DEQUEUE 0x09 >> +#define XENCAMERA_OP_CTRL_ENUM 0x0a >> +#define XENCAMERA_OP_CTRL_SET 0x0b >> +#define XENCAMERA_OP_CTRL_GET 0x0c >> +#define XENCAMERA_OP_STREAM_START 0x0d >> +#define XENCAMERA_OP_STREAM_STOP 0x0e >> + >> +#define XENCAMERA_CTRL_BRIGHTNESS 0 >> +#define XENCAMERA_CTRL_CONTRAST 1 >> +#define XENCAMERA_CTRL_SATURATION 2 >> +#define XENCAMERA_CTRL_HUE 3 >> + >> +/* Number of supported controls. */ >> +#define XENCAMERA_MAX_CTRL 4 >> + >> +/* Control is read-only. */ >> +#define XENCAMERA_CTRL_FLG_RO (1 << 0) >> +/* Control is write-only. */ >> +#define XENCAMERA_CTRL_FLG_WO (1 << 1) >> +/* Control's value is volatile. */ >> +#define XENCAMERA_CTRL_FLG_VOLATILE (1 << 2) >> + >> +/* Supported color spaces. */ >> +#define XENCAMERA_COLORSPACE_DEFAULT 0 >> +#define XENCAMERA_COLORSPACE_SMPTE170M 1 >> +#define XENCAMERA_COLORSPACE_REC709 2 >> +#define XENCAMERA_COLORSPACE_SRGB 3 >> +#define XENCAMERA_COLORSPACE_OPRGB 4 >> +#define XENCAMERA_COLORSPACE_BT2020 5 >> +#define XENCAMERA_COLORSPACE_DCI_P3 6 >> + >> +/* Color space transfer function. */ >> +#define XENCAMERA_XFER_FUNC_DEFAULT 0 >> +#define XENCAMERA_XFER_FUNC_709 1 >> +#define XENCAMERA_XFER_FUNC_SRGB 2 >> +#define XENCAMERA_XFER_FUNC_OPRGB 3 >> +#define XENCAMERA_XFER_FUNC_NONE 4 >> +#define XENCAMERA_XFER_FUNC_DCI_P3 5 >> +#define XENCAMERA_XFER_FUNC_SMPTE2084 6 >> + >> +/* Color space Y’CbCr encoding. */ >> +#define XENCAMERA_YCBCR_ENC_IGNORE 0 >> +#define XENCAMERA_YCBCR_ENC_601 1 >> +#define XENCAMERA_YCBCR_ENC_709 2 >> +#define XENCAMERA_YCBCR_ENC_XV601 3 >> +#define XENCAMERA_YCBCR_ENC_XV709 4 >> +#define XENCAMERA_YCBCR_ENC_BT2020 5 >> +#define XENCAMERA_YCBCR_ENC_BT2020_CONST_LUM 6 >> + >> +/* Quantization range. */ >> +#define XENCAMERA_QUANTIZATION_DEFAULT 0 >> +#define XENCAMERA_QUANTIZATION_FULL_RANGE 1 >> +#define XENCAMERA_QUANTIZATION_LIM_RANGE 2 >> + >> +/* >> + ****************************************************************************** >> + * EVENT CODES >> + ****************************************************************************** >> + */ >> +#define XENCAMERA_EVT_FRAME_AVAIL 0x00 >> +#define XENCAMERA_EVT_CTRL_CHANGE 0x01 >> + >> +/* >> + ****************************************************************************** >> + * XENSTORE FIELD AND PATH NAME STRINGS, HELPERS >> + ****************************************************************************** >> + */ >> +#define XENCAMERA_DRIVER_NAME "vcamera" >> + >> +#define XENCAMERA_LIST_SEPARATOR "," >> +#define XENCAMERA_RESOLUTION_SEPARATOR "x" >> +#define XENCAMERA_FRACTION_SEPARATOR "/" >> + >> +#define XENCAMERA_FIELD_BE_VERSIONS "versions" >> +#define XENCAMERA_FIELD_FE_VERSION "version" >> +#define XENCAMERA_FIELD_REQ_RING_REF "req-ring-ref" >> +#define XENCAMERA_FIELD_REQ_CHANNEL "req-event-channel" >> +#define XENCAMERA_FIELD_EVT_RING_REF "evt-ring-ref" >> +#define XENCAMERA_FIELD_EVT_CHANNEL "evt-event-channel" >> +#define XENCAMERA_FIELD_MAX_BUFFERS "max-buffers" >> +#define XENCAMERA_FIELD_CONTROLS "controls" >> +#define XENCAMERA_FIELD_FORMATS "formats" >> +#define XENCAMERA_FIELD_FRAME_RATES "frame-rates" >> +#define XENCAMERA_FIELD_BE_ALLOC "be-alloc" >> +#define XENCAMERA_FIELD_UNIQUE_ID "unique-id" >> + >> +#define XENCAMERA_CTRL_BRIGHTNESS_STR "brightness" >> +#define XENCAMERA_CTRL_CONTRAST_STR "contrast" >> +#define XENCAMERA_CTRL_SATURATION_STR "saturation" >> +#define XENCAMERA_CTRL_HUE_STR "hue" >> + >> +#define XENCAMERA_FOURCC_BIGENDIAN_STR "-BE" >> + >> +/* Maximum number of buffer planes supported. */ >> +#define XENCAMERA_MAX_PLANE 4 >> + >> +/* >> + ****************************************************************************** >> + * STATUS RETURN CODES >> + ****************************************************************************** >> + * >> + * Status return code is zero on success and -XEN_EXX on failure. >> + * >> + ****************************************************************************** >> + * Assumptions >> + ****************************************************************************** >> + * >> + * - usage of grant reference 0 as invalid grant reference: >> + * grant reference 0 is valid, but never exposed to a PV driver, >> + * because of the fact it is already in use/reserved by the PV console. >> + * - all references in this document to page sizes must be treated >> + * as pages of size XEN_PAGE_SIZE unless otherwise noted. >> + * - all FOURCC mappings used for configuration and messaging are >> + * Linux V4L2 ones: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/videodev2.h >> + * with the following exceptions: >> + * - characters are allowed in [0x20; 0x7f] range >> + * - when used for XenStore configuration entries the following >> + * are not allowed: >> + * - '/', '\', ' ' (space), '<', '>', ':', '"', '|', '?', '*' >> + * - if trailing spaces are part of the FOURCC code then those must be >> + * trimmed >> + * >> + * >> + ****************************************************************************** >> + * Description of the protocol between frontend and backend driver >> + ****************************************************************************** >> + * >> + * The two halves of a Para-virtual camera driver communicate with >> + * each other using shared pages and event channels. >> + * Shared page contains a ring with request/response packets. >> + * >> + * All reserved fields in the structures below must be 0. >> + * >> + * For all request/response/event packets: >> + * - frame rate parameter is represented as a pair of 4 octet long >> + * numerator and denominator: >> + * - frame_rate_numer - uint32_t, numerator of the frame rate >> + * - frame_rate_denom - uint32_t, denominator of the frame rate >> + * The corresponding frame rate (Hz) is calculated as: >> + * frame_rate = frame_rate_numer / frame_rate_denom >> + * - buffer index is a zero based index of the buffer. Must be less than >> + * the value of XENCAMERA_OP_CONFIG_SET.num_bufs response: >> + * - index - uint8_t, index of the buffer. >> + * >> + * >> + *---------------------------------- Requests --------------------------------- >> + * >> + * All request packets have the same length (64 octets). >> + * All request packets have common header: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | operation | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * id - uint16_t, private guest value, echoed in response. >> + * operation - uint8_t, operation code, XENCAMERA_OP_XXX. >> + * >> + * >> + * Request to set/validate the configuration - request to set the >> + * configuration/mode of the camera (XENCAMERA_OP_CONFIG_SET) or to >> + * check if the configuration is valid and can be used >> + * (XENCAMERA_OP_CONFIG_VALIDATE): >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_CONFIG_XXX | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | pixel format | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | width | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | height | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * pixel_format - uint32_t, pixel format to be used, FOURCC code. >> + * width - uint32_t, width in pixels. >> + * height - uint32_t, height in pixels. >> + * >> + * See response format for this request. >> + * >> + * Notes: >> + * - the only difference between XENCAMERA_OP_CONFIG_VALIDATE and >> + * XENCAMERA_OP_CONFIG_SET is that the former doesn't actually change >> + * camera configuration, but queries if the configuration is valid. >> + * This can be used while stream is active and/or buffers allocated. >> + * - frontend must check the corresponding response in order to see >> + * if the values reported back by the backend do match the desired ones >> + * and can be accepted. >> + * - frontend may send multiple XENCAMERA_OP_CONFIG_SET requests before >> + * sending XENCAMERA_OP_STREAM_START request to update or tune the >> + * final stream configuration. >> + * - configuration cannot be changed during active streaming, e.g. >> + * after XENCAMERA_OP_STREAM_START and before XENCAMERA_OP_STREAM_STOP >> + * requests. >> + */ >> +struct xencamera_config_req { >> + uint32_t pixel_format; >> + uint32_t width; >> + uint32_t height; >> +}; >> + >> +/* >> + * Request current configuration of the camera: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_CONFIG_GET | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * See response format for this request. >> + * >> + * >> + * Request to set the frame rate of the stream: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _FRAME_RATE_SET| reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | frame_rate_numer | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | frame_rate_denom | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * frame_rate_numer - uint32_t, numerator of the frame rate. >> + * frame_rate_denom - uint32_t, denominator of the frame rate. >> + * >> + * Notes: >> + * - to query the current (actual) frame rate use XENCAMERA_OP_CONFIG_GET >> + * request. >> + * - this request can be used with camera buffers allocated, but stream >> + * stopped, e.g. frontend is allowed to stop the stream with >> + * XENCAMERA_OP_STREAM_STOP, hold the buffers allocated (e.g. keep the >> + * configuration set with XENCAMERA_OP_CONFIG_SET), change the >> + * frame rate of the stream and (re)start the stream again with >> + * XENCAMERA_OP_STREAM_START. >> + * - frame rate cannot be changed during active streaming, e.g. >> + * after XENCAMERA_OP_STREAM_START and before XENCAMERA_OP_STREAM_STOP >> + * commands. >> + */ >> +struct xencamera_frame_rate_req { >> + uint32_t frame_rate_numer; >> + uint32_t frame_rate_denom; >> +}; >> + >> +/* >> + * Request camera buffer's layout: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _BUF_GET_LAYOUT| reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * See response format for this request. >> + * >> + * >> + * Request number of buffers to be used: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_BUF_REQUEST| reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | num_bufs | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * num_bufs - uint8_t, desired number of buffers to be used. >> + * >> + * If num_bufs is not zero then the backend validates the requested number of >> + * buffers and responds with the number of buffers allowed for this frontend. >> + * Frontend is responsible for checking the corresponding response in order to >> + * see if the values reported back by the backend do match the desired ones >> + * and can be accepted. >> + * Frontend is allowed to send multiple XENCAMERA_OP_BUF_REQUEST requests >> + * before sending XENCAMERA_OP_STREAM_START request to update or tune the >> + * final configuration. >> + * Frontend is not allowed to change the camera configuration after this call >> + * with a non-zero value of num_bufs. If camera reconfiguration is required >> + * then this request must be sent with num_bufs set to zero and any created >> + * buffers must be destroyed first. >> + * Frontend is not allowed to change the number of buffers after the >> + * streaming has started. >> + * >> + * If num_bufs is 0 and streaming has not started yet, then the backend will >> + * free all previously allocated buffers (if any). >> + * Trying to call this if streaming is in progress will result in an error. >> + * >> + * If camera reconfiguration is required then the streaming must be stopped >> + * and this request must be sent with num_bufs set to zero and any >> + * created buffers must be destroyed. >> + * >> + * Please note, that the number of buffers in this request must not exceed >> + * the value configured in XenStore.max-buffers. >> + * >> + * See response format for this request. >> + */ >> +struct xencamera_buf_request { >> + uint8_t num_bufs; >> +}; >> + >> +/* >> + * Request camera buffer creation: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_BUF_CREATE | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | index | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_offset[0] | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_offset[1] | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_offset[2] | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_offset[3] | 28 >> + * +----------------+----------------+----------------+----------------+ >> + * | gref_directory | 32 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 36 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * An attempt to create multiple buffers with the same index is an error. >> + * index can be re-used after destroying the corresponding camera buffer. >> + * >> + * index - uint8_t, index of the buffer to be created in the range >> + * from 0 to the num_bufs field returned in response for >> + * XENCAMERA_OP_BUF_REQUEST request >> + * plane_offset - array of uint32_t, offset of the corresponding plane >> + * in octets from the buffer start. Number of offsets returned is >> + * equal to the value returned in XENCAMERA_OP_BUF_GET_LAYOUT.num_planes. >> + * gref_directory - grant_ref_t, a reference to the first shared page >> + * describing shared buffer references. The size of the buffer is equal to >> + * XENCAMERA_OP_BUF_GET_LAYOUT.size response. At least one page exists. If >> + * shared buffer size exceeds what can be addressed by this single page, >> + * then reference to the next shared page must be supplied (see >> + * gref_dir_next_page below). >> + * >> + * If XENCAMERA_FIELD_BE_ALLOC configuration entry is set, then backend will >> + * allocate the buffer with the parameters provided in this request and page >> + * directory is handled as follows: >> + * Frontend on request: >> + * - allocates pages for the directory (gref_directory, >> + * gref_dir_next_page(s) >> + * - grants permissions for the pages of the directory to the backend >> + * - sets gref_dir_next_page fields >> + * Backend on response: >> + * - grants permissions for the pages of the buffer allocated to >> + * the frontend >> + * - fills in page directory with grant references >> + * (gref[] in struct xencamera_page_directory) >> + */ >> +struct xencamera_buf_create_req { >> + uint8_t index; >> + uint8_t reserved[3]; >> + uint32_t plane_offset[XENCAMERA_MAX_PLANE]; >> + grant_ref_t gref_directory; >> +}; >> + >> +/* >> + * Shared page for XENCAMERA_OP_BUF_CREATE buffer descriptor (gref_directory in >> + * the request) employs a list of pages, describing all pages of the shared >> + * data buffer: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | gref_dir_next_page | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | gref[0] | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | gref[i] | i*4+8 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | gref[N - 1] | N*4+8 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * gref_dir_next_page - grant_ref_t, reference to the next page describing >> + * page directory. Must be 0 if there are no more pages in the list. >> + * gref[i] - grant_ref_t, reference to a shared page of the buffer >> + * allocated at XENCAMERA_OP_BUF_CREATE. >> + * >> + * Number of grant_ref_t entries in the whole page directory is not >> + * passed, but instead can be calculated as: >> + * num_grefs_total = (XENCAMERA_OP_BUF_REQUEST.size + XEN_PAGE_SIZE - 1) / >> + * XEN_PAGE_SIZE >> + */ >> +struct xencamera_page_directory { >> + grant_ref_t gref_dir_next_page; >> + grant_ref_t gref[1]; /* Variable length */ >> +}; >> + >> +/* >> + * Request buffer destruction - destroy a previously allocated camera buffer: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_BUF_DESTROY| reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | index | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * index - uint8_t, index of the buffer to be destroyed. >> + * >> + * >> + * Request queueing of the buffer for backend use: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_BUF_QUEUE | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | index | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * Notes: >> + * - frontends must not access the buffer content after this request until >> + * response to XENCAMERA_OP_BUF_DEQUEUE has been received. >> + * - buffers must be queued to the backend before destroying them with >> + * XENCAMERA_OP_BUF_DESTROY. >> + * >> + * index - uint8_t, index of the buffer to be queued. >> + * >> + * >> + * Request dequeueing of the buffer for frontend use: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id |_OP_BUF_DEQUEUE | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | index | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * Notes: >> + * - frontend is allowed to access the buffer content after the corresponding >> + * response to this request. >> + * >> + * index - uint8_t, index of the buffer to be queued. >> + * >> + * >> + * Request camera control details: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_CTRL_ENUM | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | index | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * See response format for this request. >> + * >> + * index - uint8_t, index of the control to be queried. >> + */ >> +struct xencamera_index { >> + uint8_t index; >> +}; >> + >> +/* >> + * Request camera control change: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_SET_CTRL | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | type | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | value low 32-bit | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | value high 32-bit | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 28 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX. >> + * value - int64_t, new value of the control. >> + */ >> +struct xencamera_ctrl_value { >> + uint8_t type; >> + uint8_t reserved[7]; >> + int64_t value; >> +}; >> + >> +/* >> + * Request camera control state: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_GET_CTRL | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | type | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * See response format for this request. >> + * >> + * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX. >> + */ >> +struct xencamera_get_ctrl_req { >> + uint8_t type; >> +}; >> + >> +/* >> + * Request camera capture stream start: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id |_OP_STREAM_START| reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * >> + * Request camera capture stream stop: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id |_OP_STREAM_STOP | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * >> + *---------------------------------- Responses -------------------------------- >> + * >> + * All response packets have the same length (64 octets). >> + * >> + * All response packets have common header: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | operation | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | status | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * id - uint16_t, copied from the request. >> + * operation - uint8_t, XENCAMERA_OP_* - copied from request. >> + * status - int32_t, response status, zero on success and -XEN_EXX on failure. >> + * >> + * >> + * Configuration response - response for XENCAMERA_OP_CONFIG_SET, >> + * XENCAMERA_OP_CONFIG_GET and XENCAMERA_OP_CONFIG_VALIDATE requests: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_CONFIG_XXX | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | status | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | pixel format | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | width | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | height | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | colorspace | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * | xfer_func | 28 >> + * +----------------+----------------+----------------+----------------+ >> + * | ycbcr_enc | 32 >> + * +----------------+----------------+----------------+----------------+ >> + * | quantization | 36 >> + * +----------------+----------------+----------------+----------------+ >> + * | displ_asp_ratio_numer | 40 >> + * +----------------+----------------+----------------+----------------+ >> + * | displ_asp_ratio_denom | 44 >> + * +----------------+----------------+----------------+----------------+ >> + * | frame_rate_numer | 48 >> + * +----------------+----------------+----------------+----------------+ >> + * | frame_rate_denom | 52 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 56 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * Meaning of the corresponding values in this response is the same as for >> + * XENCAMERA_OP_CONFIG_SET and XENCAMERA_OP_FRAME_RATE_SET requests. >> + * >> + * colorspace - uint32_t, this supplements pixel_format parameter, >> + * one of the XENCAMERA_COLORSPACE_XXX. >> + * xfer_func - uint32_t, this supplements colorspace parameter, >> + * one of the XENCAMERA_XFER_FUNC_XXX. >> + * ycbcr_enc - uint32_t, this supplements colorspace parameter, >> + * one of the XENCAMERA_YCBCR_ENC_XXX. Please note, that ycbcr_enc is only >> + * valid for YCbCr pixelformats and should be ignored otherwise. >> + * quantization - uint32_t, this supplements colorspace parameter, >> + * one of the XENCAMERA_QUANTIZATION_XXX. >> + * displ_asp_ratio_numer - uint32_t, numerator of the display aspect ratio. >> + * displ_asp_ratio_denom - uint32_t, denominator of the display aspect ratio. >> + */ >> +struct xencamera_config_resp { >> + uint32_t pixel_format; >> + uint32_t width; >> + uint32_t height; >> + uint32_t colorspace; >> + uint32_t xfer_func; >> + uint32_t ycbcr_enc; >> + uint32_t quantization; >> + uint32_t displ_asp_ratio_numer; >> + uint32_t displ_asp_ratio_denom; >> + uint32_t frame_rate_numer; >> + uint32_t frame_rate_denom; >> +}; >> + >> +/* >> + * Request buffer response - response for XENCAMERA_OP_BUF_GET_LAYOUT >> + * request: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id |_BUF_GET_LAYOUT | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | status | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | num_planes | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | size | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_size[0] | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_size[1] | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_size[2] | 28 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_size[3] | 32 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_stride[0] | 36 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_stride[1] | 40 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_stride[2] | 44 >> + * +----------------+----------------+----------------+----------------+ >> + * | plane_stride[3] | 48 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * num_planes - uint8_t, number of planes of the buffer. >> + * size - uint32_t, overall size of the buffer including sizes of the >> + * individual planes and padding if applicable. >> + * plane_size - array of uint32_t, size in octets of the corresponding plane >> + * including padding. >> + * plane_stride - array of uint32_t, size in octets occupied by the >> + * corresponding single image line including padding if applicable. >> + * >> + * Note! The sizes and strides in this response apply to all buffers created >> + * with XENCAMERA_OP_BUF_CREATE command, but individual buffers may have >> + * different plane offsets, see XENCAMERA_OP_BUF_REQUEST.plane_offset. >> + */ >> +struct xencamera_buf_get_layout_resp { >> + uint8_t num_planes; >> + uint8_t reserved[3]; >> + uint32_t size; >> + uint32_t plane_size[XENCAMERA_MAX_PLANE]; >> + uint32_t plane_stride[XENCAMERA_MAX_PLANE]; >> +}; >> + >> +/* >> + * Request buffer response - response for XENCAMERA_OP_BUF_REQUEST >> + * request: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id |_OP_BUF_REQUEST | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | status | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | num_buffers | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * num_buffers - uint8_t, number of buffers to be used. >> + * >> + * >> + * Control enumerate response - response for XENCAMERA_OP_CTRL_ENUM: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_CTRL_ENUM | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | status | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | index | type | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | flags | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | min low 32-bits | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | min high 32-bits | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * | max low 32-bits | 28 >> + * +----------------+----------------+----------------+----------------+ >> + * | max high 32-bits | 32 >> + * +----------------+----------------+----------------+----------------+ >> + * | step low 32-bits | 36 >> + * +----------------+----------------+----------------+----------------+ >> + * | step high 32-bits | 40 >> + * +----------------+----------------+----------------+----------------+ >> + * | def_val low 32-bits | 44 >> + * +----------------+----------------+----------------+----------------+ >> + * | def_val high 32-bits | 48 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 52 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * index - uint8_t, index of the camera control in response. >> + * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX. >> + * flags - uint32_t, flags of the control, one of the XENCAMERA_CTRL_FLG_XXX. >> + * min - int64_t, minimum value of the control. >> + * max - int64_t, maximum value of the control. >> + * step - int64_t, minimum size in which control value can be changed. >> + * def_val - int64_t, default value of the control. >> + */ >> +struct xencamera_ctrl_enum_resp { >> + uint8_t index; >> + uint8_t type; >> + uint8_t reserved[2]; >> + uint32_t flags; >> + int64_t min; >> + int64_t max; >> + int64_t step; >> + int64_t def_val; >> +}; >> + >> +/* >> + * Get control response - response for XENCAMERA_OP_CTRL_GET: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | _OP_CTRL_GET | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | status | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | type | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | value low 32-bit | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * | value high 32-bit | 28 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 32 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX. >> + * value - int64_t, new value of the control. >> + */ >> + >> +/* >> + *----------------------------------- Events ---------------------------------- >> + * >> + * Events are sent via a shared page allocated by the front and propagated by >> + * evt-event-channel/evt-ring-ref XenStore entries. >> + * >> + * All event packets have the same length (64 octets). >> + * All event packets have common header: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id | type | reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * id - uint16_t, event id, may be used by front. >> + * type - uint8_t, type of the event. >> + * >> + * >> + * Frame captured event - event from back to front when a new captured >> + * frame is available: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id |_EVT_FRAME_AVAIL| reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | index | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | used_sz | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | seq_num | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * index - uint8_t, index of the buffer that contains new captured frame, >> + * see XENCAMERA_OP_BUF_CREATE description on the range >> + * used_sz - uint32_t, number of octets this frame has. This can be less >> + * than the XENCAMERA_OP_BUF_REQUEST.size (response) for compressed formats. >> + * seq_num - uint32_t, sequential number of the frame. Must be >> + * monotonically increasing. If skips are detected in seq_num then that >> + * means that the frames in-between were dropped. Note however that not >> + * all video capture hardware is capable of detecting dropped frames. >> + * In that case there will be no skips in the sequence counter. >> + */ >> +struct xencamera_frame_avail_evt { >> + uint8_t index; >> + uint8_t reserved[3]; >> + uint32_t used_sz; >> + uint32_t seq_num; >> +}; >> + >> +/* >> + * Control change event- event from back to front when camera control >> + * has changed: >> + * 0 1 2 3 octet >> + * +----------------+----------------+----------------+----------------+ >> + * | id |_EVT_CTRL_CHANGE| reserved | 4 >> + * +----------------+----------------+----------------+----------------+ >> + * | type | reserved | 8 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 12 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 16 >> + * +----------------+----------------+----------------+----------------+ >> + * | value low 32-bit | 20 >> + * +----------------+----------------+----------------+----------------+ >> + * | value high 32-bit | 24 >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 28 >> + * +----------------+----------------+----------------+----------------+ >> + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| >> + * +----------------+----------------+----------------+----------------+ >> + * | reserved | 64 >> + * +----------------+----------------+----------------+----------------+ >> + * >> + * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX. >> + * value - int64_t, new value of the control. >> + * >> + * Notes: >> + * - this event is not sent for write-only controls >> + * - this event is not sent to the originator of the control change >> + * - this event is not sent when frontend first connects, e.g. initial >> + * control state must be explicitly queried >> + */ >> + >> +struct xencamera_req { >> + uint16_t id; >> + uint8_t operation; >> + uint8_t reserved[5]; >> + union { >> + struct xencamera_config_req config; >> + struct xencamera_frame_rate_req frame_rate; >> + struct xencamera_buf_request buf_request; >> + struct xencamera_buf_create_req buf_create; >> + struct xencamera_index index; >> + struct xencamera_ctrl_value ctrl_value; >> + struct xencamera_get_ctrl_req get_ctrl; >> + uint8_t reserved[56]; >> + } req; >> +}; >> + >> +struct xencamera_resp { >> + uint16_t id; >> + uint8_t operation; >> + uint8_t reserved; >> + int32_t status; >> + union { >> + struct xencamera_config_resp config; >> + struct xencamera_buf_get_layout_resp buf_layout; >> + struct xencamera_buf_request buf_request; >> + struct xencamera_ctrl_enum_resp ctrl_enum; >> + struct xencamera_ctrl_value ctrl_value; >> + uint8_t reserved1[56]; >> + } resp; >> +}; >> + >> +struct xencamera_evt { >> + uint16_t id; >> + uint8_t type; >> + uint8_t reserved[5]; >> + union { >> + struct xencamera_frame_avail_evt frame_avail; >> + struct xencamera_ctrl_value ctrl_value; >> + uint8_t reserved[56]; >> + } evt; >> +}; >> + >> +DEFINE_RING_TYPES(xen_cameraif, struct xencamera_req, struct xencamera_resp); >> + >> +/* >> + ****************************************************************************** >> + * Back to front events delivery >> + ****************************************************************************** >> + * In order to deliver asynchronous events from back to front a shared page is >> + * allocated by front and its granted reference propagated to back via >> + * XenStore entries (evt-ring-ref/evt-event-channel). >> + * This page has a common header used by both front and back to synchronize >> + * access and control event's ring buffer, while back being a producer of the >> + * events and front being a consumer. The rest of the page after the header >> + * is used for event packets. >> + * >> + * Upon reception of an event(s) front may confirm its reception >> + * for either each event, group of events or none. >> + */ >> + >> +struct xencamera_event_page { >> + uint32_t in_cons; >> + uint32_t in_prod; >> + uint8_t reserved[56]; >> +}; >> + >> +#define XENCAMERA_EVENT_PAGE_SIZE 4096 >> +#define XENCAMERA_IN_RING_OFFS (sizeof(struct xencamera_event_page)) >> +#define XENCAMERA_IN_RING_SIZE (XENCAMERA_EVENT_PAGE_SIZE - XENCAMERA_IN_RING_OFFS) >> +#define XENCAMERA_IN_RING_LEN (XENCAMERA_IN_RING_SIZE / sizeof(struct xencamera_evt)) >> +#define XENCAMERA_IN_RING(page) \ >> + ((struct xencamera_evt *)((char *)(page) + XENCAMERA_IN_RING_OFFS)) >> +#define XENCAMERA_IN_RING_REF(page, idx) \ >> + (XENCAMERA_IN_RING((page))[(idx) % XENCAMERA_IN_RING_LEN]) >> + >> +#endif /* __XEN_PUBLIC_IO_CAMERAIF_H__ */ >> + >> +/* >> + * Local variables: >> + * mode: C >> + * c-file-style: "BSD" >> + * c-basic-offset: 4 >> + * tab-width: 4 >> + * indent-tabs-mode: nil >> + * End: >> + */ >>