Documentation/media/v4l-drivers/cx2341x.rst

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