FreeBSD/Linux Kernel Cross Reference
sys/xen/interface/io/cameraif.h

     /******************************************************************************
      * cameraif.h
      *
      * Unified camera device I/O interface for Xen guest OSes.
      *
      * Permission is hereby granted, free of charge, to any person obtaining a copy
      * of this software and associated documentation files (the "Software"), to
      * deal in the Software without restriction, including without limitation the
      * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
     * sell copies of the Software, and to permit persons to whom the Software is
     * furnished to do so, subject to the following conditions:
     *
     * The above copyright notice and this permission notice shall be included in
     * all copies or substantial portions of the Software.
     *
     * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
     * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
     * DEALINGS IN THE SOFTWARE.
     *
     * Copyright (C) 2018-2019 EPAM Systems Inc.
     *
     * Author: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>
     */
    
    #ifndef __XEN_PUBLIC_IO_CAMERAIF_H__
    #define __XEN_PUBLIC_IO_CAMERAIF_H__
    
    #include "ring.h"
    #include "../grant_table.h"
    
    /*
     ******************************************************************************
     *                           Protocol version
     ******************************************************************************
     */
    #define XENCAMERA_PROTOCOL_VERSION     "1"
    
    /*
     ******************************************************************************
     *                  Feature and Parameter Negotiation
     ******************************************************************************
     *
     * Front->back notifications: when enqueuing a new request, sending a
     * notification can be made conditional on xencamera_req (i.e., the generic
     * hold-off mechanism provided by the ring macros). Backends must set
     * xencamera_req appropriately (e.g., using RING_FINAL_CHECK_FOR_REQUESTS()).
     *
     * Back->front notifications: when enqueuing a new response, sending a
     * notification can be made conditional on xencamera_resp (i.e., the generic
     * hold-off mechanism provided by the ring macros). Frontends must set
     * xencamera_resp appropriately (e.g., using RING_FINAL_CHECK_FOR_RESPONSES()).
     *
     * The two halves of a para-virtual camera driver utilize nodes within
     * XenStore to communicate capabilities and to negotiate operating parameters.
     * This section enumerates these nodes which reside in the respective front and
     * backend portions of XenStore, following the XenBus convention.
     *
     * All data in XenStore is stored as strings. Nodes specifying numeric
     * values are encoded in decimal. Integer value ranges listed below are
     * expressed as fixed sized integer types capable of storing the conversion
     * of a properly formatted node string, without loss of information.
     *
     ******************************************************************************
     *                        Example configuration
     ******************************************************************************
     *
     * This is an example of backend and frontend configuration:
     *
     *--------------------------------- Backend -----------------------------------
     *
     * /local/domain/0/backend/vcamera/1/0/frontend-id = "1"
     * /local/domain/0/backend/vcamera/1/0/frontend = "/local/domain/1/device/vcamera/0"
     * /local/domain/0/backend/vcamera/1/0/state = "4"
     * /local/domain/0/backend/vcamera/1/0/versions = "1,2"
     *
     *--------------------------------- Frontend ----------------------------------
     *
     * /local/domain/1/device/vcamera/0/backend-id = ""
     * /local/domain/1/device/vcamera/0/backend = "/local/domain/0/backend/vcamera/1"
     * /local/domain/1/device/vcamera/0/state = "4"
     * /local/domain/1/device/vcamera/0/version = "1"
     * /local/domain/1/device/vcamera/0/be-alloc = "1"
     *
     *---------------------------- Device 0 configuration -------------------------
     *
     * /local/domain/1/device/vcamera/0/max-buffers = "3"
     * /local/domain/1/device/vcamera/0/controls = "contrast,hue"
     * /local/domain/1/device/vcamera/0/formats/YUYV/640x480/frame-rates = "30/1,15/1"
     * /local/domain/1/device/vcamera/0/formats/YUYV/1920x1080/frame-rates = "15/2"
     * /local/domain/1/device/vcamera/0/formats/BGRA/640x480/frame-rates = "15/1,15/2"
     * /local/domain/1/device/vcamera/0/formats/BGRA/1200x720/frame-rates = "15/2"
     * /local/domain/1/device/vcamera/0/unique-id = ""
     * /local/domain/1/device/vcamera/0/req-ring-ref = "2832"
     * /local/domain/1/device/vcamera/0/req-event-channel = "15"
     * /local/domain/1/device/vcamera/0/evt-ring-ref = "387"
    * /local/domain/1/device/vcamera/0/evt-event-channel = "16"
    *
    *---------------------------- Device 1 configuration -------------------------
    *
    * /local/domain/1/device/vcamera/1/max-buffers = "8"
    * /local/domain/1/device/vcamera/1/controls = "brightness,saturation,hue"
    * /local/domain/1/device/vcamera/1/formats/YUYV/640x480/frame-rates = "30/1,15/2"
    * /local/domain/1/device/vcamera/1/formats/YUYV/1920x1080/frame-rates = "15/2"
    * /local/domain/1/device/vcamera/1/unique-id = "1"
    * /local/domain/1/device/vcamera/1/req-ring-ref = "2833"
    * /local/domain/1/device/vcamera/1/req-event-channel = "17"
    * /local/domain/1/device/vcamera/1/evt-ring-ref = "388"
    * /local/domain/1/device/vcamera/1/evt-event-channel = "18"
    *
    ******************************************************************************
    *                            Backend XenBus Nodes
    ******************************************************************************
    *
    *----------------------------- Protocol version ------------------------------
    *
    * versions
    *      Values:         <string>
    *
    *      List of XENCAMERA_LIST_SEPARATOR separated protocol versions supported
    *      by the backend. For example "1,2,3".
    *
    ******************************************************************************
    *                            Frontend XenBus Nodes
    ******************************************************************************
    *
    *-------------------------------- Addressing ---------------------------------
    *
    * dom-id
    *      Values:         <uint16_t>
    *
    *      Domain identifier.
    *
    * dev-id
    *      Values:         <uint16_t>
    *
    *      Device identifier.
    *
    *      /local/domain/<dom-id>/device/vcamera/<dev-id>/...
    *
    *----------------------------- Protocol version ------------------------------
    *
    * version
    *      Values:         <string>
    *
    *      Protocol version, chosen among the ones supported by the backend.
    *
    *------------------------- Backend buffer allocation -------------------------
    *
    * be-alloc
    *      Values:         "", "1"
    *
    *      If value is set to "1", then backend will be the buffer
    *      provider/allocator for this domain during XENCAMERA_OP_BUF_CREATE
    *      operation.
    *      If value is not "1" or omitted frontend must allocate buffers itself.
    *
    *------------------------------- Camera settings -----------------------------
    *
    * unique-id
    *      Values:         <string>
    *
    *      After device instance initialization each camera is assigned a
    *      unique ID, so it can be identified by the backend by this ID.
    *      This can be UUID or such.
    *
    * max-buffers
    *      Values:         <uint8_t>
    *
    *      Maximum number of camera buffers this frontend may use.
    *
    * controls
    *      Values:         <list of string>
    *
    *      List of supported camera controls separated by XENCAMERA_LIST_SEPARATOR.
    *      Camera controls are expressed as a list of string values w/o any
    *      ordering requirement.
    *
    * formats
    *      Values:         <format, char[7]>
    *
    *      Formats are organized as a set of directories one per each
    *      supported pixel format. The name of the directory is the
    *      corresponding FOURCC string label. The next level of
    *      the directory under <formats> represents supported resolutions.
    *      If the format represents a big-endian variant of a little
    *      endian format, then the "-BE" suffix must be added. E.g. 'AR15' vs
    *      'AR15-BE'.
    *      If FOURCC string label has spaces then those are only allowed to
    *      be at the end of the label and must be trimmed, for example
    *      'Y16' and 'Y16-BE' will be trimmed.
    *
    * resolution
    *      Values:         <width, uint32_t>x<height, uint32_t>
    *
    *      Resolutions are organized as a set of directories one per each
    *      supported resolution under corresponding <formats> directory.
    *      The name of the directory is the supported width and height
    *      of the camera resolution in pixels.
    *
    * frame-rates
    *      Values:         <numerator, uint32_t>/<denominator, uint32_t>
    *
    *      List of XENCAMERA_FRAME_RATE_SEPARATOR separated supported frame rates
    *      of the camera expressed as numerator and denominator of the
    *      corresponding frame rate.
    *
    *------------------- Camera Request Transport Parameters ---------------------
    *
    * This communication path is used to deliver requests from frontend to backend
    * and get the corresponding responses from backend to frontend,
    * set up per virtual camera device.
    *
    * req-event-channel
    *      Values:         <uint32_t>
    *
    *      The identifier of the Xen camera's control event channel
    *      used to signal activity in the ring buffer.
    *
    * req-ring-ref
    *      Values:         <uint32_t>
    *
    *      The Xen grant reference granting permission for the backend to map
    *      a sole page of camera's control ring buffer.
    *
    *-------------------- Camera Event Transport Parameters ----------------------
    *
    * This communication path is used to deliver asynchronous events from backend
    * to frontend, set up per virtual camera device.
    *
    * evt-event-channel
    *      Values:         <uint32_t>
    *
    *      The identifier of the Xen camera's event channel
    *      used to signal activity in the ring buffer.
    *
    * evt-ring-ref
    *      Values:         <uint32_t>
    *
    *      The Xen grant reference granting permission for the backend to map
    *      a sole page of camera's event ring buffer.
    */
   
   /*
    ******************************************************************************
    *                               STATE DIAGRAMS
    ******************************************************************************
    *
    * Tool stack creates front and back state nodes with initial state
    * XenbusStateInitialising.
    * Tool stack creates and sets up frontend camera configuration
    * nodes per domain.
    *
    *-------------------------------- Normal flow --------------------------------
    *
    * Front                                Back
    * =================================    =====================================
    * XenbusStateInitialising              XenbusStateInitialising
    *                                       o Query backend device identification
    *                                         data.
    *                                       o Open and validate backend device.
    *                                                |
    *                                                |
    *                                                V
    *                                      XenbusStateInitWait
    *
    * o Query frontend configuration
    * o Allocate and initialize
    *   event channels per configured
    *   camera.
    * o Publish transport parameters
    *   that will be in effect during
    *   this connection.
    *              |
    *              |
    *              V
    * XenbusStateInitialised
    *
    *                                       o Query frontend transport parameters.
    *                                       o Connect to the event channels.
    *                                                |
    *                                                |
    *                                                V
    *                                      XenbusStateConnected
    *
    *  o Create and initialize OS
    *    virtual camera as per
    *    configuration.
    *              |
    *              |
    *              V
    * XenbusStateConnected
    *
    *                                      XenbusStateUnknown
    *                                      XenbusStateClosed
    *                                      XenbusStateClosing
    * o Remove virtual camera device
    * o Remove event channels
    *              |
    *              |
    *              V
    * XenbusStateClosed
    *
    *------------------------------- Recovery flow -------------------------------
    *
    * In case of frontend unrecoverable errors backend handles that as
    * if frontend goes into the XenbusStateClosed state.
    *
    * In case of backend unrecoverable errors frontend tries removing
    * the virtualized device. If this is possible at the moment of error,
    * then frontend goes into the XenbusStateInitialising state and is ready for
    * new connection with backend. If the virtualized device is still in use and
    * cannot be removed, then frontend goes into the XenbusStateReconfiguring state
    * until either the virtualized device is removed or backend initiates a new
    * connection. On the virtualized device removal frontend goes into the
    * XenbusStateInitialising state.
    *
    * Note on XenbusStateReconfiguring state of the frontend: if backend has
    * unrecoverable errors then frontend cannot send requests to the backend
    * and thus cannot provide functionality of the virtualized device anymore.
    * After backend is back to normal the virtualized device may still hold some
    * state: configuration in use, allocated buffers, client application state etc.
    * In most cases, this will require frontend to implement complex recovery
    * reconnect logic. Instead, by going into XenbusStateReconfiguring state,
    * frontend will make sure no new clients of the virtualized device are
    * accepted, allow existing client(s) to exit gracefully by signaling error
    * state etc.
    * Once all the clients are gone frontend can reinitialize the virtualized
    * device and get into XenbusStateInitialising state again signaling the
    * backend that a new connection can be made.
    *
    * There are multiple conditions possible under which frontend will go from
    * XenbusStateReconfiguring into XenbusStateInitialising, some of them are OS
    * specific. For example:
    * 1. The underlying OS framework may provide callbacks to signal that the last
    *    client of the virtualized device has gone and the device can be removed
    * 2. Frontend can schedule a deferred work (timer/tasklet/workqueue)
    *    to periodically check if this is the right time to re-try removal of
    *    the virtualized device.
    * 3. By any other means.
    *
    ******************************************************************************
    *                             REQUEST CODES
    ******************************************************************************
    */
   #define XENCAMERA_OP_CONFIG_SET        0x00
   #define XENCAMERA_OP_CONFIG_GET        0x01
   #define XENCAMERA_OP_CONFIG_VALIDATE   0x02
   #define XENCAMERA_OP_FRAME_RATE_SET    0x03
   #define XENCAMERA_OP_BUF_GET_LAYOUT    0x04
   #define XENCAMERA_OP_BUF_REQUEST       0x05
   #define XENCAMERA_OP_BUF_CREATE        0x06
   #define XENCAMERA_OP_BUF_DESTROY       0x07
   #define XENCAMERA_OP_BUF_QUEUE         0x08
   #define XENCAMERA_OP_BUF_DEQUEUE       0x09
   #define XENCAMERA_OP_CTRL_ENUM         0x0a
   #define XENCAMERA_OP_CTRL_SET          0x0b
   #define XENCAMERA_OP_CTRL_GET          0x0c
   #define XENCAMERA_OP_STREAM_START      0x0d
   #define XENCAMERA_OP_STREAM_STOP       0x0e
   
   #define XENCAMERA_CTRL_BRIGHTNESS      0
   #define XENCAMERA_CTRL_CONTRAST        1
   #define XENCAMERA_CTRL_SATURATION      2
   #define XENCAMERA_CTRL_HUE             3
   
   /* Number of supported controls. */
   #define XENCAMERA_MAX_CTRL             4
   
   /* Control is read-only. */
   #define XENCAMERA_CTRL_FLG_RO          (1 << 0)
   /* Control is write-only. */
   #define XENCAMERA_CTRL_FLG_WO          (1 << 1)
   /* Control's value is volatile. */
   #define XENCAMERA_CTRL_FLG_VOLATILE    (1 << 2)
   
   /* Supported color spaces. */
   #define XENCAMERA_COLORSPACE_DEFAULT   0
   #define XENCAMERA_COLORSPACE_SMPTE170M 1
   #define XENCAMERA_COLORSPACE_REC709    2
   #define XENCAMERA_COLORSPACE_SRGB      3
   #define XENCAMERA_COLORSPACE_OPRGB     4
   #define XENCAMERA_COLORSPACE_BT2020    5
   #define XENCAMERA_COLORSPACE_DCI_P3    6
   
   /* Color space transfer function. */
   #define XENCAMERA_XFER_FUNC_DEFAULT    0
   #define XENCAMERA_XFER_FUNC_709        1
   #define XENCAMERA_XFER_FUNC_SRGB       2
   #define XENCAMERA_XFER_FUNC_OPRGB      3
   #define XENCAMERA_XFER_FUNC_NONE       4
   #define XENCAMERA_XFER_FUNC_DCI_P3     5
   #define XENCAMERA_XFER_FUNC_SMPTE2084  6
   
   /* Color space Y’CbCr encoding. */
   #define XENCAMERA_YCBCR_ENC_IGNORE           0
   #define XENCAMERA_YCBCR_ENC_601              1
   #define XENCAMERA_YCBCR_ENC_709              2
   #define XENCAMERA_YCBCR_ENC_XV601            3
   #define XENCAMERA_YCBCR_ENC_XV709            4
   #define XENCAMERA_YCBCR_ENC_BT2020           5
   #define XENCAMERA_YCBCR_ENC_BT2020_CONST_LUM 6
   
   /* Quantization range. */
   #define XENCAMERA_QUANTIZATION_DEFAULT       0
   #define XENCAMERA_QUANTIZATION_FULL_RANGE    1
   #define XENCAMERA_QUANTIZATION_LIM_RANGE     2
   
   /*
    ******************************************************************************
    *                                 EVENT CODES
    ******************************************************************************
    */
   #define XENCAMERA_EVT_FRAME_AVAIL      0x00
   #define XENCAMERA_EVT_CTRL_CHANGE      0x01
   
   /*
    ******************************************************************************
    *               XENSTORE FIELD AND PATH NAME STRINGS, HELPERS
    ******************************************************************************
    */
   #define XENCAMERA_DRIVER_NAME          "vcamera"
   
   #define XENCAMERA_LIST_SEPARATOR       ","
   #define XENCAMERA_RESOLUTION_SEPARATOR "x"
   #define XENCAMERA_FRACTION_SEPARATOR   "/"
   
   #define XENCAMERA_FIELD_BE_VERSIONS    "versions"
   #define XENCAMERA_FIELD_FE_VERSION     "version"
   #define XENCAMERA_FIELD_REQ_RING_REF   "req-ring-ref"
   #define XENCAMERA_FIELD_REQ_CHANNEL    "req-event-channel"
   #define XENCAMERA_FIELD_EVT_RING_REF   "evt-ring-ref"
   #define XENCAMERA_FIELD_EVT_CHANNEL    "evt-event-channel"
   #define XENCAMERA_FIELD_MAX_BUFFERS    "max-buffers"
   #define XENCAMERA_FIELD_CONTROLS       "controls"
   #define XENCAMERA_FIELD_FORMATS        "formats"
   #define XENCAMERA_FIELD_FRAME_RATES    "frame-rates"
   #define XENCAMERA_FIELD_BE_ALLOC       "be-alloc"
   #define XENCAMERA_FIELD_UNIQUE_ID      "unique-id"
   
   #define XENCAMERA_CTRL_BRIGHTNESS_STR  "brightness"
   #define XENCAMERA_CTRL_CONTRAST_STR    "contrast"
   #define XENCAMERA_CTRL_SATURATION_STR  "saturation"
   #define XENCAMERA_CTRL_HUE_STR         "hue"
   
   #define XENCAMERA_FOURCC_BIGENDIAN_STR "-BE"
   
   /* Maximum number of buffer planes supported. */
   #define XENCAMERA_MAX_PLANE            4
   
   /*
    ******************************************************************************
    *                          STATUS RETURN CODES
    ******************************************************************************
    *
    * Status return code is zero on success and -XEN_EXX on failure.
    *
    ******************************************************************************
    *                              Assumptions
    ******************************************************************************
    *
    * - usage of grant reference 0 as invalid grant reference:
    *   grant reference 0 is valid, but never exposed to a PV driver,
    *   because of the fact it is already in use/reserved by the PV console.
    * - all references in this document to page sizes must be treated
    *   as pages of size XEN_PAGE_SIZE unless otherwise noted.
    * - all FOURCC mappings used for configuration and messaging are
    *   Linux V4L2 ones: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/videodev2.h
    *   with the following exceptions:
    *     - characters are allowed in [0x20; 0x7f] range
    *     - when used for XenStore configuration entries the following
    *       are not allowed:
    *       - '/', '\', ' ' (space), '<', '>', ':', '"', '|', '?', '*'
    *       - if trailing spaces are part of the FOURCC code then those must be
    *         trimmed
    *
    *
    ******************************************************************************
    *       Description of the protocol between frontend and backend driver
    ******************************************************************************
    *
    * The two halves of a Para-virtual camera driver communicate with
    * each other using shared pages and event channels.
    * Shared page contains a ring with request/response packets.
    *
    * All reserved fields in the structures below must be 0.
    *
    * For all request/response/event packets:
    *   - frame rate parameter is represented as a pair of 4 octet long
    *     numerator and denominator:
    *       - frame_rate_numer - uint32_t, numerator of the frame rate
    *       - frame_rate_denom - uint32_t, denominator of the frame rate
    *     The corresponding frame rate (Hz) is calculated as:
    *       frame_rate = frame_rate_numer / frame_rate_denom
    *   - buffer index is a zero based index of the buffer. Must be less than
    *     the value of XENCAMERA_OP_CONFIG_SET.num_bufs response:
    *       - index - uint8_t, index of the buffer.
    *
    *
    *---------------------------------- Requests ---------------------------------
    *
    * All request packets have the same length (64 octets).
    * All request packets have common header:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                |    operation   |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    *   id - uint16_t, private guest value, echoed in response.
    *   operation - uint8_t, operation code, XENCAMERA_OP_XXX.
    *
    *
    * Request to set/validate the configuration - request to set the
    * configuration/mode of the camera (XENCAMERA_OP_CONFIG_SET) or to
    * check if the configuration is valid and can be used
    * (XENCAMERA_OP_CONFIG_VALIDATE):
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_CONFIG_XXX |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |                            pixel format                           | 12
    * +----------------+----------------+----------------+----------------+
    * |                               width                               | 16
    * +----------------+----------------+----------------+----------------+
    * |                               height                              | 20
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 24
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * pixel_format - uint32_t, pixel format to be used, FOURCC code.
    * width - uint32_t, width in pixels.
    * height - uint32_t, height in pixels.
    *
    * See response format for this request.
    *
    * Notes:
    *  - the only difference between XENCAMERA_OP_CONFIG_VALIDATE and
    *    XENCAMERA_OP_CONFIG_SET is that the former doesn't actually change
    *    camera configuration, but queries if the configuration is valid.
    *    This can be used while stream is active and/or buffers allocated.
    *  - frontend must check the corresponding response in order to see
    *    if the values reported back by the backend do match the desired ones
    *    and can be accepted.
    *  - frontend may send multiple XENCAMERA_OP_CONFIG_SET requests before
    *    sending XENCAMERA_OP_STREAM_START request to update or tune the
    *    final stream configuration.
    *  - configuration cannot be changed during active streaming, e.g.
    *    after XENCAMERA_OP_STREAM_START and before XENCAMERA_OP_STREAM_STOP
    *    requests.
    */
   struct xencamera_config_req {
       uint32_t pixel_format;
       uint32_t width;
       uint32_t height;
   };
   
   /*
    * Request current configuration of the camera:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_CONFIG_GET |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * See response format for this request.
    *
    *
    * Request to set the frame rate of the stream:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _FRAME_RATE_SET|   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |                          frame_rate_numer                         | 12
    * +----------------+----------------+----------------+----------------+
    * |                          frame_rate_denom                         | 16
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 20
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * frame_rate_numer - uint32_t, numerator of the frame rate.
    * frame_rate_denom - uint32_t, denominator of the frame rate.
    *
    * Notes:
    *  - to query the current (actual) frame rate use XENCAMERA_OP_CONFIG_GET
    *    request.
    *  - this request can be used with camera buffers allocated, but stream
    *    stopped, e.g. frontend is allowed to stop the stream with
    *    XENCAMERA_OP_STREAM_STOP, hold the buffers allocated (e.g. keep the
    *    configuration set with XENCAMERA_OP_CONFIG_SET), change the
    *    frame rate of the stream and (re)start the stream again with
    *    XENCAMERA_OP_STREAM_START.
    *  - frame rate cannot be changed during active streaming, e.g.
    *    after XENCAMERA_OP_STREAM_START and before XENCAMERA_OP_STREAM_STOP
    *    commands.
    */
   struct xencamera_frame_rate_req {
       uint32_t frame_rate_numer;
       uint32_t frame_rate_denom;
   };
   
   /*
    * Request camera buffer's layout:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _BUF_GET_LAYOUT|   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * See response format for this request.
    *
    *
    * Request number of buffers to be used:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_BUF_REQUEST|   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |    num_bufs    |                     reserved                     | 12
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 16
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * num_bufs - uint8_t, desired number of buffers to be used.
    *
    * If num_bufs is not zero then the backend validates the requested number of
    * buffers and responds with the number of buffers allowed for this frontend.
    * Frontend is responsible for checking the corresponding response in order to
    * see if the values reported back by the backend do match the desired ones
    * and can be accepted.
    * Frontend is allowed to send multiple XENCAMERA_OP_BUF_REQUEST requests
    * before sending XENCAMERA_OP_STREAM_START request to update or tune the
    * final configuration.
    * Frontend is not allowed to change the camera configuration after this call
    * with a non-zero value of num_bufs. If camera reconfiguration is required
    * then this request must be sent with num_bufs set to zero and any created
    * buffers must be destroyed first.
    * Frontend is not allowed to change the number of buffers after the
    * streaming has started.
    *
    * If num_bufs is 0 and streaming has not started yet, then the backend will
    * free all previously allocated buffers (if any).
    * Trying to call this if streaming is in progress will result in an error.
    *
    * If camera reconfiguration is required then the streaming must be stopped
    * and this request must be sent with num_bufs set to zero and any
    * created buffers must be destroyed.
    *
    * Please note, that the number of buffers in this request must not exceed
    * the value configured in XenStore.max-buffers.
    *
    * See response format for this request.
    */
   struct xencamera_buf_request {
       uint8_t num_bufs;
   };
   
   /*
    * Request camera buffer creation:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_BUF_CREATE |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |      index     |                     reserved                     | 12
    * +----------------+----------------+----------------+----------------+
    * |                           plane_offset[0]                         | 16
    * +----------------+----------------+----------------+----------------+
    * |                           plane_offset[1]                         | 20
    * +----------------+----------------+----------------+----------------+
    * |                           plane_offset[2]                         | 24
    * +----------------+----------------+----------------+----------------+
    * |                           plane_offset[3]                         | 28
    * +----------------+----------------+----------------+----------------+
    * |                           gref_directory                          | 32
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 36
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * An attempt to create multiple buffers with the same index is an error.
    * index can be re-used after destroying the corresponding camera buffer.
    *
    * index - uint8_t, index of the buffer to be created in the range
    *   from 0 to the num_bufs field returned in response for
    *   XENCAMERA_OP_BUF_REQUEST request
    * plane_offset - array of uint32_t, offset of the corresponding plane
    *   in octets from the buffer start. Number of offsets returned is
    *   equal to the value returned in XENCAMERA_OP_BUF_GET_LAYOUT.num_planes.
    * gref_directory - grant_ref_t, a reference to the first shared page
    *   describing shared buffer references. The size of the buffer is equal to
    *   XENCAMERA_OP_BUF_GET_LAYOUT.size response. At least one page exists. If
    *   shared buffer size exceeds what can be addressed by this single page,
    *   then reference to the next shared page must be supplied (see
    *   gref_dir_next_page below).
    *
    * If XENCAMERA_FIELD_BE_ALLOC configuration entry is set, then backend will
    * allocate the buffer with the parameters provided in this request and page
    * directory is handled as follows:
    *   Frontend on request:
    *     - allocates pages for the directory (gref_directory,
    *       gref_dir_next_page(s)
    *     - grants permissions for the pages of the directory to the backend
    *     - sets gref_dir_next_page fields
    *   Backend on response:
    *     - grants permissions for the pages of the buffer allocated to
    *       the frontend
    *     - fills in page directory with grant references
    *       (gref[] in struct xencamera_page_directory)
    */
   struct xencamera_buf_create_req {
       uint8_t index;
       uint8_t reserved[3];
       uint32_t plane_offset[XENCAMERA_MAX_PLANE];
       grant_ref_t gref_directory;
   };
   
   /*
    * Shared page for XENCAMERA_OP_BUF_CREATE buffer descriptor (gref_directory in
    * the request) employs a list of pages, describing all pages of the shared
    * data buffer:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |                        gref_dir_next_page                         | 4
    * +----------------+----------------+----------------+----------------+
    * |                              gref[0]                              | 8
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                              gref[i]                              | i*4+8
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             gref[N - 1]                           | N*4+8
    * +----------------+----------------+----------------+----------------+
    *
    * gref_dir_next_page - grant_ref_t, reference to the next page describing
    *   page directory. Must be 0 if there are no more pages in the list.
    * gref[i] - grant_ref_t, reference to a shared page of the buffer
    *   allocated at XENCAMERA_OP_BUF_CREATE.
    *
    * Number of grant_ref_t entries in the whole page directory is not
    * passed, but instead can be calculated as:
    *   num_grefs_total = (XENCAMERA_OP_BUF_REQUEST.size + XEN_PAGE_SIZE - 1) /
    *       XEN_PAGE_SIZE
    */
   struct xencamera_page_directory {
       grant_ref_t gref_dir_next_page;
       grant_ref_t gref[1]; /* Variable length */
   };
   
   /*
    * Request buffer destruction - destroy a previously allocated camera buffer:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_BUF_DESTROY|   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |      index     |                     reserved                     | 12
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 16
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * index - uint8_t, index of the buffer to be destroyed.
    *
    *
    * Request queueing of the buffer for backend use:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_BUF_QUEUE  |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |      index     |                     reserved                     | 12
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 16
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * Notes:
    *  - frontends must not access the buffer content after this request until
    *    response to XENCAMERA_OP_BUF_DEQUEUE has been received.
    *  - buffers must be queued to the backend before destroying them with
    *    XENCAMERA_OP_BUF_DESTROY.
    *
    * index - uint8_t, index of the buffer to be queued.
    *
    *
    * Request dequeueing of the buffer for frontend use:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                |_OP_BUF_DEQUEUE |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |      index     |                     reserved                     | 12
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 16
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * Notes:
    *  - frontend is allowed to access the buffer content after the corresponding
    *    response to this request.
    *
    * index - uint8_t, index of the buffer to be queued.
    *
    *
    * Request camera control details:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_CTRL_ENUM  |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |      index     |                     reserved                     | 8
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 12
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * See response format for this request.
    *
    * index - uint8_t, index of the control to be queried.
    */
   struct xencamera_index {
       uint8_t index;
   };
   
   /*
    * Request camera control change:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                |  _OP_SET_CTRL  |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |       type     |                     reserved                     | 8
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 12
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 16
    * +----------------+----------------+----------------+----------------+
    * |                          value low 32-bit                         | 20
    * +----------------+----------------+----------------+----------------+
    * |                          value high 32-bit                        | 24
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 28
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
    * value - int64_t, new value of the control.
    */
   struct xencamera_ctrl_value {
       uint8_t type;
       uint8_t reserved[7];
       int64_t value;
   };
   
   /*
    * Request camera control state:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                |  _OP_GET_CTRL  |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |       type     |                     reserved                     | 8
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 12
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    * See response format for this request.
    *
    * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
    */
   struct xencamera_get_ctrl_req {
       uint8_t type;
   };
   
   /*
    * Request camera capture stream start:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                |_OP_STREAM_START|   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    *
    * Request camera capture stream stop:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                |_OP_STREAM_STOP |   reserved     | 4
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 8
    * +----------------+----------------+----------------+----------------+
    * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
    * +----------------+----------------+----------------+----------------+
    * |                             reserved                              | 64
    * +----------------+----------------+----------------+----------------+
    *
    *
    *---------------------------------- Responses --------------------------------
    *
    * All response packets have the same length (64 octets).
    *
    * All response packets have common header:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                |    operation   |    reserved    | 4
    * +----------------+----------------+----------------+----------------+
    * |                              status                               | 8
    * +----------------+----------------+----------------+----------------+
    *
    * id - uint16_t, copied from the request.
    * operation - uint8_t, XENCAMERA_OP_* - copied from request.
    * status - int32_t, response status, zero on success and -XEN_EXX on failure.
    *
    *
    * Configuration response - response for XENCAMERA_OP_CONFIG_SET,
    * XENCAMERA_OP_CONFIG_GET and XENCAMERA_OP_CONFIG_VALIDATE requests:
    *         0                1                 2               3        octet
    * +----------------+----------------+----------------+----------------+
    * |               id                | _OP_CONFIG_XXX |    reserved    | 4
    * +----------------+----------------+----------------+----------------+
    * |                               status                              | 8
    * +----------------+----------------+----------------+----------------+
    * |                            pixel format                           | 12
    * +----------------+----------------+----------------+----------------+
    * |                               width                               | 16
    * +----------------+----------------+----------------+----------------+
    * |                               height                              | 20
    * +----------------+----------------+----------------+----------------+
    * |                             colorspace                            | 24
    * +----------------+----------------+----------------+----------------+
    * |                             xfer_func                             | 28
    * +----------------+----------------+----------------+----------------+
    * |                             ycbcr_enc                             | 32
    * +----------------+----------------+----------------+----------------+
    * |                            quantization                           | 36
    * +----------------+----------------+----------------+----------------+
    * |                       displ_asp_ratio_numer                       | 40
    * +----------------+----------------+----------------+----------------+
    * |                       displ_asp_ratio_denom                       | 44
   * +----------------+----------------+----------------+----------------+
   * |                          frame_rate_numer                         | 48
   * +----------------+----------------+----------------+----------------+
   * |                          frame_rate_denom                         | 52
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 56
   * +----------------+----------------+----------------+----------------+
   * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 64
   * +----------------+----------------+----------------+----------------+
   *
   * Meaning of the corresponding values in this response is the same as for
   * XENCAMERA_OP_CONFIG_SET and XENCAMERA_OP_FRAME_RATE_SET requests.
   *
   * colorspace - uint32_t, this supplements pixel_format parameter,
   *   one of the XENCAMERA_COLORSPACE_XXX.
   * xfer_func - uint32_t, this supplements colorspace parameter,
   *   one of the XENCAMERA_XFER_FUNC_XXX.
   * ycbcr_enc - uint32_t, this supplements colorspace parameter,
   *   one of the XENCAMERA_YCBCR_ENC_XXX. Please note, that ycbcr_enc is only
   *   valid for YCbCr pixelformats and should be ignored otherwise.
   * quantization - uint32_t, this supplements colorspace parameter,
   *   one of the XENCAMERA_QUANTIZATION_XXX.
   * displ_asp_ratio_numer - uint32_t, numerator of the display aspect ratio.
   * displ_asp_ratio_denom - uint32_t, denominator of the display aspect ratio.
   */
  struct xencamera_config_resp {
      uint32_t pixel_format;
      uint32_t width;
      uint32_t height;
      uint32_t colorspace;
      uint32_t xfer_func;
      uint32_t ycbcr_enc;
      uint32_t quantization;
      uint32_t displ_asp_ratio_numer;
      uint32_t displ_asp_ratio_denom;
      uint32_t frame_rate_numer;
      uint32_t frame_rate_denom;
  };
  
  /*
   * Request buffer response - response for XENCAMERA_OP_BUF_GET_LAYOUT
   * request:
   *         0                1                 2               3        octet
   * +----------------+----------------+----------------+----------------+
   * |               id                |_BUF_GET_LAYOUT |    reserved    | 4
   * +----------------+----------------+----------------+----------------+
   * |                               status                              | 8
   * +----------------+----------------+----------------+----------------+
   * |   num_planes   |                     reserved                     | 12
   * +----------------+----------------+----------------+----------------+
   * |                                size                               | 16
   * +----------------+----------------+----------------+----------------+
   * |                           plane_size[0]                           | 20
   * +----------------+----------------+----------------+----------------+
   * |                           plane_size[1]                           | 24
   * +----------------+----------------+----------------+----------------+
   * |                           plane_size[2]                           | 28
   * +----------------+----------------+----------------+----------------+
   * |                           plane_size[3]                           | 32
   * +----------------+----------------+----------------+----------------+
   * |                          plane_stride[0]                          | 36
   * +----------------+----------------+----------------+----------------+
   * |                          plane_stride[1]                          | 40
   * +----------------+----------------+----------------+----------------+
   * |                          plane_stride[2]                          | 44
   * +----------------+----------------+----------------+----------------+
   * |                          plane_stride[3]                          | 48
   * +----------------+----------------+----------------+----------------+
   * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 64
   * +----------------+----------------+----------------+----------------+
   *
   * num_planes - uint8_t, number of planes of the buffer.
   * size - uint32_t, overall size of the buffer including sizes of the
   *   individual planes and padding if applicable.
   * plane_size - array of uint32_t, size in octets of the corresponding plane
   *   including padding.
   * plane_stride - array of uint32_t, size in octets occupied by the
   *   corresponding single image line including padding if applicable.
   *
   * Note! The sizes and strides in this response apply to all buffers created
   * with XENCAMERA_OP_BUF_CREATE command, but individual buffers may have
   * different plane offsets, see XENCAMERA_OP_BUF_REQUEST.plane_offset.
   */
  struct xencamera_buf_get_layout_resp {
      uint8_t num_planes;
      uint8_t reserved[3];
      uint32_t size;
      uint32_t plane_size[XENCAMERA_MAX_PLANE];
      uint32_t plane_stride[XENCAMERA_MAX_PLANE];
  };
  
  /*
   * Request buffer response - response for XENCAMERA_OP_BUF_REQUEST
   * request:
   *         0                1                 2               3        octet
   * +----------------+----------------+----------------+----------------+
   * |               id                |_OP_BUF_REQUEST |    reserved    | 4
   * +----------------+----------------+----------------+----------------+
   * |                               status                              | 8
   * +----------------+----------------+----------------+----------------+
   * |   num_buffers  |                     reserved                     | 12
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 16
   * +----------------+----------------+----------------+----------------+
   * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 64
   * +----------------+----------------+----------------+----------------+
   *
   * num_buffers - uint8_t, number of buffers to be used.
   *
   *
   * Control enumerate response - response for XENCAMERA_OP_CTRL_ENUM:
   *         0                1                 2               3        octet
   * +----------------+----------------+----------------+----------------+
   * |               id                | _OP_CTRL_ENUM  |    reserved    | 4
   * +----------------+----------------+----------------+----------------+
   * |                               status                              | 8
   * +----------------+----------------+----------------+----------------+
   * |     index      |      type      |            reserved             | 12
   * +----------------+----------------+----------------+----------------+
   * |                               flags                               | 16
   * +----------------+----------------+----------------+----------------+
   * |                          min low 32-bits                          | 20
   * +----------------+----------------+----------------+----------------+
   * |                          min high 32-bits                         | 24
   * +----------------+----------------+----------------+----------------+
   * |                          max low 32-bits                          | 28
   * +----------------+----------------+----------------+----------------+
   * |                          max high 32-bits                         | 32
   * +----------------+----------------+----------------+----------------+
   * |                         step low 32-bits                          | 36
   * +----------------+----------------+----------------+----------------+
   * |                         step high 32-bits                         | 40
   * +----------------+----------------+----------------+----------------+
   * |                        def_val low 32-bits                        | 44
   * +----------------+----------------+----------------+----------------+
   * |                        def_val high 32-bits                       | 48
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 52
   * +----------------+----------------+----------------+----------------+
   * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 64
   * +----------------+----------------+----------------+----------------+
   *
   * index - uint8_t, index of the camera control in response.
   * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
   * flags - uint32_t, flags of the control, one of the XENCAMERA_CTRL_FLG_XXX.
   * min - int64_t, minimum value of the control.
   * max - int64_t, maximum value of the control.
   * step - int64_t, minimum size in which control value can be changed.
   * def_val - int64_t, default value of the control.
   */
  struct xencamera_ctrl_enum_resp {
      uint8_t index;
      uint8_t type;
      uint8_t reserved[2];
      uint32_t flags;
      int64_t min;
      int64_t max;
      int64_t step;
      int64_t def_val;
  };
  
  /*
   * Get control response - response for XENCAMERA_OP_CTRL_GET:
   *         0                1                 2               3        octet
   * +----------------+----------------+----------------+----------------+
   * |               id                | _OP_CTRL_GET   |    reserved    | 4
   * +----------------+----------------+----------------+----------------+
   * |                               status                              | 8
   * +----------------+----------------+----------------+----------------+
   * |       type     |                     reserved                     | 12
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 16
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 20
   * +----------------+----------------+----------------+----------------+
   * |                          value low 32-bit                         | 24
   * +----------------+----------------+----------------+----------------+
   * |                          value high 32-bit                        | 28
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 32
   * +----------------+----------------+----------------+----------------+
   * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 64
   * +----------------+----------------+----------------+----------------+
   *
   * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
   * value - int64_t, new value of the control.
   */
  
  /*
   *----------------------------------- Events ----------------------------------
   *
   * Events are sent via a shared page allocated by the front and propagated by
   *   evt-event-channel/evt-ring-ref XenStore entries.
   *
   * All event packets have the same length (64 octets).
   * All event packets have common header:
   *         0                1                 2               3        octet
   * +----------------+----------------+----------------+----------------+
   * |               id                |      type      |   reserved     | 4
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 8
   * +----------------+----------------+----------------+----------------+
   *
   * id - uint16_t, event id, may be used by front.
   * type - uint8_t, type of the event.
   *
   *
   * Frame captured event - event from back to front when a new captured
   * frame is available:
   *         0                1                 2               3        octet
   * +----------------+----------------+----------------+----------------+
   * |               id                |_EVT_FRAME_AVAIL|   reserved     | 4
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 8
   * +----------------+----------------+----------------+----------------+
   * |      index     |                     reserved                     | 12
   * +----------------+----------------+----------------+----------------+
   * |                              used_sz                              | 16
   * +----------------+----------------+----------------+----------------+
   * |                              seq_num                              | 20
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 24
   * +----------------+----------------+----------------+----------------+
   * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 64
   * +----------------+----------------+----------------+----------------+
   *
   * index - uint8_t, index of the buffer that contains new captured frame,
   *   see XENCAMERA_OP_BUF_CREATE description on the range
   * used_sz - uint32_t, number of octets this frame has. This can be less
   * than the XENCAMERA_OP_BUF_REQUEST.size (response) for compressed formats.
   * seq_num - uint32_t, sequential number of the frame. Must be
   *   monotonically increasing. If skips are detected in seq_num then that
   *   means that the frames in-between were dropped. Note however that not
   *   all video capture hardware is capable of detecting dropped frames.
   *   In that case there will be no skips in the sequence counter.
   */
  struct xencamera_frame_avail_evt {
      uint8_t index;
      uint8_t reserved[3];
      uint32_t used_sz;
      uint32_t seq_num;
  };
  
  /*
   * Control change event- event from back to front when camera control
   * has changed:
   *         0                1                 2               3        octet
   * +----------------+----------------+----------------+----------------+
   * |               id                |_EVT_CTRL_CHANGE|   reserved     | 4
   * +----------------+----------------+----------------+----------------+
   * |       type     |                     reserved                     | 8
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 12
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 16
   * +----------------+----------------+----------------+----------------+
   * |                          value low 32-bit                         | 20
   * +----------------+----------------+----------------+----------------+
   * |                          value high 32-bit                        | 24
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 28
   * +----------------+----------------+----------------+----------------+
   * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
   * +----------------+----------------+----------------+----------------+
   * |                             reserved                              | 64
   * +----------------+----------------+----------------+----------------+
   *
   * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
   * value - int64_t, new value of the control.
   *
   * Notes:
   *  - this event is not sent for write-only controls
   *  - this event is not sent to the originator of the control change
   *  - this event is not sent when frontend first connects, e.g. initial
   *    control state must be explicitly queried
   */
  
  struct xencamera_req {
      uint16_t id;
      uint8_t operation;
      uint8_t reserved[5];
      union {
          struct xencamera_config_req config;
          struct xencamera_frame_rate_req frame_rate;
          struct xencamera_buf_request buf_request;
          struct xencamera_buf_create_req buf_create;
          struct xencamera_index index;
          struct xencamera_ctrl_value ctrl_value;
          struct xencamera_get_ctrl_req get_ctrl;
          uint8_t reserved[56];
      } req;
  };
  
  struct xencamera_resp {
      uint16_t id;
      uint8_t operation;
      uint8_t reserved;
      int32_t status;
      union {
          struct xencamera_config_resp config;
          struct xencamera_buf_get_layout_resp buf_layout;
          struct xencamera_buf_request buf_request;
          struct xencamera_ctrl_enum_resp ctrl_enum;
          struct xencamera_ctrl_value ctrl_value;
          uint8_t reserved1[56];
      } resp;
  };
  
  struct xencamera_evt {
      uint16_t id;
      uint8_t type;
      uint8_t reserved[5];
      union {
          struct xencamera_frame_avail_evt frame_avail;
          struct xencamera_ctrl_value ctrl_value;
          uint8_t reserved[56];
      } evt;
  };
  
  DEFINE_RING_TYPES(xen_cameraif, struct xencamera_req, struct xencamera_resp);
  
  /*
   ******************************************************************************
   *                        Back to front events delivery
   ******************************************************************************
   * In order to deliver asynchronous events from back to front a shared page is
   * allocated by front and its granted reference propagated to back via
   * XenStore entries (evt-ring-ref/evt-event-channel).
   * This page has a common header used by both front and back to synchronize
   * access and control event's ring buffer, while back being a producer of the
   * events and front being a consumer. The rest of the page after the header
   * is used for event packets.
   *
   * Upon reception of an event(s) front may confirm its reception
   * for either each event, group of events or none.
   */
  
  struct xencamera_event_page {
      uint32_t in_cons;
      uint32_t in_prod;
      uint8_t reserved[56];
  };
  
  #define XENCAMERA_EVENT_PAGE_SIZE 4096
  #define XENCAMERA_IN_RING_OFFS (sizeof(struct xencamera_event_page))
  #define XENCAMERA_IN_RING_SIZE (XENCAMERA_EVENT_PAGE_SIZE - XENCAMERA_IN_RING_OFFS)
  #define XENCAMERA_IN_RING_LEN (XENCAMERA_IN_RING_SIZE / sizeof(struct xencamera_evt))
  #define XENCAMERA_IN_RING(page) \
      ((struct xencamera_evt *)((char *)(page) + XENCAMERA_IN_RING_OFFS))
  #define XENCAMERA_IN_RING_REF(page, idx) \
      (XENCAMERA_IN_RING((page))[(idx) % XENCAMERA_IN_RING_LEN])
  
  #endif /* __XEN_PUBLIC_IO_CAMERAIF_H__ */
  
  /*
   * Local variables:
   * mode: C
   * c-file-style: "BSD"
   * c-basic-offset: 4
   * tab-width: 4
   * indent-tabs-mode: nil
   * End:
   */

Cache object: c4ec2d1e1c3f94b0ec42da198e9a6081