1 /* 2 * Copyright 2019 NXP 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 #ifndef _USB_HOST_VIDEO_H_ 9 #define _USB_HOST_VIDEO_H_ 10 11 /******************************************************************************* 12 * Definitions 13 ******************************************************************************/ 14 15 /*! @brief Video class code */ 16 #define USB_HOST_VIDEO_CLASS_CODE (0x0EU) 17 /*! @brief Video class control interface code*/ 18 #define USB_HOST_VIDEO_SUBCLASS_CODE_CONTROL (0x01U) 19 /*! @brief Video class stream interface code*/ 20 #define USB_HOST_VIDEO_SUBCLASS_CODE_STREAM (0x02U) 21 /* Video Interface Protocol Codes */ 22 #define USB_HOST_ROTOCOL_UNDEFINED (0x00U) 23 24 /* Video Class-Specific Descriptor Types */ 25 #define USB_HOST_DESC_CS_UNDEFINED (0x20U) 26 #define USB_HOST_DESC_CS_DEVICE (0x21U) 27 #define USB_HOST_DESC_CS_CONFIGURATION (0x22U) 28 #define USB_HOST_DESC_CS_STRING (0x23U) 29 #define USB_HOST_DESC_CS_INTERFACE (0x24U) 30 #define USB_HOST_DESC_CS_ENDPOINT (0x25U) 31 32 /* Video Class-Specific VC Interface Descriptor Subtypes */ 33 #define USB_HOST_DESC_SUBTYPE_VC_UNDEFINED (0x00U) 34 #define USB_HOST_DESC_SUBTYPE_VC_HEADER (0x01U) 35 #define USB_HOST_DESC_SUBTYPE_VC_INPUT_TERMINAL (0x02U) 36 #define USB_HOST_DESC_SUBTYPE_VC_OUTPUT_TERMINAL (0x03U) 37 #define USB_HOST_DESC_SUBTYPE_VC_SECLECTOR_UNIT (0x04U) 38 #define USB_HOST_DESC_SUBTYPE_VC_PROCESSING_UNIT (0X05U) 39 #define USB_HOST_DESC_SUBTYPE_VC_EXTENSION_UNIT (0X06U) 40 41 /* Video Class-specific VS Interface Desriptor Subtypes */ 42 #define USB_HOST_DESC_SUBTYPE_VS_UNDEFINED (0x00U) 43 #define USB_HOST_DESC_SUBTYPE_VS_INPUT_HEADER (0x01U) 44 #define USB_HOST_DESC_SUBTYPE_VS_OUTPUT_HEADER (0x02U) 45 #define USB_HOST_DESC_SUBTYPE_VS_STILL_IMAGE_FRAME (0x03U) 46 #define USB_HOST_DESC_SUBTYPE_VS_FORMAT_UNCOMPRESSED (0x04U) 47 #define USB_HOST_DESC_SUBTYPE_VS_FRAME_UNCOMPRESSED (0x05U) 48 #define USB_HOST_DESC_SUBTYPE_VS_FORMAT_MJPEG (0x06U) 49 #define USB_HOST_DESC_SUBTYPE_VS_FRAME_MJPEG (0x07U) 50 #define USB_HOST_DESC_SUBTYPE_VS_FORMAT_MPEG2TS (0x0AU) 51 #define USB_HOST_DESC_SUBTYPE_VS_FORMAT_DV (0x0CU) 52 #define USB_HOST_DESC_SUBTYPE_VS_COLOR_FORMAT (0x0DU) 53 #define USB_HOST_DESC_SUBTYPE_VS_FORMAT_FRAME_BASED (0x10U) 54 #define USB_HOST_DESC_SUBTYPE_VS_FRAME_FRAME_BASED (0x11U) 55 #define USB_HOST_DESC_SUBTYPE_VS_FORMAT_STREAM_BASED (0x12U) 56 57 /* Video Class-Specific Endpoint Descriptor Subtypes */ 58 #define USB_HOST_DESC_SUBTYPE_EP_UNDEFINED (0x00U) 59 #define USB_HOST_DESC_SUBTYPE_EP_GENERAL (0x01U) 60 #define USB_HOST_DESC_SUBTYPE_EP_ENDPOINT (0x02U) 61 #define USB_HOST_DESC_SUBTYPE_EP_INTERRUPT (0x03U) 62 63 /* Video Class-Specific Request Codes */ 64 #define USB_HOST_VIDEO_SET_CUR (0x01U) 65 #define USB_HOST_VIDEO_GET_CUR (0x81U) 66 #define USB_HOST_VIDEO_GET_MIN (0x82U) 67 #define USB_HOST_VIDEO_GET_MAX (0x83U) 68 #define USB_HOST_VIDEO_GET_RES (0x84U) 69 #define USB_HOST_VIDEO_GET_LEN (0x85U) 70 #define USB_HOST_VIDEO_GET_INFO (0x86U) 71 #define USB_HOST_VIDEO_GET_DEF (0x87U) 72 73 /* VideoControl Interface Control Selector Codes */ 74 #define USB_HOST_VC_CONTROL_UNDEFINED (0x00U) 75 #define USB_HOST_VC_VIDEO_POWER_MODE_CONTROL (0x01U) 76 #define USB_HOST_VC_REQUEST_ERROR_CODE_CONTROL (0x02U) 77 78 /* Terminal Control Selector Codes */ 79 #define USB_HOST_USB_HOST_TE_CONTROL_UNDEFINED (0x00U) 80 81 /* Selector Unit Control Selector Codes */ 82 #define USB_HOST_SU_CONTROL_UNDEFINED (0x00U) 83 #define USB_HOST_SU_INPUT_SELECT_CONTROL (0x01U) 84 85 /* Camera Terminal Control Selector Codes */ 86 #define USB_HOST_CT_CONTROL_UNDEFINED (0x00U) 87 #define USB_HOST_CT_SCANNING_MODE_CONTROL (0x01U) 88 #define USB_HOST_CT_AE_MODE_CONTROL (0x02U) 89 #define USB_HOST_CT_AE_PRIORITY_CONTROL (0x03U) 90 #define USB_HOST_CT_EXPOSURE_TIME_ABSOLUTE_CONTROL (0x04U) 91 #define USB_HOST_CT_EXPOSURE_TIME_RELATIVE_CONTROL (0x05U) 92 #define USB_HOST_CT_FOCUS_ABSOLUTE_CONTROL (0x06U) 93 #define USB_HOST_CT_FOCUS_RELATIVE_CONTROL (0x07U) 94 #define USB_HOST_CT_FOCUS_AUTO_CONTROL (0x08U) 95 #define USB_HOST_CT_IRIS_ABSOLUTE_CONTROL (0x09U) 96 #define USB_HOST_CT_IRIS_RELATIVE_CONTROL (0x0AU) 97 #define USB_HOST_CT_ZOOM_ABSOLUTE_CONTROL (0x0BU) 98 #define USB_HOST_CT_ZOOM_RELATIVE_CONTROL (0x0CU) 99 #define USB_HOST_CT_PANTILT_ABSOLUTE_CONTROL (0x0DU) 100 #define USB_HOST_CT_PANTILT_RELATIVE_CONTROL (0x0EU) 101 #define USB_HOST_CT_ROLL_ABSOLUTE_CONTROL (0x0FU) 102 #define USB_HOST_CT_ROLL_RELATIVE_CONTROL (0x10U) 103 #define USB_HOST_CT_PRIVACY_CONTROL (0x11U) 104 105 /* Processing Unit Control Selector Codes */ 106 #define USB_HOST_PU_CONTROL_UNDEFINED (0x00U) 107 #define USB_HOST_PU_BACKLIGHT_COMPENSATION_CONTROL (0x01U) 108 #define USB_HOST_PU_BRIGHTNESS_CONTROL (0x02U) 109 #define USB_HOST_PU_CONTRACT_CONTROL (0x03U) 110 #define USB_HOST_PU_GAIN_CONTROL (0x04U) 111 #define USB_HOST_PU_POWER_LINE_FREQUENCY_CONTROL (0x05U) 112 #define USB_HOST_PU_HUE_CONTROL (0x06U) 113 #define USB_HOST_PU_SATURATION_CONTROL (0x07U) 114 #define USB_HOST_PU_SHARRNESS_CONTROL (0x08U) 115 #define USB_HOST_PU_GAMMA_CONTROL (0x09U) 116 #define USB_HOST_PU_WHITE_BALANCE_TEMPERATURE_CONTROL (0x0AU) 117 #define USB_HOST_PU_WHITE_BALANCE_TEMPERATURE_AUTO_CONTROL (0x0BU) 118 #define USB_HOST_PU_WHITE_BALANCE_COMPONENT_CONTROL (0x0CU) 119 #define USB_HOST_PU_WHITE_BALANCE_COMPONENT_AUTO_CONTROL (0x0DU) 120 #define USB_HOST_PU_DIGITAL_MULTIPLIER_CONTROL (0x0EU) 121 #define USB_HOST_PU_DIGITAL_MULTIPLIER_LIMIT_CONTROL (0x0FU) 122 #define USB_HOST_PU_HUE_AUTO_CONTROL (0x10U) 123 #define USB_HOST_PU_ANALOG_VIDEO_STANDARD_CONTROL (0x11U) 124 #define USB_HOST_PU_ANALOG_LOCK_STATUS_CONTROL (0x12U) 125 126 /* Extension Unit Control Selectors Codes */ 127 #define USB_HOST_XU_CONTROL_UNDEFINED (0x00U) 128 129 /* VideoStreming Unit Control Selector Codes */ 130 #define USB_HOST_VS_CONTROL_UNDEFINED (0x00UL) 131 #define USB_HOST_VS_PROBE_CONTROL (0x01UL) 132 #define USB_HOST_VS_COMMIT_CONTROL (0x02UL) 133 #define USB_HOST_VS_STILL_PROBE_CONTROL (0x03UL) 134 #define USB_HOST_VS_STILL_COMMIT_CONTROL (0x04UL) 135 #define USB_HOST_VS_STILL_IMAGE_TRIGGER_CONTROL (0x05UL) 136 #define USB_HOST_VS_STREAM_ERROR_CODE_CONTROL (0x06UL) 137 #define USB_HOST_VS_GENERATE_KEY_FRAME_CONTROL (0x07UL) 138 #define USB_HOST_VS_UPDATE_FRAME_SEGMENT_CONTROL (0x08UL) 139 #define USB_HOST_VS_SYNCH_DELAY_CONTROL (0x09UL) 140 141 /*! @brief Video control interface header descriptor structure */ 142 typedef struct _usb_host_video_ctrl_header_desc 143 { 144 /*< Total size of the video control header descriptor */ 145 uint8_t bLength; 146 /*< Descriptor type of video control header descriptor */ 147 uint8_t bDescriptorType; 148 /*< Subtype of video control header descriptor */ 149 uint8_t bDescriptorSubtype; 150 /*< Video Device Class Specification release number in binary-coded decimal */ 151 uint8_t bcdVDC[2]; 152 /*< Total number of bytes returned for the class-specific VideoControl interface descriptor. Includes the combined 153 * length of this descriptor header and all Unit and Terminal descriptors */ 154 uint8_t wTotalLength[2]; 155 /*< The device clock frequency in Hz. This will specify the units used for the time information fields in the Video 156 * Payload Headers of the primary data stream and format */ 157 uint8_t dwClockFrequency[4]; 158 /*< The number of VideoStreaming interfaces in the Video Interface Collection to which this VideoControl interface 159 * belongs: n */ 160 uint8_t bInCollection; 161 } usb_host_video_ctrl_header_desc_t; 162 163 /*! @brief video control interface iutput terminal descriptor structure */ 164 typedef struct _usb_host_video_ctrl_it_desc 165 { 166 /*< Total size of the video control input terminal descriptor */ 167 uint8_t bLength; 168 /*< Descriptor type of video control input terminal descriptor */ 169 uint8_t bDescriptorType; 170 /*< Subtype of video control input terminal descriptor */ 171 uint8_t bDescriptorSubtype; 172 /*< A non-zero constant that uniquely identifies the Terminal within the video function */ 173 uint8_t bTerminalID; 174 /*< Constant that characterizes the type of Terminal */ 175 uint8_t wTerminalType[2]; 176 /*< ID of the Output Terminal to which this Input Terminal is associated, or zero (0) if no such association exists 177 */ 178 uint8_t bAssocTerminal; 179 /*< Index of a string descriptor, describing the Input Terminal */ 180 uint8_t iTerminal; 181 } usb_host_video_ctrl_it_desc_t; 182 183 /*! @brief video control interface output terminal descriptor structure */ 184 typedef struct _usb_host_video_ctrl_ot_desc 185 { 186 /*< Total size of the video control output terminal descriptor */ 187 uint8_t bLength; 188 /*< Descriptor type of video control output terminal descriptor */ 189 uint8_t bDescriptorType; 190 /*< Subtype of video control output terminal descriptor */ 191 uint8_t bDescriptorSubtype; 192 /*< A non-zero constant that uniquely identifies the Terminal within the video function */ 193 uint8_t bTerminalID; 194 /*< Constant that characterizes the type of Terminal */ 195 uint8_t wTerminalType[2]; 196 /*< Constant, identifying the Input Terminal to which this Output Terminal is associated, or zero (0) if no such 197 * association exists. */ 198 uint8_t bAssocTerminal; 199 /*< ID of the Unit or Terminal to which this Terminal is connected */ 200 uint8_t bSourceID; 201 /*< Index of a string descriptor, describing the Output Terminal. */ 202 uint8_t iTerminal; 203 } usb_host_video_ctrl_ot_desc_t; 204 205 /*! @brief video control interface camera terminal descriptor structure */ 206 typedef struct _usb_host_video_ctrl_ct_desc 207 { 208 /*< Total size of the video control camera terminal descriptor */ 209 uint8_t bLength; 210 /*< Descriptor type of video control camera terminal descriptor */ 211 uint8_t bDescriptorType; 212 /*< Subtype of video control camera terminal descriptor */ 213 uint8_t bDescriptorSubtype; 214 /*< A non-zero constant that uniquely identifies the Terminal within the video function */ 215 uint8_t bTerminalID; 216 /*< Constant that characterizes the type of Terminal */ 217 uint8_t wTerminalType[2]; 218 /*< ID of the Output Terminal to which this Input Terminal is associated */ 219 uint8_t bAssocTerminal; 220 /*< Index of a string descriptor that describes the Camera Terminal */ 221 uint8_t iTerminal; 222 /*< The value of Lmim If Optical Zoom is not supported; this field shall be set to 0 */ 223 uint8_t wObjectiveFocalLengthMin[2]; 224 /*< The value of Lmax If Optical Zoom is not supported; this field shall be set to 0 */ 225 uint8_t wObjectiveFocalLengthMax[2]; 226 /*< The value of Locular If Optical Zoom is not supported; this field shall be set to 0 */ 227 uint8_t wOcularFocalLength[2]; 228 /*< Size in bytes of the bmControls field:3 */ 229 uint8_t bControlSize; 230 /*< A bit set to 1 indicates that the mentioned Control is supported for the video stream */ 231 uint8_t bmControls[2]; 232 } usb_host_video_ctrl_ct_desc_t; 233 234 /*! @brief video control interface selcetor unit descriptor structure */ 235 typedef struct _usb_host_video_ctrl_su_desc 236 { 237 /*< Total size of the video control selector unit descriptor */ 238 uint8_t bLength; 239 /*< Descriptor type of video control selector unit descriptor */ 240 uint8_t bDescriptorType; 241 /*< Subtype of the video control selector unit descriptor */ 242 uint8_t bDescriptorSubtype; 243 /*< A non-zero constant that uniquely identifies the Unit within the video function */ 244 uint8_t bUnitID; 245 /*< Number of Input Pins of this Unit: p */ 246 uint8_t bNrInPins; 247 } usb_host_video_ctrl_su_desc_t; 248 249 /*! @brief video control interface processing unit descriptor structure */ 250 typedef struct _usb_host_video_ctrl_pu_desc 251 { 252 /*< Total size of the video control processing unit descriptor */ 253 uint8_t bLength; 254 /*< Descriptor type of video control processing unit descriptor */ 255 uint8_t bDescriptorType; 256 /*< Subtype of the video control processing unit descriptor */ 257 uint8_t bDescriptorSubtype; 258 /*< A non-zero constant that uniquely identifies the Unit within the video function */ 259 uint8_t bUnitID; 260 /*< ID of the Unit or Terminal to which this Unit is connected */ 261 uint8_t bSourceID; 262 /*< If the Digital Multiplier control is supported, this field indicates the maximum digital magnification, 263 * multiplied by 100 */ 264 uint8_t wMaxMultiplier[2]; 265 /*< Size of the bmControls field, in bytes:3 */ 266 uint8_t bControlSize; 267 268 } usb_host_video_ctrl_pu_desc_t; 269 270 /*! @brief video stream interface input header descriptor structure */ 271 typedef struct _usb_host_video_stream_input_header_desc 272 { 273 /*< Total size of the video stream input header descriptor */ 274 uint8_t bLength; 275 /*< Descriptor type of video stream input header descriptor */ 276 uint8_t bDescriptorType; 277 /*< Subtype of video stream input header descriptor */ 278 uint8_t bDescriptorSubtype; 279 /*< Number of video payload Format descriptors following for this interface */ 280 uint8_t bNumFormats; 281 /*< Total number of bytes returned for the class-specific VideoStreaming interface descriptors including this header 282 * descriptor */ 283 uint8_t wTotalLength[2]; 284 /*< The address of the isochronous or bulk endpoint used for video data */ 285 uint8_t bEndpointAddress; 286 /*< Indicates the capabilities of this VideoStreaming interface */ 287 uint8_t bmInfo; 288 /*< The terminal ID of the Output Terminal to which the video endpoint of this interface is connected */ 289 uint8_t bTerminalLink; 290 /*< Method of still image capture supported as described in section 2.4.2.4 in UVC 1.5 class Spec */ 291 uint8_t bStillCaptureMethod; 292 /*< Specifies if hardware triggering is supported through this interface */ 293 uint8_t bTriggerSupport; 294 /*< Specifies how the host software shall respond to a hardware trigger interrupt event from this interface */ 295 uint8_t bTriggerUsage; 296 /*< Size of each bmaControls(x) field, in bytes:n */ 297 uint8_t bControlSize; 298 } usb_host_video_stream_input_header_desc_t; 299 300 /*! @brief video stream interface output header descriptor structure */ 301 typedef struct _usb_host_video_stream_output_header_desc 302 { 303 /*< Total size of the video stream output header descriptor */ 304 uint8_t bLength; 305 /*< Descriptor type of video stream output header descriptor */ 306 uint8_t bDescriptorType; 307 /*< Subtype of video stream output header descriptor */ 308 uint8_t bDescriptorSubtype; 309 /*< Number of video payload Format descriptors following for this interface */ 310 uint8_t bNumFormats; 311 /*< Total number of bytes returned for the class-specific VideoStreaming interface descriptors including this header 312 * descriptor */ 313 uint8_t wTotalLength[2]; 314 /*< The address of the isochronous or bulk endpoint used for video data */ 315 uint8_t bEndpointAddress; 316 /*< The terminal ID of the Input Terminal to which the video endpoint of this interface is connected */ 317 uint8_t bTerminalLink; 318 /*< Size of each bmaControls(x) field, in bytes:n */ 319 uint8_t bControlSize; 320 } usb_host_video_stream_output_header_desc_t; 321 322 /*! @brief video stream interface Motion-JPEG format descriptor structure */ 323 typedef struct _usb_host_video_stream_payload_mjpeg_format_desc 324 { 325 /*< Total size of the video stream MJPEG format descriptor */ 326 uint8_t bLength; 327 /*< Descriptor type of video stream MJPEG format descriptor */ 328 uint8_t bDescriptorType; 329 /*< Subtype of video stream MJPEG format descriptor */ 330 uint8_t bDescriptorSubtype; 331 /*< Index of this Format Descriptor */ 332 uint8_t bFormatIndex; 333 /*< Number of Frame Descriptors following that correspond to this format */ 334 uint8_t bNumFrameDescriptors; 335 /*< Specifies characteristics of this format */ 336 uint8_t bmFlags; 337 /*< Optimum Frame Index (used to select resolution) for this stream */ 338 uint8_t bDefaultFrameIndex; 339 /*< The X dimension of the picture aspect ratio */ 340 uint8_t bAspectRatioX; 341 /*< The Y dimension of the picture aspect ratio */ 342 uint8_t bAspectRatioY; 343 /*< Specifies interlace information */ 344 uint8_t bmInterlaceFlags; 345 /*< Specifies if duplication of the video stream should be restricted (0: No restrictions, 1: Restrict duplication) 346 */ 347 uint8_t bCopyProtect; 348 } usb_host_video_stream_payload_mjpeg_format_desc_t; 349 350 /*! @brief video stream interface uncompressed format descriptor structure */ 351 typedef struct _usb_host_video_stream_payload_uncompressed_format_desc 352 { 353 /*< Total size of the video stream uncompressed format descriptor */ 354 uint8_t bLength; 355 /*< Descriptor type of video stream uncompressed format descriptor */ 356 uint8_t bDescriptorType; 357 /*< Subtype of video stream uncompressed format descriptor */ 358 uint8_t bDescriptorSubtype; 359 /*< Index of this Format Descriptor */ 360 uint8_t bFormatIndex; 361 /*< Number of Frame Descriptors following that correspond to this format */ 362 uint8_t bNumFrameDescriptors; 363 /*< Globally Unique Identifier used to identify stream-encoding format */ 364 uint8_t guidFormat[16]; 365 /*< Number of bits per pixel used to specify color in the decoded video frame */ 366 uint8_t bBitsPerPixel; 367 /*< Optimum Frame Index (used to select resolution) for this stream */ 368 uint8_t bDefaultFrameIndex; 369 /*< The X dimension of the picture aspect ratio */ 370 uint8_t bAspectRatioX; 371 /*< The Y dimension of the picture aspect ratio */ 372 uint8_t bAspectRatioY; 373 /*< Specifies interlace information */ 374 uint8_t bmInterlaceFlags; 375 /*< Specifies if duplication of the video stream should be restricted (0:No restrictions,1:Restrict duplication)*/ 376 uint8_t bCopyProtect; 377 } usb_host_video_stream_payload_uncompressed_format_desc_t; 378 379 /*! @brief video stream interface Motion-JPEG frame descriptor structure */ 380 typedef struct _usb_host_video_stream_payload_mjpeg_frame_desc 381 { 382 /*< Total size of the video stream MJPEG frame descriptor */ 383 uint8_t bLength; 384 /*< Descriptor type of video stream MJPEG frame descriptor */ 385 uint8_t bDescriptorType; 386 /*< Subtype of video stream MJPEG frame descriptor */ 387 uint8_t bDescriptorSubtype; 388 /*< Index of this Frame Descriptor */ 389 uint8_t bFrameIndex; 390 /*< D0 specifies whether still images are supported at this frame setting. D1 specifies whether the device provides 391 * a fixed frame rate on a stream associated with this frame descriptor */ 392 uint8_t bmCapabilities; 393 /*< Width of decoded bitmap frame in pixels */ 394 uint8_t wWitd[2]; 395 /*< Height of decoded bitmap frame in pixels */ 396 uint8_t wHeight[2]; 397 /*< Specifies the minimum bit rate at default compression quality and longest frame interval in Units of bps at 398 * which the data can be transmitted */ 399 uint8_t dwMinBitRate[4]; 400 /*< Specifies the maximum bit rate at default compression quality and shortest frame interval in Units of bps at 401 * which the data can be transmitted */ 402 uint8_t dwMaxBitRate[4]; 403 /*< Specifies the maximum number of bytes for a video (or still image) frame the compressor will produce */ 404 uint8_t dwMaxVideoFrameBufferSize[4]; 405 /*< Specifies the frame interval the device would like to indicate for use as a default. This must be a valid frame 406 * interval */ 407 uint8_t dwDefaultFrameInterval[4]; 408 /*< Indicates how the frame interval can be programmed */ 409 uint8_t bFrameIntervalType; 410 /*< Shortest frame interval supported (at highest frame rate), in 100ns units */ 411 uint8_t dwMinFrameInterval[0]; 412 } usb_host_video_stream_payload_mjpeg_frame_desc_t; 413 414 /*! @brief video stream interface uncompressed frame descriptor structure */ 415 typedef struct _usb_host_video_stream_payload_uncompressed_frame_desc 416 { 417 /*< Total size of the video stream uncompressed frame descriptor */ 418 uint8_t bLength; 419 /*< Descriptor type of video stream uncompressed frame descriptor */ 420 uint8_t bDescriptorType; 421 /*< Subtype of video stream uncompressed frame descriptor */ 422 uint8_t bDescriptorSubtype; 423 /*< Index of this Frame Descriptor */ 424 uint8_t bFrameIndex; 425 /*< D0 specifies whether still images are supported at this frame setting. D1 specifies whether the device provides 426 * a fixed frame rate on a stream associated with this frame descriptor */ 427 uint8_t bmCapabilities; 428 /*< Width of decoded bitmap frame in pixels */ 429 uint8_t wWitd[2]; 430 /*< Height of decoded bitmap frame in pixels */ 431 uint8_t wHeight[2]; 432 /*< Specifies the minimum bit rate at default compression quality and longest frame interval in Units of bps at 433 * which the data can be transmitted */ 434 uint8_t dwMinBitRate[4]; 435 /*< Specifies the maximum bit rate at default compression quality and shortest frame interval in Units of bps at 436 * which the data can be transmitted */ 437 uint8_t dwMaxBitRate[4]; 438 /*< Specifies the maximum number of bytes for a video (or still image) frame the compressor will produce */ 439 uint8_t dwMaxVideoFrameBufferSize[4]; 440 /*< Specifies the frame interval the device would like to indicate for use as a default. This must be a valid frame 441 * interval */ 442 uint8_t dwDefaultFrameInterval[4]; 443 /*< Indicates how the frame interval can be programmed */ 444 uint8_t bFrameIntervalType; 445 /*< Shortest frame interval supported (at highest frame rate), in 100ns units */ 446 uint8_t dwMinFrameInterval[0]; 447 } usb_host_video_stream_payload_uncompressed_frame_desc_t; 448 449 /*! @brief video stream interface probe and commit controls descriptor structure */ 450 typedef struct _usb_host_video_probe_commit_controls 451 { 452 /*< Bitfield control indicating to the function what fields shall be kept fixed */ 453 uint16_t bmHint; 454 /*< Video format index from a Format descriptor for this video interface */ 455 uint8_t bFormatIndex; 456 /*< Video frame index from a Frame descriptor */ 457 uint8_t bFrameIndex; 458 /*< Frame interval in 100 ns units */ 459 uint8_t dwFrameInterval[4]; 460 /*< Key frame rate in key-frame per video-frame units */ 461 uint8_t wKeyFrameRate[2]; 462 /*< PFrame rate in PFrame/key frame units */ 463 uint8_t wPFrameRate[2]; 464 /*< Compression quality control in abstract units 1 (lowest) to 10000 (highest) */ 465 uint8_t wCompQuality[2]; 466 /*< Window size for average bit rate control */ 467 uint8_t wCompWindowSize[2]; 468 /*< Internal video streaming interface latency in ms from video data capture to presentation on the USB */ 469 uint8_t wDelay[2]; 470 /*< Maximum video frame or codec-specific segment size in bytes */ 471 uint8_t dwMaxVideoFrameSize[4]; 472 /*< Specifies the maximum number of bytes that the device can transmit or receive in a single payload transfer. This 473 * field must be supported */ 474 uint8_t dwMaxPayloadTransferSize[4]; 475 /*< The device clock frequency in Hz for the specified format */ 476 uint8_t dwClockFrequency[4]; 477 /*< Bitfield control */ 478 uint8_t bmFramingInfo; 479 /*< The preferred payload format version supported by the host or device for the specified bFormatIndex value */ 480 uint8_t bPreferedVersion; 481 /*< The minimum payload format version supported by the device for the specified bFormatIndex value */ 482 uint8_t bMinVersion; 483 /*< The maximum payload format version supported by the device for the specified bFormatIndex value */ 484 uint8_t bMaxVersion; 485 } usb_host_video_probe_commit_controls_t; 486 487 /*! @brief video stream interface paylaod header descriptor structure */ 488 typedef struct _usb_host_video_payload_header 489 { 490 /*< Length of the payload header in bytes including this field */ 491 uint8_t bHeaderLength; 492 /*< Provides information on the sample data following the header, as well as the availability of optional header 493 * fields in this header */ 494 union 495 { 496 uint8_t bmHeaderInfo; 497 struct 498 { 499 uint8_t frame_id : 1; 500 uint8_t end_of_frame : 1; 501 uint8_t presentation_time : 1; 502 uint8_t source_clock : 1; 503 uint8_t reserved : 1; 504 uint8_t still_image : 1; 505 uint8_t error : 1; 506 uint8_t end_of_header : 1; 507 } bitMap; 508 } HeaderInfo; 509 /*< Presentation Time Stamp (PTS) */ 510 uint8_t dwPresentationTime[4]; 511 /*< The device clock frequency in Hz */ 512 uint8_t dwClockFrequency[4]; 513 /*< A two-part Source Clock Reference (SCR) value */ 514 uint8_t scrSourceClock[2]; 515 } usb_host_video_payload_header_t; 516 517 /*! usb video class Common Descriptor */ 518 typedef struct _usb_host_video_common_desc 519 { 520 /*< Total size of the usb video common descriptor */ 521 uint8_t bLength; 522 /*< Descriptor type of usb video common descriptor */ 523 uint8_t bDescriptorType; 524 /*< Subtype of video usb video common descriptor */ 525 uint8_t bDescriptorSubtype; 526 } usb_host_video_common_desc_t; 527 528 /*! @brief video stream interface format descriptor structure common*/ 529 typedef struct _usb_host_video_stream_payload_format_common_desc 530 { 531 /*< Total size of the video stream format descriptor */ 532 uint8_t bLength; 533 /*< Descriptor type of the video stream format descriptor */ 534 uint8_t bDescriptorType; 535 /*< Subtype of the video stream format descriptor */ 536 uint8_t bDescriptorSubtype; 537 /*< Index of this format Descriptor */ 538 uint8_t bFormatIndex; 539 /*< Number of Frame Descriptors following that correspond to this format */ 540 uint8_t bNumFrameDescriptors; 541 } usb_host_video_stream_payload_format_common_desc_t; 542 543 /*! @brief video stream common frame descriptor structure*/ 544 typedef struct _usb_host_video_stream_payload_frame_common_desc 545 { 546 /*< Total size of the video stream frame descriptor */ 547 uint8_t bLength; 548 /*< Descriptor type of the video stream frame descriptor */ 549 uint8_t bDescriptorType; 550 /*< Subtype of the video stream frame descriptor */ 551 uint8_t bDescriptorSubtype; 552 /*< Index of this Frame Descriptor */ 553 uint8_t bFrameIndex; 554 /*< D0 specifies whether still images are supported at this frame setting. D1 specifies whether the device provides 555 * a fixed frame rate on a stream associated with this frame descriptor */ 556 uint8_t bmCapabilities; 557 /*< Width of decoded bitmap frame in pixels */ 558 uint8_t wWitd[2]; 559 /*< Height of decoded bitmap frame in pixels */ 560 uint8_t wHeight[2]; 561 } usb_host_video_stream_payload_frame_common_desc_t; 562 563 /*! @brief video descriptor uinon */ 564 typedef union _usb_host_video_descriptor_union 565 { 566 /*< common word */ 567 uint32_t word; 568 /*< common buffer pointer */ 569 uint8_t *bufr; 570 /*< usb common descriptor */ 571 usb_descriptor_common_t *common; 572 /*< usb video common descriptor */ 573 usb_host_video_common_desc_t *video_common; 574 /*< usb interface common descriptor */ 575 usb_descriptor_interface_t *interface; 576 /*< usb endpoint common descriptor */ 577 usb_descriptor_endpoint_t *endpoint; 578 /*< usb video mjpeg frame common descriptor */ 579 usb_host_video_stream_payload_frame_common_desc_t *video_frame_common; 580 } usb_host_video_descriptor_union_t; 581 582 /*! @brief Video instance structure, Video usb_host_class_handle pointer to this structure */ 583 typedef struct _usb_host_video_instance_struct 584 { 585 usb_host_handle hostHandle; /*!< The handle of the USB host*/ 586 usb_device_handle deviceHandle; /*!< The handle of the USB device structure */ 587 usb_host_interface_handle streamIntfHandle; /*!< This instance's video stream interface handle */ 588 usb_host_interface_handle controlIntfHandle; /*!< This instance's control stream interface handle */ 589 usb_host_pipe_handle controlPipe; /*!< Video class control pipe */ 590 usb_host_pipe_handle interruptPipe; /*!< Video class interrupt pipe */ 591 usb_host_pipe_handle streamIsoInPipe; /*!< Video class stream iso in pipe */ 592 usb_host_video_ctrl_header_desc_t *vcHeaderDesc; /*!< Video class control header descriptor pointer */ 593 usb_host_video_ctrl_it_desc_t *vcInputTerminalDesc; /*!< Video class control input terminal descriptor pointer */ 594 usb_host_video_ctrl_ot_desc_t *vcOutputTerminalDesc; /*!< Video class control output terminal descriptor pointer */ 595 usb_host_video_ctrl_pu_desc_t *vcProcessingUnitDesc; /*!< Video class control processing unit descriptor pointer */ 596 usb_host_video_stream_input_header_desc_t 597 *vsInputHeaderDesc; /*!< Video class stream input header descriptor pointer */ 598 transfer_callback_t controlCallbackFn; /*!< Video control transfer callback function */ 599 void *controlCallbackParam; /*!< Video control transfer callback parameter */ 600 usb_host_transfer_t *controlTransfer; /*!< On-going control transfer */ 601 transfer_callback_t streamIsoInCallbackFn; /*!< Video stream ISO in transfer callback function */ 602 void *streamIsoInCallbackParam; /*!< Video stream ISO in transfer callback parameter */ 603 uint16_t interruptInPacketSize; /*!< Video Interrupt in maximum packet size */ 604 uint16_t isoInPacketSize; /*!< Video ISO in maximum packet size */ 605 uint8_t interruptInEpNum; /*!< Video control interrupt in endpoint number */ 606 uint8_t isoInEpNum; /*!< Video stream ISO in endpoint number */ 607 608 } usb_host_video_instance_struct_t; 609 610 /******************************************************************************* 611 * API 612 ******************************************************************************/ 613 614 #ifdef __cplusplus 615 extern "C" { 616 #endif 617 618 /*! 619 * @brief set video class stream interface. 620 * 621 * This function bind the interface with the video instance. 622 * 623 * @param classHandle The class handle. 624 * @param interfaceHandle The interface handle. 625 * @param alternateSetting The alternate setting value. 626 * @param callbackFn This callback is called after this function completes. 627 * @param callbackParam The first parameter in the callback function. 628 * 629 * @retval kStatus_USB_Success The device is initialized successfully. 630 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 631 * @retval kStatus_USB_Busy There is no idle transfer. 632 * @retval kStatus_USB_Error send transfer fail, please reference to USB_HostSendSetup. 633 * @retval kStatus_USB_Busy callback return status, there is no idle pipe. 634 * @retval kStatus_USB_TransferStall callback return status, the transfer is stall by device. 635 * @retval kStatus_USB_Error callback return status, open pipe fail, please reference to USB_HostOpenPipe. 636 */ 637 usb_status_t USB_HostVideoStreamSetInterface(usb_host_class_handle classHandle, 638 usb_host_interface_handle interfaceHandle, 639 uint8_t alternateSetting, 640 transfer_callback_t callbackFn, 641 void *callbackParam); 642 643 /*! 644 * @brief set control interface. 645 * 646 * This function bind the control interface with the video instance. 647 * 648 * @param classHandle the class handle. 649 * @param interfaceHandle the control interface handle. 650 * @param alternateSetting the alternate setting value. 651 * @param callbackFn this callback is called after this function completes. 652 * @param callbackParam the first parameter in the callback function. 653 * 654 * @retval kStatus_USB_Success The device is initialized successfully. 655 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 656 * @retval kStatus_USB_Busy There is no idle transfer. 657 * @retval kStatus_USB_Error send transfer fail, please reference to USB_HostSendSetup. 658 * @retval kStatus_USB_Busy callback return status, there is no idle pipe. 659 * @retval kStatus_USB_TransferStall callback return status, the transfer is stall by device. 660 * @retval kStatus_USB_Error callback return status, open pipe fail, please reference to USB_HostOpenPipe. 661 */ 662 usb_status_t USB_HostVideoControlSetInterface(usb_host_class_handle classHandle, 663 usb_host_interface_handle interfaceHandle, 664 uint8_t alternateSetting, 665 transfer_callback_t callbackFn, 666 void *callbackParam); 667 668 /*! 669 * @brief video stream receive data. 670 * 671 * This function implements video receiving data. 672 * 673 * @param classHandle The class handle. 674 * @param buffer The buffer pointer. 675 * @param bufferLen The buffer length. 676 * @param callbackFn This callback is called after this function completes. 677 * @param callbackParam The first parameter in the callback function. 678 * 679 * @retval kStatus_USB_Success Receive request successfully. 680 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 681 * @retval kStatus_USB_Busy There is no idle transfer. 682 * @retval kStatus_USB_Error pipe is not initialized. 683 * Or, send transfer fail, please reference to USB_HostRecv. 684 */ 685 usb_status_t USB_HosVideoStreamRecv(usb_host_class_handle classHandle, 686 uint8_t *buffer, 687 uint32_t bufferLen, 688 transfer_callback_t callbackFn, 689 void *callbackParam); 690 691 /*! 692 * @brief initialize the video instance. 693 * 694 * This function allocate the resource for video instance. 695 * 696 * @param deviceHandle the device handle. 697 * @param classHandle return class handle. 698 * 699 * @retval kStatus_USB_Success The device is initialized successfully. 700 * @retval kStatus_USB_AllocFail Allocate memory fail. 701 */ 702 usb_status_t USB_HostVideoInit(usb_device_handle deviceHandle, usb_host_class_handle *classHandle); 703 704 /*! 705 * @brief de-initialize the video instance. 706 * 707 * This function release the resource for video instance. 708 * 709 * @param deviceHandle the device handle. 710 * @param classHandle the class handle. 711 * 712 * @retval kStatus_USB_Success The device is de-initialized successfully. 713 */ 714 usb_status_t USB_HostVideoDeinit(usb_device_handle deviceHandle, usb_host_class_handle classHandle); 715 716 /*! 717 * @brief get video stream format descriptor. 718 * 719 * This function implements get video stream format descriptor. 720 * 721 * @param classHandle The class handle. 722 * @param subType The descriptor subtype. 723 * @param descriptor The pointer of specific format descriptor. 724 * 725 * @retval kStatus_USB_Success Get video stream format descriptor request successfully. 726 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 727 * @retval kStatus_USB_InvalidParameter The descriptor is NULL pointer. 728 * 729 */ 730 usb_status_t USB_HostVideoStreamGetFormatDescriptor(usb_host_class_handle classHandle, 731 uint8_t subType, 732 void **descriptor); 733 734 /*! 735 * @brief get specific video stream frame descriptor. 736 * 737 * This function implements get specific video stream frame descriptor. 738 * 739 * @param classHandle The class handle. 740 * @param formatDescriptor The frame descriptor pointer. 741 * @param index The specific frame descriptor id 742 * @param descriptor The pointer of specific frame descriptor. 743 * 744 * @retval kStatus_USB_Success Get video stream frame descriptor request successfully. 745 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 746 * @retval kStatus_USB_InvalidParameter The descriptor is NULL pointer. 747 * 748 */ 749 usb_status_t USB_HostVideoStreamGetFrameDescriptor( 750 usb_host_class_handle classHandle, void *formatDescriptor, uint8_t subType, uint8_t frameIndex, void **descriptor); 751 752 /*! 753 * @brief video set probe. 754 * 755 * This function implements the Video class-specific request (set probe). 756 * 757 * @param classHandle the class handle. 758 * @param request setup packet request value. 759 * @param probe video probe data 760 * @param callbackFn this callback is called after this function completes. 761 * @param callbackParam the first parameter in the callback function. 762 * 763 * @retval kStatus_USB_Success Request successful. 764 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 765 * @retval kStatus_USB_InvalidParameter The interface descriptor is NULL pointer. 766 */ 767 usb_status_t USB_HostVideoSetProbe(usb_host_class_handle classHandle, 768 uint8_t request, 769 uint8_t *probe, 770 transfer_callback_t callbackFn, 771 void *callbackParam); 772 773 /*! 774 * @brief video get probe. 775 * 776 * This function implements the Video class-specific request (get probe). 777 * 778 * @param classHandle the class handle. 779 * @param request setup packet request value. 780 * @param probe video probe data 781 * @param callbackFn this callback is called after this function completes. 782 * @param callbackParam the first parameter in the callback function. 783 * 784 * @retval kStatus_USB_Success Request successful. 785 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 786 * @retval kStatus_USB_InvalidParameter The interface descriptor is NULL pointer. 787 */ 788 usb_status_t USB_HostVideoGetProbe(usb_host_class_handle classHandle, 789 uint8_t request, 790 uint8_t *probe, 791 transfer_callback_t callbackFn, 792 void *callbackParam); 793 794 /*! 795 * @brief video get commit. 796 * 797 * This function implements the Video class-specific request (get commit). 798 * 799 * @param classHandle the class handle. 800 * @param request setup packet request value. 801 * @param probe video probe data 802 * @param callbackFn this callback is called after this function completes. 803 * @param callbackParam the first parameter in the callback function. 804 * 805 * @retval kStatus_USB_Success Request successful. 806 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 807 * @retval kStatus_USB_InvalidParameter The interface descriptor is NULL pointer. 808 * @retval kStatus_USB_InvalidRequest The request is invaild. 809 */ 810 usb_status_t USB_HostVideoGetCommit(usb_host_class_handle classHandle, 811 uint8_t brequest, 812 uint8_t *probe, 813 transfer_callback_t callbackFn, 814 void *callbackParam); 815 816 /*! 817 * @brief video set commit. 818 * 819 * This function implements the Video class-specific request (set commit). 820 * 821 * @param classHandle the class handle. 822 * @param request setup packet request value. 823 * @param probe video probe data 824 * @param callbackFn this callback is called after this function completes. 825 * @param callbackParam the first parameter in the callback function. 826 * 827 * @retval kStatus_USB_Success Request successful. 828 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 829 * @retval kStatus_USB_InvalidParameter The interface descriptor is NULL pointer. 830 */ 831 usb_status_t USB_HostVideoSetCommit(usb_host_class_handle classHandle, 832 uint8_t brequest, 833 uint8_t *probe, 834 transfer_callback_t callbackFn, 835 void *callbackParam); 836 /*! @}*/ 837 838 #ifdef __cplusplus 839 } 840 #endif 841 /*! @}*/ 842 843 #endif /* __USB_HOST_VIDEO_H__ */ 844
