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

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.

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

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

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