V4L/DVB (3809b): Added missing docs at kernel tree
authorMauro Carvalho Chehab <mchehab@infradead.org>
Mon, 22 May 2006 13:31:37 +0000 (10:31 -0300)
committerMauro Carvalho Chehab <mchehab@infradead.org>
Sun, 25 Jun 2006 04:59:48 +0000 (01:59 -0300)
Date:

From: Mauro Carvalho Chehab <mchehab@infradead.org>

There are some docs at V4L/DVB tree that were never included at kernel.
This patch includes those docs.

Signed-off-by: Mauro Carvalho Chehab <mchehab@infradead.org>
Documentation/video4linux/cx2341x/fw-calling.txt [new file with mode: 0644]
Documentation/video4linux/cx2341x/fw-decoder-api.txt [new file with mode: 0644]
Documentation/video4linux/cx2341x/fw-dma.txt [new file with mode: 0644]
Documentation/video4linux/cx2341x/fw-encoder-api.txt [new file with mode: 0644]
Documentation/video4linux/cx2341x/fw-memory.txt [new file with mode: 0644]
Documentation/video4linux/cx2341x/fw-osd-api.txt [new file with mode: 0644]
Documentation/video4linux/cx2341x/fw-upload.txt [new file with mode: 0644]
Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt [new file with mode: 0644]

