Documentation/video4linux/cx2341x/fw-encoder-api.txt

   1 Encoder firmware API description
   2 ================================
   3
   4 -------------------------------------------------------------------------------
   5
   6 Name    CX2341X_ENC_PING_FW
   7 Enum    128/0x80
   8 Description
   9         Does nothing. Can be used to check if the firmware is responding.
  10
  11 -------------------------------------------------------------------------------
  12
  13 Name    CX2341X_ENC_START_CAPTURE
  14 Enum    129/0x81
  15 Description
  16         Commences the capture of video, audio and/or VBI data. All encoding
  17         parameters must be initialized prior to this API call. Captures frames
  18         continuously or until a predefined number of frames have been captured.
  19 Param[0]
  20         Capture stream type:
  21             0=MPEG
  22             1=Raw
  23             2=Raw passthrough
  24             3=VBI
  25
  26 Param[1]
  27         Bitmask:
  28             Bit 0 when set, captures YUV
  29             Bit 1 when set, captures PCM audio
  30             Bit 2 when set, captures VBI (same as param[0]=3)
  31             Bit 3 when set, the capture destination is the decoder
  32                 (same as param[0]=2)
  33             Bit 4 when set, the capture destination is the host
  34         Note: this parameter is only meaningful for RAW capture type.
  35
  36 -------------------------------------------------------------------------------
  37
  38 Name    CX2341X_ENC_STOP_CAPTURE
  39 Enum    130/0x82
  40 Description
  41         Ends a capture in progress
  42 Param[0]
  43         0=stop at end of GOP (generates IRQ)
  44         1=stop immediate (no IRQ)
  45 Param[1]
  46         Stream type to stop, see param[0] of API 0x81
  47 Param[2]
  48         Subtype, see param[1] of API 0x81
  49
  50 -------------------------------------------------------------------------------
  51
  52 Name    CX2341X_ENC_SET_AUDIO_ID
  53 Enum    137/0x89
  54 Description
  55         Assigns the transport stream ID of the encoded audio stream
  56 Param[0]
  57         Audio Stream ID
  58
  59 -------------------------------------------------------------------------------
  60
  61 Name    CX2341X_ENC_SET_VIDEO_ID
  62 Enum    139/0x8B
  63 Description
  64         Set video transport stream ID
  65 Param[0]
  66         Video stream ID
  67
  68 -------------------------------------------------------------------------------
  69
  70 Name    CX2341X_ENC_SET_PCR_ID
  71 Enum    141/0x8D
  72 Description
  73         Assigns the transport stream ID for PCR packets
  74 Param[0]
  75         PCR Stream ID
  76
  77 -------------------------------------------------------------------------------
  78
  79 Name    CX2341X_ENC_SET_FRAME_RATE
  80 Enum    143/0x8F
  81 Description
  82         Set video frames per second. Change occurs at start of new GOP.
  83 Param[0]
  84         0=30fps
  85         1=25fps
  86
  87 -------------------------------------------------------------------------------
  88
  89 Name    CX2341X_ENC_SET_FRAME_SIZE
  90 Enum    145/0x91
  91 Description
  92         Select video stream encoding resolution.
  93 Param[0]
  94         Height in lines. Default 480
  95 Param[1]
  96         Width in pixels. Default 720
  97
  98 -------------------------------------------------------------------------------
  99
 100 Name    CX2341X_ENC_SET_BIT_RATE
 101 Enum    149/0x95
 102 Description
 103         Assign average video stream bitrate.
 104 Param[0]
 105         0=variable bitrate, 1=constant bitrate
 106 Param[1]
 107         bitrate in bits per second
 108 Param[2]
 109         peak bitrate in bits per second, divided by 400
 110
 111 -------------------------------------------------------------------------------
 112
 113 Name    CX2341X_ENC_SET_GOP_PROPERTIES
 114 Enum    151/0x97
 115 Description
 116         Setup the GOP structure
 117 Param[0]
 118         GOP size
 119 Param[1]
 120         Number of B frames between the I and P frame, plus 1.
 121         For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3
 122
 123 -------------------------------------------------------------------------------
 124
 125 Name    CX2341X_ENC_SET_ASPECT_RATIO
 126 Enum    153/0x99
 127 Description
 128         Sets the encoding aspect ratio. Changes in the aspect ratio take effect
 129         at the start of the next GOP.
 130 Param[0]
 131         '0000' forbidden
 132         '0001' 1:1 square
 133         '0010' 4:3
 134         '0011' 16:9
 135         '0100' 2.21:1
 136         '0101' reserved
 137          ....
 138         '1111' reserved
 139
 140 -------------------------------------------------------------------------------
 141
 142 Name    CX2341X_ENC_SET_DNR_FILTER_MODE
 143 Enum    155/0x9B
 144 Description
 145         Assign Dynamic Noise Reduction operating mode
 146 Param[0]
 147         Bit0: Spatial filter, set=auto, clear=manual
 148         Bit1: Temporal filter, set=auto, clear=manual
 149 Param[1]
 150         Median filter:
 151             0=Disabled
 152             1=Horizontal
 153             2=Vertical
 154             3=Horiz/Vert
 155             4=Diagonal
 156
 157 -------------------------------------------------------------------------------
 158
 159 Name    CX2341X_ENC_SET_DNR_FILTER_PROPS
 160 Enum    157/0x9D
 161 Description
 162         These Dynamic Noise Reduction filter values are only meaningful when
 163         the respective filter is set to "manual" (See API 0x9B)
 164 Param[0]
 165         Spatial filter: default 0, range 0:15
 166 Param[1]
 167         Temporal filter: default 0, range 0:31
 168
 169 -------------------------------------------------------------------------------
 170
 171 Name    CX2341X_ENC_SET_CORING_LEVELS
 172 Enum    159/0x9F
 173 Description
 174         Assign Dynamic Noise Reduction median filter properties.
 175 Param[0]
 176         Threshold above which the luminance median filter is enabled.
 177         Default: 0, range 0:255
 178 Param[1]
 179         Threshold below which the luminance median filter is enabled.
 180         Default: 255, range 0:255
 181 Param[2]
 182         Threshold above which the chrominance median filter is enabled.
 183         Default: 0, range 0:255
 184 Param[3]
 185         Threshold below which the chrominance median filter is enabled.
 186         Default: 255, range 0:255
 187
 188 -------------------------------------------------------------------------------
 189
 190 Name    CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
 191 Enum    161/0xA1
 192 Description
 193         Assign spatial prefilter parameters
 194 Param[0]
 195         Luminance filter
 196             0=Off
 197             1=1D Horizontal
 198             2=1D Vertical
 199             3=2D H/V Separable (default)
 200             4=2D Symmetric non-separable
 201 Param[1]
 202         Chrominance filter
 203             0=Off
 204             1=1D Horizontal (default)
 205
 206 -------------------------------------------------------------------------------
 207
 208 Name    CX2341X_ENC_SET_3_2_PULLDOWN
 209 Enum    177/0xB1
 210 Description
 211         3:2 pulldown properties
 212 Param[0]
 213         0=enabled
 214         1=disabled
 215
 216 -------------------------------------------------------------------------------
 217
 218 Name    CX2341X_ENC_SET_VBI_LINE
 219 Enum    183/0xB7
 220 Description
 221         Selects VBI line number.
 222 Param[0]
 223         Bits 0:4        line number
 224         Bit  31         0=top_field, 1=bottom_field
 225         Bits 0:31       all set specifies "all lines"
 226 Param[1]
 227         VBI line information features: 0=disabled, 1=enabled
 228 Param[2]
 229         Slicing: 0=None, 1=Closed Caption
 230         Almost certainly not implemented. Set to 0.
 231 Param[3]
 232         Luminance samples in this line.
 233         Almost certainly not implemented. Set to 0.
 234 Param[4]
 235         Chrominance samples in this line
 236         Almost certainly not implemented. Set to 0.
 237
 238 -------------------------------------------------------------------------------
 239
 240 Name    CX2341X_ENC_SET_STREAM_TYPE
 241 Enum    185/0xB9
 242 Description
 243         Assign stream type
 244 Param[0]
 245          0=Program stream
 246          1=Transport stream
 247          2=MPEG1 stream
 248          3=PES A/V stream
 249          5=PES Video stream
 250          7=PES Audio stream
 251         10=DVD stream
 252         11=VCD stream
 253         12=SVCD stream
 254         13=DVD_S1 stream
 255         14=DVD_S2 stream
 256
 257 -------------------------------------------------------------------------------
 258
 259 Name    CX2341X_ENC_SET_OUTPUT_PORT
 260 Enum    187/0xBB
 261 Description
 262         Assign stream output port (not recommended you change setting from default)
 263 Param[0]
 264         0=Memory (default)
 265         1=Streaming
 266         2=Serial
 267
 268 -------------------------------------------------------------------------------
 269
 270 Name    CX2341X_ENC_SET_AUDIO_PROPERTIES
 271 Enum    189/0xBD
 272 Description
 273         Set audio stream properties, may be called while encoding is in progress.
 274         Note: all bitfields are consistent with ISO11172 documentation except
 275         bits 2:3 which ISO docs define as:
 276                 '11' Layer I
 277                 '10' Layer II
 278                 '01' Layer III
 279                 '00' Undefined
 280         This discrepancy may indicate a possible error in the documentation.
 281 Param[0]
 282         Bitmask:
 283            0:1  '00' 44.1Khz
 284                 '01' 48Khz
 285                 '10' 32Khz
 286                 '11' reserved
 287
 288            2:3  '01'=Layer I
 289                 '10'=Layer II
 290
 291            4:7  Bitrate:
 292                      Index | Layer I     | Layer II
 293                      ------+-------------+------------
 294                     '0000' | free format | free format
 295                     '0001' |  32 kbit/s  |  32 kbit/s
 296                     '0010' |  64 kbit/s  |  48 kbit/s
 297                     '0011' |  96 kbit/s  |  56 kbit/s
 298                     '0100' | 128 kbit/s  |  64 kbit/s
 299                     '0101' | 160 kbit/s  |  80 kbit/s
 300                     '0110' | 192 kbit/s  |  96 kbit/s
 301                     '0111' | 224 kbit/s  | 112 kbit/s
 302                     '1000' | 256 kbit/s  | 128 kbit/s
 303                     '1001' | 288 kbit/s  | 160 kbit/s
 304                     '1010' | 320 kbit/s  | 192 kbit/s
 305                     '1011' | 352 kbit/s  | 224 kbit/s
 306                     '1100' | 384 kbit/s  | 256 kbit/s
 307                     '1101' | 416 kbit/s  | 320 kbit/s
 308                     '1110' | 448 kbit/s  | 384 kbit/s
 309                 Note: For Layer II, not all combinations of total bitrate
 310                 and mode are allowed. See ISO11172-3 3-Annex B, Table 3-B.2
 311
 312            8:9  '00'=Stereo
 313                 '01'=JointStereo
 314                 '10'=Dual
 315                 '11'=Mono
 316
 317           10:11 Mode Extension used in joint_stereo mode.
 318                 In Layer I and II they indicate which subbands are in
 319                 intensity_stereo. All other subbands are coded in stereo.
 320                     '00' subbands 4-31 in intensity_stereo, bound==4
 321                     '01' subbands 8-31 in intensity_stereo, bound==8
 322                     '10' subbands 12-31 in intensity_stereo, bound==12
 323                     '11' subbands 16-31 in intensity_stereo, bound==16
 324
 325           12:13 Emphasis:
 326                     '00' None
 327                     '01' 50/15uS
 328                     '10' reserved
 329                     '11' CCITT J.17
 330
 331           14    CRC:
 332                     '0' off
 333                     '1' on
 334
 335           15    Copyright:
 336                     '0' off
 337                     '1' on
 338
 339           16    Generation:
 340                     '0' copy
 341                     '1' original
 342
 343 -------------------------------------------------------------------------------
 344
 345 Name    CX2341X_ENC_HALT_FW
 346 Enum    195/0xC3
 347 Description
 348         The firmware is halted and no further API calls are serviced until the
 349         firmware is uploaded again.
 350
 351 -------------------------------------------------------------------------------
 352
 353 Name    CX2341X_ENC_GET_VERSION
 354 Enum    196/0xC4
 355 Description
 356         Returns the version of the encoder firmware.
 357 Result[0]
 358         Version bitmask:
 359             Bits  0:15 build
 360             Bits 16:23 minor
 361             Bits 24:31 major
 362
 363 -------------------------------------------------------------------------------
 364
 365 Name    CX2341X_ENC_SET_GOP_CLOSURE
 366 Enum    197/0xC5
 367 Description
 368         Assigns the GOP open/close property.
 369 Param[0]
 370         0=Open
 371         1=Closed
 372
 373 -------------------------------------------------------------------------------
 374
 375 Name    CX2341X_ENC_GET_SEQ_END
 376 Enum    198/0xC6
 377 Description
 378         Obtains the sequence end code of the encoder's buffer. When a capture
 379         is started a number of interrupts are still generated, the last of
 380         which will have Result[0] set to 1 and Result[1] will contain the size
 381         of the buffer.
 382 Result[0]
 383         State of the transfer (1 if last buffer)
 384 Result[1]
 385         If Result[0] is 1, this contains the size of the last buffer, undefined
 386         otherwise.
 387
 388 -------------------------------------------------------------------------------
 389
 390 Name    CX2341X_ENC_SET_PGM_INDEX_INFO
 391 Enum    199/0xC7
 392 Description
 393         Sets the Program Index Information.
 394 Param[0]
 395         Picture Mask:
 396             0=No index capture
 397             1=I frames
 398             3=I,P frames
 399             7=I,P,B frames
 400 Param[1]
 401         Elements requested (up to 400)
 402 Result[0]
 403         Offset in SDF memory of the table.
 404 Result[1]
 405         Number of allocated elements up to a maximum of Param[1]
 406
 407 -------------------------------------------------------------------------------
 408
 409 Name    CX2341X_ENC_SET_VBI_CONFIG
 410 Enum    200/0xC8
 411 Description
 412         Configure VBI settings
 413 Param[0]
 414         Bitmap:
 415             0    Mode '0' Sliced, '1' Raw
 416             1:3  Insertion:
 417                      '000' insert in extension & user data
 418                      '001' insert in private packets
 419                      '010' separate stream and user data
 420                      '111' separate stream and private data
 421             8:15 Stream ID (normally 0xBD)
 422 Param[1]
 423         Frames per interrupt (max 8). Only valid in raw mode.
 424 Param[2]
 425         Total raw VBI frames. Only valid in raw mode.
 426 Param[3]
 427         Start codes
 428 Param[4]
 429         Stop codes
 430 Param[5]
 431         Lines per frame
 432 Param[6]
 433         Byte per line
 434 Result[0]
 435         Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
 436 Result[1]
 437         Observed number of frames in raw mode. Range 1 to Param[2]
 438 Result[2]
 439         Memory offset to start or raw VBI data
 440
 441 -------------------------------------------------------------------------------
 442
 443 Name    CX2341X_ENC_SET_DMA_BLOCK_SIZE
 444 Enum    201/0xC9
 445 Description
 446         Set DMA transfer block size
 447 Param[0]
 448         DMA transfer block size in bytes or frames. When unit is bytes,
 449         supported block sizes are 2^7, 2^8 and 2^9 bytes.
 450 Param[1]
 451         Unit: 0=bytes, 1=frames
 452
 453 -------------------------------------------------------------------------------
 454
 455 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
 456 Enum    202/0xCA
 457 Description
 458         Returns information on the previous DMA transfer in conjunction with
 459         bit 27 of the interrupt mask. Uses mailbox 10.
 460 Result[0]
 461         Type of stream
 462 Result[1]
 463         Address Offset
 464 Result[2]
 465         Maximum size of transfer
 466
 467 -------------------------------------------------------------------------------
 468
 469 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
 470 Enum    203/0xCB
 471 Description
 472         Returns information on the previous DMA transfer in conjunction with
 473         bit 27 of the interrupt mask. Uses mailbox 9.
 474 Result[0]
 475         Status bits:
 476             Bit 0 set indicates transfer complete
 477             Bit 2 set indicates transfer error
 478             Bit 4 set indicates linked list error
 479 Result[1]
 480         DMA type
 481 Result[2]
 482         Presentation Time Stamp bits 0..31
 483 Result[3]
 484         Presentation Time Stamp bit 32
 485
 486 -------------------------------------------------------------------------------
 487
 488 Name    CX2341X_ENC_SCHED_DMA_TO_HOST
 489 Enum    204/0xCC
 490 Description
 491         Setup DMA to host operation
 492 Param[0]
 493         Memory address of link list
 494 Param[1]
 495         Length of link list (wtf: what units ???)
 496 Param[2]
 497         DMA type (0=MPEG)
 498
 499 -------------------------------------------------------------------------------
 500
 501 Name    CX2341X_ENC_INITIALIZE_INPUT
 502 Enum    205/0xCD
 503 Description
 504         Initializes the video input
 505
 506 -------------------------------------------------------------------------------
 507
 508 Name    CX2341X_ENC_SET_FRAME_DROP_RATE
 509 Enum    208/0xD0
 510 Description
 511         For each frame captured, skip specified number of frames.
 512 Param[0]
 513         Number of frames to skip
 514
 515 -------------------------------------------------------------------------------
 516
 517 Name    CX2341X_ENC_PAUSE_ENCODER
 518 Enum    210/0xD2
 519 Description
 520         During a pause condition, all frames are dropped instead of being encoded.
 521 Param[0]
 522         0=Pause encoding
 523         1=Continue encoding
 524
 525 -------------------------------------------------------------------------------
 526
 527 Name    CX2341X_ENC_REFRESH_INPUT
 528 Enum    211/0xD3
 529 Description
 530         Refreshes the video input
 531
 532 -------------------------------------------------------------------------------
 533
 534 Name    CX2341X_ENC_SET_COPYRIGHT
 535 Enum    212/0xD4
 536 Description
 537         Sets stream copyright property
 538 Param[0]
 539         0=Stream is not copyrighted
 540         1=Stream is copyrighted
 541
 542 -------------------------------------------------------------------------------
 543
 544 Name    CX2341X_ENC_SET_EVENT_NOTIFICATION
 545 Enum    213/0xD5
 546 Description
 547         Setup firmware to notify the host about a particular event. Host must
 548         unmask the interrupt bit.
 549 Param[0]
 550         Event (0=refresh encoder input)
 551 Param[1]
 552         Notification 0=disabled 1=enabled
 553 Param[2]
 554         Interrupt bit
 555 Param[3]
 556         Mailbox slot, -1 if no mailbox required.
 557
 558 -------------------------------------------------------------------------------
 559
 560 Name    CX2341X_ENC_SET_NUM_VSYNC_LINES
 561 Enum    214/0xD6
 562 Description
 563         Depending on the analog video decoder used, this assigns the number
 564         of lines for field 1 and 2.
 565 Param[0]
 566         Field 1 number of lines:
 567             0x00EF for SAA7114
 568             0x00F0 for SAA7115
 569             0x0105 for Micronas
 570 Param[1]
 571         Field 2 number of lines:
 572             0x00EF for SAA7114
 573             0x00F0 for SAA7115
 574             0x0106 for Micronas
 575
 576 -------------------------------------------------------------------------------
 577
 578 Name    CX2341X_ENC_SET_PLACEHOLDER
 579 Enum    215/0xD7
 580 Description
 581         Provides a mechanism of inserting custom user data in the MPEG stream.
 582 Param[0]
 583         0=extension & user data
 584         1=private packet with stream ID 0xBD
 585 Param[1]
 586         Rate at which to insert data, in units of frames (for private packet)
 587         or GOPs (for ext. & user data)
 588 Param[2]
 589         Number of data DWORDs (below) to insert
 590 Param[3]
 591         Custom data 0
 592 Param[4]
 593         Custom data 1
 594 Param[5]
 595         Custom data 2
 596 Param[6]
 597         Custom data 3
 598 Param[7]
 599         Custom data 4
 600 Param[8]
 601         Custom data 5
 602 Param[9]
 603         Custom data 6
 604 Param[10]
 605         Custom data 7
 606 Param[11]
 607         Custom data 8
 608
 609 -------------------------------------------------------------------------------
 610
 611 Name    CX2341X_ENC_MUTE_VIDEO
 612 Enum    217/0xD9
 613 Description
 614         Video muting
 615 Param[0]
 616         Bit usage:
 617          0      '0'=video not muted
 618                 '1'=video muted, creates frames with the YUV color defined below
 619          1:7    Unused
 620          8:15   V chrominance information
 621         16:23   U chrominance information
 622         24:31   Y luminance information
 623
 624 -------------------------------------------------------------------------------
 625
 626 Name    CX2341X_ENC_MUTE_AUDIO
 627 Enum    218/0xDA
 628 Description
 629         Audio muting
 630 Param[0]
 631         0=audio not muted
 632         1=audio muted (produces silent mpeg audio stream)
 633
 634 -------------------------------------------------------------------------------
 635
 636 Name    CX2341X_ENC_UNKNOWN
 637 Enum    219/0xDB
 638 Description
 639         Unknown API, it's used by Hauppauge though.
 640 Param[0]
 641         0 This is the value Hauppauge uses, Unknown what it means.
 642
 643 -------------------------------------------------------------------------------
 644
 645 Name    CX2341X_ENC_MISC
 646 Enum    220/0xDC
 647 Description
 648         Miscellaneous actions. Not known for 100% what it does. It's really a
 649         sort of ioctl call. The first parameter is a command number, the second
 650         the value.
 651 Param[0]
 652         Command number:
 653          1=set initial SCR value when starting encoding.
 654          2=set quality mode (apparently some test setting).
 655          3=setup advanced VIM protection handling (supposedly only for the cx23416
 656            for raw YUV).
 657            Actually it looks like this should be 0 for saa7114/5 based card and 1
 658            for cx25840 based cards.
 659          4=generate artificial PTS timestamps
 660          5=USB flush mode
 661          6=something to do with the quantization matrix
 662          7=set navigation pack insertion for DVD
 663          8=enable scene change detection (seems to be a failure)
 664          9=set history parameters of the video input module
 665         10=set input field order of VIM
 666         11=set quantization matrix
 667         12=reset audio interface
 668         13=set audio volume delay
 669         14=set audio delay
 670
 671 Param[1]
 672         Command value.