Lines Matching +full:- +full:- +full:-
24 * Copyright (C) 2018-2019 EPAM Systems Inc.
47 * Front->back notifications: when enqueuing a new request, sending a
49 * hold-off mechanism provided by the ring macros). Backends must set
52 * Back->front notifications: when enqueuing a new response, sending a
54 * hold-off mechanism provided by the ring macros). Frontends must set
57 * The two halves of a para-virtual camera driver utilize nodes within
73 *--------------------------------- Backend -----------------------------------
75 * /local/domain/0/backend/vcamera/1/0/frontend-id = "1"
80 *--------------------------------- Frontend ----------------------------------
82 * /local/domain/1/device/vcamera/0/backend-id = "0"
86 * /local/domain/1/device/vcamera/0/be-alloc = "1"
88 *---------------------------- Device 0 configuration -------------------------
90 * /local/domain/1/device/vcamera/0/max-buffers = "3"
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"
102 *---------------------------- Device 1 configuration -------------------------
104 * /local/domain/1/device/vcamera/1/max-buffers = "8"
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"
118 *----------------------------- Protocol version ------------------------------
130 *-------------------------------- Addressing ---------------------------------
132 * dom-id
137 * dev-id
142 * /local/domain/<dom-id>/device/vcamera/<dev-id>/...
144 *----------------------------- Protocol version ------------------------------
151 *------------------------- Backend buffer allocation -------------------------
153 * be-alloc
161 *------------------------------- Camera settings -----------------------------
163 * unique-id
170 * max-buffers
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'.
194 * 'Y16' and 'Y16-BE' will be trimmed.
204 * frame-rates
211 *------------------- Camera Request Transport Parameters ---------------------
217 * req-event-channel
223 * req-ring-ref
229 *-------------------- Camera Event Transport Parameters ----------------------
234 * evt-event-channel
240 * evt-ring-ref
257 *-------------------------------- Normal flow --------------------------------
307 *------------------------------- Recovery flow -------------------------------
341 * to periodically check if this is the right time to re-try removal of
373 /* Control is read-only. */
375 /* Control is write-only. */
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"
440 #define XENCAMERA_FIELD_FRAME_RATES "frame-rates"
441 #define XENCAMERA_FIELD_BE_ALLOC "be-alloc"
442 #define XENCAMERA_FIELD_UNIQUE_ID "unique-id"
449 #define XENCAMERA_FOURCC_BIGENDIAN_STR "-BE"
459 * Status return code is zero on success and -XEN_EXX on failure.
465 * - usage of grant reference 0 as invalid grant reference:
468 * - all references in this document to page sizes must be treated
470 * - all FOURCC mappings used for configuration and messaging are
473 * - characters are allowed in [0x20; 0x7f] range
474 * - when used for XenStore configuration entries the following
476 * - '/', '\', ' ' (space), '<', '>', ':', '"', '|', '?', '*'
477 * - if trailing spaces are part of the FOURCC code then those must be
485 * The two halves of a Para-virtual camera driver communicate with
492 * - frame rate parameter is represented as a pair of 4 octet long
494 * - frame_rate_numer - uint32_t, numerator of the frame rate
495 * - frame_rate_denom - uint32_t, denominator of the frame rate
498 * - buffer index is a zero based index of the buffer. Must be less than
500 * - index - uint8_t, index of the buffer.
503 *---------------------------------- Requests ---------------------------------
508 * +----------------+----------------+----------------+----------------+
510 * +----------------+----------------+----------------+----------------+
512 * +----------------+----------------+----------------+----------------+
513 * id - uint16_t, private guest value, echoed in response.
514 * operation - uint8_t, operation code, XENCAMERA_OP_XXX.
517 * Request to set/validate the configuration - request to set the
522 * +----------------+----------------+----------------+----------------+
524 * +----------------+----------------+----------------+----------------+
526 * +----------------+----------------+----------------+----------------+
528 * +----------------+----------------+----------------+----------------+
530 * +----------------+----------------+----------------+----------------+
532 * +----------------+----------------+----------------+----------------+
534 * +----------------+----------------+----------------+----------------+
536 * +----------------+----------------+----------------+----------------+
538 * +----------------+----------------+----------------+----------------+
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.
547 * - the only difference between XENCAMERA_OP_CONFIG_VALIDATE and
551 * - frontend must check the corresponding response in order to see
554 * - frontend may send multiple XENCAMERA_OP_CONFIG_SET requests before
557 * - configuration cannot be changed during active streaming, e.g.
570 * +----------------+----------------+----------------+----------------+
572 * +----------------+----------------+----------------+----------------+
574 * +----------------+----------------+----------------+----------------+
576 * +----------------+----------------+----------------+----------------+
578 * +----------------+----------------+----------------+----------------+
585 * +----------------+----------------+----------------+----------------+
587 * +----------------+----------------+----------------+----------------+
589 * +----------------+----------------+----------------+----------------+
591 * +----------------+----------------+----------------+----------------+
593 * +----------------+----------------+----------------+----------------+
595 * +----------------+----------------+----------------+----------------+
597 * +----------------+----------------+----------------+----------------+
599 * +----------------+----------------+----------------+----------------+
601 * frame_rate_numer - uint32_t, numerator of the frame rate.
602 * frame_rate_denom - uint32_t, denominator of the frame rate.
605 * - to query the current (actual) frame rate use XENCAMERA_OP_CONFIG_GET
607 * - this request can be used with camera buffers allocated, but stream
613 * - frame rate cannot be changed during active streaming, e.g.
625 * +----------------+----------------+----------------+----------------+
627 * +----------------+----------------+----------------+----------------+
629 * +----------------+----------------+----------------+----------------+
631 * +----------------+----------------+----------------+----------------+
633 * +----------------+----------------+----------------+----------------+
640 * +----------------+----------------+----------------+----------------+
642 * +----------------+----------------+----------------+----------------+
644 * +----------------+----------------+----------------+----------------+
646 * +----------------+----------------+----------------+----------------+
648 * +----------------+----------------+----------------+----------------+
650 * +----------------+----------------+----------------+----------------+
652 * +----------------+----------------+----------------+----------------+
654 * num_bufs - uint8_t, desired number of buffers to be used.
665 * with a non-zero value of num_bufs. If camera reconfiguration is required
680 * the value configured in XenStore.max-buffers.
691 * +----------------+----------------+----------------+----------------+
693 * +----------------+----------------+----------------+----------------+
695 * +----------------+----------------+----------------+----------------+
697 * +----------------+----------------+----------------+----------------+
699 * +----------------+----------------+----------------+----------------+
701 * +----------------+----------------+----------------+----------------+
703 * +----------------+----------------+----------------+----------------+
705 * +----------------+----------------+----------------+----------------+
707 * +----------------+----------------+----------------+----------------+
709 * +----------------+----------------+----------------+----------------+
711 * +----------------+----------------+----------------+----------------+
713 * +----------------+----------------+----------------+----------------+
716 * index can be re-used after destroying the corresponding camera buffer.
718 * index - uint8_t, index of the buffer to be created in the range
721 * plane_offset - array of uint32_t, offset of the corresponding plane
724 * gref_directory - grant_ref_t, a reference to the first shared page
735 * - allocates pages for the directory (gref_directory,
737 * - grants permissions for the pages of the directory to the backend
738 * - sets gref_dir_next_page fields
740 * - grants permissions for the pages of the buffer allocated to
742 * - fills in page directory with grant references
757 * +----------------+----------------+----------------+----------------+
759 * +----------------+----------------+----------------+----------------+
761 * +----------------+----------------+----------------+----------------+
763 * +----------------+----------------+----------------+----------------+
765 * +----------------+----------------+----------------+----------------+
767 * +----------------+----------------+----------------+----------------+
768 * | gref[N - 1] | N*4+8
769 * +----------------+----------------+----------------+----------------+
771 * gref_dir_next_page - grant_ref_t, reference to the next page describing
773 * gref[i] - grant_ref_t, reference to a shared page of the buffer
778 * num_grefs_total = (XENCAMERA_OP_BUF_REQUEST.size + XEN_PAGE_SIZE - 1) /
787 * Request buffer destruction - destroy a previously allocated camera buffer:
789 * +----------------+----------------+----------------+----------------+
791 * +----------------+----------------+----------------+----------------+
793 * +----------------+----------------+----------------+----------------+
795 * +----------------+----------------+----------------+----------------+
797 * +----------------+----------------+----------------+----------------+
799 * +----------------+----------------+----------------+----------------+
801 * +----------------+----------------+----------------+----------------+
803 * index - uint8_t, index of the buffer to be destroyed.
808 * +----------------+----------------+----------------+----------------+
810 * +----------------+----------------+----------------+----------------+
812 * +----------------+----------------+----------------+----------------+
814 * +----------------+----------------+----------------+----------------+
816 * +----------------+----------------+----------------+----------------+
818 * +----------------+----------------+----------------+----------------+
820 * +----------------+----------------+----------------+----------------+
823 * - frontends must not access the buffer content after this request until
825 * - buffers must be queued to the backend before destroying them with
828 * index - uint8_t, index of the buffer to be queued.
833 * +----------------+----------------+----------------+----------------+
835 * +----------------+----------------+----------------+----------------+
837 * +----------------+----------------+----------------+----------------+
839 * +----------------+----------------+----------------+----------------+
841 * +----------------+----------------+----------------+----------------+
843 * +----------------+----------------+----------------+----------------+
845 * +----------------+----------------+----------------+----------------+
848 * - frontend is allowed to access the buffer content after the corresponding
851 * index - uint8_t, index of the buffer to be queued.
856 * +----------------+----------------+----------------+----------------+
858 * +----------------+----------------+----------------+----------------+
860 * +----------------+----------------+----------------+----------------+
862 * +----------------+----------------+----------------+----------------+
864 * +----------------+----------------+----------------+----------------+
866 * +----------------+----------------+----------------+----------------+
870 * index - uint8_t, index of the control to be queried.
879 * +----------------+----------------+----------------+----------------+
881 * +----------------+----------------+----------------+----------------+
883 * +----------------+----------------+----------------+----------------+
885 * +----------------+----------------+----------------+----------------+
887 * +----------------+----------------+----------------+----------------+
888 * | value low 32-bit | 20
889 * +----------------+----------------+----------------+----------------+
890 * | value high 32-bit | 24
891 * +----------------+----------------+----------------+----------------+
893 * +----------------+----------------+----------------+----------------+
895 * +----------------+----------------+----------------+----------------+
897 * +----------------+----------------+----------------+----------------+
899 * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
900 * value - int64_t, new value of the control.
911 * +----------------+----------------+----------------+----------------+
913 * +----------------+----------------+----------------+----------------+
915 * +----------------+----------------+----------------+----------------+
917 * +----------------+----------------+----------------+----------------+
919 * +----------------+----------------+----------------+----------------+
921 * +----------------+----------------+----------------+----------------+
925 * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
934 * +----------------+----------------+----------------+----------------+
936 * +----------------+----------------+----------------+----------------+
938 * +----------------+----------------+----------------+----------------+
940 * +----------------+----------------+----------------+----------------+
942 * +----------------+----------------+----------------+----------------+
947 * +----------------+----------------+----------------+----------------+
949 * +----------------+----------------+----------------+----------------+
951 * +----------------+----------------+----------------+----------------+
953 * +----------------+----------------+----------------+----------------+
955 * +----------------+----------------+----------------+----------------+
958 *---------------------------------- Responses --------------------------------
964 * +----------------+----------------+----------------+----------------+
966 * +----------------+----------------+----------------+----------------+
968 * +----------------+----------------+----------------+----------------+
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.
975 * Configuration response - response for XENCAMERA_OP_CONFIG_SET,
978 * +----------------+----------------+----------------+----------------+
980 * +----------------+----------------+----------------+----------------+
982 * +----------------+----------------+----------------+----------------+
984 * +----------------+----------------+----------------+----------------+
986 * +----------------+----------------+----------------+----------------+
988 * +----------------+----------------+----------------+----------------+
990 * +----------------+----------------+----------------+----------------+
992 * +----------------+----------------+----------------+----------------+
994 * +----------------+----------------+----------------+----------------+
996 * +----------------+----------------+----------------+----------------+
998 * +----------------+----------------+----------------+----------------+
1000 * +----------------+----------------+----------------+----------------+
1002 * +----------------+----------------+----------------+----------------+
1004 * +----------------+----------------+----------------+----------------+
1006 * +----------------+----------------+----------------+----------------+
1008 * +----------------+----------------+----------------+----------------+
1010 * +----------------+----------------+----------------+----------------+
1015 * colorspace - uint32_t, this supplements pixel_format parameter,
1017 * xfer_func - uint32_t, this supplements colorspace parameter,
1019 * ycbcr_enc - uint32_t, this supplements colorspace parameter,
1022 * quantization - uint32_t, this supplements colorspace parameter,
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.
1042 * Request buffer response - response for XENCAMERA_OP_BUF_GET_LAYOUT
1045 * +----------------+----------------+----------------+----------------+
1047 * +----------------+----------------+----------------+----------------+
1049 * +----------------+----------------+----------------+----------------+
1051 * +----------------+----------------+----------------+----------------+
1053 * +----------------+----------------+----------------+----------------+
1055 * +----------------+----------------+----------------+----------------+
1057 * +----------------+----------------+----------------+----------------+
1059 * +----------------+----------------+----------------+----------------+
1061 * +----------------+----------------+----------------+----------------+
1063 * +----------------+----------------+----------------+----------------+
1065 * +----------------+----------------+----------------+----------------+
1067 * +----------------+----------------+----------------+----------------+
1069 * +----------------+----------------+----------------+----------------+
1071 * +----------------+----------------+----------------+----------------+
1073 * +----------------+----------------+----------------+----------------+
1075 * num_planes - uint8_t, number of planes of the buffer.
1076 * size - uint32_t, overall size of the buffer including sizes of the
1078 * plane_size - array of uint32_t, size in octets of the corresponding plane
1080 * plane_stride - array of uint32_t, size in octets occupied by the
1096 * Request buffer response - response for XENCAMERA_OP_BUF_REQUEST
1099 * +----------------+----------------+----------------+----------------+
1101 * +----------------+----------------+----------------+----------------+
1103 * +----------------+----------------+----------------+----------------+
1105 * +----------------+----------------+----------------+----------------+
1107 * +----------------+----------------+----------------+----------------+
1109 * +----------------+----------------+----------------+----------------+
1111 * +----------------+----------------+----------------+----------------+
1113 * num_buffers - uint8_t, number of buffers to be used.
1116 * Control enumerate response - response for XENCAMERA_OP_CTRL_ENUM:
1118 * +----------------+----------------+----------------+----------------+
1120 * +----------------+----------------+----------------+----------------+
1122 * +----------------+----------------+----------------+----------------+
1124 * +----------------+----------------+----------------+----------------+
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 * +----------------+----------------+----------------+----------------+
1144 * +----------------+----------------+----------------+----------------+
1146 * +----------------+----------------+----------------+----------------+
1148 * +----------------+----------------+----------------+----------------+
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.
1170 * Get control response - response for XENCAMERA_OP_CTRL_GET:
1172 * +----------------+----------------+----------------+----------------+
1174 * +----------------+----------------+----------------+----------------+
1176 * +----------------+----------------+----------------+----------------+
1178 * +----------------+----------------+----------------+----------------+
1180 * +----------------+----------------+----------------+----------------+
1182 * +----------------+----------------+----------------+----------------+
1183 * | value low 32-bit | 24
1184 * +----------------+----------------+----------------+----------------+
1185 * | value high 32-bit | 28
1186 * +----------------+----------------+----------------+----------------+
1188 * +----------------+----------------+----------------+----------------+
1190 * +----------------+----------------+----------------+----------------+
1192 * +----------------+----------------+----------------+----------------+
1194 * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
1195 * value - int64_t, new value of the control.
1199 *----------------------------------- Events ----------------------------------
1202 * evt-event-channel/evt-ring-ref XenStore entries.
1207 * +----------------+----------------+----------------+----------------+
1209 * +----------------+----------------+----------------+----------------+
1211 * +----------------+----------------+----------------+----------------+
1213 * id - uint16_t, event id, may be used by front.
1214 * type - uint8_t, type of the event.
1217 * Frame captured event - event from back to front when a new captured
1220 * +----------------+----------------+----------------+----------------+
1222 * +----------------+----------------+----------------+----------------+
1224 * +----------------+----------------+----------------+----------------+
1226 * +----------------+----------------+----------------+----------------+
1228 * +----------------+----------------+----------------+----------------+
1230 * +----------------+----------------+----------------+----------------+
1232 * +----------------+----------------+----------------+----------------+
1234 * +----------------+----------------+----------------+----------------+
1236 * +----------------+----------------+----------------+----------------+
1238 * index - uint8_t, index of the buffer that contains new captured frame,
1240 * used_sz - uint32_t, number of octets this frame has. This can be less
1242 * seq_num - uint32_t, sequential number of the frame. Must be
1244 * means that the frames in-between were dropped. Note however that not
1256 * Control change event- event from back to front when camera control
1259 * +----------------+----------------+----------------+----------------+
1261 * +----------------+----------------+----------------+----------------+
1263 * +----------------+----------------+----------------+----------------+
1265 * +----------------+----------------+----------------+----------------+
1267 * +----------------+----------------+----------------+----------------+
1268 * | value low 32-bit | 20
1269 * +----------------+----------------+----------------+----------------+
1270 * | value high 32-bit | 24
1271 * +----------------+----------------+----------------+----------------+
1273 * +----------------+----------------+----------------+----------------+
1275 * +----------------+----------------+----------------+----------------+
1277 * +----------------+----------------+----------------+----------------+
1279 * type - uint8_t, type of the control, one of the XENCAMERA_CTRL_XXX.
1280 * value - int64_t, new value of the control.
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
1339 * XenStore entries (evt-ring-ref/evt-event-channel).
1357 #define XENCAMERA_IN_RING_SIZE (XENCAMERA_EVENT_PAGE_SIZE - XENCAMERA_IN_RING_OFFS)
1369 * c-file-style: "BSD"
1370 * c-basic-offset: 4
1371 * tab-width: 4
1372 * indent-tabs-mode: nil