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