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