diff --git a/Documentation/video4linux/cx2341x/fw-calling.txt b/Documentation/video4linux/cx2341x/fw-calling.txt
new file mode 100644 (file)
index 0000000..8d21181
--- /dev/null
@@ -0,0 +1,69 @@
+This page describes how to make calls to the firmware api.
+
+How to call
+===========
+
+The preferred calling convention is known as the firmware mailbox. The
+mailboxes are basically a fixed length array that serves as the call-stack.
+
+Firmware mailboxes can be located by searching the encoder and decoder memory
+for a 16 byte signature. That signature will be located on a 256-byte boundary.
+
+Signature:
+0x78, 0x56, 0x34, 0x12, 0x12, 0x78, 0x56, 0x34,
+0x34, 0x12, 0x78, 0x56, 0x56, 0x34, 0x12, 0x78
+
+The firmware implements 20 mailboxes of 20 32-bit words. The first 10 are
+reserved for API calls. The second 10 are used by the firmware for event
+notification.
+
+  Index  Name
+  -----  ----
+  0      Flags
+  1      Command
+  2      Return value
+  3      Timeout
+  4-19   Parameter/Result
+
+
+The flags are defined in the following table. The direction is from the
+perspective of the firmware.
+
+  Bit  Direction  Purpose
+  ---  ---------  -------
+  2    O          Firmware has processed the command.
+  1    I          Driver has finished setting the parameters.
+  0    I          Driver is using this mailbox.
+
+
+The command is a 32-bit enumerator. The API specifics may be found in the
+fw-*-api.txt documents.
+
+The return value is a 32-bit enumerator. Only two values are currently defined:
+0=success and -1=command undefined.
+
+There are 16 parameters/results 32-bit fields. The driver populates these fields
+with values for all the parameters required by the call. The driver overwrites
+these fields with result values returned by the call. The API specifics may be
+found in the fw-*-api.txt documents.
+
+The timeout value protects the card from a hung driver thread. If the driver
+doesn't handle the completed call within the timeout specified, the firmware
+will reset that mailbox.
+
+To make an API call, the driver iterates over each mailbox looking for the
+first one available (bit 0 has been cleared). The driver sets that bit, fills
+in the command enumerator, the timeout value and any required parameters. The
+driver then sets the parameter ready bit (bit 1). The firmware scans the
+mailboxes for pending commands, processes them, sets the result code, populates
+the result value array with that call's return values and sets the call
+complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results
+and clear all the flags. If the driver does not perform this task within the
+time set in the timeout register, the firmware will reset that mailbox.
+
+Event notifications are sent from the firmware to the host. The host tells the
+firmware which events it is interested in via an API call. That call tells the
+firmware which notification mailbox to use. The firmware signals the host via
+an interrupt. Only the 16 Results fields are used, the Flags, Command, Return
+value and Timeout words are not used.
+
diff --git a/Documentation/video4linux/cx2341x/fw-decoder-api.txt b/Documentation/video4linux/cx2341x/fw-decoder-api.txt
new file mode 100644 (file)
index 0000000..59193b6
--- /dev/null
@@ -0,0 +1,319 @@
+Decoder firmware API description
+================================
+
+Note: this API is part of the decoder firmware, so it's cx23415 only.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_PING_FW
+Enum   0/0x00
+Description
+       This API call does nothing. It may be used to check if the firmware
+       is responding.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_START_PLAYBACK
+Enum   1/0x01
+Description
+       Begin or resume playback.
+Param[0]
+       0 based frame number in GOP to begin playback from.
+Param[1]
+       Specifies the number of muted audio frames to play before normal
+       audio resumes.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_STOP_PLAYBACK
+Enum   2/0x02
+Description
+       Ends playback and clears all decoder buffers. If PTS is not zero,
+       playback stops at specified PTS.
+Param[0]
+       Display 0=last frame, 1=black
+Param[1]
+       PTS low
+Param[2]
+       PTS high
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_PLAYBACK_SPEED
+Enum   3/0x03
+Description
+       Playback stream at speed other than normal. There are two modes of
+       operation:
+           Smooth: host transfers entire stream and firmware drops unused
+                   frames.
+           Coarse: host drops frames based on indexing as required to achieve
+                   desired speed.
+Param[0]
+       Bitmap:
+           0:7  0 normal
+                1 fast only "1.5 times"
+                n nX fast, 1/nX slow
+           30   Framedrop:
+                    '0' during 1.5 times play, every other B frame is dropped
+                    '1' during 1.5 times play, stream is unchanged (bitrate
+                        must not exceed 8mbps)
+           31   Speed:
+                    '0' slow
+                    '1' fast
+Param[1]
+       Direction: 0=forward, 1=reverse
+Param[2]
+       Picture mask:
+           1=I frames
+           3=I, P frames
+           7=I, P, B frames
+Param[3]
+       B frames per GOP (for reverse play only)
+Param[4]
+       Mute audio: 0=disable, 1=enable
+Param[5]
+       Display 0=frame, 1=field
+Param[6]
+       Specifies the number of muted audio frames to play before normal audio
+       resumes.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_STEP_VIDEO
+Enum   5/0x05
+Description
+       Each call to this API steps the playback to the next unit defined below
+       in the current playback direction.
+Param[0]
+       0=frame, 1=top field, 2=bottom field
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_DMA_BLOCK_SIZE
+Enum   8/0x08
+Description
+       Set DMA transfer block size. Counterpart to API 0xC9
+Param[0]
+       DMA transfer block size in bytes. A different size may be specified
+       when issuing the DMA transfer command.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_GET_XFER_INFO
+Enum   9/0x09
+Description
+       This API call may be used to detect an end of stream condtion.
+Result[0]
+       Stream type
+Result[1]
+       Address offset
+Result[2]
+       Maximum bytes to transfer
+Result[3]
+       Buffer fullness
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_GET_DMA_STATUS
+Enum   10/0x0A
+Description
+       Status of the last DMA transfer
+Result[0]
+       Bit 1 set means transfer complete
+       Bit 2 set means DMA error
+       Bit 3 set means linked list error
+Result[1]
+       DMA type: 0=MPEG, 1=OSD, 2=YUV
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SCHED_DMA_FROM_HOST
+Enum   11/0x0B
+Description
+       Setup DMA from host operation. Counterpart to API 0xCC
+Param[0]
+       Memory address of link list
+Param[1]
+       Total # of bytes to transfer
+Param[2]
+       DMA type (0=MPEG, 1=OSD, 2=YUV)
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_PAUSE_PLAYBACK
+Enum   13/0x0D
+Description
+       Freeze playback immediately. In this mode, when internal buffers are
+       full, no more data will be accepted and data request IRQs will be
+       masked.
+Param[0]
+       Display: 0=last frame, 1=black
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_HALT_FW
+Enum   14/0x0E
+Description
+       The firmware is halted and no further API calls are serviced until
+       the firmware is uploaded again.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_STANDARD
+Enum   16/0x10
+Description
+       Selects display standard
+Param[0]
+       0=NTSC, 1=PAL
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_GET_VERSION
+Enum   17/0x11
+Description
+       Returns decoder firmware version information
+Result[0]
+       Version bitmask:
+           Bits  0:15 build
+           Bits 16:23 minor
+           Bits 24:31 major
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_STREAM_INPUT
+Enum   20/0x14
+Description
+       Select decoder stream input port
+Param[0]
+       0=memory (default), 1=streaming
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_GET_TIMING_INFO
+Enum   21/0x15
+Description
+       Returns timing information from start of playback
+Result[0]
+       Frame count by decode order
+Result[1]
+       Video PTS bits 0:31 by display order
+Result[2]
+       Video PTS bit 32 by display order
+Result[3]
+       SCR bits 0:31 by display order
+Result[4]
+       SCR bit 32 by display order
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_AUDIO_MODE
+Enum   22/0x16
+Description
+       Select audio mode
+Param[0]
+       Dual mono mode action
+Param[1]
+       Stereo mode action:
+           0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_EVENT_NOTIFICATION
+Enum   23/0x17
+Description
+       Setup firmware to notify the host about a particular event.
+       Counterpart to API 0xD5
+Param[0]
+       Event: 0=Audio mode change between stereo and dual channel
+Param[1]
+       Notification 0=disabled, 1=enabled
+Param[2]
+       Interrupt bit
+Param[3]
+       Mailbox slot, -1 if no mailbox required.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_DISPLAY_BUFFERS
+Enum   24/0x18
+Description
+       Number of display buffers. To decode all frames in reverse playback you
+       must use nine buffers.
+Param[0]
+       0=six buffers, 1=nine buffers
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_EXTRACT_VBI
+Enum   25/0x19
+Description
+       Extracts VBI data
+Param[0]
+       0=extract from extension & user data, 1=extract from private packets
+Result[0]
+       VBI table location
+Result[1]
+       VBI table size
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_DECODER_SOURCE
+Enum   26/0x1A
+Description
+       Selects decoder source. Ensure that the parameters passed to this
+       API match the encoder settings.
+Param[0]
+       Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host
+Param[1]
+       YUV picture width
+Param[2]
+       YUV picture height
+Param[3]
+       Bitmap: see Param[0] of API 0xBD
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_AUDIO_OUTPUT
+Enum   27/0x1B
+Description
+       Select audio output format
+Param[0]
+       Bitmask:
+            0:1  Data size:
+                     '00' 16 bit
+                     '01' 20 bit
+                     '10' 24 bit
+            2:7  Unused
+            8:9  Mode:
+                     '00' 2 channels
+                     '01' 4 channels
+                     '10' 6 channels
+                     '11' 6 channels with one line data mode
+                          (for left justified MSB first mode, 20 bit only)
+           10:11 Unused
+           12:13 Channel format:
+                     '00' right justified MSB first mode
+                     '01' left justified MSB first mode
+                     '10' I2S mode
+           14:15 Unused
+           16:21 Right justify bit count
+           22:31 Unused
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_AV_DELAY
+Enum   28/0x1C
+Description
+       Set audio/video delay in 90Khz ticks
+Param[0]
+       0=A/V in sync, negative=audio lags, positive=video lags
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_DEC_SET_PREBUFFERING
+Enum   30/0x1E
+Description
+       Decoder prebuffering, when enabled up to 128KB are buffered for
+       streams <8mpbs or 640KB for streams >8mbps
+Param[0]
+       0=off, 1=on
diff --git a/Documentation/video4linux/cx2341x/fw-dma.txt b/Documentation/video4linux/cx2341x/fw-dma.txt
new file mode 100644 (file)
index 0000000..8123e26
--- /dev/null
@@ -0,0 +1,94 @@
+This page describes the structures and procedures used by the cx2341x DMA
+engine.
+
+Introduction
+============
+
+The cx2341x PCI interface is busmaster capable. This means it has a DMA
+engine to efficiently transfer large volumes of data between the card and main
+memory without requiring help from a CPU. Like most hardware, it must operate
+on contiguous physical memory. This is difficult to come by in large quantities
+on virtual memory machines.
+
+Therefore, it also supports a technique called "scatter-gather". The card can
+transfer multiple buffers in one operation. Instead of allocating one large
+contiguous buffer, the driver can allocate several smaller buffers.
+
+In practice, I've seen the average transfer to be roughly 80K, but transfers
+above 128K were not uncommon, particularly at startup. The 128K figure is
+important, because that is the largest block that the kernel can normally
+allocate. Even still, 128K blocks are hard to come by, so the driver writer is
+urged to choose a smaller block size and learn the scatter-gather technique.
+
+Mailbox #10 is reserved for DMA transfer information.
+
+Flow
+====
+
+This section describes, in general, the order of events when handling DMA
+transfers. Detailed information follows this section.
+
+- The card raises the Encoder interrupt.
+- The driver reads the transfer type, offset and size from Mailbox #10.
+- The driver constructs the scatter-gather array from enough free dma buffers
+  to cover the size.
+- The driver schedules the DMA transfer via the ScheduleDMAtoHost API call.
+- The card raises the DMA Complete interrupt.
+- The driver checks the DMA status register for any errors.
+- The driver post-processes the newly transferred buffers.
+
+NOTE! It is possible that the Encoder and DMA Complete interrupts get raised
+simultaneously. (End of the last, start of the next, etc.)
+
+Mailbox #10
+===========
+
+The Flags, Command, Return Value and Timeout fields are ignored.
+
+Name:       Mailbox #10
+Results[0]: Type: 0: MPEG.
+Results[1]: Offset: The position relative to the card's memory space.
+Results[2]: Size: The exact number of bytes to transfer.
+
+My speculation is that since the StartCapture API has a capture type of "RAW"
+available, that the type field will have other values that correspond to YUV
+and PCM data.
+
+Scatter-Gather Array
+====================
+
+The scatter-gather array is a contiguously allocated block of memory that
+tells the card the source and destination of each data-block to transfer.
+Card "addresses" are derived from the offset supplied by Mailbox #10. Host
+addresses are the physical memory location of the target DMA buffer.
+
+Each S-G array element is a struct of three 32-bit words. The first word is
+the source address, the second is the destination address. Both take up the
+entire 32 bits. The lowest 16 bits of the third word is the transfer byte
+count. The high-bit of the third word is the "last" flag. The last-flag tells
+the card to raise the DMA_DONE interrupt. From hard personal experience, if
+you forget to set this bit, the card will still "work" but the stream will
+most likely get corrupted.
+
+The transfer count must be a multiple of 256. Therefore, the driver will need
+to track how much data in the target buffer is valid and deal with it
+accordingly.
+
+Array Element:
+
+- 32-bit Source Address
+- 32-bit Destination Address
+- 16-bit reserved (high bit is the last flag)
+- 16-bit byte count
+
+DMA Transfer Status
+===================
+
+Register 0x0004 holds the DMA Transfer Status:
+
+Bit
+4   Scatter-Gather array error
+3   DMA write error
+2   DMA read error
+1   write completed
+0   read completed
diff --git a/Documentation/video4linux/cx2341x/fw-encoder-api.txt b/Documentation/video4linux/cx2341x/fw-encoder-api.txt
new file mode 100644 (file)
index 0000000..64cd111
--- /dev/null
@@ -0,0 +1,672 @@
+Encoder firmware API description
+================================
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_PING_FW
+Enum   128/0x80
+Description
+       Does nothing. Can be used to check if the firmware is responding.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_START_CAPTURE
+Enum   129/0x81
+Description
+       Commences the capture of video, audio and/or VBI data. All encoding
+       parameters must be initialized prior to this API call. Captures frames
+       continuously or until a predefined number of frames have been captured.
+Param[0]
+       Capture stream type:
+           0=MPEG
+           1=Raw
+           2=Raw passthrough
+           3=VBI
+
+Param[1]
+       Bitmask:
+           Bit 0 when set, captures YUV
+           Bit 1 when set, captures PCM audio
+           Bit 2 when set, captures VBI (same as param[0]=3)
+           Bit 3 when set, the capture destination is the decoder
+               (same as param[0]=2)
+           Bit 4 when set, the capture destination is the host
+       Note: this parameter is only meaningful for RAW capture type.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_STOP_CAPTURE
+Enum   130/0x82
+Description
+       Ends a capture in progress
+Param[0]
+       0=stop at end of GOP (generates IRQ)
+       1=stop immediate (no IRQ)
+Param[1]
+       Stream type to stop, see param[0] of API 0x81
+Param[2]
+       Subtype, see param[1] of API 0x81
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_AUDIO_ID
+Enum   137/0x89
+Description
+       Assigns the transport stream ID of the encoded audio stream
+Param[0]
+       Audio Stream ID
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_VIDEO_ID
+Enum   139/0x8B
+Description
+       Set video transport stream ID
+Param[0]
+       Video stream ID
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_PCR_ID
+Enum   141/0x8D
+Description
+       Assigns the transport stream ID for PCR packets
+Param[0]
+       PCR Stream ID
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_FRAME_RATE
+Enum   143/0x8F
+Description
+       Set video frames per second. Change occurs at start of new GOP.
+Param[0]
+       0=30fps
+       1=25fps
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_FRAME_SIZE
+Enum   145/0x91
+Description
+       Select video stream encoding resolution.
+Param[0]
+       Height in lines. Default 480
+Param[1]
+       Width in pixels. Default 720
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_BIT_RATE
+Enum   149/0x95
+Description
+       Assign average video stream bitrate.
+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
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_GOP_PROPERTIES
+Enum   151/0x97
+Description
+       Setup the GOP structure
+Param[0]
+       GOP size
+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
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_ASPECT_RATIO
+Enum   153/0x99
+Description
+       Sets the encoding aspect ratio. Changes in the aspect ratio take effect
+       at the start of the next GOP.
+Param[0]
+       '0000' forbidden
+       '0001' 1:1 square
+       '0010' 4:3
+       '0011' 16:9
+       '0100' 2.21:1
+       '0101' reserved
+        ....
+       '1111' reserved
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_DNR_FILTER_MODE
+Enum   155/0x9B
+Description
+       Assign Dynamic Noise Reduction operating mode
+Param[0]
+       Bit0: Spatial filter, set=auto, clear=manual
+       Bit1: Temporal filter, set=auto, clear=manual
+Param[1]
+       Median filter:
+           0=Disabled
+           1=Horizontal
+           2=Vertical
+           3=Horiz/Vert
+           4=Diagonal
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_DNR_FILTER_PROPS
+Enum   157/0x9D
+Description
+       These Dynamic Noise Reduction filter values are only meaningful when
+       the respective filter is set to "manual" (See API 0x9B)
+Param[0]
+       Spatial filter: default 0, range 0:15
+Param[1]
+       Temporal filter: default 0, range 0:31
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_CORING_LEVELS
+Enum   159/0x9F
+Description
+       Assign Dynamic Noise Reduction median filter properties.
+Param[0]
+       Threshold above which the luminance median filter is enabled.
+       Default: 0, range 0:255
+Param[1]
+       Threshold below which the luminance median filter is enabled.
+       Default: 255, range 0:255
+Param[2]
+       Threshold above which the chrominance median filter is enabled.
+       Default: 0, range 0:255
+Param[3]
+       Threshold below which the chrominance median filter is enabled.
+       Default: 255, range 0:255
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
+Enum   161/0xA1
+Description
+       Assign spatial prefilter parameters
+Param[0]
+       Luminance filter
+           0=Off
+           1=1D Horizontal
+           2=1D Vertical
+           3=2D H/V Separable (default)
+           4=2D Symmetric non-separable
+Param[1]
+       Chrominance filter
+           0=Off
+           1=1D Horizontal (default)
+
+-------------------------------------------------------------------------------
+
+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
+       Selects VBI line number.
+Param[0]
+       Bits 0:4        line number
+       Bit  31         0=top_field, 1=bottom_field
+       Bits 0:31       all set specifies "all lines"
+Param[1]
+       VBI line information features: 0=disabled, 1=enabled
+Param[2]
+       Slicing: 0=None, 1=Closed Caption
+       Almost certainly not implemented. Set to 0.
+Param[3]
+       Luminance samples in this line.
+       Almost certainly not implemented. Set to 0.
+Param[4]
+       Chrominance samples in this line
+       Almost certainly not implemented. Set to 0.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_STREAM_TYPE
+Enum   185/0xB9
+Description
+       Assign stream type
+Param[0]
+        0=Program stream
+        1=Transport stream
+        2=MPEG1 stream
+        3=PES A/V stream
+        5=PES Video stream
+        7=PES Audio stream
+       10=DVD stream
+       11=VCD stream
+       12=SVCD stream
+       13=DVD_S1 stream
+       14=DVD_S2 stream
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_OUTPUT_PORT
+Enum   187/0xBB
+Description
+       Assign stream output port (not recommended you change setting from default)
+Param[0]
+       0=Memory (default)
+       1=Streaming
+       2=Serial
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_AUDIO_PROPERTIES
+Enum   189/0xBD
+Description
+       Set audio stream properties, may be called while encoding is in progress.
+       Note: all bitfields are consistent with ISO11172 documentation except
+       bits 2:3 which ISO docs define as:
+               '11' Layer I
+               '10' Layer II
+               '01' Layer III
+               '00' Undefined
+       This discrepancy may indicate a possible error in the documentation.
+Param[0]
+       Bitmask:
+          0:1  '00' 44.1Khz
+               '01' 48Khz
+               '10' 32Khz
+               '11' reserved
+
+          2:3  '01'=Layer I
+               '10'=Layer II
+
+          4:7  Bitrate:
+                    Index | Layer I     | Layer II
+                    ------+-------------+------------
+                   '0000' | free format | free format
+                   '0001' |  32 kbit/s  |  32 kbit/s
+                   '0010' |  64 kbit/s  |  48 kbit/s
+                   '0011' |  96 kbit/s  |  56 kbit/s
+                   '0100' | 128 kbit/s  |  64 kbit/s
+                   '0101' | 160 kbit/s  |  80 kbit/s
+                   '0110' | 192 kbit/s  |  96 kbit/s
+                   '0111' | 224 kbit/s  | 112 kbit/s
+                   '1000' | 256 kbit/s  | 128 kbit/s
+                   '1001' | 288 kbit/s  | 160 kbit/s
+                   '1010' | 320 kbit/s  | 192 kbit/s
+                   '1011' | 352 kbit/s  | 224 kbit/s
+                   '1100' | 384 kbit/s  | 256 kbit/s
+                   '1101' | 416 kbit/s  | 320 kbit/s
+                   '1110' | 448 kbit/s  | 384 kbit/s
+               Note: For Layer II, not all combinations of total bitrate
+               and mode are allowed. See ISO11172-3 3-Annex B, Table 3-B.2
+
+          8:9  '00'=Stereo
+               '01'=JointStereo
+               '10'=Dual
+               '11'=Mono
+
+         10:11 Mode Extension used in joint_stereo mode.
+               In Layer I and II they indicate which subbands are in
+               intensity_stereo. All other subbands are coded in stereo.
+                   '00' subbands 4-31 in intensity_stereo, bound==4
+                   '01' subbands 8-31 in intensity_stereo, bound==8
+                   '10' subbands 12-31 in intensity_stereo, bound==12
+                   '11' subbands 16-31 in intensity_stereo, bound==16
+
+         12:13 Emphasis:
+                   '00' None
+                   '01' 50/15uS
+                   '10' reserved
+                   '11' CCITT J.17
+
+         14    CRC:
+                   '0' off
+                   '1' on
+
+         15    Copyright:
+                   '0' off
+                   '1' on
+
+         16    Generation:
+                   '0' copy
+                   '1' original
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_HALT_FW
+Enum   195/0xC3
+Description
+       The firmware is halted and no further API calls are serviced until the
+       firmware is uploaded again.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_GET_VERSION
+Enum   196/0xC4
+Description
+       Returns the version of the encoder firmware.
+Result[0]
+       Version bitmask:
+           Bits  0:15 build
+           Bits 16:23 minor
+           Bits 24:31 major
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_GOP_CLOSURE
+Enum   197/0xC5
+Description
+       Assigns the GOP open/close property.
+Param[0]
+       0=Open
+       1=Closed
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_GET_SEQ_END
+Enum   198/0xC6
+Description
+       Obtains the sequence end code of the encoder's buffer. When a capture
+       is started a number of interrupts are still generated, the last of
+       which will have Result[0] set to 1 and Result[1] will contain the size
+       of the buffer.
+Result[0]
+       State of the transfer (1 if last buffer)
+Result[1]
+       If Result[0] is 1, this contains the size of the last buffer, undefined
+       otherwise.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_PGM_INDEX_INFO
+Enum   199/0xC7
+Description
+       Sets the Program Index Information.
+Param[0]
+       Picture Mask:
+           0=No index capture
+           1=I frames
+           3=I,P frames
+           7=I,P,B frames
+Param[1]
+       Elements requested (up to 400)
+Result[0]
+       Offset in SDF memory of the table.
+Result[1]
+       Number of allocated elements up to a maximum of Param[1]
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_VBI_CONFIG
+Enum   200/0xC8
+Description
+       Configure VBI settings
+Param[0]
+       Bitmap:
+           0    Mode '0' Sliced, '1' Raw
+           1:3  Insertion:
+                    '000' insert in extension & user data
+                    '001' insert in private packets
+                    '010' separate stream and user data
+                    '111' separate stream and private data
+           8:15 Stream ID (normally 0xBD)
+Param[1]
+       Frames per interrupt (max 8). Only valid in raw mode.
+Param[2]
+       Total raw VBI frames. Only valid in raw mode.
+Param[3]
+       Start codes
+Param[4]
+       Stop codes
+Param[5]
+       Lines per frame
+Param[6]
+       Byte per line
+Result[0]
+       Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
+Result[1]
+       Observed number of frames in raw mode. Range 1 to Param[2]
+Result[2]
+       Memory offset to start or raw VBI data
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_DMA_BLOCK_SIZE
+Enum   201/0xC9
+Description
+       Set DMA transfer block size
+Param[0]
+       DMA transfer block size in bytes or frames. When unit is bytes,
+       supported block sizes are 2^7, 2^8 and 2^9 bytes.
+Param[1]
+       Unit: 0=bytes, 1=frames
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
+Enum   202/0xCA
+Description
+       Returns information on the previous DMA transfer in conjunction with
+       bit 27 of the interrupt mask. Uses mailbox 10.
+Result[0]
+       Type of stream
+Result[1]
+       Address Offset
+Result[2]
+       Maximum size of transfer
+
+-------------------------------------------------------------------------------
+
+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.
+Result[0]
+       Status bits:
+           Bit 0 set indicates transfer complete
+           Bit 2 set indicates transfer error
+           Bit 4 set indicates linked list error
+Result[1]
+       DMA type
+Result[2]
+       Presentation Time Stamp bits 0..31
+Result[3]
+       Presentation Time Stamp bit 32
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SCHED_DMA_TO_HOST
+Enum   204/0xCC
+Description
+       Setup DMA to host operation
+Param[0]
+       Memory address of link list
+Param[1]
+       Length of link list (wtf: what units ???)
+Param[2]
+       DMA type (0=MPEG)
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_INITIALIZE_INPUT
+Enum   205/0xCD
+Description
+       Initializes the video input
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_FRAME_DROP_RATE
+Enum   208/0xD0
+Description
+       For each frame captured, skip specified number of frames.
+Param[0]
+       Number of frames to skip
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_PAUSE_ENCODER
+Enum   210/0xD2
+Description
+       During a pause condition, all frames are dropped instead of being encoded.
+Param[0]
+       0=Pause encoding
+       1=Continue encoding
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_REFRESH_INPUT
+Enum   211/0xD3
+Description
+       Refreshes the video input
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_COPYRIGHT
+Enum   212/0xD4
+Description
+       Sets stream copyright property
+Param[0]
+       0=Stream is not copyrighted
+       1=Stream is copyrighted
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_EVENT_NOTIFICATION
+Enum   213/0xD5
+Description
+       Setup firmware to notify the host about a particular event. Host must
+       unmask the interrupt bit.
+Param[0]
+       Event (0=refresh encoder input)
+Param[1]
+       Notification 0=disabled 1=enabled
+Param[2]
+       Interrupt bit
+Param[3]
+       Mailbox slot, -1 if no mailbox required.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_NUM_VSYNC_LINES
+Enum   214/0xD6
+Description
+       Depending on the analog video decoder used, this assigns the number
+       of lines for field 1 and 2.
+Param[0]
+       Field 1 number of lines:
+           0x00EF for SAA7114
+           0x00F0 for SAA7115
+           0x0105 for Micronas
+Param[1]
+       Field 2 number of lines:
+           0x00EF for SAA7114
+           0x00F0 for SAA7115
+           0x0106 for Micronas
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_SET_PLACEHOLDER
+Enum   215/0xD7
+Description
+       Provides a mechanism of inserting custom user data in the MPEG stream.
+Param[0]
+       0=extension & user data
+       1=private packet with stream ID 0xBD
+Param[1]
+       Rate at which to insert data, in units of frames (for private packet)
+       or GOPs (for ext. & user data)
+Param[2]
+       Number of data DWORDs (below) to insert
+Param[3]
+       Custom data 0
+Param[4]
+       Custom data 1
+Param[5]
+       Custom data 2
+Param[6]
+       Custom data 3
+Param[7]
+       Custom data 4
+Param[8]
+       Custom data 5
+Param[9]
+       Custom data 6
+Param[10]
+       Custom data 7
+Param[11]
+       Custom data 8
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_MUTE_VIDEO
+Enum   217/0xD9
+Description
+       Video muting
+Param[0]
+       Bit usage:
+        0      '0'=video not muted
+               '1'=video muted, creates frames with the YUV color defined below
+        1:7    Unused
+        8:15   V chrominance information
+       16:23   U chrominance information
+       24:31   Y luminance information
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_MUTE_AUDIO
+Enum   218/0xDA
+Description
+       Audio muting
+Param[0]
+       0=audio not muted
+       1=audio muted (produces silent mpeg audio stream)
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_UNKNOWN
+Enum   219/0xDB
+Description
+       Unknown API, it's used by Hauppauge though.
+Param[0]
+       0 This is the value Hauppauge uses, Unknown what it means.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_ENC_MISC
+Enum   220/0xDC
+Description
+       Miscellaneous actions. Not known for 100% what it does. It's really a
+       sort of ioctl call. The first parameter is a command number, the second
+       the value.
+Param[0]
+       Command number:
+        1=set initial SCR value when starting encoding.
+        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
+        5=USB flush mode
+        6=something to do with the quantization matrix
+        7=set navigation pack insertion for DVD
+        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
+       13=set audio volume delay
+       14=set audio delay
+
+Param[1]
+       Command value.
diff --git a/Documentation/video4linux/cx2341x/fw-memory.txt b/Documentation/video4linux/cx2341x/fw-memory.txt
new file mode 100644 (file)
index 0000000..336d820
--- /dev/null
@@ -0,0 +1,141 @@
+This document describes the cx2341x memory map and documents some of the register
+space.
+
+Warning! This information was figured out from searching through the memory and
+registers, this information may not be correct and is certainly not complete, and
+was not derived from anything more than searching through the memory space with
+commands like:
+
+       ivtvctl -O min=0x02000000,max=0x020000ff
+
+So take this as is, I'm always searching for more stuff, it's a large
+register space :-).
+
+Memory Map
+==========
+
+The cx2341x exposes its entire 64M memory space to the PCI host via the PCI BAR0
+(Base Address Register 0). The addresses here are offsets relative to the
+address held in BAR0.
+
+0x00000000-0x00ffffff Encoder memory space
+0x00000000-0x0003ffff Encode.rom
+      ???-???         MPEG buffer(s)
+      ???-???         Raw video capture buffer(s)
+      ???-???         Raw audio capture buffer(s)
+      ???-???         Display buffers (6 or 9)
+
+0x01000000-0x01ffffff Decoder memory space
+0x01000000-0x0103ffff Decode.rom
+      ???-???         MPEG buffers(s)
+0x0114b000-0x0115afff Audio.rom (deprecated?)
+
+0x02000000-0x0200ffff Register Space
+
+Registers
+=========
+
+The registers occupy the 64k space starting at the 0x02000000 offset from BAR0.
+All of these registers are 32 bits wide.
+
+DMA Registers 0x000-0xff:
+
+ 0x00 - Control:
+       0=reset/cancel, 1=read, 2=write, 4=stop
+ 0x04 - DMA status:
+       1=read busy, 2=write busy, 4=read error, 8=write error, 16=link list error
+ 0x08 - pci DMA pointer for read link list
+ 0x0c - pci DMA pointer for write link list
+ 0x10 - read/write DMA enable:
+       1=read enable, 2=write enable
+ 0x14 - always 0xffffffff, if set any lower instability occurs, 0x00 crashes
+ 0x18 - ??
+ 0x1c - always 0x20 or 32, smaller values slow down DMA transactions
+ 0x20 - always value of 0x780a010a
+ 0x24-0x3c - usually just random values???
+ 0x40 - Interrupt status
+ 0x44 - Write a bit here and shows up in Interrupt status 0x40
+ 0x48 - Interrupt Mask
+ 0x4C - always value of 0xfffdffff,
+       if changed to 0xffffffff DMA write interrupts break.
+ 0x50 - always 0xffffffff
+ 0x54 - always 0xffffffff (0x4c, 0x50, 0x54 seem like interrupt masks, are
+       3 processors on chip, Java ones, VPU, SPU, APU, maybe these are the
+       interrupt masks???).
+ 0x60-0x7C - random values
+ 0x80 - first write linked list reg, for Encoder Memory addr
+ 0x84 - first write linked list reg, for pci memory addr
+ 0x88 - first write linked list reg, for length of buffer in memory addr
+       (|0x80000000 or this for last link)
+ 0x8c-0xcc - rest of write linked list reg, 8 sets of 3 total, DMA goes here
+       from linked list addr in reg 0x0c, firmware must push through or
+       something.
+ 0xe0 - first (and only) read linked list reg, for pci memory addr
+ 0xe4 - first (and only) read linked list reg, for Decoder memory addr
+ 0xe8 - first (and only) read linked list reg, for length of buffer
+ 0xec-0xff - Nothing seems to be in these registers, 0xec-f4 are 0x00000000.
+
+Memory locations for Encoder Buffers 0x700-0x7ff:
+
+These registers show offsets of memory locations pertaining to each
+buffer area used for encoding, have to shift them by <<1 first.
+
+0x07F8: Encoder SDRAM refresh
+0x07FC: Encoder SDRAM pre-charge
+
+Memory locations for Decoder Buffers 0x800-0x8ff:
+
+These registers show offsets of memory locations pertaining to each
+buffer area used for decoding, have to shift them by <<1 first.
+
+0x08F8: Decoder SDRAM refresh
+0x08FC: Decoder SDRAM pre-charge
+
+Other memory locations:
+
+0x2800: Video Display Module control
+0x2D00: AO (audio output?) control
+0x2D24: Bytes Flushed
+0x7000: LSB I2C write clock bit (inverted)
+0x7004: LSB I2C write data bit (inverted)
+0x7008: LSB I2C read clock bit
+0x700c: LSB I2C read data bit
+0x9008: GPIO get input state
+0x900c: GPIO set output state
+0x9020: GPIO direction (Bit7 (GPIO 0..7) - 0:input, 1:output)
+0x9050: SPU control
+0x9054: Reset HW blocks
+0x9058: VPU control
+0xA018: Bit6: interrupt pending?
+0xA064: APU command
+
+
+Interrupt Status Register
+=========================
+
+The definition of the bits in the interrupt status register 0x0040, and the
+interrupt mask 0x0048. If a bit is cleared in the mask, then we want our ISR to
+execute.
+
+Bit
+31 Encoder Start Capture
+30 Encoder EOS
+29 Encoder VBI capture
+28 Encoder Video Input Module reset event
+27 Encoder DMA complete
+26
+25 Decoder copy protect detection event
+24 Decoder audio mode change detection event
+23
+22 Decoder data request
+21 Decoder I-Frame? done
+20 Decoder DMA complete
+19 Decoder VBI re-insertion
+18 Decoder DMA err (linked-list bad)
+
+Missing
+Encoder API call completed
+Decoder API call completed
+Encoder API post(?)
+Decoder API post(?)
+Decoder VTRACE event
diff --git a/Documentation/video4linux/cx2341x/fw-osd-api.txt b/Documentation/video4linux/cx2341x/fw-osd-api.txt
new file mode 100644 (file)
index 0000000..da98ae3
--- /dev/null
@@ -0,0 +1,342 @@
+OSD firmware API description
+============================
+
+Note: this API is part of the decoder firmware, so it's cx23415 only.
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_FRAMEBUFFER
+Enum   65/0x41
+Description
+       Return base and length of contiguous OSD memory.
+Result[0]
+       OSD base address
+Result[1]
+       OSD length
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_PIXEL_FORMAT
+Enum   66/0x42
+Description
+       Query OSD format
+Result[0]
+       0=8bit index, 4=AlphaRGB 8:8:8:8
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_PIXEL_FORMAT
+Enum   67/0x43
+Description
+       Assign pixel format
+Param[0]
+       0=8bit index, 4=AlphaRGB 8:8:8:8
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_STATE
+Enum   68/0x44
+Description
+       Query OSD state
+Result[0]
+       Bit  0   0=off, 1=on
+       Bits 1:2 alpha control
+       Bits 3:5 pixel format
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_STATE
+Enum   69/0x45
+Description
+       OSD switch
+Param[0]
+       0=off, 1=on
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_OSD_COORDS
+Enum   70/0x46
+Description
+       Retrieve coordinates of OSD area blended with video
+Result[0]
+       OSD buffer address
+Result[1]
+       Stride in pixels
+Result[2]
+       Lines in OSD buffer
+Result[3]
+       Horizontal offset in buffer
+Result[4]
+       Vertical offset in buffer
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_OSD_COORDS
+Enum   71/0x47
+Description
+       Assign the coordinates of the OSD area to blend with video
+Param[0]
+       buffer address
+Param[1]
+       buffer stride in pixels
+Param[2]
+       lines in buffer
+Param[3]
+       horizontal offset
+Param[4]
+       vertical offset
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_SCREEN_COORDS
+Enum   72/0x48
+Description
+       Retrieve OSD screen area coordinates
+Result[0]
+       top left horizontal offset
+Result[1]
+       top left vertical offset
+Result[2]
+       bottom right hotizontal offset
+Result[3]
+       bottom right vertical offset
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_SCREEN_COORDS
+Enum   73/0x49
+Description
+       Assign the coordinates of the screen area to blend with video
+Param[0]
+       top left horizontal offset
+Param[1]
+       top left vertical offset
+Param[2]
+       bottom left horizontal offset
+Param[3]
+       bottom left vertical offset
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_GLOBAL_ALPHA
+Enum   74/0x4A
+Description
+       Retrieve OSD global alpha
+Result[0]
+       global alpha: 0=off, 1=on
+Result[1]
+       bits 0:7 global alpha
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_GLOBAL_ALPHA
+Enum   75/0x4B
+Description
+       Update global alpha
+Param[0]
+       global alpha: 0=off, 1=on
+Param[1]
+       global alpha (8 bits)
+Param[2]
+       local alpha: 0=on, 1=off
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_BLEND_COORDS
+Enum   78/0x4C
+Description
+       Move start of blending area within display buffer
+Param[0]
+       horizontal offset in buffer
+Param[1]
+       vertical offset in buffer
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_FLICKER_STATE
+Enum   79/0x4F
+Description
+       Retrieve flicker reduction module state
+Result[0]
+       flicker state: 0=off, 1=on
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_FLICKER_STATE
+Enum   80/0x50
+Description
+       Set flicker reduction module state
+Param[0]
+       State: 0=off, 1=on
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_BLT_COPY
+Enum   82/0x52
+Description
+       BLT copy
+Param[0]
+'0000'  zero
+'0001' ~destination AND ~source
+'0010' ~destination AND  source
+'0011' ~destination
+'0100'  destination AND ~source
+'0101'                  ~source
+'0110'  destination XOR  source
+'0111' ~destination OR  ~source
+'1000' ~destination AND ~source
+'1001'  destination XNOR source
+'1010'                   source
+'1011' ~destination OR   source
+'1100'  destination
+'1101'  destination OR  ~source
+'1110'  destination OR   source
+'1111'  one
+
+Param[1]
+       Resulting alpha blending
+           '01' source_alpha
+           '10' destination_alpha
+           '11' source_alpha*destination_alpha+1
+                (zero if both source and destination alpha are zero)
+Param[2]
+       '00' output_pixel = source_pixel
+
+       '01' if source_alpha=0:
+                output_pixel = destination_pixel
+            if 256 > source_alpha > 1:
+                output_pixel = ((source_alpha + 1)*source_pixel +
+                                (255 - source_alpha)*destination_pixel)/256
+
+       '10' if destination_alpha=0:
+                output_pixel = source_pixel
+             if 255 > destination_alpha > 0:
+                output_pixel = ((255 - destination_alpha)*source_pixel +
+                                (destination_alpha + 1)*destination_pixel)/256
+
+       '11' if source_alpha=0:
+                source_temp = 0
+            if source_alpha=255:
+                source_temp = source_pixel*256
+            if 255 > source_alpha > 0:
+                source_temp = source_pixel*(source_alpha + 1)
+            if destination_alpha=0:
+                destination_temp = 0
+            if destination_alpha=255:
+                destination_temp = destination_pixel*256
+            if 255 > destination_alpha > 0:
+                destination_temp = destination_pixel*(destination_alpha + 1)
+            output_pixel = (source_temp + destination_temp)/256
+Param[3]
+       width
+Param[4]
+       height
+Param[5]
+       destination pixel mask
+Param[6]
+       destination rectangle start address
+Param[7]
+       destination stride in dwords
+Param[8]
+       source stride in dwords
+Param[9]
+       source rectangle start address
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_BLT_FILL
+Enum   83/0x53
+Description
+       BLT fill color
+Param[0]
+       Same as Param[0] on API 0x52
+Param[1]
+       Same as Param[1] on API 0x52
+Param[2]
+       Same as Param[2] on API 0x52
+Param[3]
+       width
+Param[4]
+       height
+Param[5]
+       destination pixel mask
+Param[6]
+       destination rectangle start address
+Param[7]
+       destination stride in dwords
+Param[8]
+       color fill value
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_BLT_TEXT
+Enum   84/0x54
+Description
+       BLT for 8 bit alpha text source
+Param[0]
+       Same as Param[0] on API 0x52
+Param[1]
+       Same as Param[1] on API 0x52
+Param[2]
+       Same as Param[2] on API 0x52
+Param[3]
+       width
+Param[4]
+       height
+Param[5]
+       destination pixel mask
+Param[6]
+       destination rectangle start address
+Param[7]
+       destination stride in dwords
+Param[8]
+       source stride in dwords
+Param[9]
+       source rectangle start address
+Param[10]
+       color fill value
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_FRAMEBUFFER_WINDOW
+Enum   86/0x56
+Description
+       Positions the main output window on the screen. The coordinates must be
+       such that the entire window fits on the screen.
+Param[0]
+       window width
+Param[1]
+       window height
+Param[2]
+       top left window corner horizontal offset
+Param[3]
+       top left window corner vertical offset
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_CHROMA_KEY
+Enum   96/0x60
+Description
+       Chroma key switch and color
+Param[0]
+       state: 0=off, 1=on
+Param[1]
+       color
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_GET_ALPHA_CONTENT_INDEX
+Enum   97/0x61
+Description
+       Retrieve alpha content index
+Result[0]
+       alpha content index, Range 0:15
+
+-------------------------------------------------------------------------------
+
+Name   CX2341X_OSD_SET_ALPHA_CONTENT_INDEX
+Enum   98/0x62
+Description
+       Assign alpha content index
+Param[0]
+       alpha content index, range 0:15
diff --git a/Documentation/video4linux/cx2341x/fw-upload.txt b/Documentation/video4linux/cx2341x/fw-upload.txt
new file mode 100644 (file)
index 0000000..60c502c
--- /dev/null
@@ -0,0 +1,49 @@
+This document describes how to upload the cx2341x firmware to the card.
+
+How to find
+===========
+
+See the web pages of the various projects that uses this chip for information
+on how to obtain the firmware.
+
+The firmware stored in a Windows driver can be detected as follows:
+
+- Each firmware image is 256k bytes.
+- The 1st 32-bit word of the Encoder image is 0x0000da7
+- The 1st 32-bit word of the Decoder image is 0x00003a7
+- The 2nd 32-bit word of both images is 0xaa55bb66
+
+How to load
+===========
+
+- Issue the FWapi command to stop the encoder if it is running. Wait for the
+  command to complete.
+- Issue the FWapi command to stop the decoder if it is running. Wait for the
+  command to complete.
+- Issue the I2C command to the digitizer to stop emitting VSYNC events.
+- Issue the FWapi command to halt the encoder's firmware.
+- Sleep for 10ms.
+- Issue the FWapi command to halt the decoder's firmware.
+- Sleep for 10ms.
+- Write 0x00000000 to register 0x2800 to stop the Video Display Module.
+- Write 0x00000005 to register 0x2D00 to stop the AO (audio output?).
+- Write 0x00000000 to register 0xA064 to ping? the APU.
+- Write 0xFFFFFFFE to register 0x9058 to stop the VPU.
+- Write 0xFFFFFFFF to register 0x9054 to reset the HW blocks.
+- Write 0x00000001 to register 0x9050 to stop the SPU.
+- Sleep for 10ms.
+- Write 0x0000001A to register 0x07FC to init the Encoder SDRAM's pre-charge.
+- Write 0x80000640 to register 0x07F8 to init the Encoder SDRAM's refresh to 1us.
+- Write 0x0000001A to register 0x08FC to init the Decoder SDRAM's pre-charge.
+- Write 0x80000640 to register 0x08F8 to init the Decoder SDRAM's refresh to 1us.
+- Sleep for 512ms. (600ms is recommended)
+- Transfer the encoder's firmware image to offset 0 in Encoder memory space.
+- Transfer the decoder's firmware image to offset 0 in Decoder memory space.
+- Use a read-modify-write operation to Clear bit 0 of register 0x9050 to
+  re-enable the SPU.
+- Sleep for 1 second.
+- Use a read-modify-write operation to Clear bits 3 and 0 of register 0x9058
+  to re-enable the VPU.
+- Sleep for 1 second.
+- Issue status API commands to both firmware images to verify.
+
diff --git a/Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt b/Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt
new file mode 100644 (file)
index 0000000..93fec32
--- /dev/null
@@ -0,0 +1,54 @@
+The controls for the mux are GPIO [0,1] for source, and GPIO 2 for muting.
+
+GPIO0  GPIO1
+  0        0    TV Audio
+  1        0    FM radio
+  0        1    Line-In
+  1        1    Mono tuner bypass or CD passthru (tuner specific)
+
+GPIO 16(i believe) is tied to the IR port (if present).
+
+------------------------------------------------------------------------------------
+
+>From the data sheet:
+ Register 24'h20004  PCI Interrupt Status
+  bit [18]  IR_SMP_INT Set when 32 input samples have been collected over
+  gpio[16] pin into GP_SAMPLE register.
+
+What's missing from the data sheet:
+
+Setup 4KHz sampling rate (roughly 2x oversampled; good enough for our RC5
+compat remote)
+set register 0x35C050 to  0xa80a80
+
+enable sampling
+set register 0x35C054 to 0x5
+
+Of course, enable the IRQ bit 18 in the interrupt mask register .(and
+provide for a handler)
+
+GP_SAMPLE register is at 0x35C058
+
+Bits are then right shifted into the GP_SAMPLE register at the specified
+rate; you get an interrupt when a full DWORD is recieved.
+You need to recover the actual RC5 bits out of the (oversampled) IR sensor
+bits. (Hint: look for the 0/1and 1/0 crossings of the RC5 bi-phase data)  An
+actual raw RC5 code will span 2-3 DWORDS, depending on the actual alignment.
+
+I'm pretty sure when no IR signal is present the receiver is always in a
+marking state(1); but stray light, etc can cause intermittent noise values
+as well.  Remember, this is a free running sample of the IR receiver state
+over time, so don't assume any sample starts at any particular place.
+
+http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf
+This data sheet (google search) seems to have a lovely description of the
+RC5 basics
+
+http://users.pandora.be/nenya/electronics/rc5/  and more data
+
+http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt
+and even a reference to how to decode a bi-phase data stream.
+
+http://www.xs4all.nl/~sbp/knowledge/ir/rc5.htm
+still more info
+