Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a785ddb8 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[media] doc-rst: start adding documentation for cx2341x 



move the contents of fw-decoder-api.txt to cx2341x and
convert it to ReST file, adding it to media/v4l-drivers

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent d197a370

Documentation/media/v4l-drivers/cx2341x.rst

0 → 100644
+564 −0
Original line number Diff line number Diff line 
The cx2341x driver

==================



Decoder firmware API description

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



.. note:: this API is part of the decoder firmware, so it's cx23415 only.







CX2341X_DEC_PING_FW

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



Enum: 0/0x00



Description

~~~~~~~~~~~



This API call does nothing. It may be used to check if the firmware

is responding.







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. (This is not implemented in the firmware, leave at 0)







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



.. note::



	this takes effect immediately, so if you want to wait for a PTS,

	then use '0', otherwise the screen goes to black at once.

	You can call this later (even if there is no playback) with a 1 value

	to set the screen to black.



Param[1]

~~~~~~~~



PTS low



Param[2]

~~~~~~~~



PTS high







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]

~~~~~~~~



.. code-block:: none



	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



.. note::



	n is limited to 2. Anything higher does not result in

	faster playback. Instead the host should start dropping frames.



Param[1]

~~~~~~~~



Direction: 0=forward, 1=reverse



.. note::



	to make reverse playback work you have to write full GOPs in

	reverse order.



Param[2]

~~~~~~~~



.. code-block:: none



	Picture mask:

	    1=I frames

	    3=I, P frames

	    7=I, P, B frames



Param[3]

~~~~~~~~



B frames per GOP (for reverse play only)



.. note::



	for reverse playback the Picture Mask should be set to I or I, P.

	Adding B frames to the mask will result in corrupt video. This field

	has to be set to the correct value in order to keep the timing correct.



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. (Not implemented in the firmware, leave at 0)







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







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.







CX2341X_DEC_GET_XFER_INFO

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



Enum: 9/0x09



Description

~~~~~~~~~~~



This API call may be used to detect an end of stream condition.



Result[0]

~~~~~~~~~



Stream type



Result[1]

~~~~~~~~~



Address offset



Result[2]

~~~~~~~~~



Maximum bytes to transfer



Result[3]

~~~~~~~~~



Buffer fullness







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







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)







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







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.







CX2341X_DEC_SET_STANDARD

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



Enum: 16/0x10



Description

~~~~~~~~~~~



Selects display standard



Param[0]

~~~~~~~~



0=NTSC, 1=PAL







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







CX2341X_DEC_SET_STREAM_INPUT

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



Enum: 20/0x14



Description

~~~~~~~~~~~



Select decoder stream input port



Param[0]

~~~~~~~~



0=memory (default), 1=streaming







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







CX2341X_DEC_SET_AUDIO_MODE

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



Enum: 22/0x16



Description

~~~~~~~~~~~



Select audio mode



Param[0]

~~~~~~~~



Dual mono mode action

	0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged



Param[1]

~~~~~~~~



Stereo mode action:

	0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged







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 mono, (joint) stereo and dual channel.

	- 3=Decoder started

	- 4=Unknown: goes off 10-15 times per second while decoding.

	- 5=Some sync event: goes off once per frame.



Param[1]

~~~~~~~~



Notification 0=disabled, 1=enabled



Param[2]

~~~~~~~~



Interrupt bit



Param[3]

~~~~~~~~



Mailbox slot, -1 if no mailbox required.







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







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







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







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

Documentation/media/v4l-drivers/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -27,6 +27,7 @@ License". 
	cafe_ccic

	cpia2

	cx18

	cx2341x

	cx88

	davinci-vpbe

	fimc

Documentation/video4linux/cx2341x/fw-decoder-api.txt

deleted100644 → 0
+0 −297
Original line number Diff line number Diff line 
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. (This is not implemented in the firmware, leave at 0)



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



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

	Note: this takes effect immediately, so if you want to wait for a PTS,

	then use '0', otherwise the screen goes to black at once.

	You can call this later (even if there is no playback) with a 1 value

	to set the screen to 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

	Note: n is limited to 2. Anything higher does not result in

	faster playback. Instead the host should start dropping frames.

Param[1]

	Direction: 0=forward, 1=reverse

	Note: to make reverse playback work you have to write full GOPs in

	reverse order.

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)

	Note: for reverse playback the Picture Mask should be set to I or I, P.

	Adding B frames to the mask will result in corrupt video. This field

	has to be set to the correct value in order to keep the timing correct.

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. (Not implemented in the firmware, leave at 0)



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



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

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

	    0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged

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 mono, (joint) stereo and dual channel.

	Event: 3=Decoder started

	Event: 4=Unknown: goes off 10-15 times per second while decoding.

	Event: 5=Some sync event: goes off once per frame.

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