Decoder firmware API description
================================

-------------------------------------------------------------------------------

Name 	IVTV_API_DEC_PING_FW
Enum 	0/0x00 
Description
	This API call does nothing. It may be used to check if the firmware
	is responding. 

-------------------------------------------------------------------------------
 
Name 	IVTV_API_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 	IVTV_API_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 	IVTV_API_DEC_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 	IVTV_API_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 	IVTV_API_DEC_DMA_BLOCKSIZE
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 	IVTV_API_DEC_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 	IVTV_API_DEC_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 	IVTV_API_DEC_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 	IVTV_API_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 	IVTV_API_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 	IVTV_API_DEC_DISP_STANDARD
Enum 	16/0x10 
Description
	Selects display standard 
Param[0]
	0=NTSC, 1=PAL

-------------------------------------------------------------------------------
 
Name 	IVTV_API_DEC_GETVER
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 	IVTV_API_DEC_STREAM_INPUT
Enum 	20/0x14 
Description
	Select decoder stream input port 
Param[0]
	0=memory (default), 1=streaming

-------------------------------------------------------------------------------
 
Name 	IVTV_API_DEC_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 	IVTV_API_DEC_SELECT_AUDIO
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 	IVTV_API_DEC_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[32]
	Mailbox slot, -1 if no mailbox required.

-------------------------------------------------------------------------------
 
Name 	IVTV_API_DEC_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 	IVTV_API_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 	IVTV_API_DEC_DECODE_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 	IVTV_API_DEC_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 	IVTV_API_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 	IVTV_API_DEC_BUFFER
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 
