xref: /freebsd-src/sys/contrib/xen/io/cameraif.h (revision 3a9fd8242b35884921dfc4e886f284a75870a536)
1*3a9fd824SRoger Pau Monné /******************************************************************************
2*3a9fd824SRoger Pau Monné  * cameraif.h
3*3a9fd824SRoger Pau Monné  *
4*3a9fd824SRoger Pau Monné  * Unified camera device I/O interface for Xen guest OSes.
5*3a9fd824SRoger Pau Monné  *
6*3a9fd824SRoger Pau Monné  * Permission is hereby granted, free of charge, to any person obtaining a copy
7*3a9fd824SRoger Pau Monné  * of this software and associated documentation files (the "Software"), to
8*3a9fd824SRoger Pau Monné  * deal in the Software without restriction, including without limitation the
9*3a9fd824SRoger Pau Monné  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10*3a9fd824SRoger Pau Monné  * sell copies of the Software, and to permit persons to whom the Software is
11*3a9fd824SRoger Pau Monné  * furnished to do so, subject to the following conditions:
12*3a9fd824SRoger Pau Monné  *
13*3a9fd824SRoger Pau Monné  * The above copyright notice and this permission notice shall be included in
14*3a9fd824SRoger Pau Monné  * all copies or substantial portions of the Software.
15*3a9fd824SRoger Pau Monné  *
16*3a9fd824SRoger Pau Monné  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17*3a9fd824SRoger Pau Monné  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18*3a9fd824SRoger Pau Monné  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19*3a9fd824SRoger Pau Monné  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20*3a9fd824SRoger Pau Monné  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21*3a9fd824SRoger Pau Monné  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22*3a9fd824SRoger Pau Monné  * DEALINGS IN THE SOFTWARE.
23*3a9fd824SRoger Pau Monné  *
24*3a9fd824SRoger Pau Monné  * Copyright (C) 2018-2019 EPAM Systems Inc.
25*3a9fd824SRoger Pau Monné  *
26*3a9fd824SRoger Pau Monné  * Author: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>
27*3a9fd824SRoger Pau Monné  */
28*3a9fd824SRoger Pau Monné 
29*3a9fd824SRoger Pau Monné #ifndef __XEN_PUBLIC_IO_CAMERAIF_H__
30*3a9fd824SRoger Pau Monné #define __XEN_PUBLIC_IO_CAMERAIF_H__
31*3a9fd824SRoger Pau Monné 
32*3a9fd824SRoger Pau Monné #include "ring.h"
33*3a9fd824SRoger Pau Monné #include "../grant_table.h"
34*3a9fd824SRoger Pau Monné 
35*3a9fd824SRoger Pau Monné /*
36*3a9fd824SRoger Pau Monné  ******************************************************************************
37*3a9fd824SRoger Pau Monné  *                           Protocol version
38*3a9fd824SRoger Pau Monné  ******************************************************************************
39*3a9fd824SRoger Pau Monné  */
40*3a9fd824SRoger Pau Monné #define XENCAMERA_PROTOCOL_VERSION     "1"
41*3a9fd824SRoger Pau Monné 
42*3a9fd824SRoger Pau Monné /*
43*3a9fd824SRoger Pau Monné  ******************************************************************************
44*3a9fd824SRoger Pau Monné  *                  Feature and Parameter Negotiation
45*3a9fd824SRoger Pau Monné  ******************************************************************************
46*3a9fd824SRoger Pau Monné  *
47*3a9fd824SRoger Pau Monné  * Front->back notifications: when enqueuing a new request, sending a
48*3a9fd824SRoger Pau Monné  * notification can be made conditional on xencamera_req (i.e., the generic
49*3a9fd824SRoger Pau Monné  * hold-off mechanism provided by the ring macros). Backends must set
50*3a9fd824SRoger Pau Monné  * xencamera_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()).
51*3a9fd824SRoger Pau Monné  *
52*3a9fd824SRoger Pau Monné  * Back->front notifications: when enqueuing a new response, sending a
53*3a9fd824SRoger Pau Monné  * notification can be made conditional on xencamera_resp (i.e., the generic
54*3a9fd824SRoger Pau Monné  * hold-off mechanism provided by the ring macros). Frontends must set
55*3a9fd824SRoger Pau Monné  * xencamera_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()).
56*3a9fd824SRoger Pau Monné  *
57*3a9fd824SRoger Pau Monné  * The two halves of a para-virtual camera driver utilize nodes within
58*3a9fd824SRoger Pau Monné  * XenStore to communicate capabilities and to negotiate operating parameters.
59*3a9fd824SRoger Pau Monné  * This section enumerates these nodes which reside in the respective front and
60*3a9fd824SRoger Pau Monné  * backend portions of XenStore, following the XenBus convention.
61*3a9fd824SRoger Pau Monné  *
62*3a9fd824SRoger Pau Monné  * All data in XenStore is stored as strings. Nodes specifying numeric
63*3a9fd824SRoger Pau Monné  * values are encoded in decimal. Integer value ranges listed below are
64*3a9fd824SRoger Pau Monné  * expressed as fixed sized integer types capable of storing the conversion
65*3a9fd824SRoger Pau Monné  * of a properly formatted node string, without loss of information.
66*3a9fd824SRoger Pau Monné  *
67*3a9fd824SRoger Pau Monné  ******************************************************************************
68*3a9fd824SRoger Pau Monné  *                        Example configuration
69*3a9fd824SRoger Pau Monné  ******************************************************************************
70*3a9fd824SRoger Pau Monné  *
71*3a9fd824SRoger Pau Monné  * This is an example of backend and frontend configuration:
72*3a9fd824SRoger Pau Monné  *
73*3a9fd824SRoger Pau Monné  *--------------------------------- Backend -----------------------------------
74*3a9fd824SRoger Pau Monné  *
75*3a9fd824SRoger Pau Monné  * /local/domain/0/backend/vcamera/1/0/frontend-id = "1"
76*3a9fd824SRoger Pau Monné  * /local/domain/0/backend/vcamera/1/0/frontend = "/local/domain/1/device/vcamera/0"
77*3a9fd824SRoger Pau Monné  * /local/domain/0/backend/vcamera/1/0/state = "4"
78*3a9fd824SRoger Pau Monné  * /local/domain/0/backend/vcamera/1/0/versions = "1,2"
79*3a9fd824SRoger Pau Monné  *
80*3a9fd824SRoger Pau Monné  *--------------------------------- Frontend ----------------------------------
81*3a9fd824SRoger Pau Monné  *
82*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/backend-id = "0"
83*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/backend = "/local/domain/0/backend/vcamera/1"
84*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/state = "4"
85*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/version = "1"
86*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/be-alloc = "1"
87*3a9fd824SRoger Pau Monné  *
88*3a9fd824SRoger Pau Monné  *---------------------------- Device 0 configuration -------------------------
89*3a9fd824SRoger Pau Monné  *
90*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/max-buffers = "3"
91*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/controls = "contrast,hue"
92*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/formats/YUYV/640x480/frame-rates = "30/1,15/1"
93*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/formats/YUYV/1920x1080/frame-rates = "15/2"
94*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/formats/BGRA/640x480/frame-rates = "15/1,15/2"
95*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/formats/BGRA/1200x720/frame-rates = "15/2"
96*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/unique-id = "0"
97*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/req-ring-ref = "2832"
98*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/req-event-channel = "15"
99*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/evt-ring-ref = "387"
100*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/0/evt-event-channel = "16"
101*3a9fd824SRoger Pau Monné  *
102*3a9fd824SRoger Pau Monné  *---------------------------- Device 1 configuration -------------------------
103*3a9fd824SRoger Pau Monné  *
104*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/max-buffers = "8"
105*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/controls = "brightness,saturation,hue"
106*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/formats/YUYV/640x480/frame-rates = "30/1,15/2"
107*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/formats/YUYV/1920x1080/frame-rates = "15/2"
108*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/unique-id = "1"
109*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/req-ring-ref = "2833"
110*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/req-event-channel = "17"
111*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/evt-ring-ref = "388"
112*3a9fd824SRoger Pau Monné  * /local/domain/1/device/vcamera/1/evt-event-channel = "18"
113*3a9fd824SRoger Pau Monné  *
114*3a9fd824SRoger Pau Monné  ******************************************************************************
115*3a9fd824SRoger Pau Monné  *                            Backend XenBus Nodes
116*3a9fd824SRoger Pau Monné  ******************************************************************************
117*3a9fd824SRoger Pau Monné  *
118*3a9fd824SRoger Pau Monné  *----------------------------- Protocol version ------------------------------
119*3a9fd824SRoger Pau Monné  *
120*3a9fd824SRoger Pau Monné  * versions
121*3a9fd824SRoger Pau Monné  *      Values:         <string>
122*3a9fd824SRoger Pau Monné  *
123*3a9fd824SRoger Pau Monné  *      List of XENCAMERA_LIST_SEPARATOR separated protocol versions supported
124*3a9fd824SRoger Pau Monné  *      by the backend. For example "1,2,3".
125*3a9fd824SRoger Pau Monné  *
126*3a9fd824SRoger Pau Monné  ******************************************************************************
127*3a9fd824SRoger Pau Monné  *                            Frontend XenBus Nodes
128*3a9fd824SRoger Pau Monné  ******************************************************************************
129*3a9fd824SRoger Pau Monné  *
130*3a9fd824SRoger Pau Monné  *-------------------------------- Addressing ---------------------------------
131*3a9fd824SRoger Pau Monné  *
132*3a9fd824SRoger Pau Monné  * dom-id
133*3a9fd824SRoger Pau Monné  *      Values:         <uint16_t>
134*3a9fd824SRoger Pau Monné  *
135*3a9fd824SRoger Pau Monné  *      Domain identifier.
136*3a9fd824SRoger Pau Monné  *
137*3a9fd824SRoger Pau Monné  * dev-id
138*3a9fd824SRoger Pau Monné  *      Values:         <uint16_t>
139*3a9fd824SRoger Pau Monné  *
140*3a9fd824SRoger Pau Monné  *      Device identifier.
141*3a9fd824SRoger Pau Monné  *
142*3a9fd824SRoger Pau Monné  *      /local/domain/<dom-id>/device/vcamera/<dev-id>/...
143*3a9fd824SRoger Pau Monné  *
144*3a9fd824SRoger Pau Monné  *----------------------------- Protocol version ------------------------------
145*3a9fd824SRoger Pau Monné  *
146*3a9fd824SRoger Pau Monné  * version
147*3a9fd824SRoger Pau Monné  *      Values:         <string>
148*3a9fd824SRoger Pau Monné  *
149*3a9fd824SRoger Pau Monné  *      Protocol version, chosen among the ones supported by the backend.
150*3a9fd824SRoger Pau Monné  *
151*3a9fd824SRoger Pau Monné  *------------------------- Backend buffer allocation -------------------------
152*3a9fd824SRoger Pau Monné  *
153*3a9fd824SRoger Pau Monné  * be-alloc
154*3a9fd824SRoger Pau Monné  *      Values:         "0", "1"
155*3a9fd824SRoger Pau Monné  *
156*3a9fd824SRoger Pau Monné  *      If value is set to "1", then backend will be the buffer
157*3a9fd824SRoger Pau Monné  *      provider/allocator for this domain during XENCAMERA_OP_BUF_CREATE
158*3a9fd824SRoger Pau Monné  *      operation.
159*3a9fd824SRoger Pau Monné  *      If value is not "1" or omitted frontend must allocate buffers itself.
160*3a9fd824SRoger Pau Monné  *
161*3a9fd824SRoger Pau Monné  *------------------------------- Camera settings -----------------------------
162*3a9fd824SRoger Pau Monné  *
163*3a9fd824SRoger Pau Monné  * unique-id
164*3a9fd824SRoger Pau Monné  *      Values:         <string>
165*3a9fd824SRoger Pau Monné  *
166*3a9fd824SRoger Pau Monné  *      After device instance initialization each camera is assigned a
167*3a9fd824SRoger Pau Monné  *      unique ID, so it can be identified by the backend by this ID.
168*3a9fd824SRoger Pau Monné  *      This can be UUID or such.
169*3a9fd824SRoger Pau Monné  *
170*3a9fd824SRoger Pau Monné  * max-buffers
171*3a9fd824SRoger Pau Monné  *      Values:         <uint8_t>
172*3a9fd824SRoger Pau Monné  *
173*3a9fd824SRoger Pau Monné  *      Maximum number of camera buffers this frontend may use.
174*3a9fd824SRoger Pau Monné  *
175*3a9fd824SRoger Pau Monné  * controls
176*3a9fd824SRoger Pau Monné  *      Values:         <list of string>
177*3a9fd824SRoger Pau Monné  *
178*3a9fd824SRoger Pau Monné  *      List of supported camera controls separated by XENCAMERA_LIST_SEPARATOR.
179*3a9fd824SRoger Pau Monné  *      Camera controls are expressed as a list of string values w/o any
180*3a9fd824SRoger Pau Monné  *      ordering requirement.
181*3a9fd824SRoger Pau Monné  *
182*3a9fd824SRoger Pau Monné  * formats
183*3a9fd824SRoger Pau Monné  *      Values:         <format, char[7]>
184*3a9fd824SRoger Pau Monné  *
185*3a9fd824SRoger Pau Monné  *      Formats are organized as a set of directories one per each
186*3a9fd824SRoger Pau Monné  *      supported pixel format. The name of the directory is the
187*3a9fd824SRoger Pau Monné  *      corresponding FOURCC string label. The next level of
188*3a9fd824SRoger Pau Monné  *      the directory under <formats> represents supported resolutions.
189*3a9fd824SRoger Pau Monné  *      If the format represents a big-endian variant of a little
190*3a9fd824SRoger Pau Monné  *      endian format, then the "-BE" suffix must be added. E.g. 'AR15' vs
191*3a9fd824SRoger Pau Monné  *      'AR15-BE'.
192*3a9fd824SRoger Pau Monné  *      If FOURCC string label has spaces then those are only allowed to
193*3a9fd824SRoger Pau Monné  *      be at the end of the label and must be trimmed, for example
194*3a9fd824SRoger Pau Monné  *      'Y16' and 'Y16-BE' will be trimmed.
195*3a9fd824SRoger Pau Monné  *
196*3a9fd824SRoger Pau Monné  * resolution
197*3a9fd824SRoger Pau Monné  *      Values:         <width, uint32_t>x<height, uint32_t>
198*3a9fd824SRoger Pau Monné  *
199*3a9fd824SRoger Pau Monné  *      Resolutions are organized as a set of directories one per each
200*3a9fd824SRoger Pau Monné  *      supported resolution under corresponding <formats> directory.
201*3a9fd824SRoger Pau Monné  *      The name of the directory is the supported width and height
202*3a9fd824SRoger Pau Monné  *      of the camera resolution in pixels.
203*3a9fd824SRoger Pau Monné  *
204*3a9fd824SRoger Pau Monné  * frame-rates
205*3a9fd824SRoger Pau Monné  *      Values:         <numerator, uint32_t>/<denominator, uint32_t>
206*3a9fd824SRoger Pau Monné  *
207*3a9fd824SRoger Pau Monné  *      List of XENCAMERA_FRAME_RATE_SEPARATOR separated supported frame rates
208*3a9fd824SRoger Pau Monné  *      of the camera expressed as numerator and denominator of the
209*3a9fd824SRoger Pau Monné  *      corresponding frame rate.
210*3a9fd824SRoger Pau Monné  *
211*3a9fd824SRoger Pau Monné  *------------------- Camera Request Transport Parameters ---------------------
212*3a9fd824SRoger Pau Monné  *
213*3a9fd824SRoger Pau Monné  * This communication path is used to deliver requests from frontend to backend
214*3a9fd824SRoger Pau Monné  * and get the corresponding responses from backend to frontend,
215*3a9fd824SRoger Pau Monné  * set up per virtual camera device.
216*3a9fd824SRoger Pau Monné  *
217*3a9fd824SRoger Pau Monné  * req-event-channel
218*3a9fd824SRoger Pau Monné  *      Values:         <uint32_t>
219*3a9fd824SRoger Pau Monné  *
220*3a9fd824SRoger Pau Monné  *      The identifier of the Xen camera's control event channel
221*3a9fd824SRoger Pau Monné  *      used to signal activity in the ring buffer.
222*3a9fd824SRoger Pau Monné  *
223*3a9fd824SRoger Pau Monné  * req-ring-ref
224*3a9fd824SRoger Pau Monné  *      Values:         <uint32_t>
225*3a9fd824SRoger Pau Monné  *
226*3a9fd824SRoger Pau Monné  *      The Xen grant reference granting permission for the backend to map
227*3a9fd824SRoger Pau Monné  *      a sole page of camera's control ring buffer.
228*3a9fd824SRoger Pau Monné  *
229*3a9fd824SRoger Pau Monné  *-------------------- Camera Event Transport Parameters ----------------------
230*3a9fd824SRoger Pau Monné  *
231*3a9fd824SRoger Pau Monné  * This communication path is used to deliver asynchronous events from backend
232*3a9fd824SRoger Pau Monné  * to frontend, set up per virtual camera device.
233*3a9fd824SRoger Pau Monné  *
234*3a9fd824SRoger Pau Monné  * evt-event-channel
235*3a9fd824SRoger Pau Monné  *      Values:         <uint32_t>
236*3a9fd824SRoger Pau Monné  *
237*3a9fd824SRoger Pau Monné  *      The identifier of the Xen camera's event channel
238*3a9fd824SRoger Pau Monné  *      used to signal activity in the ring buffer.
239*3a9fd824SRoger Pau Monné  *
240*3a9fd824SRoger Pau Monné  * evt-ring-ref
241*3a9fd824SRoger Pau Monné  *      Values:         <uint32_t>
242*3a9fd824SRoger Pau Monné  *
243*3a9fd824SRoger Pau Monné  *      The Xen grant reference granting permission for the backend to map
244*3a9fd824SRoger Pau Monné  *      a sole page of camera's event ring buffer.
245*3a9fd824SRoger Pau Monné  */
246*3a9fd824SRoger Pau Monné 
247*3a9fd824SRoger Pau Monné /*
248*3a9fd824SRoger Pau Monné  ******************************************************************************
249*3a9fd824SRoger Pau Monné  *                               STATE DIAGRAMS
250*3a9fd824SRoger Pau Monné  ******************************************************************************
251*3a9fd824SRoger Pau Monné  *
252*3a9fd824SRoger Pau Monné  * Tool stack creates front and back state nodes with initial state
253*3a9fd824SRoger Pau Monné  * XenbusStateInitialising.
254*3a9fd824SRoger Pau Monné  * Tool stack creates and sets up frontend camera configuration
255*3a9fd824SRoger Pau Monné  * nodes per domain.
256*3a9fd824SRoger Pau Monné  *
257*3a9fd824SRoger Pau Monné  *-------------------------------- Normal flow --------------------------------
258*3a9fd824SRoger Pau Monné  *
259*3a9fd824SRoger Pau Monné  * Front                                Back
260*3a9fd824SRoger Pau Monné  * =================================    =====================================
261*3a9fd824SRoger Pau Monné  * XenbusStateInitialising              XenbusStateInitialising
262*3a9fd824SRoger Pau Monné  *                                       o Query backend device identification
263*3a9fd824SRoger Pau Monné  *                                         data.
264*3a9fd824SRoger Pau Monné  *                                       o Open and validate backend device.
265*3a9fd824SRoger Pau Monné  *                                                |
266*3a9fd824SRoger Pau Monné  *                                                |
267*3a9fd824SRoger Pau Monné  *                                                V
268*3a9fd824SRoger Pau Monné  *                                      XenbusStateInitWait
269*3a9fd824SRoger Pau Monné  *
270*3a9fd824SRoger Pau Monné  * o Query frontend configuration
271*3a9fd824SRoger Pau Monné  * o Allocate and initialize
272*3a9fd824SRoger Pau Monné  *   event channels per configured
273*3a9fd824SRoger Pau Monné  *   camera.
274*3a9fd824SRoger Pau Monné  * o Publish transport parameters
275*3a9fd824SRoger Pau Monné  *   that will be in effect during
276*3a9fd824SRoger Pau Monné  *   this connection.
277*3a9fd824SRoger Pau Monné  *              |
278*3a9fd824SRoger Pau Monné  *              |
279*3a9fd824SRoger Pau Monné  *              V
280*3a9fd824SRoger Pau Monné  * XenbusStateInitialised
281*3a9fd824SRoger Pau Monné  *
282*3a9fd824SRoger Pau Monné  *                                       o Query frontend transport parameters.
283*3a9fd824SRoger Pau Monné  *                                       o Connect to the event channels.
284*3a9fd824SRoger Pau Monné  *                                                |
285*3a9fd824SRoger Pau Monné  *                                                |
286*3a9fd824SRoger Pau Monné  *                                                V
287*3a9fd824SRoger Pau Monné  *                                      XenbusStateConnected
288*3a9fd824SRoger Pau Monné  *
289*3a9fd824SRoger Pau Monné  *  o Create and initialize OS
290*3a9fd824SRoger Pau Monné  *    virtual camera as per
291*3a9fd824SRoger Pau Monné  *    configuration.
292*3a9fd824SRoger Pau Monné  *              |
293*3a9fd824SRoger Pau Monné  *              |
294*3a9fd824SRoger Pau Monné  *              V
295*3a9fd824SRoger Pau Monné  * XenbusStateConnected
296*3a9fd824SRoger Pau Monné  *
297*3a9fd824SRoger Pau Monné  *                                      XenbusStateUnknown
298*3a9fd824SRoger Pau Monné  *                                      XenbusStateClosed
299*3a9fd824SRoger Pau Monné  *                                      XenbusStateClosing
300*3a9fd824SRoger Pau Monné  * o Remove virtual camera device
301*3a9fd824SRoger Pau Monné  * o Remove event channels
302*3a9fd824SRoger Pau Monné  *              |
303*3a9fd824SRoger Pau Monné  *              |
304*3a9fd824SRoger Pau Monné  *              V
305*3a9fd824SRoger Pau Monné  * XenbusStateClosed
306*3a9fd824SRoger Pau Monné  *
307*3a9fd824SRoger Pau Monné  *------------------------------- Recovery flow -------------------------------
308*3a9fd824SRoger Pau Monné  *
309*3a9fd824SRoger Pau Monné  * In case of frontend unrecoverable errors backend handles that as
310*3a9fd824SRoger Pau Monné  * if frontend goes into the XenbusStateClosed state.
311*3a9fd824SRoger Pau Monné  *
312*3a9fd824SRoger Pau Monné  * In case of backend unrecoverable errors frontend tries removing
313*3a9fd824SRoger Pau Monné  * the virtualized device. If this is possible at the moment of error,
314*3a9fd824SRoger Pau Monné  * then frontend goes into the XenbusStateInitialising state and is ready for
315*3a9fd824SRoger Pau Monné  * new connection with backend. If the virtualized device is still in use and
316*3a9fd824SRoger Pau Monné  * cannot be removed, then frontend goes into the XenbusStateReconfiguring state
317*3a9fd824SRoger Pau Monné  * until either the virtualized device is removed or backend initiates a new
318*3a9fd824SRoger Pau Monné  * connection. On the virtualized device removal frontend goes into the
319*3a9fd824SRoger Pau Monné  * XenbusStateInitialising state.
320*3a9fd824SRoger Pau Monné  *
321*3a9fd824SRoger Pau Monné  * Note on XenbusStateReconfiguring state of the frontend: if backend has
322*3a9fd824SRoger Pau Monné  * unrecoverable errors then frontend cannot send requests to the backend
323*3a9fd824SRoger Pau Monné  * and thus cannot provide functionality of the virtualized device anymore.
324*3a9fd824SRoger Pau Monné  * After backend is back to normal the virtualized device may still hold some
325*3a9fd824SRoger Pau Monné  * state: configuration in use, allocated buffers, client application state etc.
326*3a9fd824SRoger Pau Monné  * In most cases, this will require frontend to implement complex recovery
327*3a9fd824SRoger Pau Monné  * reconnect logic. Instead, by going into XenbusStateReconfiguring state,
328*3a9fd824SRoger Pau Monné  * frontend will make sure no new clients of the virtualized device are
329*3a9fd824SRoger Pau Monné  * accepted, allow existing client(s) to exit gracefully by signaling error
330*3a9fd824SRoger Pau Monné  * state etc.
331*3a9fd824SRoger Pau Monné  * Once all the clients are gone frontend can reinitialize the virtualized
332*3a9fd824SRoger Pau Monné  * device and get into XenbusStateInitialising state again signaling the
333*3a9fd824SRoger Pau Monné  * backend that a new connection can be made.
334*3a9fd824SRoger Pau Monné  *
335*3a9fd824SRoger Pau Monné  * There are multiple conditions possible under which frontend will go from
336*3a9fd824SRoger Pau Monné  * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS
337*3a9fd824SRoger Pau Monné  * specific. For example:
338*3a9fd824SRoger Pau Monné  * 1. The underlying OS framework may provide callbacks to signal that the last
339*3a9fd824SRoger Pau Monné  *    client of the virtualized device has gone and the device can be removed
340*3a9fd824SRoger Pau Monné  * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue)
341*3a9fd824SRoger Pau Monné  *    to periodically check if this is the right time to re-try removal of
342*3a9fd824SRoger Pau Monné  *    the virtualized device.
343*3a9fd824SRoger Pau Monné  * 3. By any other means.
344*3a9fd824SRoger Pau Monné  *
345*3a9fd824SRoger Pau Monné  ******************************************************************************
346*3a9fd824SRoger Pau Monné  *                             REQUEST CODES
347*3a9fd824SRoger Pau Monné  ******************************************************************************
348*3a9fd824SRoger Pau Monné  */
349*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_CONFIG_SET        0x00
350*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_CONFIG_GET        0x01
351*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_CONFIG_VALIDATE   0x02
352*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_FRAME_RATE_SET    0x03
353*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_BUF_GET_LAYOUT    0x04
354*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_BUF_REQUEST       0x05
355*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_BUF_CREATE        0x06
356*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_BUF_DESTROY       0x07
357*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_BUF_QUEUE         0x08
358*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_BUF_DEQUEUE       0x09
359*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_CTRL_ENUM         0x0a
360*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_CTRL_SET          0x0b
361*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_CTRL_GET          0x0c
362*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_STREAM_START      0x0d
363*3a9fd824SRoger Pau Monné #define XENCAMERA_OP_STREAM_STOP       0x0e
364*3a9fd824SRoger Pau Monné 
365*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_BRIGHTNESS      0
366*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_CONTRAST        1
367*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_SATURATION      2
368*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_HUE             3
369*3a9fd824SRoger Pau Monné 
370*3a9fd824SRoger Pau Monné /* Number of supported controls. */
371*3a9fd824SRoger Pau Monné #define XENCAMERA_MAX_CTRL             4
372*3a9fd824SRoger Pau Monné 
373*3a9fd824SRoger Pau Monné /* Control is read-only. */
374*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_FLG_RO          (1 << 0)
375*3a9fd824SRoger Pau Monné /* Control is write-only. */
376*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_FLG_WO          (1 << 1)
377*3a9fd824SRoger Pau Monné /* Control's value is volatile. */
378*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_FLG_VOLATILE    (1 << 2)
379*3a9fd824SRoger Pau Monné 
380*3a9fd824SRoger Pau Monné /* Supported color spaces. */
381*3a9fd824SRoger Pau Monné #define XENCAMERA_COLORSPACE_DEFAULT   0
382*3a9fd824SRoger Pau Monné #define XENCAMERA_COLORSPACE_SMPTE170M 1
383*3a9fd824SRoger Pau Monné #define XENCAMERA_COLORSPACE_REC709    2
384*3a9fd824SRoger Pau Monné #define XENCAMERA_COLORSPACE_SRGB      3
385*3a9fd824SRoger Pau Monné #define XENCAMERA_COLORSPACE_OPRGB     4
386*3a9fd824SRoger Pau Monné #define XENCAMERA_COLORSPACE_BT2020    5
387*3a9fd824SRoger Pau Monné #define XENCAMERA_COLORSPACE_DCI_P3    6
388*3a9fd824SRoger Pau Monné 
389*3a9fd824SRoger Pau Monné /* Color space transfer function. */
390*3a9fd824SRoger Pau Monné #define XENCAMERA_XFER_FUNC_DEFAULT    0
391*3a9fd824SRoger Pau Monné #define XENCAMERA_XFER_FUNC_709        1
392*3a9fd824SRoger Pau Monné #define XENCAMERA_XFER_FUNC_SRGB       2
393*3a9fd824SRoger Pau Monné #define XENCAMERA_XFER_FUNC_OPRGB      3
394*3a9fd824SRoger Pau Monné #define XENCAMERA_XFER_FUNC_NONE       4
395*3a9fd824SRoger Pau Monné #define XENCAMERA_XFER_FUNC_DCI_P3     5
396*3a9fd824SRoger Pau Monné #define XENCAMERA_XFER_FUNC_SMPTE2084  6
397*3a9fd824SRoger Pau Monné 
398*3a9fd824SRoger Pau Monné /* Color space Y’CbCr encoding. */
399*3a9fd824SRoger Pau Monné #define XENCAMERA_YCBCR_ENC_IGNORE           0
400*3a9fd824SRoger Pau Monné #define XENCAMERA_YCBCR_ENC_601              1
401*3a9fd824SRoger Pau Monné #define XENCAMERA_YCBCR_ENC_709              2
402*3a9fd824SRoger Pau Monné #define XENCAMERA_YCBCR_ENC_XV601            3
403*3a9fd824SRoger Pau Monné #define XENCAMERA_YCBCR_ENC_XV709            4
404*3a9fd824SRoger Pau Monné #define XENCAMERA_YCBCR_ENC_BT2020           5
405*3a9fd824SRoger Pau Monné #define XENCAMERA_YCBCR_ENC_BT2020_CONST_LUM 6
406*3a9fd824SRoger Pau Monné 
407*3a9fd824SRoger Pau Monné /* Quantization range. */
408*3a9fd824SRoger Pau Monné #define XENCAMERA_QUANTIZATION_DEFAULT       0
409*3a9fd824SRoger Pau Monné #define XENCAMERA_QUANTIZATION_FULL_RANGE    1
410*3a9fd824SRoger Pau Monné #define XENCAMERA_QUANTIZATION_LIM_RANGE     2
411*3a9fd824SRoger Pau Monné 
412*3a9fd824SRoger Pau Monné /*
413*3a9fd824SRoger Pau Monné  ******************************************************************************
414*3a9fd824SRoger Pau Monné  *                                 EVENT CODES
415*3a9fd824SRoger Pau Monné  ******************************************************************************
416*3a9fd824SRoger Pau Monné  */
417*3a9fd824SRoger Pau Monné #define XENCAMERA_EVT_FRAME_AVAIL      0x00
418*3a9fd824SRoger Pau Monné #define XENCAMERA_EVT_CTRL_CHANGE      0x01
419*3a9fd824SRoger Pau Monné 
420*3a9fd824SRoger Pau Monné /*
421*3a9fd824SRoger Pau Monné  ******************************************************************************
422*3a9fd824SRoger Pau Monné  *               XENSTORE FIELD AND PATH NAME STRINGS, HELPERS
423*3a9fd824SRoger Pau Monné  ******************************************************************************
424*3a9fd824SRoger Pau Monné  */
425*3a9fd824SRoger Pau Monné #define XENCAMERA_DRIVER_NAME          "vcamera"
426*3a9fd824SRoger Pau Monné 
427*3a9fd824SRoger Pau Monné #define XENCAMERA_LIST_SEPARATOR       ","
428*3a9fd824SRoger Pau Monné #define XENCAMERA_RESOLUTION_SEPARATOR "x"
429*3a9fd824SRoger Pau Monné #define XENCAMERA_FRACTION_SEPARATOR   "/"
430*3a9fd824SRoger Pau Monné 
431*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_BE_VERSIONS    "versions"
432*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_FE_VERSION     "version"
433*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_REQ_RING_REF   "req-ring-ref"
434*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_REQ_CHANNEL    "req-event-channel"
435*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_EVT_RING_REF   "evt-ring-ref"
436*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_EVT_CHANNEL    "evt-event-channel"
437*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_MAX_BUFFERS    "max-buffers"
438*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_CONTROLS       "controls"
439*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_FORMATS        "formats"
440*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_FRAME_RATES    "frame-rates"
441*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_BE_ALLOC       "be-alloc"
442*3a9fd824SRoger Pau Monné #define XENCAMERA_FIELD_UNIQUE_ID      "unique-id"
443*3a9fd824SRoger Pau Monné 
444*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_BRIGHTNESS_STR  "brightness"
445*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_CONTRAST_STR    "contrast"
446*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_SATURATION_STR  "saturation"
447*3a9fd824SRoger Pau Monné #define XENCAMERA_CTRL_HUE_STR         "hue"
448*3a9fd824SRoger Pau Monné 
449*3a9fd824SRoger Pau Monné #define XENCAMERA_FOURCC_BIGENDIAN_STR "-BE"
450*3a9fd824SRoger Pau Monné 
451*3a9fd824SRoger Pau Monné /* Maximum number of buffer planes supported. */
452*3a9fd824SRoger Pau Monné #define XENCAMERA_MAX_PLANE            4
453*3a9fd824SRoger Pau Monné 
454*3a9fd824SRoger Pau Monné /*
455*3a9fd824SRoger Pau Monné  ******************************************************************************
456*3a9fd824SRoger Pau Monné  *                          STATUS RETURN CODES
457*3a9fd824SRoger Pau Monné  ******************************************************************************
458*3a9fd824SRoger Pau Monné  *
459*3a9fd824SRoger Pau Monné  * Status return code is zero on success and -XEN_EXX on failure.
460*3a9fd824SRoger Pau Monné  *
461*3a9fd824SRoger Pau Monné  ******************************************************************************
462*3a9fd824SRoger Pau Monné  *                              Assumptions
463*3a9fd824SRoger Pau Monné  ******************************************************************************
464*3a9fd824SRoger Pau Monné  *
465*3a9fd824SRoger Pau Monné  * - usage of grant reference 0 as invalid grant reference:
466*3a9fd824SRoger Pau Monné  *   grant reference 0 is valid, but never exposed to a PV driver,
467*3a9fd824SRoger Pau Monné  *   because of the fact it is already in use/reserved by the PV console.
468*3a9fd824SRoger Pau Monné  * - all references in this document to page sizes must be treated
469*3a9fd824SRoger Pau Monné  *   as pages of size XEN_PAGE_SIZE unless otherwise noted.
470*3a9fd824SRoger Pau Monné  * - all FOURCC mappings used for configuration and messaging are
471*3a9fd824SRoger Pau Monné  *   Linux V4L2 ones: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/videodev2.h
472*3a9fd824SRoger Pau Monné  *   with the following exceptions:
473*3a9fd824SRoger Pau Monné  *     - characters are allowed in [0x20; 0x7f] range
474*3a9fd824SRoger Pau Monné  *     - when used for XenStore configuration entries the following
475*3a9fd824SRoger Pau Monné  *       are not allowed:
476*3a9fd824SRoger Pau Monné  *       - '/', '\', ' ' (space), '<', '>', ':', '"', '|', '?', '*'
477*3a9fd824SRoger Pau Monné  *       - if trailing spaces are part of the FOURCC code then those must be
478*3a9fd824SRoger Pau Monné  *         trimmed
479*3a9fd824SRoger Pau Monné  *
480*3a9fd824SRoger Pau Monné  *
481*3a9fd824SRoger Pau Monné  ******************************************************************************
482*3a9fd824SRoger Pau Monné  *       Description of the protocol between frontend and backend driver
483*3a9fd824SRoger Pau Monné  ******************************************************************************
484*3a9fd824SRoger Pau Monné  *
485*3a9fd824SRoger Pau Monné  * The two halves of a Para-virtual camera driver communicate with
486*3a9fd824SRoger Pau Monné  * each other using shared pages and event channels.
487*3a9fd824SRoger Pau Monné  * Shared page contains a ring with request/response packets.
488*3a9fd824SRoger Pau Monné  *
489*3a9fd824SRoger Pau Monné  * All reserved fields in the structures below must be 0.
490*3a9fd824SRoger Pau Monné  *
491*3a9fd824SRoger Pau Monné  * For all request/response/event packets:
492*3a9fd824SRoger Pau Monné  *   - frame rate parameter is represented as a pair of 4 octet long
493*3a9fd824SRoger Pau Monné  *     numerator and denominator:
494*3a9fd824SRoger Pau Monné  *       - frame_rate_numer - uint32_t, numerator of the frame rate
495*3a9fd824SRoger Pau Monné  *       - frame_rate_denom - uint32_t, denominator of the frame rate
496*3a9fd824SRoger Pau Monné  *     The corresponding frame rate (Hz) is calculated as:
497*3a9fd824SRoger Pau Monné  *       frame_rate = frame_rate_numer / frame_rate_denom
498*3a9fd824SRoger Pau Monné  *   - buffer index is a zero based index of the buffer. Must be less than
499*3a9fd824SRoger Pau Monné  *     the value of XENCAMERA_OP_CONFIG_SET.num_bufs response:
500*3a9fd824SRoger Pau Monné  *       - index - uint8_t, index of the buffer.
501*3a9fd824SRoger Pau Monné  *
502*3a9fd824SRoger Pau Monné  *
503*3a9fd824SRoger Pau Monné  *---------------------------------- Requests ---------------------------------
504*3a9fd824SRoger Pau Monné  *
505*3a9fd824SRoger Pau Monné  * All request packets have the same length (64 octets).
506*3a9fd824SRoger Pau Monné  * All request packets have common header:
507*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
508*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
509*3a9fd824SRoger Pau Monné  * |               id                |    operation   |   reserved     | 4
510*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
511*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
512*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
513*3a9fd824SRoger Pau Monné  *   id - uint16_t, private guest value, echoed in response.
514*3a9fd824SRoger Pau Monné  *   operation - uint8_t, operation code, XENCAMERA_OP_XXX.
515*3a9fd824SRoger Pau Monné  *
516*3a9fd824SRoger Pau Monné  *
517*3a9fd824SRoger Pau Monné  * Request to set/validate the configuration - request to set the
518*3a9fd824SRoger Pau Monné  * configuration/mode of the camera (XENCAMERA_OP_CONFIG_SET) or to
519*3a9fd824SRoger Pau Monné  * check if the configuration is valid and can be used
520*3a9fd824SRoger Pau Monné  * (XENCAMERA_OP_CONFIG_VALIDATE):
521*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
522*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
523*3a9fd824SRoger Pau Monné  * |               id                | _OP_CONFIG_XXX |   reserved     | 4
524*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
525*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
526*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
527*3a9fd824SRoger Pau Monné  * |                            pixel format                           | 12
528*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
529*3a9fd824SRoger Pau Monné  * |                               width                               | 16
530*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
531*3a9fd824SRoger Pau Monné  * |                               height                              | 20
532*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
533*3a9fd824SRoger Pau Monné  * |                             reserved                              | 24
534*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
535*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
536*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
537*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
538*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
539*3a9fd824SRoger Pau Monné  *
540*3a9fd824SRoger Pau Monné  * pixel_format - uint32_t, pixel format to be used, FOURCC code.
541*3a9fd824SRoger Pau Monné  * width - uint32_t, width in pixels.
542*3a9fd824SRoger Pau Monné  * height - uint32_t, height in pixels.
543*3a9fd824SRoger Pau Monné  *
544*3a9fd824SRoger Pau Monné  * See response format for this request.
545*3a9fd824SRoger Pau Monné  *
546*3a9fd824SRoger Pau Monné  * Notes:
547*3a9fd824SRoger Pau Monné  *  - the only difference between XENCAMERA_OP_CONFIG_VALIDATE and
548*3a9fd824SRoger Pau Monné  *    XENCAMERA_OP_CONFIG_SET is that the former doesn't actually change
549*3a9fd824SRoger Pau Monné  *    camera configuration, but queries if the configuration is valid.
550*3a9fd824SRoger Pau Monné  *    This can be used while stream is active and/or buffers allocated.
551*3a9fd824SRoger Pau Monné  *  - frontend must check the corresponding response in order to see
552*3a9fd824SRoger Pau Monné  *    if the values reported back by the backend do match the desired ones
553*3a9fd824SRoger Pau Monné  *    and can be accepted.
554*3a9fd824SRoger Pau Monné  *  - frontend may send multiple XENCAMERA_OP_CONFIG_SET requests before
555*3a9fd824SRoger Pau Monné  *    sending XENCAMERA_OP_STREAM_START request to update or tune the
556*3a9fd824SRoger Pau Monné  *    final stream configuration.
557*3a9fd824SRoger Pau Monné  *  - configuration cannot be changed during active streaming, e.g.
558*3a9fd824SRoger Pau Monné  *    after XENCAMERA_OP_STREAM_START and before XENCAMERA_OP_STREAM_STOP
559*3a9fd824SRoger Pau Monné  *    requests.
560*3a9fd824SRoger Pau Monné  */
561*3a9fd824SRoger Pau Monné struct xencamera_config_req {
562*3a9fd824SRoger Pau Monné     uint32_t pixel_format;
563*3a9fd824SRoger Pau Monné     uint32_t width;
564*3a9fd824SRoger Pau Monné     uint32_t height;
565*3a9fd824SRoger Pau Monné };
566*3a9fd824SRoger Pau Monné 
567*3a9fd824SRoger Pau Monné /*
568*3a9fd824SRoger Pau Monné  * Request current configuration of the camera:
569*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
570*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
571*3a9fd824SRoger Pau Monné  * |               id                | _OP_CONFIG_GET |   reserved     | 4
572*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
573*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
574*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
575*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
576*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
577*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
578*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
579*3a9fd824SRoger Pau Monné  *
580*3a9fd824SRoger Pau Monné  * See response format for this request.
581*3a9fd824SRoger Pau Monné  *
582*3a9fd824SRoger Pau Monné  *
583*3a9fd824SRoger Pau Monné  * Request to set the frame rate of the stream:
584*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
585*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
586*3a9fd824SRoger Pau Monné  * |               id                | _FRAME_RATE_SET|   reserved     | 4
587*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
588*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
589*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
590*3a9fd824SRoger Pau Monné  * |                          frame_rate_numer                         | 12
591*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
592*3a9fd824SRoger Pau Monné  * |                          frame_rate_denom                         | 16
593*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
594*3a9fd824SRoger Pau Monné  * |                             reserved                              | 20
595*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
596*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
597*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
598*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
599*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
600*3a9fd824SRoger Pau Monné  *
601*3a9fd824SRoger Pau Monné  * frame_rate_numer - uint32_t, numerator of the frame rate.
602*3a9fd824SRoger Pau Monné  * frame_rate_denom - uint32_t, denominator of the frame rate.
603*3a9fd824SRoger Pau Monné  *
604*3a9fd824SRoger Pau Monné  * Notes:
605*3a9fd824SRoger Pau Monné  *  - to query the current (actual) frame rate use XENCAMERA_OP_CONFIG_GET
606*3a9fd824SRoger Pau Monné  *    request.
607*3a9fd824SRoger Pau Monné  *  - this request can be used with camera buffers allocated, but stream
608*3a9fd824SRoger Pau Monné  *    stopped, e.g. frontend is allowed to stop the stream with
609*3a9fd824SRoger Pau Monné  *    XENCAMERA_OP_STREAM_STOP, hold the buffers allocated (e.g. keep the
610*3a9fd824SRoger Pau Monné  *    configuration set with XENCAMERA_OP_CONFIG_SET), change the
611*3a9fd824SRoger Pau Monné  *    frame rate of the stream and (re)start the stream again with
612*3a9fd824SRoger Pau Monné  *    XENCAMERA_OP_STREAM_START.
613*3a9fd824SRoger Pau Monné  *  - frame rate cannot be changed during active streaming, e.g.
614*3a9fd824SRoger Pau Monné  *    after XENCAMERA_OP_STREAM_START and before XENCAMERA_OP_STREAM_STOP
615*3a9fd824SRoger Pau Monné  *    commands.
616*3a9fd824SRoger Pau Monné  */
617*3a9fd824SRoger Pau Monné struct xencamera_frame_rate_req {
618*3a9fd824SRoger Pau Monné     uint32_t frame_rate_numer;
619*3a9fd824SRoger Pau Monné     uint32_t frame_rate_denom;
620*3a9fd824SRoger Pau Monné };
621*3a9fd824SRoger Pau Monné 
622*3a9fd824SRoger Pau Monné /*
623*3a9fd824SRoger Pau Monné  * Request camera buffer's layout:
624*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
625*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
626*3a9fd824SRoger Pau Monné  * |               id                | _BUF_GET_LAYOUT|   reserved     | 4
627*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
628*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
629*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
630*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
631*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
632*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
633*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
634*3a9fd824SRoger Pau Monné  *
635*3a9fd824SRoger Pau Monné  * See response format for this request.
636*3a9fd824SRoger Pau Monné  *
637*3a9fd824SRoger Pau Monné  *
638*3a9fd824SRoger Pau Monné  * Request number of buffers to be used:
639*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
640*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
641*3a9fd824SRoger Pau Monné  * |               id                | _OP_BUF_REQUEST|   reserved     | 4
642*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
643*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
644*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
645*3a9fd824SRoger Pau Monné  * |    num_bufs    |                     reserved                     | 12
646*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
647*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
648*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
649*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
650*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
651*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
652*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
653*3a9fd824SRoger Pau Monné  *
654*3a9fd824SRoger Pau Monné  * num_bufs - uint8_t, desired number of buffers to be used.
655*3a9fd824SRoger Pau Monné  *
656*3a9fd824SRoger Pau Monné  * If num_bufs is not zero then the backend validates the requested number of
657*3a9fd824SRoger Pau Monné  * buffers and responds with the number of buffers allowed for this frontend.
658*3a9fd824SRoger Pau Monné  * Frontend is responsible for checking the corresponding response in order to
659*3a9fd824SRoger Pau Monné  * see if the values reported back by the backend do match the desired ones
660*3a9fd824SRoger Pau Monné  * and can be accepted.
661*3a9fd824SRoger Pau Monné  * Frontend is allowed to send multiple XENCAMERA_OP_BUF_REQUEST requests
662*3a9fd824SRoger Pau Monné  * before sending XENCAMERA_OP_STREAM_START request to update or tune the
663*3a9fd824SRoger Pau Monné  * final configuration.
664*3a9fd824SRoger Pau Monné  * Frontend is not allowed to change the camera configuration after this call
665*3a9fd824SRoger Pau Monné  * with a non-zero value of num_bufs. If camera reconfiguration is required
666*3a9fd824SRoger Pau Monné  * then this request must be sent with num_bufs set to zero and any created
667*3a9fd824SRoger Pau Monné  * buffers must be destroyed first.
668*3a9fd824SRoger Pau Monné  * Frontend is not allowed to change the number of buffers after the
669*3a9fd824SRoger Pau Monné  * streaming has started.
670*3a9fd824SRoger Pau Monné  *
671*3a9fd824SRoger Pau Monné  * If num_bufs is 0 and streaming has not started yet, then the backend will
672*3a9fd824SRoger Pau Monné  * free all previously allocated buffers (if any).
673*3a9fd824SRoger Pau Monné  * Trying to call this if streaming is in progress will result in an error.
674*3a9fd824SRoger Pau Monné  *
675*3a9fd824SRoger Pau Monné  * If camera reconfiguration is required then the streaming must be stopped
676*3a9fd824SRoger Pau Monné  * and this request must be sent with num_bufs set to zero and any
677*3a9fd824SRoger Pau Monné  * created buffers must be destroyed.
678*3a9fd824SRoger Pau Monné  *
679*3a9fd824SRoger Pau Monné  * Please note, that the number of buffers in this request must not exceed
680*3a9fd824SRoger Pau Monné  * the value configured in XenStore.max-buffers.
681*3a9fd824SRoger Pau Monné  *
682*3a9fd824SRoger Pau Monné  * See response format for this request.
683*3a9fd824SRoger Pau Monné  */
684*3a9fd824SRoger Pau Monné struct xencamera_buf_request {
685*3a9fd824SRoger Pau Monné     uint8_t num_bufs;
686*3a9fd824SRoger Pau Monné };
687*3a9fd824SRoger Pau Monné 
688*3a9fd824SRoger Pau Monné /*
689*3a9fd824SRoger Pau Monné  * Request camera buffer creation:
690*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
691*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
692*3a9fd824SRoger Pau Monné  * |               id                | _OP_BUF_CREATE |   reserved     | 4
693*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
694*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
695*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
696*3a9fd824SRoger Pau Monné  * |      index     |                     reserved                     | 12
697*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
698*3a9fd824SRoger Pau Monné  * |                           plane_offset[0]                         | 16
699*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
700*3a9fd824SRoger Pau Monné  * |                           plane_offset[1]                         | 20
701*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
702*3a9fd824SRoger Pau Monné  * |                           plane_offset[2]                         | 24
703*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
704*3a9fd824SRoger Pau Monné  * |                           plane_offset[3]                         | 28
705*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
706*3a9fd824SRoger Pau Monné  * |                           gref_directory                          | 32
707*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
708*3a9fd824SRoger Pau Monné  * |                             reserved                              | 36
709*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
710*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
711*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
712*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
713*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
714*3a9fd824SRoger Pau Monné  *
715*3a9fd824SRoger Pau Monné  * An attempt to create multiple buffers with the same index is an error.
716*3a9fd824SRoger Pau Monné  * index can be re-used after destroying the corresponding camera buffer.
717*3a9fd824SRoger Pau Monné  *
718*3a9fd824SRoger Pau Monné  * index - uint8_t, index of the buffer to be created in the range
719*3a9fd824SRoger Pau Monné  *   from 0 to the num_bufs field returned in response for
720*3a9fd824SRoger Pau Monné  *   XENCAMERA_OP_BUF_REQUEST request
721*3a9fd824SRoger Pau Monné  * plane_offset - array of uint32_t, offset of the corresponding plane
722*3a9fd824SRoger Pau Monné  *   in octets from the buffer start. Number of offsets returned is
723*3a9fd824SRoger Pau Monné  *   equal to the value returned in XENCAMERA_OP_BUF_GET_LAYOUT.num_planes.
724*3a9fd824SRoger Pau Monné  * gref_directory - grant_ref_t, a reference to the first shared page
725*3a9fd824SRoger Pau Monné  *   describing shared buffer references. The size of the buffer is equal to
726*3a9fd824SRoger Pau Monné  *   XENCAMERA_OP_BUF_GET_LAYOUT.size response. At least one page exists. If
727*3a9fd824SRoger Pau Monné  *   shared buffer size exceeds what can be addressed by this single page,
728*3a9fd824SRoger Pau Monné  *   then reference to the next shared page must be supplied (see
729*3a9fd824SRoger Pau Monné  *   gref_dir_next_page below).
730*3a9fd824SRoger Pau Monné  *
731*3a9fd824SRoger Pau Monné  * If XENCAMERA_FIELD_BE_ALLOC configuration entry is set, then backend will
732*3a9fd824SRoger Pau Monné  * allocate the buffer with the parameters provided in this request and page
733*3a9fd824SRoger Pau Monné  * directory is handled as follows:
734*3a9fd824SRoger Pau Monné  *   Frontend on request:
735*3a9fd824SRoger Pau Monné  *     - allocates pages for the directory (gref_directory,
736*3a9fd824SRoger Pau Monné  *       gref_dir_next_page(s)
737*3a9fd824SRoger Pau Monné  *     - grants permissions for the pages of the directory to the backend
738*3a9fd824SRoger Pau Monné  *     - sets gref_dir_next_page fields
739*3a9fd824SRoger Pau Monné  *   Backend on response:
740*3a9fd824SRoger Pau Monné  *     - grants permissions for the pages of the buffer allocated to
741*3a9fd824SRoger Pau Monné  *       the frontend
742*3a9fd824SRoger Pau Monné  *     - fills in page directory with grant references
743*3a9fd824SRoger Pau Monné  *       (gref[] in struct xencamera_page_directory)
744*3a9fd824SRoger Pau Monné  */
745*3a9fd824SRoger Pau Monné struct xencamera_buf_create_req {
746*3a9fd824SRoger Pau Monné     uint8_t index;
747*3a9fd824SRoger Pau Monné     uint8_t reserved[3];
748*3a9fd824SRoger Pau Monné     uint32_t plane_offset[XENCAMERA_MAX_PLANE];
749*3a9fd824SRoger Pau Monné     grant_ref_t gref_directory;
750*3a9fd824SRoger Pau Monné };
751*3a9fd824SRoger Pau Monné 
752*3a9fd824SRoger Pau Monné /*
753*3a9fd824SRoger Pau Monné  * Shared page for XENCAMERA_OP_BUF_CREATE buffer descriptor (gref_directory in
754*3a9fd824SRoger Pau Monné  * the request) employs a list of pages, describing all pages of the shared
755*3a9fd824SRoger Pau Monné  * data buffer:
756*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
757*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
758*3a9fd824SRoger Pau Monné  * |                        gref_dir_next_page                         | 4
759*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
760*3a9fd824SRoger Pau Monné  * |                              gref[0]                              | 8
761*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
762*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
763*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
764*3a9fd824SRoger Pau Monné  * |                              gref[i]                              | i*4+8
765*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
766*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
767*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
768*3a9fd824SRoger Pau Monné  * |                             gref[N - 1]                           | N*4+8
769*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
770*3a9fd824SRoger Pau Monné  *
771*3a9fd824SRoger Pau Monné  * gref_dir_next_page - grant_ref_t, reference to the next page describing
772*3a9fd824SRoger Pau Monné  *   page directory. Must be 0 if there are no more pages in the list.
773*3a9fd824SRoger Pau Monné  * gref[i] - grant_ref_t, reference to a shared page of the buffer
774*3a9fd824SRoger Pau Monné  *   allocated at XENCAMERA_OP_BUF_CREATE.
775*3a9fd824SRoger Pau Monné  *
776*3a9fd824SRoger Pau Monné  * Number of grant_ref_t entries in the whole page directory is not
777*3a9fd824SRoger Pau Monné  * passed, but instead can be calculated as:
778*3a9fd824SRoger Pau Monné  *   num_grefs_total = (XENCAMERA_OP_BUF_REQUEST.size + XEN_PAGE_SIZE - 1) /
779*3a9fd824SRoger Pau Monné  *       XEN_PAGE_SIZE
780*3a9fd824SRoger Pau Monné  */
781*3a9fd824SRoger Pau Monné struct xencamera_page_directory {
782*3a9fd824SRoger Pau Monné     grant_ref_t gref_dir_next_page;
783*3a9fd824SRoger Pau Monné     grant_ref_t gref[1]; /* Variable length */
784*3a9fd824SRoger Pau Monné };
785*3a9fd824SRoger Pau Monné 
786*3a9fd824SRoger Pau Monné /*
787*3a9fd824SRoger Pau Monné  * Request buffer destruction - destroy a previously allocated camera buffer:
788*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
789*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
790*3a9fd824SRoger Pau Monné  * |               id                | _OP_BUF_DESTROY|   reserved     | 4
791*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
792*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
793*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
794*3a9fd824SRoger Pau Monné  * |      index     |                     reserved                     | 12
795*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
796*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
797*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
798*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
799*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
800*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
801*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
802*3a9fd824SRoger Pau Monné  *
803*3a9fd824SRoger Pau Monné  * index - uint8_t, index of the buffer to be destroyed.
804*3a9fd824SRoger Pau Monné  *
805*3a9fd824SRoger Pau Monné  *
806*3a9fd824SRoger Pau Monné  * Request queueing of the buffer for backend use:
807*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
808*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
809*3a9fd824SRoger Pau Monné  * |               id                | _OP_BUF_QUEUE  |   reserved     | 4
810*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
811*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
812*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
813*3a9fd824SRoger Pau Monné  * |      index     |                     reserved                     | 12
814*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
815*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
816*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
817*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
818*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
819*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
820*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
821*3a9fd824SRoger Pau Monné  *
822*3a9fd824SRoger Pau Monné  * Notes:
823*3a9fd824SRoger Pau Monné  *  - frontends must not access the buffer content after this request until
824*3a9fd824SRoger Pau Monné  *    response to XENCAMERA_OP_BUF_DEQUEUE has been received.
825*3a9fd824SRoger Pau Monné  *  - buffers must be queued to the backend before destroying them with
826*3a9fd824SRoger Pau Monné  *    XENCAMERA_OP_BUF_DESTROY.
827*3a9fd824SRoger Pau Monné  *
828*3a9fd824SRoger Pau Monné  * index - uint8_t, index of the buffer to be queued.
829*3a9fd824SRoger Pau Monné  *
830*3a9fd824SRoger Pau Monné  *
831*3a9fd824SRoger Pau Monné  * Request dequeueing of the buffer for frontend use:
832*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
833*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
834*3a9fd824SRoger Pau Monné  * |               id                |_OP_BUF_DEQUEUE |   reserved     | 4
835*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
836*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
837*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
838*3a9fd824SRoger Pau Monné  * |      index     |                     reserved                     | 12
839*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
840*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
841*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
842*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
843*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
844*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
845*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
846*3a9fd824SRoger Pau Monné  *
847*3a9fd824SRoger Pau Monné  * Notes:
848*3a9fd824SRoger Pau Monné  *  - frontend is allowed to access the buffer content after the corresponding
849*3a9fd824SRoger Pau Monné  *    response to this request.
850*3a9fd824SRoger Pau Monné  *
851*3a9fd824SRoger Pau Monné  * index - uint8_t, index of the buffer to be queued.
852*3a9fd824SRoger Pau Monné  *
853*3a9fd824SRoger Pau Monné  *
854*3a9fd824SRoger Pau Monné  * Request camera control details:
855*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
856*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
857*3a9fd824SRoger Pau Monné  * |               id                | _OP_CTRL_ENUM  |   reserved     | 4
858*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
859*3a9fd824SRoger Pau Monné  * |      index     |                     reserved                     | 8
860*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
861*3a9fd824SRoger Pau Monné  * |                             reserved                              | 12
862*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
863*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
864*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
865*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
866*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
867*3a9fd824SRoger Pau Monné  *
868*3a9fd824SRoger Pau Monné  * See response format for this request.
869*3a9fd824SRoger Pau Monné  *
870*3a9fd824SRoger Pau Monné  * index - uint8_t, index of the control to be queried.
871*3a9fd824SRoger Pau Monné  */
872*3a9fd824SRoger Pau Monné struct xencamera_index {
873*3a9fd824SRoger Pau Monné     uint8_t index;
874*3a9fd824SRoger Pau Monné };
875*3a9fd824SRoger Pau Monné 
876*3a9fd824SRoger Pau Monné /*
877*3a9fd824SRoger Pau Monné  * Request camera control change:
878*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
879*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
880*3a9fd824SRoger Pau Monné  * |               id                |  _OP_SET_CTRL  |   reserved     | 4
881*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
882*3a9fd824SRoger Pau Monné  * |       type     |                     reserved                     | 8
883*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
884*3a9fd824SRoger Pau Monné  * |                             reserved                              | 12
885*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
886*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
887*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
888*3a9fd824SRoger Pau Monné  * |                          value low 32-bit                         | 20
889*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
890*3a9fd824SRoger Pau Monné  * |                          value high 32-bit                        | 24
891*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
892*3a9fd824SRoger Pau Monné  * |                             reserved                              | 28
893*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
894*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
895*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
896*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
897*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
898*3a9fd824SRoger Pau Monné  *
899*3a9fd824SRoger Pau Monné  * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
900*3a9fd824SRoger Pau Monné  * value - int64_t, new value of the control.
901*3a9fd824SRoger Pau Monné  */
902*3a9fd824SRoger Pau Monné struct xencamera_ctrl_value {
903*3a9fd824SRoger Pau Monné     uint8_t type;
904*3a9fd824SRoger Pau Monné     uint8_t reserved[7];
905*3a9fd824SRoger Pau Monné     int64_t value;
906*3a9fd824SRoger Pau Monné };
907*3a9fd824SRoger Pau Monné 
908*3a9fd824SRoger Pau Monné /*
909*3a9fd824SRoger Pau Monné  * Request camera control state:
910*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
911*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
912*3a9fd824SRoger Pau Monné  * |               id                |  _OP_GET_CTRL  |   reserved     | 4
913*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
914*3a9fd824SRoger Pau Monné  * |       type     |                     reserved                     | 8
915*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
916*3a9fd824SRoger Pau Monné  * |                             reserved                              | 12
917*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
918*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
919*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
920*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
921*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
922*3a9fd824SRoger Pau Monné  *
923*3a9fd824SRoger Pau Monné  * See response format for this request.
924*3a9fd824SRoger Pau Monné  *
925*3a9fd824SRoger Pau Monné  * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
926*3a9fd824SRoger Pau Monné  */
927*3a9fd824SRoger Pau Monné struct xencamera_get_ctrl_req {
928*3a9fd824SRoger Pau Monné     uint8_t type;
929*3a9fd824SRoger Pau Monné };
930*3a9fd824SRoger Pau Monné 
931*3a9fd824SRoger Pau Monné /*
932*3a9fd824SRoger Pau Monné  * Request camera capture stream start:
933*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
934*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
935*3a9fd824SRoger Pau Monné  * |               id                |_OP_STREAM_START|   reserved     | 4
936*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
937*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
938*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
939*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
940*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
941*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
942*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
943*3a9fd824SRoger Pau Monné  *
944*3a9fd824SRoger Pau Monné  *
945*3a9fd824SRoger Pau Monné  * Request camera capture stream stop:
946*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
947*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
948*3a9fd824SRoger Pau Monné  * |               id                |_OP_STREAM_STOP |   reserved     | 4
949*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
950*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
951*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
952*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
953*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
954*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
955*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
956*3a9fd824SRoger Pau Monné  *
957*3a9fd824SRoger Pau Monné  *
958*3a9fd824SRoger Pau Monné  *---------------------------------- Responses --------------------------------
959*3a9fd824SRoger Pau Monné  *
960*3a9fd824SRoger Pau Monné  * All response packets have the same length (64 octets).
961*3a9fd824SRoger Pau Monné  *
962*3a9fd824SRoger Pau Monné  * All response packets have common header:
963*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
964*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
965*3a9fd824SRoger Pau Monné  * |               id                |    operation   |    reserved    | 4
966*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
967*3a9fd824SRoger Pau Monné  * |                              status                               | 8
968*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
969*3a9fd824SRoger Pau Monné  *
970*3a9fd824SRoger Pau Monné  * id - uint16_t, copied from the request.
971*3a9fd824SRoger Pau Monné  * operation - uint8_t, XENCAMERA_OP_* - copied from request.
972*3a9fd824SRoger Pau Monné  * status - int32_t, response status, zero on success and -XEN_EXX on failure.
973*3a9fd824SRoger Pau Monné  *
974*3a9fd824SRoger Pau Monné  *
975*3a9fd824SRoger Pau Monné  * Configuration response - response for XENCAMERA_OP_CONFIG_SET,
976*3a9fd824SRoger Pau Monné  * XENCAMERA_OP_CONFIG_GET and XENCAMERA_OP_CONFIG_VALIDATE requests:
977*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
978*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
979*3a9fd824SRoger Pau Monné  * |               id                | _OP_CONFIG_XXX |    reserved    | 4
980*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
981*3a9fd824SRoger Pau Monné  * |                               status                              | 8
982*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
983*3a9fd824SRoger Pau Monné  * |                            pixel format                           | 12
984*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
985*3a9fd824SRoger Pau Monné  * |                               width                               | 16
986*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
987*3a9fd824SRoger Pau Monné  * |                               height                              | 20
988*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
989*3a9fd824SRoger Pau Monné  * |                             colorspace                            | 24
990*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
991*3a9fd824SRoger Pau Monné  * |                             xfer_func                             | 28
992*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
993*3a9fd824SRoger Pau Monné  * |                             ycbcr_enc                             | 32
994*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
995*3a9fd824SRoger Pau Monné  * |                            quantization                           | 36
996*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
997*3a9fd824SRoger Pau Monné  * |                       displ_asp_ratio_numer                       | 40
998*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
999*3a9fd824SRoger Pau Monné  * |                       displ_asp_ratio_denom                       | 44
1000*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1001*3a9fd824SRoger Pau Monné  * |                          frame_rate_numer                         | 48
1002*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1003*3a9fd824SRoger Pau Monné  * |                          frame_rate_denom                         | 52
1004*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1005*3a9fd824SRoger Pau Monné  * |                             reserved                              | 56
1006*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1007*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
1008*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1009*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
1010*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1011*3a9fd824SRoger Pau Monné  *
1012*3a9fd824SRoger Pau Monné  * Meaning of the corresponding values in this response is the same as for
1013*3a9fd824SRoger Pau Monné  * XENCAMERA_OP_CONFIG_SET and XENCAMERA_OP_FRAME_RATE_SET requests.
1014*3a9fd824SRoger Pau Monné  *
1015*3a9fd824SRoger Pau Monné  * colorspace - uint32_t, this supplements pixel_format parameter,
1016*3a9fd824SRoger Pau Monné  *   one of the XENCAMERA_COLORSPACE_XXX.
1017*3a9fd824SRoger Pau Monné  * xfer_func - uint32_t, this supplements colorspace parameter,
1018*3a9fd824SRoger Pau Monné  *   one of the XENCAMERA_XFER_FUNC_XXX.
1019*3a9fd824SRoger Pau Monné  * ycbcr_enc - uint32_t, this supplements colorspace parameter,
1020*3a9fd824SRoger Pau Monné  *   one of the XENCAMERA_YCBCR_ENC_XXX. Please note, that ycbcr_enc is only
1021*3a9fd824SRoger Pau Monné  *   valid for YCbCr pixelformats and should be ignored otherwise.
1022*3a9fd824SRoger Pau Monné  * quantization - uint32_t, this supplements colorspace parameter,
1023*3a9fd824SRoger Pau Monné  *   one of the XENCAMERA_QUANTIZATION_XXX.
1024*3a9fd824SRoger Pau Monné  * displ_asp_ratio_numer - uint32_t, numerator of the display aspect ratio.
1025*3a9fd824SRoger Pau Monné  * displ_asp_ratio_denom - uint32_t, denominator of the display aspect ratio.
1026*3a9fd824SRoger Pau Monné  */
1027*3a9fd824SRoger Pau Monné struct xencamera_config_resp {
1028*3a9fd824SRoger Pau Monné     uint32_t pixel_format;
1029*3a9fd824SRoger Pau Monné     uint32_t width;
1030*3a9fd824SRoger Pau Monné     uint32_t height;
1031*3a9fd824SRoger Pau Monné     uint32_t colorspace;
1032*3a9fd824SRoger Pau Monné     uint32_t xfer_func;
1033*3a9fd824SRoger Pau Monné     uint32_t ycbcr_enc;
1034*3a9fd824SRoger Pau Monné     uint32_t quantization;
1035*3a9fd824SRoger Pau Monné     uint32_t displ_asp_ratio_numer;
1036*3a9fd824SRoger Pau Monné     uint32_t displ_asp_ratio_denom;
1037*3a9fd824SRoger Pau Monné     uint32_t frame_rate_numer;
1038*3a9fd824SRoger Pau Monné     uint32_t frame_rate_denom;
1039*3a9fd824SRoger Pau Monné };
1040*3a9fd824SRoger Pau Monné 
1041*3a9fd824SRoger Pau Monné /*
1042*3a9fd824SRoger Pau Monné  * Request buffer response - response for XENCAMERA_OP_BUF_GET_LAYOUT
1043*3a9fd824SRoger Pau Monné  * request:
1044*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
1045*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1046*3a9fd824SRoger Pau Monné  * |               id                |_BUF_GET_LAYOUT |    reserved    | 4
1047*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1048*3a9fd824SRoger Pau Monné  * |                               status                              | 8
1049*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1050*3a9fd824SRoger Pau Monné  * |   num_planes   |                     reserved                     | 12
1051*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1052*3a9fd824SRoger Pau Monné  * |                                size                               | 16
1053*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1054*3a9fd824SRoger Pau Monné  * |                           plane_size[0]                           | 20
1055*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1056*3a9fd824SRoger Pau Monné  * |                           plane_size[1]                           | 24
1057*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1058*3a9fd824SRoger Pau Monné  * |                           plane_size[2]                           | 28
1059*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1060*3a9fd824SRoger Pau Monné  * |                           plane_size[3]                           | 32
1061*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1062*3a9fd824SRoger Pau Monné  * |                          plane_stride[0]                          | 36
1063*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1064*3a9fd824SRoger Pau Monné  * |                          plane_stride[1]                          | 40
1065*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1066*3a9fd824SRoger Pau Monné  * |                          plane_stride[2]                          | 44
1067*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1068*3a9fd824SRoger Pau Monné  * |                          plane_stride[3]                          | 48
1069*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1070*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
1071*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1072*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
1073*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1074*3a9fd824SRoger Pau Monné  *
1075*3a9fd824SRoger Pau Monné  * num_planes - uint8_t, number of planes of the buffer.
1076*3a9fd824SRoger Pau Monné  * size - uint32_t, overall size of the buffer including sizes of the
1077*3a9fd824SRoger Pau Monné  *   individual planes and padding if applicable.
1078*3a9fd824SRoger Pau Monné  * plane_size - array of uint32_t, size in octets of the corresponding plane
1079*3a9fd824SRoger Pau Monné  *   including padding.
1080*3a9fd824SRoger Pau Monné  * plane_stride - array of uint32_t, size in octets occupied by the
1081*3a9fd824SRoger Pau Monné  *   corresponding single image line including padding if applicable.
1082*3a9fd824SRoger Pau Monné  *
1083*3a9fd824SRoger Pau Monné  * Note! The sizes and strides in this response apply to all buffers created
1084*3a9fd824SRoger Pau Monné  * with XENCAMERA_OP_BUF_CREATE command, but individual buffers may have
1085*3a9fd824SRoger Pau Monné  * different plane offsets, see XENCAMERA_OP_BUF_REQUEST.plane_offset.
1086*3a9fd824SRoger Pau Monné  */
1087*3a9fd824SRoger Pau Monné struct xencamera_buf_get_layout_resp {
1088*3a9fd824SRoger Pau Monné     uint8_t num_planes;
1089*3a9fd824SRoger Pau Monné     uint8_t reserved[3];
1090*3a9fd824SRoger Pau Monné     uint32_t size;
1091*3a9fd824SRoger Pau Monné     uint32_t plane_size[XENCAMERA_MAX_PLANE];
1092*3a9fd824SRoger Pau Monné     uint32_t plane_stride[XENCAMERA_MAX_PLANE];
1093*3a9fd824SRoger Pau Monné };
1094*3a9fd824SRoger Pau Monné 
1095*3a9fd824SRoger Pau Monné /*
1096*3a9fd824SRoger Pau Monné  * Request buffer response - response for XENCAMERA_OP_BUF_REQUEST
1097*3a9fd824SRoger Pau Monné  * request:
1098*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
1099*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1100*3a9fd824SRoger Pau Monné  * |               id                |_OP_BUF_REQUEST |    reserved    | 4
1101*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1102*3a9fd824SRoger Pau Monné  * |                               status                              | 8
1103*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1104*3a9fd824SRoger Pau Monné  * |   num_buffers  |                     reserved                     | 12
1105*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1106*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
1107*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1108*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
1109*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1110*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
1111*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1112*3a9fd824SRoger Pau Monné  *
1113*3a9fd824SRoger Pau Monné  * num_buffers - uint8_t, number of buffers to be used.
1114*3a9fd824SRoger Pau Monné  *
1115*3a9fd824SRoger Pau Monné  *
1116*3a9fd824SRoger Pau Monné  * Control enumerate response - response for XENCAMERA_OP_CTRL_ENUM:
1117*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
1118*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1119*3a9fd824SRoger Pau Monné  * |               id                | _OP_CTRL_ENUM  |    reserved    | 4
1120*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1121*3a9fd824SRoger Pau Monné  * |                               status                              | 8
1122*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1123*3a9fd824SRoger Pau Monné  * |     index      |      type      |            reserved             | 12
1124*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1125*3a9fd824SRoger Pau Monné  * |                               flags                               | 16
1126*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1127*3a9fd824SRoger Pau Monné  * |                          min low 32-bits                          | 20
1128*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1129*3a9fd824SRoger Pau Monné  * |                          min high 32-bits                         | 24
1130*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1131*3a9fd824SRoger Pau Monné  * |                          max low 32-bits                          | 28
1132*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1133*3a9fd824SRoger Pau Monné  * |                          max high 32-bits                         | 32
1134*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1135*3a9fd824SRoger Pau Monné  * |                         step low 32-bits                          | 36
1136*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1137*3a9fd824SRoger Pau Monné  * |                         step high 32-bits                         | 40
1138*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1139*3a9fd824SRoger Pau Monné  * |                        def_val low 32-bits                        | 44
1140*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1141*3a9fd824SRoger Pau Monné  * |                        def_val high 32-bits                       | 48
1142*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1143*3a9fd824SRoger Pau Monné  * |                             reserved                              | 52
1144*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1145*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
1146*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1147*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
1148*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1149*3a9fd824SRoger Pau Monné  *
1150*3a9fd824SRoger Pau Monné  * index - uint8_t, index of the camera control in response.
1151*3a9fd824SRoger Pau Monné  * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
1152*3a9fd824SRoger Pau Monné  * flags - uint32_t, flags of the control, one of the XENCAMERA_CTRL_FLG_XXX.
1153*3a9fd824SRoger Pau Monné  * min - int64_t, minimum value of the control.
1154*3a9fd824SRoger Pau Monné  * max - int64_t, maximum value of the control.
1155*3a9fd824SRoger Pau Monné  * step - int64_t, minimum size in which control value can be changed.
1156*3a9fd824SRoger Pau Monné  * def_val - int64_t, default value of the control.
1157*3a9fd824SRoger Pau Monné  */
1158*3a9fd824SRoger Pau Monné struct xencamera_ctrl_enum_resp {
1159*3a9fd824SRoger Pau Monné     uint8_t index;
1160*3a9fd824SRoger Pau Monné     uint8_t type;
1161*3a9fd824SRoger Pau Monné     uint8_t reserved[2];
1162*3a9fd824SRoger Pau Monné     uint32_t flags;
1163*3a9fd824SRoger Pau Monné     int64_t min;
1164*3a9fd824SRoger Pau Monné     int64_t max;
1165*3a9fd824SRoger Pau Monné     int64_t step;
1166*3a9fd824SRoger Pau Monné     int64_t def_val;
1167*3a9fd824SRoger Pau Monné };
1168*3a9fd824SRoger Pau Monné 
1169*3a9fd824SRoger Pau Monné /*
1170*3a9fd824SRoger Pau Monné  * Get control response - response for XENCAMERA_OP_CTRL_GET:
1171*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
1172*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1173*3a9fd824SRoger Pau Monné  * |               id                | _OP_CTRL_GET   |    reserved    | 4
1174*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1175*3a9fd824SRoger Pau Monné  * |                               status                              | 8
1176*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1177*3a9fd824SRoger Pau Monné  * |       type     |                     reserved                     | 12
1178*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1179*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
1180*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1181*3a9fd824SRoger Pau Monné  * |                             reserved                              | 20
1182*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1183*3a9fd824SRoger Pau Monné  * |                          value low 32-bit                         | 24
1184*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1185*3a9fd824SRoger Pau Monné  * |                          value high 32-bit                        | 28
1186*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1187*3a9fd824SRoger Pau Monné  * |                             reserved                              | 32
1188*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1189*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
1190*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1191*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
1192*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1193*3a9fd824SRoger Pau Monné  *
1194*3a9fd824SRoger Pau Monné  * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
1195*3a9fd824SRoger Pau Monné  * value - int64_t, new value of the control.
1196*3a9fd824SRoger Pau Monné  */
1197*3a9fd824SRoger Pau Monné 
1198*3a9fd824SRoger Pau Monné /*
1199*3a9fd824SRoger Pau Monné  *----------------------------------- Events ----------------------------------
1200*3a9fd824SRoger Pau Monné  *
1201*3a9fd824SRoger Pau Monné  * Events are sent via a shared page allocated by the front and propagated by
1202*3a9fd824SRoger Pau Monné  *   evt-event-channel/evt-ring-ref XenStore entries.
1203*3a9fd824SRoger Pau Monné  *
1204*3a9fd824SRoger Pau Monné  * All event packets have the same length (64 octets).
1205*3a9fd824SRoger Pau Monné  * All event packets have common header:
1206*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
1207*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1208*3a9fd824SRoger Pau Monné  * |               id                |      type      |   reserved     | 4
1209*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1210*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
1211*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1212*3a9fd824SRoger Pau Monné  *
1213*3a9fd824SRoger Pau Monné  * id - uint16_t, event id, may be used by front.
1214*3a9fd824SRoger Pau Monné  * type - uint8_t, type of the event.
1215*3a9fd824SRoger Pau Monné  *
1216*3a9fd824SRoger Pau Monné  *
1217*3a9fd824SRoger Pau Monné  * Frame captured event - event from back to front when a new captured
1218*3a9fd824SRoger Pau Monné  * frame is available:
1219*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
1220*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1221*3a9fd824SRoger Pau Monné  * |               id                |_EVT_FRAME_AVAIL|   reserved     | 4
1222*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1223*3a9fd824SRoger Pau Monné  * |                             reserved                              | 8
1224*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1225*3a9fd824SRoger Pau Monné  * |      index     |                     reserved                     | 12
1226*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1227*3a9fd824SRoger Pau Monné  * |                              used_sz                              | 16
1228*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1229*3a9fd824SRoger Pau Monné  * |                              seq_num                              | 20
1230*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1231*3a9fd824SRoger Pau Monné  * |                             reserved                              | 24
1232*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1233*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
1234*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1235*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
1236*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1237*3a9fd824SRoger Pau Monné  *
1238*3a9fd824SRoger Pau Monné  * index - uint8_t, index of the buffer that contains new captured frame,
1239*3a9fd824SRoger Pau Monné  *   see XENCAMERA_OP_BUF_CREATE description on the range
1240*3a9fd824SRoger Pau Monné  * used_sz - uint32_t, number of octets this frame has. This can be less
1241*3a9fd824SRoger Pau Monné  * than the XENCAMERA_OP_BUF_REQUEST.size (response) for compressed formats.
1242*3a9fd824SRoger Pau Monné  * seq_num - uint32_t, sequential number of the frame. Must be
1243*3a9fd824SRoger Pau Monné  *   monotonically increasing. If skips are detected in seq_num then that
1244*3a9fd824SRoger Pau Monné  *   means that the frames in-between were dropped. Note however that not
1245*3a9fd824SRoger Pau Monné  *   all video capture hardware is capable of detecting dropped frames.
1246*3a9fd824SRoger Pau Monné  *   In that case there will be no skips in the sequence counter.
1247*3a9fd824SRoger Pau Monné  */
1248*3a9fd824SRoger Pau Monné struct xencamera_frame_avail_evt {
1249*3a9fd824SRoger Pau Monné     uint8_t index;
1250*3a9fd824SRoger Pau Monné     uint8_t reserved[3];
1251*3a9fd824SRoger Pau Monné     uint32_t used_sz;
1252*3a9fd824SRoger Pau Monné     uint32_t seq_num;
1253*3a9fd824SRoger Pau Monné };
1254*3a9fd824SRoger Pau Monné 
1255*3a9fd824SRoger Pau Monné /*
1256*3a9fd824SRoger Pau Monné  * Control change event- event from back to front when camera control
1257*3a9fd824SRoger Pau Monné  * has changed:
1258*3a9fd824SRoger Pau Monné  *         0                1                 2               3        octet
1259*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1260*3a9fd824SRoger Pau Monné  * |               id                |_EVT_CTRL_CHANGE|   reserved     | 4
1261*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1262*3a9fd824SRoger Pau Monné  * |       type     |                     reserved                     | 8
1263*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1264*3a9fd824SRoger Pau Monné  * |                             reserved                              | 12
1265*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1266*3a9fd824SRoger Pau Monné  * |                             reserved                              | 16
1267*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1268*3a9fd824SRoger Pau Monné  * |                          value low 32-bit                         | 20
1269*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1270*3a9fd824SRoger Pau Monné  * |                          value high 32-bit                        | 24
1271*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1272*3a9fd824SRoger Pau Monné  * |                             reserved                              | 28
1273*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1274*3a9fd824SRoger Pau Monné  * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
1275*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1276*3a9fd824SRoger Pau Monné  * |                             reserved                              | 64
1277*3a9fd824SRoger Pau Monné  * +----------------+----------------+----------------+----------------+
1278*3a9fd824SRoger Pau Monné  *
1279*3a9fd824SRoger Pau Monné  * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
1280*3a9fd824SRoger Pau Monné  * value - int64_t, new value of the control.
1281*3a9fd824SRoger Pau Monné  *
1282*3a9fd824SRoger Pau Monné  * Notes:
1283*3a9fd824SRoger Pau Monné  *  - this event is not sent for write-only controls
1284*3a9fd824SRoger Pau Monné  *  - this event is not sent to the originator of the control change
1285*3a9fd824SRoger Pau Monné  *  - this event is not sent when frontend first connects, e.g. initial
1286*3a9fd824SRoger Pau Monné  *    control state must be explicitly queried
1287*3a9fd824SRoger Pau Monné  */
1288*3a9fd824SRoger Pau Monné 
1289*3a9fd824SRoger Pau Monné struct xencamera_req {
1290*3a9fd824SRoger Pau Monné     uint16_t id;
1291*3a9fd824SRoger Pau Monné     uint8_t operation;
1292*3a9fd824SRoger Pau Monné     uint8_t reserved[5];
1293*3a9fd824SRoger Pau Monné     union {
1294*3a9fd824SRoger Pau Monné         struct xencamera_config_req config;
1295*3a9fd824SRoger Pau Monné         struct xencamera_frame_rate_req frame_rate;
1296*3a9fd824SRoger Pau Monné         struct xencamera_buf_request buf_request;
1297*3a9fd824SRoger Pau Monné         struct xencamera_buf_create_req buf_create;
1298*3a9fd824SRoger Pau Monné         struct xencamera_index index;
1299*3a9fd824SRoger Pau Monné         struct xencamera_ctrl_value ctrl_value;
1300*3a9fd824SRoger Pau Monné         struct xencamera_get_ctrl_req get_ctrl;
1301*3a9fd824SRoger Pau Monné         uint8_t reserved[56];
1302*3a9fd824SRoger Pau Monné     } req;
1303*3a9fd824SRoger Pau Monné };
1304*3a9fd824SRoger Pau Monné 
1305*3a9fd824SRoger Pau Monné struct xencamera_resp {
1306*3a9fd824SRoger Pau Monné     uint16_t id;
1307*3a9fd824SRoger Pau Monné     uint8_t operation;
1308*3a9fd824SRoger Pau Monné     uint8_t reserved;
1309*3a9fd824SRoger Pau Monné     int32_t status;
1310*3a9fd824SRoger Pau Monné     union {
1311*3a9fd824SRoger Pau Monné         struct xencamera_config_resp config;
1312*3a9fd824SRoger Pau Monné         struct xencamera_buf_get_layout_resp buf_layout;
1313*3a9fd824SRoger Pau Monné         struct xencamera_buf_request buf_request;
1314*3a9fd824SRoger Pau Monné         struct xencamera_ctrl_enum_resp ctrl_enum;
1315*3a9fd824SRoger Pau Monné         struct xencamera_ctrl_value ctrl_value;
1316*3a9fd824SRoger Pau Monné         uint8_t reserved1[56];
1317*3a9fd824SRoger Pau Monné     } resp;
1318*3a9fd824SRoger Pau Monné };
1319*3a9fd824SRoger Pau Monné 
1320*3a9fd824SRoger Pau Monné struct xencamera_evt {
1321*3a9fd824SRoger Pau Monné     uint16_t id;
1322*3a9fd824SRoger Pau Monné     uint8_t type;
1323*3a9fd824SRoger Pau Monné     uint8_t reserved[5];
1324*3a9fd824SRoger Pau Monné     union {
1325*3a9fd824SRoger Pau Monné         struct xencamera_frame_avail_evt frame_avail;
1326*3a9fd824SRoger Pau Monné         struct xencamera_ctrl_value ctrl_value;
1327*3a9fd824SRoger Pau Monné         uint8_t reserved[56];
1328*3a9fd824SRoger Pau Monné     } evt;
1329*3a9fd824SRoger Pau Monné };
1330*3a9fd824SRoger Pau Monné 
1331*3a9fd824SRoger Pau Monné DEFINE_RING_TYPES(xen_cameraif, struct xencamera_req, struct xencamera_resp);
1332*3a9fd824SRoger Pau Monné 
1333*3a9fd824SRoger Pau Monné /*
1334*3a9fd824SRoger Pau Monné  ******************************************************************************
1335*3a9fd824SRoger Pau Monné  *                        Back to front events delivery
1336*3a9fd824SRoger Pau Monné  ******************************************************************************
1337*3a9fd824SRoger Pau Monné  * In order to deliver asynchronous events from back to front a shared page is
1338*3a9fd824SRoger Pau Monné  * allocated by front and its granted reference propagated to back via
1339*3a9fd824SRoger Pau Monné  * XenStore entries (evt-ring-ref/evt-event-channel).
1340*3a9fd824SRoger Pau Monné  * This page has a common header used by both front and back to synchronize
1341*3a9fd824SRoger Pau Monné  * access and control event's ring buffer, while back being a producer of the
1342*3a9fd824SRoger Pau Monné  * events and front being a consumer. The rest of the page after the header
1343*3a9fd824SRoger Pau Monné  * is used for event packets.
1344*3a9fd824SRoger Pau Monné  *
1345*3a9fd824SRoger Pau Monné  * Upon reception of an event(s) front may confirm its reception
1346*3a9fd824SRoger Pau Monné  * for either each event, group of events or none.
1347*3a9fd824SRoger Pau Monné  */
1348*3a9fd824SRoger Pau Monné 
1349*3a9fd824SRoger Pau Monné struct xencamera_event_page {
1350*3a9fd824SRoger Pau Monné     uint32_t in_cons;
1351*3a9fd824SRoger Pau Monné     uint32_t in_prod;
1352*3a9fd824SRoger Pau Monné     uint8_t reserved[56];
1353*3a9fd824SRoger Pau Monné };
1354*3a9fd824SRoger Pau Monné 
1355*3a9fd824SRoger Pau Monné #define XENCAMERA_EVENT_PAGE_SIZE 4096
1356*3a9fd824SRoger Pau Monné #define XENCAMERA_IN_RING_OFFS (sizeof(struct xencamera_event_page))
1357*3a9fd824SRoger Pau Monné #define XENCAMERA_IN_RING_SIZE (XENCAMERA_EVENT_PAGE_SIZE - XENCAMERA_IN_RING_OFFS)
1358*3a9fd824SRoger Pau Monné #define XENCAMERA_IN_RING_LEN (XENCAMERA_IN_RING_SIZE / sizeof(struct xencamera_evt))
1359*3a9fd824SRoger Pau Monné #define XENCAMERA_IN_RING(page) \
1360*3a9fd824SRoger Pau Monné     ((struct xencamera_evt *)((char *)(page) + XENCAMERA_IN_RING_OFFS))
1361*3a9fd824SRoger Pau Monné #define XENCAMERA_IN_RING_REF(page, idx) \
1362*3a9fd824SRoger Pau Monné     (XENCAMERA_IN_RING((page))[(idx) % XENCAMERA_IN_RING_LEN])
1363*3a9fd824SRoger Pau Monné 
1364*3a9fd824SRoger Pau Monné #endif /* __XEN_PUBLIC_IO_CAMERAIF_H__ */
1365*3a9fd824SRoger Pau Monné 
1366*3a9fd824SRoger Pau Monné /*
1367*3a9fd824SRoger Pau Monné  * Local variables:
1368*3a9fd824SRoger Pau Monné  * mode: C
1369*3a9fd824SRoger Pau Monné  * c-file-style: "BSD"
1370*3a9fd824SRoger Pau Monné  * c-basic-offset: 4
1371*3a9fd824SRoger Pau Monné  * tab-width: 4
1372*3a9fd824SRoger Pau Monné  * indent-tabs-mode: nil
1373*3a9fd824SRoger Pau Monné  * End:
1374*3a9fd824SRoger Pau Monné  */
1375