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-2 are the type mask:
 411                                         // 1=I, 2=P, 4=B
 412                                         // 0=End of Program Index, other fields
 413                                         //   are invalid.
 414                 u32 pts;                // The PTS of the frame
 415                 u32 mask2;              // Bit 0 is bit 32 of the pts.
 416         };
 417         u32 table_ptr;
 418         struct info index[400];
 419
 420         The table_ptr is the encoder memory address in the table were
 421         *new* entries will be written. Note that this is a ringbuffer,
 422         so the table_ptr will wraparound.
 423 Param[0]
 424         Picture Mask:
 425             0=No index capture
 426             1=I frames
 427             3=I,P frames
 428             7=I,P,B frames
 429         (Seems to be ignored, it always indexes I, P and B frames)
 430 Param[1]
 431         Elements requested (up to 400)
 432 Result[0]
 433         Offset in the encoder memory of the start of the table.
 434 Result[1]
 435         Number of allocated elements up to a maximum of Param[1]
 436
 437 -------------------------------------------------------------------------------
 438
 439 Name    CX2341X_ENC_SET_VBI_CONFIG
 440 Enum    200/0xC8
 441 Description
 442         Configure VBI settings
 443 Param[0]
 444         Bitmap:
 445             0    Mode '0' Sliced, '1' Raw
 446             1:3  Insertion:
 447                      '000' insert in extension & user data
 448                      '001' insert in private packets
 449                      '010' separate stream and user data
 450                      '111' separate stream and private data
 451             8:15 Stream ID (normally 0xBD)
 452 Param[1]
 453         Frames per interrupt (max 8). Only valid in raw mode.
 454 Param[2]
 455         Total raw VBI frames. Only valid in raw mode.
 456 Param[3]
 457         Start codes
 458 Param[4]
 459         Stop codes
 460 Param[5]
 461         Lines per frame
 462 Param[6]
 463         Byte per line
 464 Result[0]
 465         Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
 466 Result[1]
 467         Observed number of frames in raw mode. Range 1 to Param[2]
 468 Result[2]
 469         Memory offset to start or raw VBI data
 470
 471 -------------------------------------------------------------------------------
 472
 473 Name    CX2341X_ENC_SET_DMA_BLOCK_SIZE
 474 Enum    201/0xC9
 475 Description
 476         Set DMA transfer block size
 477 Param[0]
 478         DMA transfer block size in bytes or frames. When unit is bytes,
 479         supported block sizes are 2^7, 2^8 and 2^9 bytes.
 480 Param[1]
 481         Unit: 0=bytes, 1=frames
 482
 483 -------------------------------------------------------------------------------
 484
 485 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
 486 Enum    202/0xCA
 487 Description
 488         Returns information on the previous DMA transfer in conjunction with
 489         bit 27 of the interrupt mask. Uses mailbox 10.
 490 Result[0]
 491         Type of stream
 492 Result[1]
 493         Address Offset
 494 Result[2]
 495         Maximum size of transfer
 496
 497 -------------------------------------------------------------------------------
 498
 499 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
 500 Enum    203/0xCB
 501 Description
 502         Returns information on the previous DMA transfer in conjunction with
 503         bit 27 or 18 of the interrupt mask. Uses mailbox 9.
 504 Result[0]
 505         Status bits:
 506                 0   read completed
 507                 1   write completed
 508                 2   DMA read error
 509                 3   DMA write error
 510                 4   Scatter-Gather array error
 511 Result[1]
 512         DMA type
 513 Result[2]
 514         Presentation Time Stamp bits 0..31
 515 Result[3]
 516         Presentation Time Stamp bit 32
 517
 518 -------------------------------------------------------------------------------
 519
 520 Name    CX2341X_ENC_SCHED_DMA_TO_HOST
 521 Enum    204/0xCC
 522 Description
 523         Setup DMA to host operation
 524 Param[0]
 525         Memory address of link list
 526 Param[1]
 527         Length of link list (wtf: what units ???)
 528 Param[2]
 529         DMA type (0=MPEG)
 530
 531 -------------------------------------------------------------------------------
 532
 533 Name    CX2341X_ENC_INITIALIZE_INPUT
 534 Enum    205/0xCD
 535 Description
 536         Initializes the video input
 537
 538 -------------------------------------------------------------------------------
 539
 540 Name    CX2341X_ENC_SET_FRAME_DROP_RATE
 541 Enum    208/0xD0
 542 Description
 543         For each frame captured, skip specified number of frames.
 544 Param[0]
 545         Number of frames to skip
 546
 547 -------------------------------------------------------------------------------
 548
 549 Name    CX2341X_ENC_PAUSE_ENCODER
 550 Enum    210/0xD2
 551 Description
 552         During a pause condition, all frames are dropped instead of being encoded.
 553 Param[0]
 554         0=Pause encoding
 555         1=Continue encoding
 556
 557 -------------------------------------------------------------------------------
 558
 559 Name    CX2341X_ENC_REFRESH_INPUT
 560 Enum    211/0xD3
 561 Description
 562         Refreshes the video input
 563
 564 -------------------------------------------------------------------------------
 565
 566 Name    CX2341X_ENC_SET_COPYRIGHT
 567 Enum    212/0xD4
 568 Description
 569         Sets stream copyright property
 570 Param[0]
 571         0=Stream is not copyrighted
 572         1=Stream is copyrighted
 573
 574 -------------------------------------------------------------------------------
 575
 576 Name    CX2341X_ENC_SET_EVENT_NOTIFICATION
 577 Enum    213/0xD5
 578 Description
 579         Setup firmware to notify the host about a particular event. Host must
 580         unmask the interrupt bit.
 581 Param[0]
 582         Event (0=refresh encoder input)
 583 Param[1]
 584         Notification 0=disabled 1=enabled
 585 Param[2]
 586         Interrupt bit
 587 Param[3]
 588         Mailbox slot, -1 if no mailbox required.
 589
 590 -------------------------------------------------------------------------------
 591
 592 Name    CX2341X_ENC_SET_NUM_VSYNC_LINES
 593 Enum    214/0xD6
 594 Description
 595         Depending on the analog video decoder used, this assigns the number
 596         of lines for field 1 and 2.
 597 Param[0]
 598         Field 1 number of lines:
 599             0x00EF for SAA7114
 600             0x00F0 for SAA7115
 601             0x0105 for Micronas
 602 Param[1]
 603         Field 2 number of lines:
 604             0x00EF for SAA7114
 605             0x00F0 for SAA7115
 606             0x0106 for Micronas
 607
 608 -------------------------------------------------------------------------------
 609
 610 Name    CX2341X_ENC_SET_PLACEHOLDER
 611 Enum    215/0xD7
 612 Description
 613         Provides a mechanism of inserting custom user data in the MPEG stream.
 614 Param[0]
 615         0=extension & user data
 616         1=private packet with stream ID 0xBD
 617 Param[1]
 618         Rate at which to insert data, in units of frames (for private packet)
 619         or GOPs (for ext. & user data)
 620 Param[2]
 621         Number of data DWORDs (below) to insert
 622 Param[3]
 623         Custom data 0
 624 Param[4]
 625         Custom data 1
 626 Param[5]
 627         Custom data 2
 628 Param[6]
 629         Custom data 3
 630 Param[7]
 631         Custom data 4
 632 Param[8]
 633         Custom data 5
 634 Param[9]
 635         Custom data 6
 636 Param[10]
 637         Custom data 7
 638 Param[11]
 639         Custom data 8
 640
 641 -------------------------------------------------------------------------------
 642
 643 Name    CX2341X_ENC_MUTE_VIDEO
 644 Enum    217/0xD9
 645 Description
 646         Video muting
 647 Param[0]
 648         Bit usage:
 649          0      '0'=video not muted
 650                 '1'=video muted, creates frames with the YUV color defined below
 651          1:7    Unused
 652          8:15   V chrominance information
 653         16:23   U chrominance information
 654         24:31   Y luminance information
 655
 656 -------------------------------------------------------------------------------
 657
 658 Name    CX2341X_ENC_MUTE_AUDIO
 659 Enum    218/0xDA
 660 Description
 661         Audio muting
 662 Param[0]
 663         0=audio not muted
 664         1=audio muted (produces silent mpeg audio stream)
 665
 666 -------------------------------------------------------------------------------
 667
 668 Name    CX2341X_ENC_SET_VERT_CROP_LINE
 669 Enum    219/0xDB
 670 Description
 671         Something to do with 'Vertical Crop Line'
 672 Param[0]
 673         If saa7114 and raw VBI capture and 60 Hz, then set to 10001.
 674         Else 0.
 675
 676 -------------------------------------------------------------------------------
 677
 678 Name    CX2341X_ENC_MISC
 679 Enum    220/0xDC
 680 Description
 681         Miscellaneous actions. Not known for 100% what it does. It's really a
 682         sort of ioctl call. The first parameter is a command number, the second
 683         the value.
 684 Param[0]
 685         Command number:
 686          1=set initial SCR value when starting encoding (works).
 687          2=set quality mode (apparently some test setting).
 688          3=setup advanced VIM protection handling.
 689            Always 1 for the cx23416 and 0 for cx23415.
 690          4=generate DVD compatible PTS timestamps
 691          5=USB flush mode
 692          6=something to do with the quantization matrix
 693          7=set navigation pack insertion for DVD: adds 0xbf (private stream 2)
 694            packets to the MPEG. The size of these packets is 2048 bytes (including
 695            the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
 696            it is up to the application to fill them in. These packets are apparently
 697            inserted every four frames.
 698          8=enable scene change detection (seems to be a failure)
 699          9=set history parameters of the video input module
 700         10=set input field order of VIM
 701         11=set quantization matrix
 702         12=reset audio interface after channel change or input switch (has no argument).
 703            Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to
 704            do any harm calling it regardless.
 705         13=set audio volume delay
 706         14=set audio delay
 707
 708 Param[1]
 709         Command value.