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