Documentation/media/v4l-drivers/cx2341x.rst

   1 The cx2341x driver
   2 ==================
   3
   4 Memory at cx2341x chips
   5 -----------------------
   6
   7 This section describes the cx2341x memory map and documents some of the
   8 register space.
   9
  10 .. note:: the memory long words are little-endian ('intel format').
  11
  12 .. warning::
  13
  14         This information was figured out from searching through the memory
  15         and registers, this information may not be correct and is certainly
  16         not complete, and was not derived from anything more than searching
  17         through the memory space with commands like:
  18
  19         .. code-block:: none
  20
  21                 ivtvctl -O min=0x02000000,max=0x020000ff
  22
  23         So take this as is, I'm always searching for more stuff, it's a large
  24         register space :-).
  25
  26 Memory Map
  27 ~~~~~~~~~~
  28
  29 The cx2341x exposes its entire 64M memory space to the PCI host via the PCI BAR0
  30 (Base Address Register 0). The addresses here are offsets relative to the
  31 address held in BAR0.
  32
  33 .. code-block:: none
  34
  35         0x00000000-0x00ffffff Encoder memory space
  36         0x00000000-0x0003ffff Encode.rom
  37         ???-???         MPEG buffer(s)
  38         ???-???         Raw video capture buffer(s)
  39         ???-???         Raw audio capture buffer(s)
  40         ???-???         Display buffers (6 or 9)
  41
  42         0x01000000-0x01ffffff Decoder memory space
  43         0x01000000-0x0103ffff Decode.rom
  44         ???-???         MPEG buffers(s)
  45         0x0114b000-0x0115afff Audio.rom (deprecated?)
  46
  47         0x02000000-0x0200ffff Register Space
  48
  49 Registers
  50 ~~~~~~~~~
  51
  52 The registers occupy the 64k space starting at the 0x02000000 offset from BAR0.
  53 All of these registers are 32 bits wide.
  54
  55 .. code-block:: none
  56
  57         DMA Registers 0x000-0xff:
  58
  59         0x00 - Control:
  60                 0=reset/cancel, 1=read, 2=write, 4=stop
  61         0x04 - DMA status:
  62                 1=read busy, 2=write busy, 4=read error, 8=write error, 16=link list error
  63         0x08 - pci DMA pointer for read link list
  64         0x0c - pci DMA pointer for write link list
  65         0x10 - read/write DMA enable:
  66                 1=read enable, 2=write enable
  67         0x14 - always 0xffffffff, if set any lower instability occurs, 0x00 crashes
  68         0x18 - ??
  69         0x1c - always 0x20 or 32, smaller values slow down DMA transactions
  70         0x20 - always value of 0x780a010a
  71         0x24-0x3c - usually just random values???
  72         0x40 - Interrupt status
  73         0x44 - Write a bit here and shows up in Interrupt status 0x40
  74         0x48 - Interrupt Mask
  75         0x4C - always value of 0xfffdffff,
  76                 if changed to 0xffffffff DMA write interrupts break.
  77         0x50 - always 0xffffffff
  78         0x54 - always 0xffffffff (0x4c, 0x50, 0x54 seem like interrupt masks, are
  79                 3 processors on chip, Java ones, VPU, SPU, APU, maybe these are the
  80                 interrupt masks???).
  81         0x60-0x7C - random values
  82         0x80 - first write linked list reg, for Encoder Memory addr
  83         0x84 - first write linked list reg, for pci memory addr
  84         0x88 - first write linked list reg, for length of buffer in memory addr
  85                 (|0x80000000 or this for last link)
  86         0x8c-0xdc - rest of write linked list reg, 8 sets of 3 total, DMA goes here
  87                 from linked list addr in reg 0x0c, firmware must push through or
  88                 something.
  89         0xe0 - first (and only) read linked list reg, for pci memory addr
  90         0xe4 - first (and only) read linked list reg, for Decoder memory addr
  91         0xe8 - first (and only) read linked list reg, for length of buffer
  92         0xec-0xff - Nothing seems to be in these registers, 0xec-f4 are 0x00000000.
  93
  94 Memory locations for Encoder Buffers 0x700-0x7ff:
  95
  96 These registers show offsets of memory locations pertaining to each
  97 buffer area used for encoding, have to shift them by <<1 first.
  98
  99 - 0x07F8: Encoder SDRAM refresh
 100 - 0x07FC: Encoder SDRAM pre-charge
 101
 102 Memory locations for Decoder Buffers 0x800-0x8ff:
 103
 104 These registers show offsets of memory locations pertaining to each
 105 buffer area used for decoding, have to shift them by <<1 first.
 106
 107 - 0x08F8: Decoder SDRAM refresh
 108 - 0x08FC: Decoder SDRAM pre-charge
 109
 110 Other memory locations:
 111
 112 - 0x2800: Video Display Module control
 113 - 0x2D00: AO (audio output?) control
 114 - 0x2D24: Bytes Flushed
 115 - 0x7000: LSB I2C write clock bit (inverted)
 116 - 0x7004: LSB I2C write data bit (inverted)
 117 - 0x7008: LSB I2C read clock bit
 118 - 0x700c: LSB I2C read data bit
 119 - 0x9008: GPIO get input state
 120 - 0x900c: GPIO set output state
 121 - 0x9020: GPIO direction (Bit7 (GPIO 0..7) - 0:input, 1:output)
 122 - 0x9050: SPU control
 123 - 0x9054: Reset HW blocks
 124 - 0x9058: VPU control
 125 - 0xA018: Bit6: interrupt pending?
 126 - 0xA064: APU command
 127
 128
 129 Interrupt Status Register
 130 ~~~~~~~~~~~~~~~~~~~~~~~~~
 131
 132 The definition of the bits in the interrupt status register 0x0040, and the
 133 interrupt mask 0x0048. If a bit is cleared in the mask, then we want our ISR to
 134 execute.
 135
 136 - bit 31 Encoder Start Capture
 137 - bit 30 Encoder EOS
 138 - bit 29 Encoder VBI capture
 139 - bit 28 Encoder Video Input Module reset event
 140 - bit 27 Encoder DMA complete
 141 - bit 24 Decoder audio mode change detection event (through event notification)
 142 - bit 22 Decoder data request
 143 - bit 20 Decoder DMA complete
 144 - bit 19 Decoder VBI re-insertion
 145 - bit 18 Decoder DMA err (linked-list bad)
 146
 147 Missing documentation
 148 ---------------------
 149
 150 - Encoder API post(?)
 151 - Decoder API post(?)
 152 - Decoder VTRACE event
 153
 154
 155 The cx2341x firmware upload
 156 ---------------------------
 157
 158 This document describes how to upload the cx2341x firmware to the card.
 159
 160 How to find
 161 ~~~~~~~~~~~
 162
 163 See the web pages of the various projects that uses this chip for information
 164 on how to obtain the firmware.
 165
 166 The firmware stored in a Windows driver can be detected as follows:
 167
 168 - Each firmware image is 256k bytes.
 169 - The 1st 32-bit word of the Encoder image is 0x0000da7
 170 - The 1st 32-bit word of the Decoder image is 0x00003a7
 171 - The 2nd 32-bit word of both images is 0xaa55bb66
 172
 173 How to load
 174 ~~~~~~~~~~~
 175
 176 - Issue the FWapi command to stop the encoder if it is running. Wait for the
 177   command to complete.
 178 - Issue the FWapi command to stop the decoder if it is running. Wait for the
 179   command to complete.
 180 - Issue the I2C command to the digitizer to stop emitting VSYNC events.
 181 - Issue the FWapi command to halt the encoder's firmware.
 182 - Sleep for 10ms.
 183 - Issue the FWapi command to halt the decoder's firmware.
 184 - Sleep for 10ms.
 185 - Write 0x00000000 to register 0x2800 to stop the Video Display Module.
 186 - Write 0x00000005 to register 0x2D00 to stop the AO (audio output?).
 187 - Write 0x00000000 to register 0xA064 to ping? the APU.
 188 - Write 0xFFFFFFFE to register 0x9058 to stop the VPU.
 189 - Write 0xFFFFFFFF to register 0x9054 to reset the HW blocks.
 190 - Write 0x00000001 to register 0x9050 to stop the SPU.
 191 - Sleep for 10ms.
 192 - Write 0x0000001A to register 0x07FC to init the Encoder SDRAM's pre-charge.
 193 - Write 0x80000640 to register 0x07F8 to init the Encoder SDRAM's refresh to 1us.
 194 - Write 0x0000001A to register 0x08FC to init the Decoder SDRAM's pre-charge.
 195 - Write 0x80000640 to register 0x08F8 to init the Decoder SDRAM's refresh to 1us.
 196 - Sleep for 512ms. (600ms is recommended)
 197 - Transfer the encoder's firmware image to offset 0 in Encoder memory space.
 198 - Transfer the decoder's firmware image to offset 0 in Decoder memory space.
 199 - Use a read-modify-write operation to Clear bit 0 of register 0x9050 to
 200   re-enable the SPU.
 201 - Sleep for 1 second.
 202 - Use a read-modify-write operation to Clear bits 3 and 0 of register 0x9058
 203   to re-enable the VPU.
 204 - Sleep for 1 second.
 205 - Issue status API commands to both firmware images to verify.
 206
 207
 208 How to call the firmware API
 209 ----------------------------
 210
 211 The preferred calling convention is known as the firmware mailbox. The
 212 mailboxes are basically a fixed length array that serves as the call-stack.
 213
 214 Firmware mailboxes can be located by searching the encoder and decoder memory
 215 for a 16 byte signature. That signature will be located on a 256-byte boundary.
 216
 217 Signature:
 218
 219 .. code-block:: none
 220
 221         0x78, 0x56, 0x34, 0x12, 0x12, 0x78, 0x56, 0x34,
 222         0x34, 0x12, 0x78, 0x56, 0x56, 0x34, 0x12, 0x78
 223
 224 The firmware implements 20 mailboxes of 20 32-bit words. The first 10 are
 225 reserved for API calls. The second 10 are used by the firmware for event
 226 notification.
 227
 228   ====== =================
 229   Index  Name
 230   ====== =================
 231   0      Flags
 232   1      Command
 233   2      Return value
 234   3      Timeout
 235   4-19   Parameter/Result
 236   ====== =================
 237
 238
 239 The flags are defined in the following table. The direction is from the
 240 perspective of the firmware.
 241
 242   ==== ========== ============================================
 243   Bit  Direction  Purpose
 244   ==== ========== ============================================
 245   2    O          Firmware has processed the command.
 246   1    I          Driver has finished setting the parameters.
 247   0    I          Driver is using this mailbox.
 248   ==== ========== ============================================
 249
 250 The command is a 32-bit enumerator. The API specifics may be found in this
 251 chapter.
 252
 253 The return value is a 32-bit enumerator. Only two values are currently defined:
 254
 255 - 0=success
 256 - -1=command undefined.
 257
 258 There are 16 parameters/results 32-bit fields. The driver populates these fields
 259 with values for all the parameters required by the call. The driver overwrites
 260 these fields with result values returned by the call.
 261
 262 The timeout value protects the card from a hung driver thread. If the driver
 263 doesn't handle the completed call within the timeout specified, the firmware
 264 will reset that mailbox.
 265
 266 To make an API call, the driver iterates over each mailbox looking for the
 267 first one available (bit 0 has been cleared). The driver sets that bit, fills
 268 in the command enumerator, the timeout value and any required parameters. The
 269 driver then sets the parameter ready bit (bit 1). The firmware scans the
 270 mailboxes for pending commands, processes them, sets the result code, populates
 271 the result value array with that call's return values and sets the call
 272 complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results
 273 and clear all the flags. If the driver does not perform this task within the
 274 time set in the timeout register, the firmware will reset that mailbox.
 275
 276 Event notifications are sent from the firmware to the host. The host tells the
 277 firmware which events it is interested in via an API call. That call tells the
 278 firmware which notification mailbox to use. The firmware signals the host via
 279 an interrupt. Only the 16 Results fields are used, the Flags, Command, Return
 280 value and Timeout words are not used.
 281
 282
 283 OSD firmware API description
 284 ----------------------------
 285
 286 .. note:: this API is part of the decoder firmware, so it's cx23415 only.
 287
 288
 289
 290 CX2341X_OSD_GET_FRAMEBUFFER
 291 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 292
 293 Enum: 65/0x41
 294
 295 Description
 296 ^^^^^^^^^^^
 297
 298 Return base and length of contiguous OSD memory.
 299
 300 Result[0]
 301 ^^^^^^^^^
 302
 303 OSD base address
 304
 305 Result[1]
 306 ^^^^^^^^^
 307
 308 OSD length
 309
 310
 311
 312 CX2341X_OSD_GET_PIXEL_FORMAT
 313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 314
 315 Enum: 66/0x42
 316
 317 Description
 318 ^^^^^^^^^^^
 319
 320 Query OSD format
 321
 322 Result[0]
 323 ^^^^^^^^^
 324
 325 0=8bit index
 326 1=16bit RGB 5:6:5
 327 2=16bit ARGB 1:5:5:5
 328 3=16bit ARGB 1:4:4:4
 329 4=32bit ARGB 8:8:8:8
 330
 331
 332
 333 CX2341X_OSD_SET_PIXEL_FORMAT
 334 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 335
 336 Enum: 67/0x43
 337
 338 Description
 339 ^^^^^^^^^^^
 340
 341 Assign pixel format
 342
 343 Param[0]
 344 ^^^^^^^^
 345
 346 - 0=8bit index
 347 - 1=16bit RGB 5:6:5
 348 - 2=16bit ARGB 1:5:5:5
 349 - 3=16bit ARGB 1:4:4:4
 350 - 4=32bit ARGB 8:8:8:8
 351
 352
 353
 354 CX2341X_OSD_GET_STATE
 355 ~~~~~~~~~~~~~~~~~~~~~
 356
 357 Enum: 68/0x44
 358
 359 Description
 360 ^^^^^^^^^^^
 361
 362 Query OSD state
 363
 364 Result[0]
 365 ^^^^^^^^^
 366
 367 - Bit  0   0=off, 1=on
 368 - Bits 1:2 alpha control
 369 - Bits 3:5 pixel format
 370
 371
 372
 373 CX2341X_OSD_SET_STATE
 374 ~~~~~~~~~~~~~~~~~~~~~
 375
 376 Enum: 69/0x45
 377
 378 Description
 379 ^^^^^^^^^^^
 380
 381 OSD switch
 382
 383 Param[0]
 384 ^^^^^^^^
 385
 386 0=off, 1=on
 387
 388
 389
 390 CX2341X_OSD_GET_OSD_COORDS
 391 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 392
 393 Enum: 70/0x46
 394
 395 Description
 396 ^^^^^^^^^^^
 397
 398 Retrieve coordinates of OSD area blended with video
 399
 400 Result[0]
 401 ^^^^^^^^^
 402
 403 OSD buffer address
 404
 405 Result[1]
 406 ^^^^^^^^^
 407
 408 Stride in pixels
 409
 410 Result[2]
 411 ^^^^^^^^^
 412
 413 Lines in OSD buffer
 414
 415 Result[3]
 416 ^^^^^^^^^
 417
 418 Horizontal offset in buffer
 419
 420 Result[4]
 421 ^^^^^^^^^
 422
 423 Vertical offset in buffer
 424
 425
 426
 427 CX2341X_OSD_SET_OSD_COORDS
 428 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 429
 430 Enum: 71/0x47
 431
 432 Description
 433 ^^^^^^^^^^^
 434
 435 Assign the coordinates of the OSD area to blend with video
 436
 437 Param[0]
 438 ^^^^^^^^
 439
 440 buffer address
 441
 442 Param[1]
 443 ^^^^^^^^
 444
 445 buffer stride in pixels
 446
 447 Param[2]
 448 ^^^^^^^^
 449
 450 lines in buffer
 451
 452 Param[3]
 453 ^^^^^^^^
 454
 455 horizontal offset
 456
 457 Param[4]
 458 ^^^^^^^^
 459
 460 vertical offset
 461
 462
 463
 464 CX2341X_OSD_GET_SCREEN_COORDS
 465 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 466
 467 Enum: 72/0x48
 468
 469 Description
 470 ^^^^^^^^^^^
 471
 472 Retrieve OSD screen area coordinates
 473
 474 Result[0]
 475 ^^^^^^^^^
 476
 477 top left horizontal offset
 478
 479 Result[1]
 480 ^^^^^^^^^
 481
 482 top left vertical offset
 483
 484 Result[2]
 485 ^^^^^^^^^
 486
 487 bottom right horizontal offset
 488
 489 Result[3]
 490 ^^^^^^^^^
 491
 492 bottom right vertical offset
 493
 494
 495
 496 CX2341X_OSD_SET_SCREEN_COORDS
 497 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 498
 499 Enum: 73/0x49
 500
 501 Description
 502 ^^^^^^^^^^^
 503
 504 Assign the coordinates of the screen area to blend with video
 505
 506 Param[0]
 507 ^^^^^^^^
 508
 509 top left horizontal offset
 510
 511 Param[1]
 512 ^^^^^^^^
 513
 514 top left vertical offset
 515
 516 Param[2]
 517 ^^^^^^^^
 518
 519 bottom left horizontal offset
 520
 521 Param[3]
 522 ^^^^^^^^
 523
 524 bottom left vertical offset
 525
 526
 527
 528 CX2341X_OSD_GET_GLOBAL_ALPHA
 529 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 530
 531 Enum: 74/0x4A
 532
 533 Description
 534 ^^^^^^^^^^^
 535
 536 Retrieve OSD global alpha
 537
 538 Result[0]
 539 ^^^^^^^^^
 540
 541 global alpha: 0=off, 1=on
 542
 543 Result[1]
 544 ^^^^^^^^^
 545
 546 bits 0:7 global alpha
 547
 548
 549
 550 CX2341X_OSD_SET_GLOBAL_ALPHA
 551 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 552
 553 Enum: 75/0x4B
 554
 555 Description
 556 ^^^^^^^^^^^
 557
 558 Update global alpha
 559
 560 Param[0]
 561 ^^^^^^^^
 562
 563 global alpha: 0=off, 1=on
 564
 565 Param[1]
 566 ^^^^^^^^
 567
 568 global alpha (8 bits)
 569
 570 Param[2]
 571 ^^^^^^^^
 572
 573 local alpha: 0=on, 1=off
 574
 575
 576
 577 CX2341X_OSD_SET_BLEND_COORDS
 578 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 579
 580 Enum: 78/0x4C
 581
 582 Description
 583 ^^^^^^^^^^^
 584
 585 Move start of blending area within display buffer
 586
 587 Param[0]
 588 ^^^^^^^^
 589
 590 horizontal offset in buffer
 591
 592 Param[1]
 593 ^^^^^^^^
 594
 595 vertical offset in buffer
 596
 597
 598
 599 CX2341X_OSD_GET_FLICKER_STATE
 600 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 601
 602 Enum: 79/0x4F
 603
 604 Description
 605 ^^^^^^^^^^^
 606
 607 Retrieve flicker reduction module state
 608
 609 Result[0]
 610 ^^^^^^^^^
 611
 612 flicker state: 0=off, 1=on
 613
 614
 615
 616 CX2341X_OSD_SET_FLICKER_STATE
 617 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 618
 619 Enum: 80/0x50
 620
 621 Description
 622 ^^^^^^^^^^^
 623
 624 Set flicker reduction module state
 625
 626 Param[0]
 627 ^^^^^^^^
 628
 629 State: 0=off, 1=on
 630
 631
 632
 633 CX2341X_OSD_BLT_COPY
 634 ~~~~~~~~~~~~~~~~~~~~
 635
 636 Enum: 82/0x52
 637
 638 Description
 639 ^^^^^^^^^^^
 640
 641 BLT copy
 642
 643 Param[0]
 644 ^^^^^^^^
 645
 646 .. code-block:: none
 647
 648         '0000'  zero
 649         '0001' ~destination AND ~source
 650         '0010' ~destination AND  source
 651         '0011' ~destination
 652         '0100'  destination AND ~source
 653         '0101'                  ~source
 654         '0110'  destination XOR  source
 655         '0111' ~destination OR  ~source
 656         '1000' ~destination AND ~source
 657         '1001'  destination XNOR source
 658         '1010'                   source
 659         '1011' ~destination OR   source
 660         '1100'  destination
 661         '1101'  destination OR  ~source
 662         '1110'  destination OR   source
 663         '1111'  one
 664
 665
 666 Param[1]
 667 ^^^^^^^^
 668
 669 Resulting alpha blending
 670
 671 - '01' source_alpha
 672 - '10' destination_alpha
 673 - '11' source_alpha*destination_alpha+1
 674   (zero if both source and destination alpha are zero)
 675
 676 Param[2]
 677 ^^^^^^^^
 678
 679 .. code-block:: none
 680
 681         '00' output_pixel = source_pixel
 682
 683         '01' if source_alpha=0:
 684                  output_pixel = destination_pixel
 685              if 256 > source_alpha > 1:
 686                  output_pixel = ((source_alpha + 1)*source_pixel +
 687                                  (255 - source_alpha)*destination_pixel)/256
 688
 689         '10' if destination_alpha=0:
 690                  output_pixel = source_pixel
 691               if 255 > destination_alpha > 0:
 692                  output_pixel = ((255 - destination_alpha)*source_pixel +
 693                                  (destination_alpha + 1)*destination_pixel)/256
 694
 695         '11' if source_alpha=0:
 696                  source_temp = 0
 697              if source_alpha=255:
 698                  source_temp = source_pixel*256
 699              if 255 > source_alpha > 0:
 700                  source_temp = source_pixel*(source_alpha + 1)
 701              if destination_alpha=0:
 702                  destination_temp = 0
 703              if destination_alpha=255:
 704                  destination_temp = destination_pixel*256
 705              if 255 > destination_alpha > 0:
 706                  destination_temp = destination_pixel*(destination_alpha + 1)
 707              output_pixel = (source_temp + destination_temp)/256
 708
 709 Param[3]
 710 ^^^^^^^^
 711
 712 width
 713
 714 Param[4]
 715 ^^^^^^^^
 716
 717 height
 718
 719 Param[5]
 720 ^^^^^^^^
 721
 722 destination pixel mask
 723
 724 Param[6]
 725 ^^^^^^^^
 726
 727 destination rectangle start address
 728
 729 Param[7]
 730 ^^^^^^^^
 731
 732 destination stride in dwords
 733
 734 Param[8]
 735 ^^^^^^^^
 736
 737 source stride in dwords
 738
 739 Param[9]
 740 ^^^^^^^^
 741
 742 source rectangle start address
 743
 744
 745
 746 CX2341X_OSD_BLT_FILL
 747 ~~~~~~~~~~~~~~~~~~~~
 748
 749 Enum: 83/0x53
 750
 751 Description
 752 ^^^^^^^^^^^
 753
 754 BLT fill color
 755
 756 Param[0]
 757 ^^^^^^^^
 758
 759 Same as Param[0] on API 0x52
 760
 761 Param[1]
 762 ^^^^^^^^
 763
 764 Same as Param[1] on API 0x52
 765
 766 Param[2]
 767 ^^^^^^^^
 768
 769 Same as Param[2] on API 0x52
 770
 771 Param[3]
 772 ^^^^^^^^
 773
 774 width
 775
 776 Param[4]
 777 ^^^^^^^^
 778
 779 height
 780
 781 Param[5]
 782 ^^^^^^^^
 783
 784 destination pixel mask
 785
 786 Param[6]
 787 ^^^^^^^^
 788
 789 destination rectangle start address
 790
 791 Param[7]
 792 ^^^^^^^^
 793
 794 destination stride in dwords
 795
 796 Param[8]
 797 ^^^^^^^^
 798
 799 color fill value
 800
 801
 802
 803 CX2341X_OSD_BLT_TEXT
 804 ~~~~~~~~~~~~~~~~~~~~
 805
 806 Enum: 84/0x54
 807
 808 Description
 809 ^^^^^^^^^^^
 810
 811 BLT for 8 bit alpha text source
 812
 813 Param[0]
 814 ^^^^^^^^
 815
 816 Same as Param[0] on API 0x52
 817
 818 Param[1]
 819 ^^^^^^^^
 820
 821 Same as Param[1] on API 0x52
 822
 823 Param[2]
 824 ^^^^^^^^
 825
 826 Same as Param[2] on API 0x52
 827
 828 Param[3]
 829 ^^^^^^^^
 830
 831 width
 832
 833 Param[4]
 834 ^^^^^^^^
 835
 836 height
 837
 838 Param[5]
 839 ^^^^^^^^
 840
 841 destination pixel mask
 842
 843 Param[6]
 844 ^^^^^^^^
 845
 846 destination rectangle start address
 847
 848 Param[7]
 849 ^^^^^^^^
 850
 851 destination stride in dwords
 852
 853 Param[8]
 854 ^^^^^^^^
 855
 856 source stride in dwords
 857
 858 Param[9]
 859 ^^^^^^^^
 860
 861 source rectangle start address
 862
 863 Param[10]
 864 ^^^^^^^^^
 865
 866 color fill value
 867
 868
 869
 870 CX2341X_OSD_SET_FRAMEBUFFER_WINDOW
 871 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 872
 873 Enum: 86/0x56
 874
 875 Description
 876 ^^^^^^^^^^^
 877
 878 Positions the main output window on the screen. The coordinates must be
 879 such that the entire window fits on the screen.
 880
 881 Param[0]
 882 ^^^^^^^^
 883
 884 window width
 885
 886 Param[1]
 887 ^^^^^^^^
 888
 889 window height
 890
 891 Param[2]
 892 ^^^^^^^^
 893
 894 top left window corner horizontal offset
 895
 896 Param[3]
 897 ^^^^^^^^
 898
 899 top left window corner vertical offset
 900
 901
 902
 903 CX2341X_OSD_SET_CHROMA_KEY
 904 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 905
 906 Enum: 96/0x60
 907
 908 Description
 909 ^^^^^^^^^^^
 910
 911 Chroma key switch and color
 912
 913 Param[0]
 914 ^^^^^^^^
 915
 916 state: 0=off, 1=on
 917
 918 Param[1]
 919 ^^^^^^^^
 920
 921 color
 922
 923
 924
 925 CX2341X_OSD_GET_ALPHA_CONTENT_INDEX
 926 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 927
 928 Enum: 97/0x61
 929
 930 Description
 931 ^^^^^^^^^^^
 932
 933 Retrieve alpha content index
 934
 935 Result[0]
 936 ^^^^^^^^^
 937
 938 alpha content index, Range 0:15
 939
 940
 941
 942 CX2341X_OSD_SET_ALPHA_CONTENT_INDEX
 943 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 944
 945 Enum: 98/0x62
 946
 947 Description
 948 ^^^^^^^^^^^
 949
 950 Assign alpha content index
 951
 952 Param[0]
 953 ^^^^^^^^
 954
 955 alpha content index, range 0:15
 956
 957
 958 Encoder firmware API description
 959 --------------------------------
 960
 961 CX2341X_ENC_PING_FW
 962 ~~~~~~~~~~~~~~~~~~~
 963
 964 Enum: 128/0x80
 965
 966 Description
 967 ^^^^^^^^^^^
 968
 969 Does nothing. Can be used to check if the firmware is responding.
 970
 971
 972
 973 CX2341X_ENC_START_CAPTURE
 974 ~~~~~~~~~~~~~~~~~~~~~~~~~
 975
 976 Enum: 129/0x81
 977
 978 Description
 979 ^^^^^^^^^^^
 980
 981 Commences the capture of video, audio and/or VBI data. All encoding
 982 parameters must be initialized prior to this API call. Captures frames
 983 continuously or until a predefined number of frames have been captured.
 984
 985 Param[0]
 986 ^^^^^^^^
 987
 988 Capture stream type:
 989
 990         - 0=MPEG
 991         - 1=Raw
 992         - 2=Raw passthrough
 993         - 3=VBI
 994
 995
 996 Param[1]
 997 ^^^^^^^^
 998
 999 Bitmask:
