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_SET_VERT_CROP_LINE
 667 Enum    219/0xDB
 668 Description
 669         Something to do with 'Vertical Crop Line'
 670 Param[0]
 671         If saa7114 and raw VBI capture and 60 Hz, then set to 10001.
 672         Else 0.
 673
 674 -------------------------------------------------------------------------------
 675
 676 Name    CX2341X_ENC_MISC
 677 Enum    220/0xDC
 678 Description
 679         Miscellaneous actions. Not known for 100% what it does. It's really a
 680         sort of ioctl call. The first parameter is a command number, the second
 681         the value.
 682 Param[0]
 683         Command number:
 684          1=set initial SCR value when starting encoding (works).
 685          2=set quality mode (apparently some test setting).
 686          3=setup advanced VIM protection handling.
 687            Always 1 for the cx23416 and 0 for cx23415.
 688          4=generate DVD compatible PTS timestamps
 689          5=USB flush mode
 690          6=something to do with the quantization matrix
 691          7=set navigation pack insertion for DVD: adds 0xbf (private stream 2)
 692            packets to the MPEG. The size of these packets is 2048 bytes (including
 693            the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
 694            it is up to the application to fill them in. These packets are apparently
 695            inserted every four frames.
 696          8=enable scene change detection (seems to be a failure)
 697          9=set history parameters of the video input module
 698         10=set input field order of VIM
 699         11=set quantization matrix
 700         12=reset audio interface after channel change or input switch (has no argument).
 701            Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to
 702            do any harm calling it regardless.
 703         13=set audio volume delay
 704         14=set audio delay
 705
 706 Param[1]
 707         Command value.