Merge tag 'trace-3.15-v2' of git://git.kernel.org/pub/scm/linux/kernel/git/rostedt...
[firefly-linux-kernel-4.4.55.git] / Documentation / video4linux / cx2341x / fw-encoder-api.txt
index 08ee9f5303f9b252c299927729e27c8320a0f0f3..5a27af2ee1c66ee74d2032e998168ee209e19ae2 100644 (file)
@@ -100,13 +100,20 @@ Param[1]
 Name   CX2341X_ENC_SET_BIT_RATE
 Enum   149/0x95
 Description
-       Assign average video stream bitrate.
+       Assign average video stream bitrate. Note on the last three params:
+       Param[3] and [4] seem to be always 0, param [5] doesn't seem to be used.
 Param[0]
        0=variable bitrate, 1=constant bitrate
 Param[1]
        bitrate in bits per second
 Param[2]
        peak bitrate in bits per second, divided by 400
+Param[3]
+       Mux bitrate in bits per second, divided by 400. May be 0 (default).
+Param[4]
+       Rate Control VBR Padding
+Param[5]
+       VBV Buffer used by encoder
 
 -------------------------------------------------------------------------------
 
@@ -115,10 +122,11 @@ Enum      151/0x97
 Description
        Setup the GOP structure
 Param[0]
-       GOP size
+       GOP size (maximum is 34)
 Param[1]
        Number of B frames between the I and P frame, plus 1.
        For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3
+       Note that GOP size must be a multiple of (B-frames + 1).
 
 -------------------------------------------------------------------------------
 
@@ -205,16 +213,6 @@ Param[1]
 
 -------------------------------------------------------------------------------
 
-Name   CX2341X_ENC_SET_3_2_PULLDOWN
-Enum   177/0xB1
-Description
-       3:2 pulldown properties
-Param[0]
-       0=enabled
-       1=disabled
-
--------------------------------------------------------------------------------
-
 Name   CX2341X_ENC_SET_VBI_LINE
 Enum   183/0xB7
 Description
@@ -241,6 +239,9 @@ Name        CX2341X_ENC_SET_STREAM_TYPE
 Enum   185/0xB9
 Description
        Assign stream type
+       Note: Transport stream is not working in recent firmwares.
+       And in older firmwares the timestamps in the TS seem to be
+       unreliable.
 Param[0]
         0=Program stream
         1=Transport stream
@@ -259,11 +260,17 @@ Param[0]
 Name   CX2341X_ENC_SET_OUTPUT_PORT
 Enum   187/0xBB
 Description
-       Assign stream output port (not recommended you change setting from default)
+       Assign stream output port. Normally 0 when the data is copied through
+       the PCI bus (DMA), and 1 when the data is streamed to another chip
+       (pvrusb and cx88-blackbird).
 Param[0]
        0=Memory (default)
        1=Streaming
        2=Serial
+Param[1]
+       Unknown, but leaving this to 0 seems to work best. Indications are that
+       this might have to do with USB support, although passing anything but 0
+       only breaks things.
 
 -------------------------------------------------------------------------------
 
@@ -278,6 +285,8 @@ Description
                '01' Layer III
                '00' Undefined
        This discrepancy may indicate a possible error in the documentation.
+       Testing indicated that only Layer II is actually working, and that
+       the minimum bitrate should be 192 kbps.
 Param[0]
        Bitmask:
           0:1  '00' 44.1Khz
@@ -313,6 +322,7 @@ Param[0]
                '01'=JointStereo
                '10'=Dual
                '11'=Mono
+               Note: the cx23415 cannot decode Joint Stereo properly.
 
          10:11 Mode Extension used in joint_stereo mode.
                In Layer I and II they indicate which subbands are in
@@ -391,16 +401,36 @@ Name      CX2341X_ENC_SET_PGM_INDEX_INFO
 Enum   199/0xC7
 Description
        Sets the Program Index Information.
+       The information is stored as follows:
+
+       struct info {
+               u32 length;             // Length of this frame
+               u32 offset_low;         // Offset in the file of the
+               u32 offset_high;        // start of this frame
+               u32 mask1;              // Bits 0-2 are the type mask:
+                                       // 1=I, 2=P, 4=B
+                                       // 0=End of Program Index, other fields
+                                       //   are invalid.
+               u32 pts;                // The PTS of the frame
+               u32 mask2;              // Bit 0 is bit 32 of the pts.
+       };
+       u32 table_ptr;
+       struct info index[400];
+
+       The table_ptr is the encoder memory address in the table were
+       *new* entries will be written. Note that this is a ringbuffer,
+       so the table_ptr will wraparound.
 Param[0]
        Picture Mask:
            0=No index capture
            1=I frames
            3=I,P frames
            7=I,P,B frames
+       (Seems to be ignored, it always indexes I, P and B frames)
 Param[1]
        Elements requested (up to 400)
 Result[0]
-       Offset in SDF memory of the table.
+       Offset in the encoder memory of the start of the table.
 Result[1]
        Number of allocated elements up to a maximum of Param[1]
 
@@ -470,12 +500,14 @@ Name      CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
 Enum   203/0xCB
 Description
        Returns information on the previous DMA transfer in conjunction with
-       bit 27 of the interrupt mask. Uses mailbox 9.
+       bit 27 or 18 of the interrupt mask. Uses mailbox 9.
 Result[0]
        Status bits:
-           Bit 0 set indicates transfer complete
-           Bit 2 set indicates transfer error
-           Bit 4 set indicates linked list error
+               0   read completed
+               1   write completed
+               2   DMA read error
+               3   DMA write error
+               4   Scatter-Gather array error
 Result[1]
        DMA type
 Result[2]
@@ -633,12 +665,13 @@ Param[0]
 
 -------------------------------------------------------------------------------
 
-Name   CX2341X_ENC_UNKNOWN
+Name   CX2341X_ENC_SET_VERT_CROP_LINE
 Enum   219/0xDB
 Description
-       Unknown API, it's used by Hauppauge though.
+       Something to do with 'Vertical Crop Line'
 Param[0]
-       0 This is the value Hauppauge uses, Unknown what it means.
+       If saa7114 and raw VBI capture and 60 Hz, then set to 10001.
+       Else 0.
 
 -------------------------------------------------------------------------------
 
@@ -650,21 +683,25 @@ Description
        the value.
 Param[0]
        Command number:
-        1=set initial SCR value when starting encoding.
+        1=set initial SCR value when starting encoding (works).
         2=set quality mode (apparently some test setting).
-        3=setup advanced VIM protection handling (supposedly only for the cx23416
-          for raw YUV).
-          Actually it looks like this should be 0 for saa7114/5 based card and 1
-          for cx25840 based cards.
-        4=generate artificial PTS timestamps
+        3=setup advanced VIM protection handling.
+          Always 1 for the cx23416 and 0 for cx23415.
+        4=generate DVD compatible PTS timestamps
         5=USB flush mode
         6=something to do with the quantization matrix
-        7=set navigation pack insertion for DVD
+        7=set navigation pack insertion for DVD: adds 0xbf (private stream 2)
+          packets to the MPEG. The size of these packets is 2048 bytes (including
+          the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
+          it is up to the application to fill them in. These packets are apparently
+          inserted every four frames.
         8=enable scene change detection (seems to be a failure)
         9=set history parameters of the video input module
        10=set input field order of VIM
        11=set quantization matrix
-       12=reset audio interface
+       12=reset audio interface after channel change or input switch (has no argument).
+          Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to
+          do any harm calling it regardless.
        13=set audio volume delay
        14=set audio delay