1000
1001         - Bit 0 when set, captures YUV
1002         - Bit 1 when set, captures PCM audio
1003         - Bit 2 when set, captures VBI (same as param[0]=3)
1004         - Bit 3 when set, the capture destination is the decoder
1005           (same as param[0]=2)
1006         - Bit 4 when set, the capture destination is the host
1007
1008 .. note:: this parameter is only meaningful for RAW capture type.
1009
1010
1011
1012 CX2341X_ENC_STOP_CAPTURE
1013 ~~~~~~~~~~~~~~~~~~~~~~~~
1014
1015 Enum: 130/0x82
1016
1017 Description
1018 ^^^^^^^^^^^
1019
1020 Ends a capture in progress
1021
1022 Param[0]
1023 ^^^^^^^^
1024
1025 - 0=stop at end of GOP (generates IRQ)
1026 - 1=stop immediate (no IRQ)
1027
1028 Param[1]
1029 ^^^^^^^^
1030
1031 Stream type to stop, see param[0] of API 0x81
1032
1033 Param[2]
1034 ^^^^^^^^
1035
1036 Subtype, see param[1] of API 0x81
1037
1038
1039
1040 CX2341X_ENC_SET_AUDIO_ID
1041 ~~~~~~~~~~~~~~~~~~~~~~~~
1042
1043 Enum: 137/0x89
1044
1045 Description
1046 ^^^^^^^^^^^
1047
1048 Assigns the transport stream ID of the encoded audio stream
1049
1050 Param[0]
1051 ^^^^^^^^
1052
1053 Audio Stream ID
1054
1055
1056
1057 CX2341X_ENC_SET_VIDEO_ID
1058 ~~~~~~~~~~~~~~~~~~~~~~~~
1059
1060 Enum: 139/0x8B
1061
1062 Description
1063 ^^^^^^^^^^^
1064
1065 Set video transport stream ID
1066
1067 Param[0]
1068 ^^^^^^^^
1069
1070 Video stream ID
1071
1072
1073
1074 CX2341X_ENC_SET_PCR_ID
1075 ~~~~~~~~~~~~~~~~~~~~~~
1076
1077 Enum: 141/0x8D
1078
1079 Description
1080 ^^^^^^^^^^^
1081
1082 Assigns the transport stream ID for PCR packets
1083
1084 Param[0]
1085 ^^^^^^^^
1086
1087 PCR Stream ID
1088
1089
1090
1091 CX2341X_ENC_SET_FRAME_RATE
1092 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1093
1094 Enum: 143/0x8F
1095
1096 Description
1097 ^^^^^^^^^^^
1098
1099 Set video frames per second. Change occurs at start of new GOP.
1100
1101 Param[0]
1102 ^^^^^^^^
1103
1104 - 0=30fps
1105 - 1=25fps
1106
1107
1108
1109 CX2341X_ENC_SET_FRAME_SIZE
1110 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1111
1112 Enum: 145/0x91
1113
1114 Description
1115 ^^^^^^^^^^^
1116
1117 Select video stream encoding resolution.
1118
1119 Param[0]
1120 ^^^^^^^^
1121
1122 Height in lines. Default 480
1123
1124 Param[1]
1125 ^^^^^^^^
1126
1127 Width in pixels. Default 720
1128
1129
1130
1131 CX2341X_ENC_SET_BIT_RATE
1132 ~~~~~~~~~~~~~~~~~~~~~~~~
1133
1134 Enum: 149/0x95
1135
1136 Description
1137 ^^^^^^^^^^^
1138
1139 Assign average video stream bitrate.
1140
1141 Param[0]
1142 ^^^^^^^^
1143
1144 0=variable bitrate, 1=constant bitrate
1145
1146 Param[1]
1147 ^^^^^^^^
1148
1149 bitrate in bits per second
1150
1151 Param[2]
1152 ^^^^^^^^
1153
1154 peak bitrate in bits per second, divided by 400
1155
1156 Param[3]
1157 ^^^^^^^^
1158
1159 Mux bitrate in bits per second, divided by 400. May be 0 (default).
1160
1161 Param[4]
1162 ^^^^^^^^
1163
1164 Rate Control VBR Padding
1165
1166 Param[5]
1167 ^^^^^^^^
1168
1169 VBV Buffer used by encoder
1170
1171 .. note::
1172
1173         #) Param\[3\] and Param\[4\] seem to be always 0
1174         #) Param\[5\] doesn't seem to be used.
1175
1176
1177
1178 CX2341X_ENC_SET_GOP_PROPERTIES
1179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1180
1181 Enum: 151/0x97
1182
1183 Description
1184 ^^^^^^^^^^^
1185
1186 Setup the GOP structure
1187
1188 Param[0]
1189 ^^^^^^^^
1190
1191 GOP size (maximum is 34)
1192
1193 Param[1]
1194 ^^^^^^^^
1195
1196 Number of B frames between the I and P frame, plus 1.
1197 For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3
1198
1199 .. note::
1200
1201         GOP size must be a multiple of (B-frames + 1).
1202
1203
1204
1205 CX2341X_ENC_SET_ASPECT_RATIO
1206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1207
1208 Enum: 153/0x99
1209
1210 Description
1211 ^^^^^^^^^^^
1212
1213 Sets the encoding aspect ratio. Changes in the aspect ratio take effect
1214 at the start of the next GOP.
1215
1216 Param[0]
1217 ^^^^^^^^
1218
1219 - '0000' forbidden
1220 - '0001' 1:1 square
1221 - '0010' 4:3
1222 - '0011' 16:9
1223 - '0100' 2.21:1
1224 - '0101' to '1111' reserved
1225
1226
1227
1228 CX2341X_ENC_SET_DNR_FILTER_MODE
1229 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1230
1231 Enum: 155/0x9B
1232
1233 Description
1234 ^^^^^^^^^^^
1235
1236 Assign Dynamic Noise Reduction operating mode
1237
1238 Param[0]
1239 ^^^^^^^^
1240
1241 Bit0: Spatial filter, set=auto, clear=manual
1242 Bit1: Temporal filter, set=auto, clear=manual
1243
1244 Param[1]
1245 ^^^^^^^^
1246
1247 Median filter:
1248
1249 - 0=Disabled
1250 - 1=Horizontal
1251 - 2=Vertical
1252 - 3=Horiz/Vert
1253 - 4=Diagonal
1254
1255
1256
1257 CX2341X_ENC_SET_DNR_FILTER_PROPS
1258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1259
1260 Enum: 157/0x9D
1261
1262 Description
1263 ^^^^^^^^^^^
1264
1265 These Dynamic Noise Reduction filter values are only meaningful when
1266 the respective filter is set to "manual" (See API 0x9B)
1267
1268 Param[0]
1269 ^^^^^^^^
1270
1271 Spatial filter: default 0, range 0:15
1272
1273 Param[1]
1274 ^^^^^^^^
1275
1276 Temporal filter: default 0, range 0:31
1277
1278
1279
1280 CX2341X_ENC_SET_CORING_LEVELS
1281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1282
1283 Enum: 159/0x9F
1284
1285 Description
1286 ^^^^^^^^^^^
1287
1288 Assign Dynamic Noise Reduction median filter properties.
1289
1290 Param[0]
1291 ^^^^^^^^
1292
1293 Threshold above which the luminance median filter is enabled.
1294 Default: 0, range 0:255
1295
1296 Param[1]
1297 ^^^^^^^^
1298
1299 Threshold below which the luminance median filter is enabled.
1300 Default: 255, range 0:255
1301
1302 Param[2]
1303 ^^^^^^^^
1304
1305 Threshold above which the chrominance median filter is enabled.
1306 Default: 0, range 0:255
1307
1308 Param[3]
1309 ^^^^^^^^
1310
1311 Threshold below which the chrominance median filter is enabled.
1312 Default: 255, range 0:255
1313
1314
1315
1316 CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
1317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1318
1319 Enum: 161/0xA1
1320
1321 Description
1322 ^^^^^^^^^^^
1323
1324 Assign spatial prefilter parameters
1325
1326 Param[0]
1327 ^^^^^^^^
1328
1329 Luminance filter
1330
1331 - 0=Off
1332 - 1=1D Horizontal
1333 - 2=1D Vertical
1334 - 3=2D H/V Separable (default)
1335 - 4=2D Symmetric non-separable
1336
1337 Param[1]
1338 ^^^^^^^^
1339
1340 Chrominance filter
1341
1342 - 0=Off
1343 - 1=1D Horizontal (default)
1344
1345
1346
1347 CX2341X_ENC_SET_VBI_LINE
1348 ~~~~~~~~~~~~~~~~~~~~~~~~
1349
1350 Enum: 183/0xB7
1351
1352 Description
1353 ^^^^^^^^^^^
1354
1355 Selects VBI line number.
1356
1357 Param[0]
1358 ^^^^^^^^
1359
1360 - Bits 0:4      line number
1361 - Bit  31               0=top_field, 1=bottom_field
1362 - Bits 0:31     all set specifies "all lines"
1363
1364 Param[1]
1365 ^^^^^^^^
1366
1367 VBI line information features: 0=disabled, 1=enabled
1368
1369 Param[2]
1370 ^^^^^^^^
1371
1372 Slicing: 0=None, 1=Closed Caption
1373 Almost certainly not implemented. Set to 0.
1374
1375 Param[3]
1376 ^^^^^^^^
1377
1378 Luminance samples in this line.
1379 Almost certainly not implemented. Set to 0.
1380
1381 Param[4]
1382 ^^^^^^^^
1383
1384 Chrominance samples in this line
1385 Almost certainly not implemented. Set to 0.
1386
1387
1388
1389 CX2341X_ENC_SET_STREAM_TYPE
1390 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1391
1392 Enum: 185/0xB9
1393
1394 Description
1395 ^^^^^^^^^^^
1396
1397 Assign stream type
1398
1399 .. note::
1400
1401         Transport stream is not working in recent firmwares.
1402         And in older firmwares the timestamps in the TS seem to be
1403         unreliable.
1404
1405 Param[0]
1406 ^^^^^^^^
1407
1408 - 0=Program stream
1409 - 1=Transport stream
1410 - 2=MPEG1 stream
1411 - 3=PES A/V stream
1412 - 5=PES Video stream
1413 - 7=PES Audio stream
1414 - 10=DVD stream
1415 - 11=VCD stream
1416 - 12=SVCD stream
1417 - 13=DVD_S1 stream
1418 - 14=DVD_S2 stream
1419
1420
1421
1422 CX2341X_ENC_SET_OUTPUT_PORT
1423 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1424
1425 Enum: 187/0xBB
1426
1427 Description
1428 ^^^^^^^^^^^
1429
1430 Assign stream output port. Normally 0 when the data is copied through
1431 the PCI bus (DMA), and 1 when the data is streamed to another chip
1432 (pvrusb and cx88-blackbird).
1433
1434 Param[0]
1435 ^^^^^^^^
1436
1437 - 0=Memory (default)
1438 - 1=Streaming
1439 - 2=Serial
1440
1441 Param[1]
1442 ^^^^^^^^
1443
1444 Unknown, but leaving this to 0 seems to work best. Indications are that
1445 this might have to do with USB support, although passing anything but 0
1446 only breaks things.
1447
1448
1449
1450 CX2341X_ENC_SET_AUDIO_PROPERTIES
1451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1452
1453 Enum: 189/0xBD
1454
1455 Description
1456 ^^^^^^^^^^^
1457
1458 Set audio stream properties, may be called while encoding is in progress.
1459
1460 .. note::
1461
1462         All bitfields are consistent with ISO11172 documentation except
1463         bits 2:3 which ISO docs define as:
1464
1465         - '11' Layer I
1466         - '10' Layer II
1467         - '01' Layer III
1468         - '00' Undefined
1469
1470         This discrepancy may indicate a possible error in the documentation.
1471         Testing indicated that only Layer II is actually working, and that
1472         the minimum bitrate should be 192 kbps.
1473
1474 Param[0]
1475 ^^^^^^^^
1476
1477 Bitmask:
1478
1479 .. code-block:: none
1480
1481            0:1  '00' 44.1Khz
1482                 '01' 48Khz
1483                 '10' 32Khz
1484                 '11' reserved
1485
1486            2:3  '01'=Layer I
1487                 '10'=Layer II
1488
1489            4:7  Bitrate:
1490                      Index | Layer I     | Layer II
1491                      ------+-------------+------------
1492                     '0000' | free format | free format
1493                     '0001' |  32 kbit/s  |  32 kbit/s
1494                     '0010' |  64 kbit/s  |  48 kbit/s
1495                     '0011' |  96 kbit/s  |  56 kbit/s
1496                     '0100' | 128 kbit/s  |  64 kbit/s
1497                     '0101' | 160 kbit/s  |  80 kbit/s
1498                     '0110' | 192 kbit/s  |  96 kbit/s
1499                     '0111' | 224 kbit/s  | 112 kbit/s
1500                     '1000' | 256 kbit/s  | 128 kbit/s
1501                     '1001' | 288 kbit/s  | 160 kbit/s
1502                     '1010' | 320 kbit/s  | 192 kbit/s
1503                     '1011' | 352 kbit/s  | 224 kbit/s
1504                     '1100' | 384 kbit/s  | 256 kbit/s
1505                     '1101' | 416 kbit/s  | 320 kbit/s
1506                     '1110' | 448 kbit/s  | 384 kbit/s
1507
1508                 .. note::
1509
1510                         For Layer II, not all combinations of total bitrate
1511                         and mode are allowed. See ISO11172-3 3-Annex B,
1512                         Table 3-B.2
1513
1514            8:9  '00'=Stereo
1515                 '01'=JointStereo
1516                 '10'=Dual
1517                 '11'=Mono
1518
1519                 .. note::
1520
1521                         The cx23415 cannot decode Joint Stereo properly.
1522
1523           10:11 Mode Extension used in joint_stereo mode.
1524                 In Layer I and II they indicate which subbands are in
1525                 intensity_stereo. All other subbands are coded in stereo.
1526                     '00' subbands 4-31 in intensity_stereo, bound==4
1527                     '01' subbands 8-31 in intensity_stereo, bound==8
1528                     '10' subbands 12-31 in intensity_stereo, bound==12
1529                     '11' subbands 16-31 in intensity_stereo, bound==16
1530
1531           12:13 Emphasis:
1532                     '00' None
1533                     '01' 50/15uS
1534                     '10' reserved
1535                     '11' CCITT J.17
1536
1537           14    CRC:
1538                     '0' off
1539                     '1' on
1540
1541           15    Copyright:
1542                     '0' off
1543                     '1' on
1544
1545           16    Generation:
1546                     '0' copy
1547                     '1' original
1548
1549
1550
1551 CX2341X_ENC_HALT_FW
1552 ~~~~~~~~~~~~~~~~~~~
1553
1554 Enum: 195/0xC3
1555
1556 Description
1557 ^^^^^^^^^^^
1558
1559 The firmware is halted and no further API calls are serviced until the
1560 firmware is uploaded again.
1561
1562
1563
1564 CX2341X_ENC_GET_VERSION
1565 ~~~~~~~~~~~~~~~~~~~~~~~
1566
1567 Enum: 196/0xC4
1568
1569 Description
1570 ^^^^^^^^^^^
1571
1572 Returns the version of the encoder firmware.
1573
1574 Result[0]
1575 ^^^^^^^^^
1576
1577 Version bitmask:
1578 - Bits  0:15 build
1579 - Bits 16:23 minor
1580 - Bits 24:31 major
1581
1582
1583
1584 CX2341X_ENC_SET_GOP_CLOSURE
1585 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1586
1587 Enum: 197/0xC5
1588
1589 Description
1590 ^^^^^^^^^^^
1591
1592 Assigns the GOP open/close property.
1593
1594 Param[0]
1595 ^^^^^^^^
1596
1597 - 0=Open
1598 - 1=Closed
1599
1600
1601
1602 CX2341X_ENC_GET_SEQ_END
1603 ~~~~~~~~~~~~~~~~~~~~~~~
1604
1605 Enum: 198/0xC6
1606
1607 Description
1608 ^^^^^^^^^^^
1609
1610 Obtains the sequence end code of the encoder's buffer. When a capture
1611 is started a number of interrupts are still generated, the last of
1612 which will have Result[0] set to 1 and Result[1] will contain the size
1613 of the buffer.
1614
1615 Result[0]
1616 ^^^^^^^^^
1617
1618 State of the transfer (1 if last buffer)
1619
1620 Result[1]
1621 ^^^^^^^^^
1622
1623 If Result[0] is 1, this contains the size of the last buffer, undefined
1624 otherwise.
1625
1626
1627
1628 CX2341X_ENC_SET_PGM_INDEX_INFO
1629 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1630
1631 Enum: 199/0xC7
1632
1633 Description
1634 ^^^^^^^^^^^
1635
1636 Sets the Program Index Information.
1637 The information is stored as follows:
1638
1639 .. code-block:: c
1640
1641         struct info {
1642                 u32 length;             // Length of this frame
1643                 u32 offset_low;         // Offset in the file of the
1644                 u32 offset_high;        // start of this frame
1645                 u32 mask1;              // Bits 0-2 are the type mask:
1646                                         // 1=I, 2=P, 4=B
1647                                         // 0=End of Program Index, other fields
1648                                         //   are invalid.
1649                 u32 pts;                // The PTS of the frame
1650                 u32 mask2;              // Bit 0 is bit 32 of the pts.
1651         };
1652         u32 table_ptr;
1653         struct info index[400];
1654
1655 The table_ptr is the encoder memory address in the table were
1656 *new* entries will be written.
1657
1658 .. note:: This is a ringbuffer, so the table_ptr will wraparound.
1659
1660 Param[0]
1661 ^^^^^^^^
1662
1663 Picture Mask:
1664 - 0=No index capture
1665 - 1=I frames
1666 - 3=I,P frames
1667 - 7=I,P,B frames
1668
1669 (Seems to be ignored, it always indexes I, P and B frames)
1670
1671 Param[1]
1672 ^^^^^^^^
1673
1674 Elements requested (up to 400)
1675
1676 Result[0]
1677 ^^^^^^^^^
1678
1679 Offset in the encoder memory of the start of the table.
1680
1681 Result[1]
1682 ^^^^^^^^^
1683
1684 Number of allocated elements up to a maximum of Param[1]
1685
1686
1687
1688 CX2341X_ENC_SET_VBI_CONFIG
1689 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1690
1691 Enum: 200/0xC8
1692
1693 Description
1694 ^^^^^^^^^^^
1695
1696 Configure VBI settings
1697
1698 Param[0]
1699 ^^^^^^^^
1700
1701 Bitmap:
1702
1703 .. code-block:: none
1704
1705             0    Mode '0' Sliced, '1' Raw
1706             1:3  Insertion:
1707                      '000' insert in extension & user data
1708                      '001' insert in private packets
1709                      '010' separate stream and user data
1710                      '111' separate stream and private data
1711             8:15 Stream ID (normally 0xBD)
1712
1713 Param[1]
1714 ^^^^^^^^
1715
1716 Frames per interrupt (max 8). Only valid in raw mode.
1717
1718 Param[2]
1719 ^^^^^^^^
1720
1721 Total raw VBI frames. Only valid in raw mode.
1722
1723 Param[3]
1724 ^^^^^^^^
1725
1726 Start codes
1727
1728 Param[4]
1729 ^^^^^^^^
1730
1731 Stop codes
1732
1733 Param[5]
1734 ^^^^^^^^
1735
1736 Lines per frame
1737
1738 Param[6]
1739 ^^^^^^^^
1740
1741 Byte per line
1742
1743 Result[0]
1744 ^^^^^^^^^
1745
1746 Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
1747
1748 Result[1]
1749 ^^^^^^^^^
1750
1751 Observed number of frames in raw mode. Range 1 to Param[2]
1752
1753 Result[2]
1754 ^^^^^^^^^
1755
1756 Memory offset to start or raw VBI data
1757
1758
1759
1760 CX2341X_ENC_SET_DMA_BLOCK_SIZE
1761 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1762
1763 Enum: 201/0xC9
1764
1765 Description
1766 ^^^^^^^^^^^
1767
1768 Set DMA transfer block size
1769
1770 Param[0]
1771 ^^^^^^^^
1772
1773 DMA transfer block size in bytes or frames. When unit is bytes,
1774 supported block sizes are 2^7, 2^8 and 2^9 bytes.
1775
1776 Param[1]
1777 ^^^^^^^^
1778
1779 Unit: 0=bytes, 1=frames
1780
1781
1782
1783 CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
1784 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1785
1786 Enum: 202/0xCA
1787
1788 Description
1789 ^^^^^^^^^^^
1790
1791 Returns information on the previous DMA transfer in conjunction with
1792 bit 27 of the interrupt mask. Uses mailbox 10.
1793
1794 Result[0]
1795 ^^^^^^^^^
1796
1797 Type of stream
1798
1799 Result[1]
1800 ^^^^^^^^^
1801
1802 Address Offset
1803
1804 Result[2]
1805 ^^^^^^^^^
1806
1807 Maximum size of transfer
1808
1809
1810
1811 CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
1812 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1813
1814 Enum: 203/0xCB
1815
1816 Description
1817 ^^^^^^^^^^^
1818
1819 Returns information on the previous DMA transfer in conjunction with
1820 bit 27 or 18 of the interrupt mask. Uses mailbox 9.
1821
1822 Result[0]
1823 ^^^^^^^^^
1824
1825 Status bits:
1826 - 0   read completed
1827 - 1   write completed
1828 - 2   DMA read error
1829 - 3   DMA write error
1830 - 4   Scatter-Gather array error
1831
1832 Result[1]
1833 ^^^^^^^^^
1834
1835 DMA type
1836
1837 Result[2]
1838 ^^^^^^^^^
1839
1840 Presentation Time Stamp bits 0..31
1841
1842 Result[3]
1843 ^^^^^^^^^
1844
1845 Presentation Time Stamp bit 32
1846
1847
1848
1849 CX2341X_ENC_SCHED_DMA_TO_HOST
1850 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1851
1852 Enum: 204/0xCC
1853
1854 Description
1855 ^^^^^^^^^^^
1856
1857 Setup DMA to host operation
1858
1859 Param[0]
1860 ^^^^^^^^
1861
1862 Memory address of link list
1863
1864 Param[1]
1865 ^^^^^^^^
1866
1867 Length of link list (wtf: what units ???)
1868
1869 Param[2]
1870 ^^^^^^^^
1871
1872 DMA type (0=MPEG)
1873
1874
1875
1876 CX2341X_ENC_INITIALIZE_INPUT
1877 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1878
1879 Enum: 205/0xCD
1880
1881 Description
1882 ^^^^^^^^^^^
1883
1884 Initializes the video input
1885
1886
1887
1888 CX2341X_ENC_SET_FRAME_DROP_RATE
1889 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1890
1891 Enum: 208/0xD0
1892
1893 Description
1894 ^^^^^^^^^^^
1895
1896 For each frame captured, skip specified number of frames.
1897
1898 Param[0]
1899 ^^^^^^^^
1900
1901 Number of frames to skip
1902
1903
1904
1905 CX2341X_ENC_PAUSE_ENCODER
1906 ~~~~~~~~~~~~~~~~~~~~~~~~~
1907
1908 Enum: 210/0xD2
1909
1910 Description
1911 ^^^^^^^^^^^
1912
1913 During a pause condition, all frames are dropped instead of being encoded.
1914
1915 Param[0]
1916 ^^^^^^^^
1917
1918 - 0=Pause encoding
1919 - 1=Continue encoding
1920
1921
1922
1923 CX2341X_ENC_REFRESH_INPUT
1924 ~~~~~~~~~~~~~~~~~~~~~~~~~
1925
1926 Enum: 211/0xD3
1927
1928 Description
1929 ^^^^^^^^^^^
1930
1931 Refreshes the video input
1932
1933
1934
1935 CX2341X_ENC_SET_COPYRIGHT
1936 ~~~~~~~~~~~~~~~~~~~~~~~~~
1937
1938 Enum: 212/0xD4
1939
1940 Description
1941 ^^^^^^^^^^^
1942
1943 Sets stream copyright property
1944
1945 Param[0]
1946 ^^^^^^^^
1947
1948
1949 - 0=Stream is not copyrighted
1950 - 1=Stream is copyrighted
1951
1952
1953
1954 CX2341X_ENC_SET_EVENT_NOTIFICATION
1955 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1956
1957 Enum: 213/0xD5
1958
1959 Description
1960 ^^^^^^^^^^^
1961
1962 Setup firmware to notify the host about a particular event. Host must
1963 unmask the interrupt bit.
1964
1965 Param[0]
1966 ^^^^^^^^
1967
1968 Event (0=refresh encoder input)
1969
1970 Param[1]
1971 ^^^^^^^^
1972
1973 Notification 0=disabled 1=enabled
1974
1975 Param[2]
1976 ^^^^^^^^
1977
1978 Interrupt bit
1979
1980 Param[3]
1981 ^^^^^^^^
1982
1983 Mailbox slot, -1 if no mailbox required.
1984
1985
1986
1987 CX2341X_ENC_SET_NUM_VSYNC_LINES
1988 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1989
1990 Enum: 214/0xD6
1991
1992 Description
1993 ^^^^^^^^^^^
1994
1995 Depending on the analog video decoder used, this assigns the number
1996 of lines for field 1 and 2.
1997
1998 Param[0]
1999 ^^^^^^^^
2000
2001 Field 1 number of lines:
2002 - 0x00EF for SAA7114
2003 - 0x00F0 for SAA7115
2004 - 0x0105 for Micronas
2005
2006 Param[1]
2007 ^^^^^^^^
2008
2009 Field 2 number of lines:
2010 - 0x00EF for SAA7114
2011 - 0x00F0 for SAA7115
2012 - 0x0106 for Micronas
2013
2014
2015
2016 CX2341X_ENC_SET_PLACEHOLDER
2017 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2018
2019 Enum: 215/0xD7
2020
2021 Description
2022 ^^^^^^^^^^^
2023
2024 Provides a mechanism of inserting custom user data in the MPEG stream.
2025
2026 Param[0]
2027 ^^^^^^^^
2028
2029 - 0=extension & user data
2030 - 1=private packet with stream ID 0xBD
2031
2032 Param[1]
2033 ^^^^^^^^
2034
2035 Rate at which to insert data, in units of frames (for private packet)
2036 or GOPs (for ext. & user data)
2037
2038 Param[2]
2039 ^^^^^^^^
2040
2041 Number of data DWORDs (below) to insert
2042
2043 Param[3]
2044 ^^^^^^^^
2045
2046 Custom data 0
2047
2048 Param[4]
2049 ^^^^^^^^
2050
2051 Custom data 1
2052
2053 Param[5]
2054 ^^^^^^^^
2055
2056 Custom data 2
2057
2058 Param[6]
2059 ^^^^^^^^
2060
2061 Custom data 3
2062
2063 Param[7]
2064 ^^^^^^^^
2065
2066 Custom data 4
2067
2068 Param[8]
2069 ^^^^^^^^
2070
2071 Custom data 5
2072
2073 Param[9]
2074 ^^^^^^^^
2075
2076 Custom data 6
2077
2078 Param[10]
2079 ^^^^^^^^^
2080
2081 Custom data 7
2082
2083 Param[11]
2084 ^^^^^^^^^
2085
2086 Custom data 8
2087
2088
2089
2090 CX2341X_ENC_MUTE_VIDEO
2091 ~~~~~~~~~~~~~~~~~~~~~~
2092
2093 Enum: 217/0xD9
2094
2095 Description
2096 ^^^^^^^^^^^
2097
2098 Video muting
2099
2100 Param[0]
2101 ^^^^^^^^
2102
2103 Bit usage:
2104
2105 .. code-block:: none
2106
2107          0      '0'=video not muted
2108                 '1'=video muted, creates frames with the YUV color defined below
2109          1:7    Unused
2110          8:15   V chrominance information
2111         16:23   U chrominance information
2112         24:31   Y luminance information
2113
2114
2115
2116 CX2341X_ENC_MUTE_AUDIO
2117 ~~~~~~~~~~~~~~~~~~~~~~
2118
2119 Enum: 218/0xDA
2120
2121 Description
2122 ^^^^^^^^^^^
2123
2124 Audio muting
2125
2126 Param[0]
2127 ^^^^^^^^
2128
2129 - 0=audio not muted
2130 - 1=audio muted (produces silent mpeg audio stream)
2131
2132
2133
2134 CX2341X_ENC_SET_VERT_CROP_LINE
2135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2136
2137 Enum: 219/0xDB
2138
2139 Description
2140 ^^^^^^^^^^^
2141
2142 Something to do with 'Vertical Crop Line'
2143
2144 Param[0]
2145 ^^^^^^^^
2146
2147 If saa7114 and raw VBI capture and 60 Hz, then set to 10001.
2148 Else 0.
2149
2150
2151
2152 CX2341X_ENC_MISC
2153 ~~~~~~~~~~~~~~~~
2154
2155 Enum: 220/0xDC
2156
2157 Description
2158 ^^^^^^^^^^^
2159
2160 Miscellaneous actions. Not known for 100% what it does. It's really a
2161 sort of ioctl call. The first parameter is a command number, the second
2162 the value.
2163
2164 Param[0]
2165 ^^^^^^^^
2166
2167 Command number:
2168
2169 .. code-block:: none
2170
2171          1=set initial SCR value when starting encoding (works).
2172          2=set quality mode (apparently some test setting).
2173          3=setup advanced VIM protection handling.
2174            Always 1 for the cx23416 and 0 for cx23415.
2175          4=generate DVD compatible PTS timestamps
2176          5=USB flush mode
2177          6=something to do with the quantization matrix
2178          7=set navigation pack insertion for DVD: adds 0xbf (private stream 2)
2179            packets to the MPEG. The size of these packets is 2048 bytes (including
2180            the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
2181            it is up to the application to fill them in. These packets are apparently
2182            inserted every four frames.
2183          8=enable scene change detection (seems to be a failure)
2184          9=set history parameters of the video input module
2185         10=set input field order of VIM
2186         11=set quantization matrix
2187         12=reset audio interface after channel change or input switch (has no argument).
2188            Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to
2189            do any harm calling it regardless.
2190         13=set audio volume delay
2191         14=set audio delay
2192
2193
2194 Param[1]
2195 ^^^^^^^^
2196
2197 Command value.
2198
2199 Decoder firmware API description
2200 --------------------------------
2201
2202 .. note:: this API is part of the decoder firmware, so it's cx23415 only.
2203
2204
2205
2206 CX2341X_DEC_PING_FW
2207 ~~~~~~~~~~~~~~~~~~~
2208
2209 Enum: 0/0x00
2210
2211 Description
2212 ^^^^^^^^^^^
2213
2214 This API call does nothing. It may be used to check if the firmware
2215 is responding.
2216
2217
2218
2219 CX2341X_DEC_START_PLAYBACK
2220 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2221
2222 Enum: 1/0x01
2223
2224 Description
2225 ^^^^^^^^^^^
2226
2227 Begin or resume playback.
2228
2229 Param[0]
2230 ^^^^^^^^
2231
2232 0 based frame number in GOP to begin playback from.
2233
2234 Param[1]
2235 ^^^^^^^^
2236
2237 Specifies the number of muted audio frames to play before normal
2238 audio resumes. (This is not implemented in the firmware, leave at 0)
2239
2240
2241
2242 CX2341X_DEC_STOP_PLAYBACK
2243 ~~~~~~~~~~~~~~~~~~~~~~~~~
2244
2245 Enum: 2/0x02
2246
2247 Description
2248 ^^^^^^^^^^^
2249
2250 Ends playback and clears all decoder buffers. If PTS is not zero,
2251 playback stops at specified PTS.
2252
2253 Param[0]
2254 ^^^^^^^^
2255
2256 Display 0=last frame, 1=black
2257
2258 .. note::
2259
2260         this takes effect immediately, so if you want to wait for a PTS,
2261         then use '0', otherwise the screen goes to black at once.
2262         You can call this later (even if there is no playback) with a 1 value
2263         to set the screen to black.
2264
2265 Param[1]
2266 ^^^^^^^^
2267
2268 PTS low
2269
2270 Param[2]
2271 ^^^^^^^^
2272
2273 PTS high
2274
2275
2276
2277 CX2341X_DEC_SET_PLAYBACK_SPEED
2278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2279
2280 Enum: 3/0x03
2281
2282 Description
2283 ^^^^^^^^^^^
2284
2285 Playback stream at speed other than normal. There are two modes of
2286 operation:
2287
2288         - Smooth: host transfers entire stream and firmware drops unused
2289           frames.
2290         - Coarse: host drops frames based on indexing as required to achieve
2291           desired speed.
2292
2293 Param[0]
2294 ^^^^^^^^
2295
2296 .. code-block:: none
2297
2298         Bitmap:
2299             0:7  0 normal
2300                  1 fast only "1.5 times"
2301                  n nX fast, 1/nX slow
2302             30   Framedrop:
2303                      '0' during 1.5 times play, every other B frame is dropped
2304                      '1' during 1.5 times play, stream is unchanged (bitrate
2305                          must not exceed 8mbps)
2306             31   Speed:
2307                      '0' slow
2308                      '1' fast
2309
2310 .. note::
2311
2312         n is limited to 2. Anything higher does not result in
2313         faster playback. Instead the host should start dropping frames.
2314
2315 Param[1]
2316 ^^^^^^^^
2317
2318 Direction: 0=forward, 1=reverse
2319
2320 .. note::
2321
2322         to make reverse playback work you have to write full GOPs in
2323         reverse order.
2324
2325 Param[2]
2326 ^^^^^^^^
2327
2328 .. code-block:: none
2329
2330         Picture mask:
2331             1=I frames
2332             3=I, P frames
2333             7=I, P, B frames
2334
2335 Param[3]
2336 ^^^^^^^^
2337
2338 B frames per GOP (for reverse play only)
2339
2340 .. note::
2341
2342         for reverse playback the Picture Mask should be set to I or I, P.
2343         Adding B frames to the mask will result in corrupt video. This field
2344         has to be set to the correct value in order to keep the timing correct.
2345
2346 Param[4]
2347 ^^^^^^^^
2348
2349 Mute audio: 0=disable, 1=enable
2350
2351 Param[5]
2352 ^^^^^^^^
2353
2354 Display 0=frame, 1=field
2355
2356 Param[6]
2357 ^^^^^^^^
2358
2359 Specifies the number of muted audio frames to play before normal audio
2360 resumes. (Not implemented in the firmware, leave at 0)
2361
2362
2363
2364 CX2341X_DEC_STEP_VIDEO
2365 ~~~~~~~~~~~~~~~~~~~~~~
2366
2367 Enum: 5/0x05
2368
2369 Description
2370 ^^^^^^^^^^^
2371
2372 Each call to this API steps the playback to the next unit defined below
2373 in the current playback direction.
2374
2375 Param[0]
2376 ^^^^^^^^
2377
2378 0=frame, 1=top field, 2=bottom field
2379
2380
2381
2382 CX2341X_DEC_SET_DMA_BLOCK_SIZE
2383 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2384
2385 Enum: 8/0x08
2386
2387 Description
2388 ^^^^^^^^^^^
2389
2390 Set DMA transfer block size. Counterpart to API 0xC9
2391
2392 Param[0]
2393 ^^^^^^^^
2394
2395 DMA transfer block size in bytes. A different size may be specified
2396 when issuing the DMA transfer command.
2397
2398
2399
2400 CX2341X_DEC_GET_XFER_INFO
2401 ~~~~~~~~~~~~~~~~~~~~~~~~~
2402
2403 Enum: 9/0x09
2404
2405 Description
2406 ^^^^^^^^^^^
2407
2408 This API call may be used to detect an end of stream condition.
2409
2410 Result[0]
2411 ^^^^^^^^^
2412
2413 Stream type
2414
2415 Result[1]
2416 ^^^^^^^^^
2417
2418 Address offset
2419
2420 Result[2]
2421 ^^^^^^^^^
2422
2423 Maximum bytes to transfer
2424
2425 Result[3]
2426 ^^^^^^^^^
2427
2428 Buffer fullness
2429
2430
2431
2432 CX2341X_DEC_GET_DMA_STATUS
2433 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2434
2435 Enum: 10/0x0A
2436
2437 Description
2438 ^^^^^^^^^^^
2439
2440 Status of the last DMA transfer
2441
2442 Result[0]
2443 ^^^^^^^^^
2444
2445 Bit 1 set means transfer complete
2446 Bit 2 set means DMA error
2447 Bit 3 set means linked list error
2448
2449 Result[1]
2450 ^^^^^^^^^
2451
2452 DMA type: 0=MPEG, 1=OSD, 2=YUV
2453
2454
2455
2456 CX2341X_DEC_SCHED_DMA_FROM_HOST
2457 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2458
2459 Enum: 11/0x0B
2460
2461 Description
2462 ^^^^^^^^^^^
2463
2464 Setup DMA from host operation. Counterpart to API 0xCC
2465
2466 Param[0]
2467 ^^^^^^^^
2468
2469 Memory address of link list
2470
2471 Param[1]
2472 ^^^^^^^^
2473
2474 Total # of bytes to transfer
2475
2476 Param[2]
2477 ^^^^^^^^
2478
2479 DMA type (0=MPEG, 1=OSD, 2=YUV)
2480
2481
2482
2483 CX2341X_DEC_PAUSE_PLAYBACK
2484 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2485
2486 Enum: 13/0x0D
2487
2488 Description
2489 ^^^^^^^^^^^
2490
2491 Freeze playback immediately. In this mode, when internal buffers are
2492 full, no more data will be accepted and data request IRQs will be
2493 masked.
2494
2495 Param[0]
2496 ^^^^^^^^
2497
2498 Display: 0=last frame, 1=black
2499
2500
2501
2502 CX2341X_DEC_HALT_FW
2503 ~~~~~~~~~~~~~~~~~~~
2504
2505 Enum: 14/0x0E
2506
2507 Description
2508 ^^^^^^^^^^^
2509
2510 The firmware is halted and no further API calls are serviced until
2511 the firmware is uploaded again.
2512
2513
2514
2515 CX2341X_DEC_SET_STANDARD
2516 ~~~~~~~~~~~~~~~~~~~~~~~~
2517
2518 Enum: 16/0x10
2519
2520 Description
2521 ^^^^^^^^^^^
2522
2523 Selects display standard
2524
2525 Param[0]
2526 ^^^^^^^^
2527
2528 0=NTSC, 1=PAL
2529
2530
2531
2532 CX2341X_DEC_GET_VERSION
2533 ~~~~~~~~~~~~~~~~~~~~~~~
2534
2535 Enum: 17/0x11
2536
2537 Description
2538 ^^^^^^^^^^^
2539
2540 Returns decoder firmware version information
2541
2542 Result[0]
2543 ^^^^^^^^^
2544
2545 Version bitmask:
2546         - Bits  0:15 build
2547         - Bits 16:23 minor
2548         - Bits 24:31 major
2549
2550
2551
2552 CX2341X_DEC_SET_STREAM_INPUT
2553 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2554
2555 Enum: 20/0x14
2556
2557 Description
2558 ^^^^^^^^^^^
2559
2560 Select decoder stream input port
2561
2562 Param[0]
2563 ^^^^^^^^
2564
2565 0=memory (default), 1=streaming
2566
2567
2568
2569 CX2341X_DEC_GET_TIMING_INFO
2570 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2571
2572 Enum: 21/0x15
2573
2574 Description
2575 ^^^^^^^^^^^
2576
2577 Returns timing information from start of playback
2578
2579 Result[0]
2580 ^^^^^^^^^
2581
2582 Frame count by decode order
2583
2584 Result[1]
2585 ^^^^^^^^^
2586
2587 Video PTS bits 0:31 by display order
2588
2589 Result[2]
2590 ^^^^^^^^^
2591
2592 Video PTS bit 32 by display order
2593
2594 Result[3]
2595 ^^^^^^^^^
2596
2597 SCR bits 0:31 by display order
2598
2599 Result[4]
2600 ^^^^^^^^^
2601
2602 SCR bit 32 by display order
2603
2604
2605
2606 CX2341X_DEC_SET_AUDIO_MODE
2607 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2608
2609 Enum: 22/0x16
2610
2611 Description
2612 ^^^^^^^^^^^
2613
2614 Select audio mode
2615
2616 Param[0]
2617 ^^^^^^^^
2618
2619 Dual mono mode action
2620         0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
2621
2622 Param[1]
2623 ^^^^^^^^
2624
2625 Stereo mode action:
2626         0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
2627
2628
2629
2630 CX2341X_DEC_SET_EVENT_NOTIFICATION
2631 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2632
2633 Enum: 23/0x17
2634
2635 Description
2636 ^^^^^^^^^^^
2637
2638 Setup firmware to notify the host about a particular event.
2639 Counterpart to API 0xD5
2640
2641 Param[0]
2642 ^^^^^^^^
2643
2644 Event:
2645         - 0=Audio mode change between mono, (joint) stereo and dual channel.
2646         - 3=Decoder started
2647         - 4=Unknown: goes off 10-15 times per second while decoding.
2648         - 5=Some sync event: goes off once per frame.
2649
2650 Param[1]
2651 ^^^^^^^^
2652
2653 Notification 0=disabled, 1=enabled
2654
2655 Param[2]
2656 ^^^^^^^^
2657
2658 Interrupt bit
2659
2660 Param[3]
2661 ^^^^^^^^
2662
2663 Mailbox slot, -1 if no mailbox required.
2664
2665
2666
2667 CX2341X_DEC_SET_DISPLAY_BUFFERS
2668 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2669
2670 Enum: 24/0x18
2671
2672 Description
2673 ^^^^^^^^^^^
2674
2675 Number of display buffers. To decode all frames in reverse playback you
2676 must use nine buffers.
2677
2678 Param[0]
2679 ^^^^^^^^
2680
2681 0=six buffers, 1=nine buffers
2682
2683
2684
2685 CX2341X_DEC_EXTRACT_VBI
2686 ~~~~~~~~~~~~~~~~~~~~~~~
2687
2688 Enum: 25/0x19
2689
2690 Description
2691 ^^^^^^^^^^^
2692
2693 Extracts VBI data
2694
2695 Param[0]
2696 ^^^^^^^^
2697
2698 0=extract from extension & user data, 1=extract from private packets
2699
2700 Result[0]
2701 ^^^^^^^^^
2702
2703 VBI table location
2704
2705 Result[1]
2706 ^^^^^^^^^
2707
2708 VBI table size
2709
2710
2711
2712 CX2341X_DEC_SET_DECODER_SOURCE
2713 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2714
2715 Enum: 26/0x1A
2716
2717 Description
2718 ^^^^^^^^^^^
2719
2720 Selects decoder source. Ensure that the parameters passed to this
2721 API match the encoder settings.
2722
2723 Param[0]
2724 ^^^^^^^^
2725
2726 Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host
2727
2728 Param[1]
2729 ^^^^^^^^
2730
2731 YUV picture width
2732
2733 Param[2]
2734 ^^^^^^^^
2735
2736 YUV picture height
2737
2738 Param[3]
2739 ^^^^^^^^
2740
2741 Bitmap: see Param[0] of API 0xBD
2742
2743
2744
2745 CX2341X_DEC_SET_PREBUFFERING
2746 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2747
2748 Enum: 30/0x1E
2749
2750 Description
2751 ^^^^^^^^^^^
2752
2753 Decoder prebuffering, when enabled up to 128KB are buffered for
2754 streams <8mpbs or 640KB for streams >8mbps
2755
2756 Param[0]
2757 ^^^^^^^^
2758
2759 0=off, 1=on
2760
2761 PVR350 Video decoder registers 0x02002800 -> 0x02002B00
2762 -------------------------------------------------------
2763
2764 Author: Ian Armstrong <ian@iarmst.demon.co.uk>
2765
2766 Version: v0.4
2767
2768 Date: 12 March 2007
2769
2770
2771 This list has been worked out through trial and error. There will be mistakes
2772 and omissions. Some registers have no obvious effect so it's hard to say what
2773 they do, while others interact with each other, or require a certain load
2774 sequence. Horizontal filter setup is one example, with six registers working
2775 in unison and requiring a certain load sequence to correctly configure. The
2776 indexed colour palette is much easier to set at just two registers, but again
2777 it requires a certain load sequence.
2778
2779 Some registers are fussy about what they are set to. Load in a bad value & the
2780 decoder will fail. A firmware reload will often recover, but sometimes a reset
2781 is required. For registers containing size information, setting them to 0 is
2782 generally a bad idea. For other control registers i.e. 2878, you'll only find
2783 out what values are bad when it hangs.
2784
2785 .. code-block:: none
2786
2787         --------------------------------------------------------------------------------
2788         2800
2789         bit 0
2790                 Decoder enable
2791                 0 = disable
2792                 1 = enable
2793         --------------------------------------------------------------------------------
2794         2804
2795         bits 0:31
2796                 Decoder horizontal Y alias register 1
2797         ---------------
2798         2808
2799         bits 0:31
2800                 Decoder horizontal Y alias register 2
2801         ---------------
2802         280C
2803         bits 0:31
2804                 Decoder horizontal Y alias register 3
2805         ---------------
2806         2810
2807         bits 0:31
2808                 Decoder horizontal Y alias register 4
2809         ---------------
2810         2814
2811         bits 0:31
2812                 Decoder horizontal Y alias register 5
2813         ---------------
2814         2818
2815         bits 0:31
2816                 Decoder horizontal Y alias trigger
2817
2818         These six registers control the horizontal aliasing filter for the Y plane.
2819         The first five registers must all be loaded before accessing the trigger
2820         (2818), as this register actually clocks the data through for the first
2821         five.
2822
2823         To correctly program set the filter, this whole procedure must be done 16
2824         times. The actual register contents are copied from a lookup-table in the
2825         firmware which contains 4 different filter settings.
2826
2827         --------------------------------------------------------------------------------
2828         281C
2829         bits 0:31
2830                 Decoder horizontal UV alias register 1
2831         ---------------
2832         2820
2833         bits 0:31
2834                 Decoder horizontal UV alias register 2
2835         ---------------
2836         2824
2837         bits 0:31
2838                 Decoder horizontal UV alias register 3
2839         ---------------
2840         2828
2841         bits 0:31
2842                 Decoder horizontal UV alias register 4
2843         ---------------
2844         282C
2845         bits 0:31
2846                 Decoder horizontal UV alias register 5
2847         ---------------
2848         2830
2849         bits 0:31
2850                 Decoder horizontal UV alias trigger
2851
2852         These six registers control the horizontal aliasing for the UV plane.
2853         Operation is the same as the Y filter, with 2830 being the trigger
2854         register.
2855
2856         --------------------------------------------------------------------------------
2857         2834
2858         bits 0:15
2859                 Decoder Y source width in pixels
2860
2861         bits 16:31
2862                 Decoder Y destination width in pixels
2863         ---------------
2864         2838
2865         bits 0:15
2866                 Decoder UV source width in pixels
2867
2868         bits 16:31
2869                 Decoder UV destination width in pixels
2870
2871         NOTE: For both registers, the resulting image must be fully visible on
2872         screen. If the image exceeds the right edge both the source and destination
2873         size must be adjusted to reflect the visible portion. For the source width,
2874         you must take into account the scaling when calculating the new value.
2875         --------------------------------------------------------------------------------
2876
2877         283C
2878         bits 0:31
2879                 Decoder Y horizontal scaling
2880                         Normally = Reg 2854 >> 2
2881         ---------------
2882         2840
2883         bits 0:31
2884                 Decoder ?? unknown - horizontal scaling
2885                 Usually 0x00080514
2886         ---------------
2887         2844
2888         bits 0:31
2889                 Decoder UV horizontal scaling
2890                 Normally = Reg 2854 >> 2
2891         ---------------
2892         2848
2893         bits 0:31
2894                 Decoder ?? unknown - horizontal scaling
2895                 Usually 0x00100514
2896         ---------------
2897         284C
2898         bits 0:31
2899                 Decoder ?? unknown - Y plane
2900                 Usually 0x00200020
2901         ---------------
2902         2850
2903         bits 0:31
2904                 Decoder ?? unknown - UV plane
2905                 Usually 0x00200020
2906         ---------------
2907         2854
2908         bits 0:31
2909                 Decoder 'master' value for horizontal scaling
2910         ---------------
2911         2858
2912         bits 0:31
2913                 Decoder ?? unknown
2914                 Usually 0
2915         ---------------
2916         285C
2917         bits 0:31
2918                 Decoder ?? unknown
2919                 Normally = Reg 2854 >> 1
2920         ---------------
2921         2860
2922         bits 0:31
2923                 Decoder ?? unknown
2924                 Usually 0
2925         ---------------
2926         2864
2927         bits 0:31
2928                 Decoder ?? unknown
2929                 Normally = Reg 2854 >> 1
2930         ---------------
2931         2868
2932         bits 0:31
2933                 Decoder ?? unknown
2934                 Usually 0
2935
2936         Most of these registers either control horizontal scaling, or appear linked
2937         to it in some way. Register 2854 contains the 'master' value & the other
2938         registers can be calculated from that one. You must also remember to
2939         correctly set the divider in Reg 2874.
2940
2941         To enlarge:
2942                 Reg 2854 = (source_width * 0x00200000) / destination_width
2943                 Reg 2874 = No divide
2944
2945         To reduce from full size down to half size:
2946                 Reg 2854 = (source_width/2 * 0x00200000) / destination width
2947                 Reg 2874 = Divide by 2
2948
2949         To reduce from half size down to quarter size:
2950                 Reg 2854 = (source_width/4 * 0x00200000) / destination width
2951                 Reg 2874 = Divide by 4
2952
2953         The result is always rounded up.
2954
2955         --------------------------------------------------------------------------------
2956         286C
2957         bits 0:15
2958                 Decoder horizontal Y buffer offset
2959
2960         bits 15:31
2961                 Decoder horizontal UV buffer offset
2962
2963         Offset into the video image buffer. If the offset is gradually incremented,
2964         the on screen image will move left & wrap around higher up on the right.
2965
2966         --------------------------------------------------------------------------------
2967         2870
2968         bits 0:15
2969                 Decoder horizontal Y output offset
2970
2971         bits 16:31
2972                 Decoder horizontal UV output offset
2973
2974         Offsets the actual video output. Controls output alignment of the Y & UV
2975         planes. The higher the value, the greater the shift to the left. Use
2976         reg 2890 to move the image right.
2977
2978         --------------------------------------------------------------------------------
2979         2874
2980         bits 0:1
2981                 Decoder horizontal Y output size divider
2982                 00 = No divide
2983                 01 = Divide by 2
2984                 10 = Divide by 3
2985
2986         bits 4:5
2987                 Decoder horizontal UV output size divider
2988                 00 = No divide
2989                 01 = Divide by 2
2990                 10 = Divide by 3
2991
2992         bit 8
2993                 Decoder ?? unknown
2994                 0 = Normal
2995                 1 = Affects video output levels
2996
2997         bit 16
2998                 Decoder ?? unknown
2999                 0 = Normal
3000                 1 = Disable horizontal filter
3001
3002         --------------------------------------------------------------------------------
3003         2878
3004         bit 0
3005                 ?? unknown
3006
3007         bit 1
3008                 osd on/off
3009                 0 = osd off
3010                 1 = osd on
3011
3012         bit 2
3013                 Decoder + osd video timing
3014                 0 = NTSC
3015                 1 = PAL
3016
3017         bits 3:4
3018                 ?? unknown
3019
3020         bit 5
3021                 Decoder + osd
3022                 Swaps upper & lower fields
3023
3024         --------------------------------------------------------------------------------
3025         287C
3026         bits 0:10
3027                 Decoder & osd ?? unknown
3028                 Moves entire screen horizontally. Starts at 0x005 with the screen
3029                 shifted heavily to the right. Incrementing in steps of 0x004 will
3030                 gradually shift the screen to the left.
3031
3032         bits 11:31
3033                 ?? unknown
3034
3035         Normally contents are 0x00101111 (NTSC) or 0x1010111d (PAL)
3036
3037         --------------------------------------------------------------------------------
3038         2880  --------    ?? unknown
3039         2884  --------    ?? unknown
3040         --------------------------------------------------------------------------------
3041         2888
3042         bit 0
3043                 Decoder + osd ?? unknown
3044                 0 = Normal
3045                 1 = Misaligned fields (Correctable through 289C & 28A4)
3046
3047         bit 4
3048                 ?? unknown
3049
3050         bit 8
3051                 ?? unknown
3052
3053         Warning: Bad values will require a firmware reload to recover.
3054                         Known to be bad are 0x000,0x011,0x100,0x111
3055         --------------------------------------------------------------------------------
3056         288C
3057         bits 0:15
3058                 osd ?? unknown
3059                 Appears to affect the osd position stability. The higher the value the
3060                 more unstable it becomes. Decoder output remains stable.
3061
3062         bits 16:31
3063                 osd ?? unknown
3064                 Same as bits 0:15
3065
3066         --------------------------------------------------------------------------------
3067         2890
3068         bits 0:11
3069                 Decoder output horizontal offset.
3070
3071         Horizontal offset moves the video image right. A small left shift is
3072         possible, but it's better to use reg 2870 for that due to its greater
3073         range.
3074
3075         NOTE: Video corruption will occur if video window is shifted off the right
3076         edge. To avoid this read the notes for 2834 & 2838.
3077         --------------------------------------------------------------------------------
3078         2894
3079         bits 0:23
3080                 Decoder output video surround colour.
3081
3082         Contains the colour (in yuv) used to fill the screen when the video is
3083         running in a window.
3084         --------------------------------------------------------------------------------
3085         2898
3086         bits 0:23
3087                 Decoder video window colour
3088                 Contains the colour (in yuv) used to fill the video window when the
3089                 video is turned off.
3090
3091         bit 24
3092                 Decoder video output
3093                 0 = Video on
3094                 1 = Video off
3095
3096         bit 28
3097                 Decoder plane order
3098                 0 = Y,UV
3099                 1 = UV,Y
3100
3101         bit 29
3102                 Decoder second plane byte order
3103                 0 = Normal (UV)
3104                 1 = Swapped (VU)
3105
3106         In normal usage, the first plane is Y & the second plane is UV. Though the
3107         order of the planes can be swapped, only the byte order of the second plane
3108         can be swapped. This isn't much use for the Y plane, but can be useful for
3109         the UV plane.
3110
3111         --------------------------------------------------------------------------------
3112         289C
3113         bits 0:15
3114                 Decoder vertical field offset 1
3115
3116         bits 16:31
3117                 Decoder vertical field offset 2
3118
3119         Controls field output vertical alignment. The higher the number, the lower
3120         the image on screen. Known starting values are 0x011E0017 (NTSC) &
3121         0x01500017 (PAL)
3122         --------------------------------------------------------------------------------
3123         28A0
3124         bits 0:15
3125                 Decoder & osd width in pixels
3126
3127         bits 16:31
3128                 Decoder & osd height in pixels
3129
3130         All output from the decoder & osd are disabled beyond this area. Decoder
3131         output will simply go black outside of this region. If the osd tries to
3132         exceed this area it will become corrupt.
3133         --------------------------------------------------------------------------------
3134         28A4
3135         bits 0:11
3136                 osd left shift.
3137
3138         Has a range of 0x770->0x7FF. With the exception of 0, any value outside of
3139         this range corrupts the osd.
3140         --------------------------------------------------------------------------------
3141         28A8
3142         bits 0:15
3143                 osd vertical field offset 1
3144
3145         bits 16:31
3146                 osd vertical field offset 2
3147
3148         Controls field output vertical alignment. The higher the number, the lower
3149         the image on screen. Known starting values are 0x011E0017 (NTSC) &
3150         0x01500017 (PAL)
3151         --------------------------------------------------------------------------------
3152         28AC  --------    ?? unknown
3153         |
3154         V
3155         28BC  --------    ?? unknown
3156         --------------------------------------------------------------------------------
3157         28C0
3158         bit 0
3159                 Current output field
3160                 0 = first field
3161                 1 = second field
3162
3163         bits 16:31
3164                 Current scanline
3165                 The scanline counts from the top line of the first field
3166                 through to the last line of the second field.
3167         --------------------------------------------------------------------------------
3168         28C4  --------    ?? unknown
3169         |
3170         V
3171         28F8  --------    ?? unknown
3172         --------------------------------------------------------------------------------
3173         28FC
3174         bit 0
3175                 ?? unknown
3176                 0 = Normal
3177                 1 = Breaks decoder & osd output
3178         --------------------------------------------------------------------------------
3179         2900
3180         bits 0:31
3181                 Decoder vertical Y alias register 1
3182         ---------------
3183         2904
3184         bits 0:31
3185                 Decoder vertical Y alias register 2
3186         ---------------
3187         2908
3188         bits 0:31
3189                 Decoder vertical Y alias trigger
3190
3191         These three registers control the vertical aliasing filter for the Y plane.
3192         Operation is similar to the horizontal Y filter (2804). The only real
3193         difference is that there are only two registers to set before accessing
3194         the trigger register (2908). As for the horizontal filter, the values are
3195         taken from a lookup table in the firmware, and the procedure must be
3196         repeated 16 times to fully program the filter.
3197         --------------------------------------------------------------------------------
3198         290C
3199         bits 0:31
3200                 Decoder vertical UV alias register 1
3201         ---------------
3202         2910
3203         bits 0:31
3204                 Decoder vertical UV alias register 2
3205         ---------------
3206         2914
3207         bits 0:31
3208                 Decoder vertical UV alias trigger
3209
3210         These three registers control the vertical aliasing filter for the UV
3211         plane. Operation is the same as the Y filter, with 2914 being the trigger.
3212         --------------------------------------------------------------------------------
3213         2918
3214         bits 0:15
3215                 Decoder Y source height in pixels
3216
3217         bits 16:31
3218                 Decoder Y destination height in pixels
3219         ---------------
3220         291C
3221         bits 0:15
3222                 Decoder UV source height in pixels divided by 2
3223
3224         bits 16:31
3225                 Decoder UV destination height in pixels
3226
3227         NOTE: For both registers, the resulting image must be fully visible on
3228         screen. If the image exceeds the bottom edge both the source and
3229         destination size must be adjusted to reflect the visible portion. For the
3230         source height, you must take into account the scaling when calculating the
3231         new value.
3232         --------------------------------------------------------------------------------
3233         2920
3234         bits 0:31
3235                 Decoder Y vertical scaling
3236                 Normally = Reg 2930 >> 2
3237         ---------------
3238         2924
3239         bits 0:31
3240                 Decoder Y vertical scaling
3241                 Normally = Reg 2920 + 0x514
3242         ---------------
3243         2928
3244         bits 0:31
3245                 Decoder UV vertical scaling
3246                 When enlarging = Reg 2930 >> 2
3247                 When reducing = Reg 2930 >> 3
3248         ---------------
3249         292C
3250         bits 0:31
3251                 Decoder UV vertical scaling
3252                 Normally = Reg 2928 + 0x514
3253         ---------------
3254         2930
3255         bits 0:31
3256                 Decoder 'master' value for vertical scaling
3257         ---------------
3258         2934
3259         bits 0:31
3260                 Decoder ?? unknown - Y vertical scaling
3261         ---------------
3262         2938
3263         bits 0:31
3264                 Decoder Y vertical scaling
3265                 Normally = Reg 2930
3266         ---------------
3267         293C
3268         bits 0:31
3269                 Decoder ?? unknown - Y vertical scaling
3270         ---------------
3271         2940
3272         bits 0:31
3273                 Decoder UV vertical scaling
3274                 When enlarging = Reg 2930 >> 1
3275                 When reducing = Reg 2930
3276         ---------------
3277         2944
3278         bits 0:31
3279                 Decoder ?? unknown - UV vertical scaling
3280         ---------------
3281         2948
3282         bits 0:31
3283                 Decoder UV vertical scaling
3284                 Normally = Reg 2940
3285         ---------------
3286         294C
3287         bits 0:31
3288                 Decoder ?? unknown - UV vertical scaling
3289
3290         Most of these registers either control vertical scaling, or appear linked
3291         to it in some way. Register 2930 contains the 'master' value & all other
3292         registers can be calculated from that one. You must also remember to
3293         correctly set the divider in Reg 296C
3294
3295         To enlarge:
3296                 Reg 2930 = (source_height * 0x00200000) / destination_height
3297                 Reg 296C = No divide
3298
3299         To reduce from full size down to half size:
3300                 Reg 2930 = (source_height/2 * 0x00200000) / destination height
3301                 Reg 296C = Divide by 2
3302
3303         To reduce from half down to quarter.
3304                 Reg 2930 = (source_height/4 * 0x00200000) / destination height
3305                 Reg 296C = Divide by 4
3306
3307         --------------------------------------------------------------------------------
3308         2950
3309         bits 0:15
3310                 Decoder Y line index into display buffer, first field
3311
3312         bits 16:31
3313                 Decoder Y vertical line skip, first field
3314         --------------------------------------------------------------------------------
3315         2954
3316         bits 0:15
3317                 Decoder Y line index into display buffer, second field
3318
3319         bits 16:31
3320                 Decoder Y vertical line skip, second field
3321         --------------------------------------------------------------------------------
3322         2958
3323         bits 0:15
3324                 Decoder UV line index into display buffer, first field
3325
3326         bits 16:31
3327                 Decoder UV vertical line skip, first field
3328         --------------------------------------------------------------------------------
3329         295C
3330         bits 0:15
3331                 Decoder UV line index into display buffer, second field
3332
3333         bits 16:31
3334                 Decoder UV vertical line skip, second field
3335         --------------------------------------------------------------------------------
3336         2960
3337         bits 0:15
3338                 Decoder destination height minus 1
3339
3340         bits 16:31
3341                 Decoder destination height divided by 2
3342         --------------------------------------------------------------------------------
3343         2964
3344         bits 0:15
3345                 Decoder Y vertical offset, second field
3346
3347         bits 16:31
3348                 Decoder Y vertical offset, first field
3349
3350         These two registers shift the Y plane up. The higher the number, the
3351         greater the shift.
3352         --------------------------------------------------------------------------------
3353         2968
3354         bits 0:15
3355                 Decoder UV vertical offset, second field
3356
3357         bits 16:31
3358                 Decoder UV vertical offset, first field
3359
3360         These two registers shift the UV plane up. The higher the number, the
3361         greater the shift.
3362         --------------------------------------------------------------------------------
3363         296C
3364         bits 0:1
3365                 Decoder vertical Y output size divider
3366                 00 = No divide
3367                 01 = Divide by 2
3368                 10 = Divide by 4
3369
3370         bits 8:9
3371                 Decoder vertical UV output size divider
3372                 00 = No divide
3373                 01 = Divide by 2
3374                 10 = Divide by 4
3375         --------------------------------------------------------------------------------
3376         2970
3377         bit 0
3378                 Decoder ?? unknown
3379                 0 = Normal
3380                 1 = Affect video output levels
3381
3382         bit 16
3383                 Decoder ?? unknown
3384                 0 = Normal
3385                 1 = Disable vertical filter
3386
3387         --------------------------------------------------------------------------------
3388         2974  --------   ?? unknown
3389         |
3390         V
3391         29EF  --------   ?? unknown
3392         --------------------------------------------------------------------------------
3393         2A00
3394         bits 0:2
3395                 osd colour mode
3396                 000 = 8 bit indexed
3397                 001 = 16 bit (565)
3398                 010 = 15 bit (555)
3399                 011 = 12 bit (444)
3400                 100 = 32 bit (8888)
3401
3402         bits 4:5
3403                 osd display bpp
3404                 01 = 8 bit
3405                 10 = 16 bit
3406                 11 = 32 bit
3407
3408         bit 8
3409                 osd global alpha
3410                 0 = Off
3411                 1 = On
3412
3413         bit 9
3414                 osd local alpha
3415                 0 = Off
3416                 1 = On
3417
3418         bit 10
3419                 osd colour key
3420                 0 = Off
3421                 1 = On
3422
3423         bit 11
3424                 osd ?? unknown
3425                 Must be 1
3426
3427         bit 13
3428                 osd colour space
3429                 0 = ARGB
3430                 1 = AYVU
3431
3432         bits 16:31
3433                 osd ?? unknown
3434                 Must be 0x001B (some kind of buffer pointer ?)
3435
3436         When the bits-per-pixel is set to 8, the colour mode is ignored and
3437         assumed to be 8 bit indexed. For 16 & 32 bits-per-pixel the colour depth
3438         is honoured, and when using a colour depth that requires fewer bytes than
3439         allocated the extra bytes are used as padding. So for a 32 bpp with 8 bit
3440         index colour, there are 3 padding bytes per pixel. It's also possible to
3441         select 16bpp with a 32 bit colour mode. This results in the pixel width
3442         being doubled, but the color key will not work as expected in this mode.
3443
3444         Colour key is as it suggests. You designate a colour which will become
3445         completely transparent. When using 565, 555 or 444 colour modes, the
3446         colour key is always 16 bits wide. The colour to key on is set in Reg 2A18.
3447
3448         Local alpha works differently depending on the colour mode. For 32bpp & 8
3449         bit indexed, local alpha is a per-pixel 256 step transparency, with 0 being
3450         transparent and 255 being solid. For the 16bpp modes 555 & 444, the unused
3451         bit(s) act as a simple transparency switch, with 0 being solid & 1 being
3452         fully transparent. There is no local alpha support for 16bit 565.
3453
3454         Global alpha is a 256 step transparency that applies to the entire osd,
3455         with 0 being transparent & 255 being solid.
3456
3457         It's possible to combine colour key, local alpha & global alpha.
3458         --------------------------------------------------------------------------------
3459         2A04
3460         bits 0:15
3461                 osd x coord for left edge
3462
3463         bits 16:31
3464                 osd y coord for top edge
3465         ---------------
3466         2A08
3467         bits 0:15
3468                 osd x coord for right edge
3469
3470         bits 16:31
3471                 osd y coord for bottom edge
3472
3473         For both registers, (0,0) = top left corner of the display area. These
3474         registers do not control the osd size, only where it's positioned & how
3475         much is visible. The visible osd area cannot exceed the right edge of the
3476         display, otherwise the osd will become corrupt. See reg 2A10 for
3477         setting osd width.
3478         --------------------------------------------------------------------------------
3479         2A0C
3480         bits 0:31
3481                 osd buffer index
3482
3483         An index into the osd buffer. Slowly incrementing this moves the osd left,
3484         wrapping around onto the right edge
3485         --------------------------------------------------------------------------------
3486         2A10
3487         bits 0:11
3488                 osd buffer 32 bit word width
3489
3490         Contains the width of the osd measured in 32 bit words. This means that all
3491         colour modes are restricted to a byte width which is divisible by 4.
3492         --------------------------------------------------------------------------------
3493         2A14
3494         bits 0:15
3495                 osd height in pixels
3496
3497         bits 16:32
3498                 osd line index into buffer
3499                 osd will start displaying from this line.
3500         --------------------------------------------------------------------------------
3501         2A18
3502         bits 0:31
3503                 osd colour key
3504
3505         Contains the colour value which will be transparent.
3506         --------------------------------------------------------------------------------
3507         2A1C
3508         bits 0:7
3509                 osd global alpha
3510
3511         Contains the global alpha value (equiv ivtvfbctl --alpha XX)
3512         --------------------------------------------------------------------------------
3513         2A20  --------    ?? unknown
3514         |
3515         V
3516         2A2C  --------    ?? unknown
3517         --------------------------------------------------------------------------------
3518         2A30
3519         bits 0:7
3520                 osd colour to change in indexed palette
3521         ---------------
3522         2A34
3523         bits 0:31
3524                 osd colour for indexed palette
3525
3526         To set the new palette, first load the index of the colour to change into
3527         2A30, then load the new colour into 2A34. The full palette is 256 colours,
3528         so the index range is 0x00-0xFF
3529         --------------------------------------------------------------------------------
3530         2A38  --------    ?? unknown
3531         2A3C  --------    ?? unknown
3532         --------------------------------------------------------------------------------
3533         2A40
3534         bits 0:31
3535                 osd ?? unknown
3536
3537         Affects overall brightness, wrapping around to black
3538         --------------------------------------------------------------------------------
3539         2A44
3540         bits 0:31
3541                 osd ?? unknown
3542
3543         Green tint
3544         --------------------------------------------------------------------------------
3545         2A48
3546         bits 0:31
3547                 osd ?? unknown
3548
3549         Red tint
3550         --------------------------------------------------------------------------------
3551         2A4C
3552         bits 0:31
3553                 osd ?? unknown
3554
3555         Affects overall brightness, wrapping around to black
3556         --------------------------------------------------------------------------------
3557         2A50
3558         bits 0:31
3559                 osd ?? unknown
3560
3561         Colour shift
3562         --------------------------------------------------------------------------------
3563         2A54
3564         bits 0:31
3565                 osd ?? unknown
3566
3567         Colour shift
3568         --------------------------------------------------------------------------------
3569         2A58  --------    ?? unknown
3570         |
3571         V
3572         2AFC  --------    ?? unknown
3573         --------------------------------------------------------------------------------
3574         2B00
3575         bit 0
3576                 osd filter control
3577                 0 = filter off
3578                 1 = filter on
3579
3580         bits 1:4
3581                 osd ?? unknown
3582
3583         --------------------------------------------------------------------------------
3584
3585 The cx231xx DMA engine
3586 ----------------------
3587
3588
3589 This page describes the structures and procedures used by the cx2341x DMA
3590 engine.
3591
3592 Introduction
3593 ~~~~~~~~~~~~
3594
3595 The cx2341x PCI interface is busmaster capable. This means it has a DMA
3596 engine to efficiently transfer large volumes of data between the card and main
3597 memory without requiring help from a CPU. Like most hardware, it must operate
3598 on contiguous physical memory. This is difficult to come by in large quantities
3599 on virtual memory machines.
3600
3601 Therefore, it also supports a technique called "scatter-gather". The card can
3602 transfer multiple buffers in one operation. Instead of allocating one large
3603 contiguous buffer, the driver can allocate several smaller buffers.
3604
3605 In practice, I've seen the average transfer to be roughly 80K, but transfers
3606 above 128K were not uncommon, particularly at startup. The 128K figure is
3607 important, because that is the largest block that the kernel can normally
3608 allocate. Even still, 128K blocks are hard to come by, so the driver writer is
3609 urged to choose a smaller block size and learn the scatter-gather technique.
3610
3611 Mailbox #10 is reserved for DMA transfer information.
3612
3613 Note: the hardware expects little-endian data ('intel format').
3614
3615 Flow
3616 ~~~~
3617
3618 This section describes, in general, the order of events when handling DMA
3619 transfers. Detailed information follows this section.
3620
3621 - The card raises the Encoder interrupt.
3622 - The driver reads the transfer type, offset and size from Mailbox #10.
3623 - The driver constructs the scatter-gather array from enough free dma buffers
3624   to cover the size.
3625 - The driver schedules the DMA transfer via the ScheduleDMAtoHost API call.
3626 - The card raises the DMA Complete interrupt.
3627 - The driver checks the DMA status register for any errors.
3628 - The driver post-processes the newly transferred buffers.
3629
3630 NOTE! It is possible that the Encoder and DMA Complete interrupts get raised
3631 simultaneously. (End of the last, start of the next, etc.)
3632
3633 Mailbox #10
3634 ~~~~~~~~~~~
3635
3636 The Flags, Command, Return Value and Timeout fields are ignored.
3637
3638 - Name:       Mailbox #10
3639 - Results[0]: Type: 0: MPEG.
3640 - Results[1]: Offset: The position relative to the card's memory space.
3641 - Results[2]: Size: The exact number of bytes to transfer.
3642
3643 My speculation is that since the StartCapture API has a capture type of "RAW"
3644 available, that the type field will have other values that correspond to YUV
3645 and PCM data.
3646
3647 Scatter-Gather Array
3648 ~~~~~~~~~~~~~~~~~~~~
3649
3650 The scatter-gather array is a contiguously allocated block of memory that
3651 tells the card the source and destination of each data-block to transfer.
3652 Card "addresses" are derived from the offset supplied by Mailbox #10. Host
3653 addresses are the physical memory location of the target DMA buffer.
3654
3655 Each S-G array element is a struct of three 32-bit words. The first word is
3656 the source address, the second is the destination address. Both take up the
3657 entire 32 bits. The lowest 18 bits of the third word is the transfer byte
3658 count. The high-bit of the third word is the "last" flag. The last-flag tells
3659 the card to raise the DMA_DONE interrupt. From hard personal experience, if
3660 you forget to set this bit, the card will still "work" but the stream will
3661 most likely get corrupted.
3662
3663 The transfer count must be a multiple of 256. Therefore, the driver will need
3664 to track how much data in the target buffer is valid and deal with it
3665 accordingly.
3666
3667 Array Element:
3668
3669 - 32-bit Source Address
3670 - 32-bit Destination Address
3671 - 14-bit reserved (high bit is the last flag)
3672 - 18-bit byte count
3673
3674 DMA Transfer Status
3675 ~~~~~~~~~~~~~~~~~~~
3676
3677 Register 0x0004 holds the DMA Transfer Status:
3678
3679 - bit 0:   read completed
3680 - bit 1:   write completed
3681 - bit 2:   DMA read error
3682 - bit 3:   DMA write error
3683 - bit 4:   Scatter-Gather array error
3684
3685 Non-compressed file format
3686 --------------------------
3687
3688 The cx23416 can produce (and the cx23415 can also read) raw YUV output. The
3689 format of a YUV frame is specific to this chip and is called HM12. 'HM' stands
3690 for 'Hauppauge Macroblock', which is a misnomer as 'Conexant Macroblock' would
3691 be more accurate.
3692
3693 The format is YUV 4:2:0 which uses 1 Y byte per pixel and 1 U and V byte per
3694 four pixels.
3695
3696 The data is encoded as two macroblock planes, the first containing the Y
3697 values, the second containing UV macroblocks.
3698
3699 The Y plane is divided into blocks of 16x16 pixels from left to right
3700 and from top to bottom. Each block is transmitted in turn, line-by-line.
3701
3702 So the first 16 bytes are the first line of the top-left block, the
3703 second 16 bytes are the second line of the top-left block, etc. After
3704 transmitting this block the first line of the block on the right to the
3705 first block is transmitted, etc.
3706
3707 The UV plane is divided into blocks of 16x8 UV values going from left
3708 to right, top to bottom. Each block is transmitted in turn, line-by-line.
3709
3710 So the first 16 bytes are the first line of the top-left block and
3711 contain 8 UV value pairs (16 bytes in total). The second 16 bytes are the
3712 second line of 8 UV pairs of the top-left block, etc. After transmitting
3713 this block the first line of the block on the right to the first block is
3714 transmitted, etc.
3715
3716 The code below is given as an example on how to convert HM12 to separate
3717 Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels.
3718
3719 The width of a frame is always 720 pixels, regardless of the actual specified
3720 width.
3721
3722 If the height is not a multiple of 32 lines, then the captured video is
3723 missing macroblocks at the end and is unusable. So the height must be a
3724 multiple of 32.
3725
3726 Raw format c example
3727 ~~~~~~~~~~~~~~~~~~~~
3728
3729 .. code-block:: c
3730
3731         #include <stdio.h>
3732         #include <stdlib.h>
3733         #include <string.h>
3734
3735         static unsigned char frame[576*720*3/2];
3736         static unsigned char framey[576*720];
3737         static unsigned char frameu[576*720 / 4];
3738         static unsigned char framev[576*720 / 4];
3739
3740         static void de_macro_y(unsigned char* dst, unsigned char *src, int dstride, int w, int h)
3741         {
3742         unsigned int y, x, i;
3743
3744         // descramble Y plane
3745         // dstride = 720 = w
3746         // The Y plane is divided into blocks of 16x16 pixels
3747         // Each block in transmitted in turn, line-by-line.
3748         for (y = 0; y < h; y += 16) {
3749                 for (x = 0; x < w; x += 16) {
3750                 for (i = 0; i < 16; i++) {
3751                         memcpy(dst + x + (y + i) * dstride, src, 16);
3752                         src += 16;
3753                 }
3754                 }
3755         }
3756         }
3757
3758         static void de_macro_uv(unsigned char *dstu, unsigned char *dstv, unsigned char *src, int dstride, int w, int h)
3759         {
3760         unsigned int y, x, i;
3761
3762         // descramble U/V plane
3763         // dstride = 720 / 2 = w
3764         // The U/V values are interlaced (UVUV...).
3765         // Again, the UV plane is divided into blocks of 16x16 UV values.
3766         // Each block in transmitted in turn, line-by-line.
3767         for (y = 0; y < h; y += 16) {
3768                 for (x = 0; x < w; x += 8) {
3769                 for (i = 0; i < 16; i++) {
3770                         int idx = x + (y + i) * dstride;
3771
3772                         dstu[idx+0] = src[0];  dstv[idx+0] = src[1];
3773                         dstu[idx+1] = src[2];  dstv[idx+1] = src[3];
3774                         dstu[idx+2] = src[4];  dstv[idx+2] = src[5];
3775                         dstu[idx+3] = src[6];  dstv[idx+3] = src[7];
3776                         dstu[idx+4] = src[8];  dstv[idx+4] = src[9];
3777                         dstu[idx+5] = src[10]; dstv[idx+5] = src[11];
3778                         dstu[idx+6] = src[12]; dstv[idx+6] = src[13];
3779                         dstu[idx+7] = src[14]; dstv[idx+7] = src[15];
3780                         src += 16;
3781                 }
3782                 }
3783         }
3784         }
3785
3786         /*************************************************************************/
3787         int main(int argc, char **argv)
3788         {
3789         FILE *fin;
3790         int i;
3791
3792         if (argc == 1) fin = stdin;
3793         else fin = fopen(argv[1], "r");
3794
3795         if (fin == NULL) {
3796                 fprintf(stderr, "cannot open input\n");
3797                 exit(-1);
3798         }
3799         while (fread(frame, sizeof(frame), 1, fin) == 1) {
3800                 de_macro_y(framey, frame, 720, 720, 576);
3801                 de_macro_uv(frameu, framev, frame + 720 * 576, 720 / 2, 720 / 2, 576 / 2);
3802                 fwrite(framey, sizeof(framey), 1, stdout);
3803                 fwrite(framev, sizeof(framev), 1, stdout);
3804                 fwrite(frameu, sizeof(frameu), 1, stdout);
3805         }
3806         fclose(fin);
3807         return 0;
3808         }
3809
3810
3811 Format of embedded V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data
3812 ---------------------------------------------------------
3813
3814 Author: Hans Verkuil <hverkuil@xs4all.nl>
3815
3816
3817 This section describes the V4L2_MPEG_STREAM_VBI_FMT_IVTV format of the VBI data
3818 embedded in an MPEG-2 program stream. This format is in part dictated by some
3819 hardware limitations of the ivtv driver (the driver for the Conexant cx23415/6
3820 chips), in particular a maximum size for the VBI data. Anything longer is cut
3821 off when the MPEG stream is played back through the cx23415.
3822
3823 The advantage of this format is it is very compact and that all VBI data for
3824 all lines can be stored while still fitting within the maximum allowed size.
3825
3826 The stream ID of the VBI data is 0xBD. The maximum size of the embedded data is
3827 4 + 43 * 36, which is 4 bytes for a header and 2 * 18 VBI lines with a 1 byte
3828 header and a 42 bytes payload each. Anything beyond this limit is cut off by
3829 the cx23415/6 firmware. Besides the data for the VBI lines we also need 36 bits
3830 for a bitmask determining which lines are captured and 4 bytes for a magic cookie,
3831 signifying that this data package contains V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data.
3832 If all lines are used, then there is no longer room for the bitmask. To solve this
3833 two different magic numbers were introduced:
3834
3835 'itv0': After this magic number two unsigned longs follow. Bits 0-17 of the first
3836 unsigned long denote which lines of the first field are captured. Bits 18-31 of
3837 the first unsigned long and bits 0-3 of the second unsigned long are used for the
3838 second field.
3839
3840 'ITV0': This magic number assumes all VBI lines are captured, i.e. it implicitly
3841 implies that the bitmasks are 0xffffffff and 0xf.
3842
3843 After these magic cookies (and the 8 byte bitmask in case of cookie 'itv0') the
3844 captured VBI lines start:
3845
3846 For each line the least significant 4 bits of the first byte contain the data type.
3847 Possible values are shown in the table below. The payload is in the following 42
3848 bytes.
3849
3850 Here is the list of possible data types:
3851
3852 .. code-block:: c
3853
3854         #define IVTV_SLICED_TYPE_TELETEXT       0x1     // Teletext (uses lines 6-22 for PAL)
3855         #define IVTV_SLICED_TYPE_CC             0x4     // Closed Captions (line 21 NTSC)
3856         #define IVTV_SLICED_TYPE_WSS            0x5     // Wide Screen Signal (line 23 PAL)
3857         #define IVTV_SLICED_TYPE_VPS            0x7     // Video Programming System (PAL) (line 16)
3858