adulau/aha
1
0
Fork 0
mirror of https://github.com/adulau/aha.git synced 2024-12-28 11:46:19 +00:00
Code Issues Projects Releases Packages Wiki Activity

V4L/DVB (3809b): Added missing docs at kernel tree

Browse source 
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>
This commit is contained in:
Mauro Carvalho Chehab 2006-05-22 10:31:37 -03:00
parent b8d4c235d5
commit 447d6fb8cc
8 changed files with 1740 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

69
Documentation/video4linux/cx2341x/fw-calling.txt Normal file
View file

@ -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.

319
Documentation/video4linux/cx2341x/fw-decoder-api.txt Normal file
View file

@ -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

94
Documentation/video4linux/cx2341x/fw-dma.txt Normal file
View file

@ -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

672
Documentation/video4linux/cx2341x/fw-encoder-api.txt Normal file
View file

@ -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.

141
Documentation/video4linux/cx2341x/fw-memory.txt Normal file
View file

@ -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

342
Documentation/video4linux/cx2341x/fw-osd-api.txt Normal file
View file

@ -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

49
Documentation/video4linux/cx2341x/fw-upload.txt Normal file
View file

@ -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.

54
Documentation/video4linux/cx88/hauppauge-wintv-cx88-ir.txt Normal file
View file

@ -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