1 /* 2 * Copyright (c) 2025 tinyVision.ai Inc. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * @file 9 * @brief USB Video Class private header 10 * 11 * Header follows below documentation: 12 * - USB Device Class Definition for Video Devices (Revision 1.5) 13 * 14 * Additional documentation considered a part of UVC 1.5: 15 * - USB Device Class Definition for Video Devices: Uncompressed Payload (Revision 1.5) 16 * - USB Device Class Definition for Video Devices: Motion-JPEG Payload (Revision 1.5) 17 */ 18 19 #ifndef ZEPHYR_INCLUDE_USBD_CLASS_UVC_H_ 20 #define ZEPHYR_INCLUDE_USBD_CLASS_UVC_H_ 21 22 #include <zephyr/usb/usb_ch9.h> 23 24 /* Video Class-Specific Request Codes */ 25 #define UVC_SET_CUR 0x01 26 #define UVC_GET_CUR 0x81 27 #define UVC_GET_MIN 0x82 28 #define UVC_GET_MAX 0x83 29 #define UVC_GET_RES 0x84 30 #define UVC_GET_LEN 0x85 31 #define UVC_GET_INFO 0x86 32 #define UVC_GET_DEF 0x87 33 34 /* Flags announcing which controls are supported */ 35 #define UVC_INFO_SUPPORTS_GET BIT(0) 36 #define UVC_INFO_SUPPORTS_SET BIT(1) 37 38 /* Request Error Code Control */ 39 #define UVC_ERR_NOT_READY 0x01 40 #define UVC_ERR_WRONG_STATE 0x02 41 #define UVC_ERR_OUT_OF_RANGE 0x04 42 #define UVC_ERR_INVALID_UNIT 0x05 43 #define UVC_ERR_INVALID_CONTROL 0x06 44 #define UVC_ERR_INVALID_REQUEST 0x07 45 #define UVC_ERR_INVALID_VALUE_WITHIN_RANGE 0x08 46 #define UVC_ERR_UNKNOWN 0xff 47 48 /* Video and Still Image Payload Headers */ 49 #define UVC_BMHEADERINFO_FRAMEID BIT(0) 50 #define UVC_BMHEADERINFO_END_OF_FRAME BIT(1) 51 #define UVC_BMHEADERINFO_HAS_PRESENTATIONTIME BIT(2) 52 #define UVC_BMHEADERINFO_HAS_SOURCECLOCK BIT(3) 53 #define UVC_BMHEADERINFO_PAYLOAD_SPECIFIC_BIT BIT(4) 54 #define UVC_BMHEADERINFO_STILL_IMAGE BIT(5) 55 #define UVC_BMHEADERINFO_ERROR BIT(6) 56 #define UVC_BMHEADERINFO_END_OF_HEADER BIT(7) 57 58 /* Video Interface Subclass Codes */ 59 #define UVC_SC_VIDEOCONTROL 0x01 60 #define UVC_SC_VIDEOSTREAMING 0x02 61 #define UVC_SC_VIDEO_INTERFACE_COLLECTION 0x03 62 63 /* Video Class-Specific Video Control Interface Descriptor Subtypes */ 64 #define UVC_VC_DESCRIPTOR_UNDEFINED 0x00 65 #define UVC_VC_HEADER 0x01 66 #define UVC_VC_INPUT_TERMINAL 0x02 67 #define UVC_VC_OUTPUT_TERMINAL 0x03 68 #define UVC_VC_SELECTOR_UNIT 0x04 69 #define UVC_VC_PROCESSING_UNIT 0x05 70 #define UVC_VC_EXTENSION_UNIT 0x06 71 #define UVC_VC_ENCODING_UNIT 0x07 72 73 /* Video Class-Specific Video Stream Interface Descriptor Subtypes */ 74 #define UVC_VS_UNDEFINED 0x00 75 #define UVC_VS_INPUT_HEADER 0x01 76 #define UVC_VS_OUTPUT_HEADER 0x02 77 #define UVC_VS_STILL_IMAGE_FRAME 0x03 78 #define UVC_VS_FORMAT_UNCOMPRESSED 0x04 79 #define UVC_VS_FRAME_UNCOMPRESSED 0x05 80 #define UVC_VS_FORMAT_MJPEG 0x06 81 #define UVC_VS_FRAME_MJPEG 0x07 82 #define UVC_VS_FORMAT_MPEG2TS 0x0A 83 #define UVC_VS_FORMAT_DV 0x0C 84 #define UVC_VS_COLORFORMAT 0x0D 85 #define UVC_VS_FORMAT_FRAME_BASED 0x10 86 #define UVC_VS_FRAME_FRAME_BASED 0x11 87 #define UVC_VS_FORMAT_STREAM_BASED 0x12 88 #define UVC_VS_FORMAT_H264 0x13 89 #define UVC_VS_FRAME_H264 0x14 90 #define UVC_VS_FORMAT_H264_SIMULCAST 0x15 91 #define UVC_VS_FORMAT_VP8 0x16 92 #define UVC_VS_FRAME_VP8 0x17 93 #define UVC_VS_FORMAT_VP8_SIMULCAST 0x18 94 95 /* Video Class-Specific Endpoint Descriptor Subtypes */ 96 #define UVC_EP_UNDEFINED 0x00 97 #define UVC_EP_GENERAL 0x01 98 #define UVC_EP_ENDPOINT 0x02 99 #define UVC_EP_INTERRUPT 0x03 100 101 /* USB Terminal Types */ 102 #define UVC_TT_VENDOR_SPECIFIC 0x0100 103 #define UVC_TT_STREAMING 0x0101 104 105 /* Input Terminal Types */ 106 #define UVC_ITT_VENDOR_SPECIFIC 0x0200 107 #define UVC_ITT_CAMERA 0x0201 108 #define UVC_ITT_MEDIA_TRANSPORT_INPUT 0x0202 109 110 /* Output Terminal Types */ 111 #define UVC_OTT_VENDOR_SPECIFIC 0x0300 112 #define UVC_OTT_DISPLAY 0x0301 113 #define UVC_OTT_MEDIA_TRANSPORT_OUTPUT 0x0302 114 115 /* External Terminal Types */ 116 #define UVC_EXT_EXTERNAL_VENDOR_SPECIFIC 0x0400 117 #define UVC_EXT_COMPOSITE_CONNECTOR 0x0401 118 #define UVC_EXT_SVIDEO_CONNECTOR 0x0402 119 #define UVC_EXT_COMPONENT_CONNECTOR 0x0403 120 121 /* VideoStreaming Interface Controls */ 122 #define UVC_VS_PROBE_CONTROL 0x01 123 #define UVC_VS_COMMIT_CONTROL 0x02 124 #define UVC_VS_STILL_PROBE_CONTROL 0x03 125 #define UVC_VS_STILL_COMMIT_CONTROL 0x04 126 #define UVC_VS_STILL_IMAGE_TRIGGER_CONTROL 0x05 127 #define UVC_VS_STREAM_ERROR_CODE_CONTROL 0x06 128 #define UVC_VS_GENERATE_KEY_FRAME_CONTROL 0x07 129 #define UVC_VS_UPDATE_FRAME_SEGMENT_CONTROL 0x08 130 #define UVC_VS_SYNCH_DELAY_CONTROL 0x09 131 132 /* VideoControl Interface Controls */ 133 #define UVC_VC_CONTROL_UNDEFINED 0x00 134 #define UVC_VC_VIDEO_POWER_MODE_CONTROL 0x01 135 #define UVC_VC_REQUEST_ERROR_CODE_CONTROL 0x02 136 137 /* Selector Unit Controls */ 138 #define UVC_SU_INPUT_SELECT_CONTROL 0x01 139 140 /* Camera Terminal Controls */ 141 #define UVC_CT_SCANNING_MODE_CONTROL 0x01 142 #define UVC_CT_AE_MODE_CONTROL 0x02 143 #define UVC_CT_AE_PRIORITY_CONTROL 0x03 144 #define UVC_CT_EXPOSURE_TIME_ABS_CONTROL 0x04 145 #define UVC_CT_EXPOSURE_TIME_REL_CONTROL 0x05 146 #define UVC_CT_FOCUS_ABS_CONTROL 0x06 147 #define UVC_CT_FOCUS_REL_CONTROL 0x07 148 #define UVC_CT_FOCUS_AUTO_CONTROL 0x08 149 #define UVC_CT_IRIS_ABS_CONTROL 0x09 150 #define UVC_CT_IRIS_REL_CONTROL 0x0A 151 #define UVC_CT_ZOOM_ABS_CONTROL 0x0B 152 #define UVC_CT_ZOOM_REL_CONTROL 0x0C 153 #define UVC_CT_PANTILT_ABS_CONTROL 0x0D 154 #define UVC_CT_PANTILT_REL_CONTROL 0x0E 155 #define UVC_CT_ROLL_ABS_CONTROL 0x0F 156 #define UVC_CT_ROLL_REL_CONTROL 0x10 157 #define UVC_CT_PRIVACY_CONTROL 0x11 158 #define UVC_CT_FOCUS_SIMPLE_CONTROL 0x12 159 #define UVC_CT_WINDOW_CONTROL 0x13 160 #define UVC_CT_REGION_OF_INTEREST_CONTROL 0x14 161 162 /* Processing Unit Controls */ 163 #define UVC_PU_BACKLIGHT_COMPENSATION_CONTROL 0x01 164 #define UVC_PU_BRIGHTNESS_CONTROL 0x02 165 #define UVC_PU_CONTRAST_CONTROL 0x03 166 #define UVC_PU_GAIN_CONTROL 0x04 167 #define UVC_PU_POWER_LINE_FREQUENCY_CONTROL 0x05 168 #define UVC_PU_HUE_CONTROL 0x06 169 #define UVC_PU_SATURATION_CONTROL 0x07 170 #define UVC_PU_SHARPNESS_CONTROL 0x08 171 #define UVC_PU_GAMMA_CONTROL 0x09 172 #define UVC_PU_WHITE_BALANCE_TEMP_CONTROL 0x0A 173 #define UVC_PU_WHITE_BALANCE_TEMP_AUTO_CONTROL 0x0B 174 #define UVC_PU_WHITE_BALANCE_COMPONENT_CONTROL 0x0C 175 #define UVC_PU_WHITE_BALANCE_COMPONENT_AUTO_CONTROL 0x0D 176 #define UVC_PU_DIGITAL_MULTIPLIER_CONTROL 0x0E 177 #define UVC_PU_DIGITAL_MULTIPLIER_LIMIT_CONTROL 0x0F 178 #define UVC_PU_HUE_AUTO_CONTROL 0x10 179 #define UVC_PU_ANALOG_VIDEO_STANDARD_CONTROL 0x11 180 #define UVC_PU_ANALOG_LOCK_STATUS_CONTROL 0x12 181 #define UVC_PU_CONTRAST_AUTO_CONTROL 0x13 182 183 /* Encoding Unit Controls */ 184 #define UVC_EU_SELECT_LAYER_CONTROL 0x01 185 #define UVC_EU_PROFILE_TOOLSET_CONTROL 0x02 186 #define UVC_EU_VIDEO_RESOLUTION_CONTROL 0x03 187 #define UVC_EU_MIN_FRAME_INTERVAL_CONTROL 0x04 188 #define UVC_EU_SLICE_MODE_CONTROL 0x05 189 #define UVC_EU_RATE_CONTROL_MODE_CONTROL 0x06 190 #define UVC_EU_AVERAGE_BITRATE_CONTROL 0x07 191 #define UVC_EU_CPB_SIZE_CONTROL 0x08 192 #define UVC_EU_PEAK_BIT_RATE_CONTROL 0x09 193 #define UVC_EU_QUANTIZATION_PARAMS_CONTROL 0x0A 194 #define UVC_EU_SYNC_REF_FRAME_CONTROL 0x0B 195 #define UVC_EU_LTR_BUFFER_CONTROL 0x0C 196 #define UVC_EU_LTR_PICTURE_CONTROL 0x0D 197 #define UVC_EU_LTR_VALIDATION_CONTROL 0x0E 198 #define UVC_EU_LEVEL_IDC_LIMIT_CONTROL 0x0F 199 #define UVC_EU_SEI_PAYLOADTYPE_CONTROL 0x10 200 #define UVC_EU_QP_RANGE_CONTROL 0x11 201 #define UVC_EU_PRIORITY_CONTROL 0x12 202 #define UVC_EU_START_OR_STOP_LAYER_CONTROL 0x13 203 #define UVC_EU_ERROR_RESILIENCY_CONTROL 0x14 204 205 /* Extension Unit Controls */ 206 #define UVC_XU_BASE_CONTROL 0x00 207 208 /* Base GUID string present at the end of most GUID formats, preceded by the FourCC code */ 209 #define UVC_FORMAT_GUID(fourcc) fourcc "\x00\x00\x10\x00\x80\x00\x00\xaa\x00\x38\x9b\x71" 210 211 struct uvc_if_descriptor { 212 uint8_t bLength; 213 uint8_t bDescriptorType; 214 uint8_t bDescriptorSubtype; 215 } __packed; 216 217 struct uvc_control_header_descriptor { 218 uint8_t bLength; 219 uint8_t bDescriptorType; 220 uint8_t bDescriptorSubtype; 221 uint16_t bcdUVC; 222 uint16_t wTotalLength; 223 uint32_t dwClockFrequency; 224 uint8_t bInCollection; 225 uint8_t baInterfaceNr[1]; 226 } __packed; 227 228 struct uvc_unit_descriptor { 229 uint8_t bLength; 230 uint8_t bDescriptorType; 231 uint8_t bDescriptorSubtype; 232 uint8_t bUnitID; 233 }; 234 235 struct uvc_output_terminal_descriptor { 236 uint8_t bLength; 237 uint8_t bDescriptorType; 238 uint8_t bDescriptorSubtype; 239 uint8_t bTerminalID; 240 uint16_t wTerminalType; 241 uint8_t bAssocTerminal; 242 uint8_t bSourceID; 243 uint8_t iTerminal; 244 } __packed; 245 246 struct uvc_camera_terminal_descriptor { 247 uint8_t bLength; 248 uint8_t bDescriptorType; 249 uint8_t bDescriptorSubtype; 250 uint8_t bTerminalID; 251 uint16_t wTerminalType; 252 uint8_t bAssocTerminal; 253 uint8_t iTerminal; 254 uint16_t wObjectiveFocalLengthMin; 255 uint16_t wObjectiveFocalLengthMax; 256 uint16_t wOcularFocalLength; 257 uint8_t bControlSize; 258 uint8_t bmControls[3]; 259 } __packed; 260 261 struct uvc_selector_unit_descriptor { 262 uint8_t bLength; 263 uint8_t bDescriptorType; 264 uint8_t bDescriptorSubtype; 265 uint8_t bUnitID; 266 uint8_t bNrInPins; 267 uint8_t baSourceID[1]; 268 uint8_t iSelector; 269 } __packed; 270 271 struct uvc_processing_unit_descriptor { 272 uint8_t bLength; 273 uint8_t bDescriptorType; 274 uint8_t bDescriptorSubtype; 275 uint8_t bUnitID; 276 uint8_t bSourceID; 277 uint16_t wMaxMultiplier; 278 uint8_t bControlSize; 279 uint8_t bmControls[3]; 280 uint8_t iProcessing; 281 uint8_t bmVideoStandards; 282 } __packed; 283 284 struct uvc_encoding_unit_descriptor { 285 uint8_t bLength; 286 uint8_t bDescriptorType; 287 uint8_t bDescriptorSubtype; 288 uint8_t bUnitID; 289 uint8_t bSourceID; 290 uint8_t iEncoding; 291 uint8_t bControlSize; 292 uint8_t bmControls[3]; 293 uint8_t bmControlsRuntime[3]; 294 } __packed; 295 296 struct uvc_extension_unit_descriptor { 297 uint8_t bLength; 298 uint8_t bDescriptorType; 299 uint8_t bDescriptorSubtype; 300 uint8_t bUnitID; 301 uint8_t guidExtensionCode[16]; 302 uint8_t bNumControls; 303 uint8_t bNrInPins; 304 uint8_t baSourceID[1]; 305 uint8_t bControlSize; 306 uint8_t bmControls[4]; 307 uint8_t iExtension; 308 } __packed; 309 310 struct uvc_stream_header_descriptor { 311 uint8_t bLength; 312 uint8_t bDescriptorType; 313 uint8_t bDescriptorSubtype; 314 uint8_t bNumFormats; 315 uint16_t wTotalLength; 316 uint8_t bEndpointAddress; 317 uint8_t bmInfo; 318 uint8_t bTerminalLink; 319 uint8_t bStillCaptureMethod; 320 uint8_t bTriggerSupport; 321 uint8_t bTriggerUsage; 322 uint8_t bControlSize; 323 } __packed; 324 325 struct uvc_frame_still_image_descriptor { 326 uint8_t bLength; 327 uint8_t bDescriptorType; 328 uint8_t bDescriptorSubtype; 329 uint8_t bEndpointAddress; 330 uint8_t bNumImageSizePatterns; 331 struct { 332 uint16_t wWidth; 333 uint16_t wHeight; 334 } n[1] __packed; 335 uint8_t bNumCompressionPattern; 336 uint8_t bCompression[1]; 337 } __packed; 338 339 struct uvc_format_descriptor { 340 uint8_t bLength; 341 uint8_t bDescriptorType; 342 uint8_t bDescriptorSubtype; 343 uint8_t bFormatIndex; 344 uint8_t bNumFrameDescriptors; 345 /* Other fields depending on bDescriptorSubtype value */ 346 } __packed; 347 348 struct uvc_format_uncomp_descriptor { 349 uint8_t bLength; 350 uint8_t bDescriptorType; 351 uint8_t bDescriptorSubtype; 352 uint8_t bFormatIndex; 353 uint8_t bNumFrameDescriptors; 354 uint8_t guidFormat[16]; 355 uint8_t bBitsPerPixel; 356 uint8_t bDefaultFrameIndex; 357 uint8_t bAspectRatioX; 358 uint8_t bAspectRatioY; 359 uint8_t bmInterlaceFlags; 360 uint8_t bCopyProtect; 361 } __packed; 362 363 struct uvc_format_mjpeg_descriptor { 364 uint8_t bLength; 365 uint8_t bDescriptorType; 366 uint8_t bDescriptorSubtype; 367 uint8_t bFormatIndex; 368 uint8_t bNumFrameDescriptors; 369 uint8_t bmFlags; 370 #define UVC_MJPEG_FLAGS_FIXEDSIZESAMPLES (1 << 0) 371 uint8_t bDefaultFrameIndex; 372 uint8_t bAspectRatioX; 373 uint8_t bAspectRatioY; 374 uint8_t bmInterlaceFlags; 375 uint8_t bCopyProtect; 376 } __packed; 377 378 struct uvc_frame_descriptor { 379 uint8_t bLength; 380 uint8_t bDescriptorType; 381 uint8_t bDescriptorSubtype; 382 uint8_t bFrameIndex; 383 uint8_t bmCapabilities; 384 uint16_t wWidth; 385 uint16_t wHeight; 386 uint32_t dwMinBitRate; 387 uint32_t dwMaxBitRate; 388 uint32_t dwMaxVideoFrameBufferSize; 389 uint32_t dwDefaultFrameInterval; 390 uint8_t bFrameIntervalType; 391 /* Other fields depending on bFrameIntervalType value */ 392 } __packed; 393 394 struct uvc_frame_continuous_descriptor { 395 uint8_t bLength; 396 uint8_t bDescriptorType; 397 uint8_t bDescriptorSubtype; 398 uint8_t bFrameIndex; 399 uint8_t bmCapabilities; 400 uint16_t wWidth; 401 uint16_t wHeight; 402 uint32_t dwMinBitRate; 403 uint32_t dwMaxBitRate; 404 uint32_t dwMaxVideoFrameBufferSize; 405 uint32_t dwDefaultFrameInterval; 406 uint8_t bFrameIntervalType; 407 uint32_t dwMinFrameInterval; 408 uint32_t dwMaxFrameInterval; 409 uint32_t dwFrameIntervalStep; 410 } __packed; 411 412 struct uvc_frame_discrete_descriptor { 413 uint8_t bLength; 414 uint8_t bDescriptorType; 415 uint8_t bDescriptorSubtype; 416 uint8_t bFrameIndex; 417 uint8_t bmCapabilities; 418 uint16_t wWidth; 419 uint16_t wHeight; 420 uint32_t dwMinBitRate; 421 uint32_t dwMaxBitRate; 422 uint32_t dwMaxVideoFrameBufferSize; 423 uint32_t dwDefaultFrameInterval; 424 uint8_t bFrameIntervalType; 425 uint32_t dwFrameInterval[CONFIG_USBD_VIDEO_MAX_FRMIVAL]; 426 } __packed; 427 428 struct uvc_color_descriptor { 429 uint8_t bLength; 430 uint8_t bDescriptorType; 431 uint8_t bDescriptorSubtype; 432 uint8_t bColorPrimaries; 433 uint8_t bTransferCharacteristics; 434 uint8_t bMatrixCoefficients; 435 #define UVC_COLOR_BT709 1 436 #define UVC_COLOR_BT470M 2 437 #define UVC_COLOR_BT470BG 3 438 #define UVC_COLOR_BT601 4 439 #define UVC_COLOR_SMPTE170M 4 440 #define UVC_COLOR_SMPTE240M 5 441 #define UVC_COLOR_LINEAR 6 442 #define UVC_COLOR_SRGB 7 443 } __packed; 444 445 struct uvc_probe { 446 uint16_t bmHint; 447 uint8_t bFormatIndex; 448 uint8_t bFrameIndex; 449 uint32_t dwFrameInterval; 450 uint16_t wKeyFrameRate; 451 uint16_t wPFrameRate; 452 uint16_t wCompQuality; 453 uint16_t wCompWindowSize; 454 uint16_t wDelay; 455 uint32_t dwMaxVideoFrameSize; 456 uint32_t dwMaxPayloadTransferSize; 457 uint32_t dwClockFrequency; 458 uint8_t bmFramingInfo; 459 #define UVC_BMFRAMING_INFO_FID BIT(0) 460 #define UVC_BMFRAMING_INFO_EOF BIT(1) 461 #define UVC_BMFRAMING_INFO_EOS BIT(2) 462 uint8_t bPreferedVersion; 463 uint8_t bMinVersion; 464 uint8_t bMaxVersion; 465 uint8_t bUsage; 466 uint8_t bBitDepthLuma; 467 uint8_t bmSettings; 468 uint8_t bMaxNumberOfRefFramesPlus1; 469 uint16_t bmRateControlModes; 470 uint64_t bmLayoutPerStream; 471 } __packed; 472 473 /* This is a particular variant of this struct that is used by the Zephyr implementation. Other 474 * organization of the fields are allowed by the standard. 475 */ 476 struct uvc_payload_header { 477 uint8_t bHeaderLength; 478 uint8_t bmHeaderInfo; 479 uint32_t dwPresentationTime; /* optional */ 480 uint32_t scrSourceClockSTC; /* optional */ 481 uint16_t scrSourceClockSOF; /* optional */ 482 } __packed; 483 484 #endif /* ZEPHYR_INCLUDE_USBD_CLASS_UVC_H_ */ 485