git.oblomov.eu Git - linux-2.6/blob - Documentation/video4linux/cx2341x/fw-decoder-api.txt

   1 Decoder firmware API description
   2 ================================
   3
   4 Note: this API is part of the decoder firmware, so it's cx23415 only.
   5
   6 -------------------------------------------------------------------------------
   7
   8 Name    CX2341X_DEC_PING_FW
   9 Enum    0/0x00
  10 Description
  11         This API call does nothing. It may be used to check if the firmware
  12         is responding.
  13
  14 -------------------------------------------------------------------------------
  15
  16 Name    CX2341X_DEC_START_PLAYBACK
  17 Enum    1/0x01
  18 Description
  19         Begin or resume playback.
  20 Param[0]
  21         0 based frame number in GOP to begin playback from.
  22 Param[1]
  23         Specifies the number of muted audio frames to play before normal
  24         audio resumes. (This is not implemented in the firmware, leave at 0)
  25
  26 -------------------------------------------------------------------------------
  27
  28 Name    CX2341X_DEC_STOP_PLAYBACK
  29 Enum    2/0x02
  30 Description
  31         Ends playback and clears all decoder buffers. If PTS is not zero,
  32         playback stops at specified PTS.
  33 Param[0]
  34         Display 0=last frame, 1=black
  35         Note: this takes effect immediately, so if you want to wait for a PTS,
  36         then use '0', otherwise the screen goes to black at once.
  37         You can call this later (even if there is no playback) with a 1 value
  38         to set the screen to black.
  39 Param[1]
  40         PTS low
  41 Param[2]
  42         PTS high
  43
  44 -------------------------------------------------------------------------------
  45
  46 Name    CX2341X_DEC_SET_PLAYBACK_SPEED
  47 Enum    3/0x03
  48 Description
  49         Playback stream at speed other than normal. There are two modes of
  50         operation:
  51             Smooth: host transfers entire stream and firmware drops unused
  52                     frames.
  53             Coarse: host drops frames based on indexing as required to achieve
  54                     desired speed.
  55 Param[0]
  56         Bitmap:
  57             0:7  0 normal
  58                  1 fast only "1.5 times"
  59                  n nX fast, 1/nX slow
  60             30   Framedrop:
  61                      '0' during 1.5 times play, every other B frame is dropped
  62                      '1' during 1.5 times play, stream is unchanged (bitrate
  63                          must not exceed 8mbps)
  64             31   Speed:
  65                      '0' slow
  66                      '1' fast
  67         Note: n is limited to 2. Anything higher does not result in
  68         faster playback. Instead the host should start dropping frames.
  69 Param[1]
  70         Direction: 0=forward, 1=reverse
  71         Note: to make reverse playback work you have to write full GOPs in
  72         reverse order.
  73 Param[2]
  74         Picture mask:
  75             1=I frames
  76             3=I, P frames
  77             7=I, P, B frames
  78 Param[3]
  79         B frames per GOP (for reverse play only)
  80         Note: for reverse playback the Picture Mask should be set to I or I, P.
  81         Adding B frames to the mask will result in corrupt video. This field
  82         has to be set to the correct value in order to keep the timing correct.
  83 Param[4]
  84         Mute audio: 0=disable, 1=enable
  85 Param[5]
  86         Display 0=frame, 1=field
  87 Param[6]
  88         Specifies the number of muted audio frames to play before normal audio
  89         resumes. (Not implemented in the firmware, leave at 0)
  90
  91 -------------------------------------------------------------------------------
  92
  93 Name    CX2341X_DEC_STEP_VIDEO
  94 Enum    5/0x05
  95 Description
  96         Each call to this API steps the playback to the next unit defined below
  97         in the current playback direction.
  98 Param[0]
  99         0=frame, 1=top field, 2=bottom field
 100
 101 -------------------------------------------------------------------------------
 102
 103 Name    CX2341X_DEC_SET_DMA_BLOCK_SIZE
 104 Enum    8/0x08
 105 Description
 106         Set DMA transfer block size. Counterpart to API 0xC9
 107 Param[0]
 108         DMA transfer block size in bytes. A different size may be specified
 109         when issuing the DMA transfer command.
 110
 111 -------------------------------------------------------------------------------
 112
 113 Name    CX2341X_DEC_GET_XFER_INFO
 114 Enum    9/0x09
 115 Description
 116         This API call may be used to detect an end of stream condition.
 117 Result[0]
 118         Stream type
 119 Result[1]
 120         Address offset
 121 Result[2]
 122         Maximum bytes to transfer
 123 Result[3]
 124         Buffer fullness
 125
 126 -------------------------------------------------------------------------------
 127
 128 Name    CX2341X_DEC_GET_DMA_STATUS
 129 Enum    10/0x0A
 130 Description
 131         Status of the last DMA transfer
 132 Result[0]
 133         Bit 1 set means transfer complete
 134         Bit 2 set means DMA error
 135         Bit 3 set means linked list error
 136 Result[1]
 137         DMA type: 0=MPEG, 1=OSD, 2=YUV
 138
 139 -------------------------------------------------------------------------------
 140
 141 Name    CX2341X_DEC_SCHED_DMA_FROM_HOST
 142 Enum    11/0x0B
 143 Description
 144         Setup DMA from host operation. Counterpart to API 0xCC
 145 Param[0]
 146         Memory address of link list
 147 Param[1]
 148         Total # of bytes to transfer
 149 Param[2]
 150         DMA type (0=MPEG, 1=OSD, 2=YUV)
 151
 152 -------------------------------------------------------------------------------
 153
 154 Name    CX2341X_DEC_PAUSE_PLAYBACK
 155 Enum    13/0x0D
 156 Description
 157         Freeze playback immediately. In this mode, when internal buffers are
 158         full, no more data will be accepted and data request IRQs will be
 159         masked.
 160 Param[0]
 161         Display: 0=last frame, 1=black
 162
 163 -------------------------------------------------------------------------------
 164
 165 Name    CX2341X_DEC_HALT_FW
 166 Enum    14/0x0E
 167 Description
 168         The firmware is halted and no further API calls are serviced until
 169         the firmware is uploaded again.
 170
 171 -------------------------------------------------------------------------------
 172
 173 Name    CX2341X_DEC_SET_STANDARD
 174 Enum    16/0x10
 175 Description
 176         Selects display standard
 177 Param[0]
 178         0=NTSC, 1=PAL
 179
 180 -------------------------------------------------------------------------------
 181
 182 Name    CX2341X_DEC_GET_VERSION
 183 Enum    17/0x11
 184 Description
 185         Returns decoder firmware version information
 186 Result[0]
 187         Version bitmask:
 188             Bits  0:15 build
 189             Bits 16:23 minor
 190             Bits 24:31 major
 191
 192 -------------------------------------------------------------------------------
 193
 194 Name    CX2341X_DEC_SET_STREAM_INPUT
 195 Enum    20/0x14
 196 Description
 197         Select decoder stream input port
 198 Param[0]
 199         0=memory (default), 1=streaming
 200
 201 -------------------------------------------------------------------------------
 202
 203 Name    CX2341X_DEC_GET_TIMING_INFO
 204 Enum    21/0x15
 205 Description
 206         Returns timing information from start of playback
 207 Result[0]
 208         Frame count by decode order
 209 Result[1]
 210         Video PTS bits 0:31 by display order
 211 Result[2]
 212         Video PTS bit 32 by display order
 213 Result[3]
 214         SCR bits 0:31 by display order
 215 Result[4]
 216         SCR bit 32 by display order
 217
 218 -------------------------------------------------------------------------------
 219
 220 Name    CX2341X_DEC_SET_AUDIO_MODE
 221 Enum    22/0x16
 222 Description
 223         Select audio mode
 224 Param[0]
 225         Dual mono mode action
 226             0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
 227 Param[1]
 228         Stereo mode action:
 229             0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
 230
 231 -------------------------------------------------------------------------------
 232
 233 Name    CX2341X_DEC_SET_EVENT_NOTIFICATION
 234 Enum    23/0x17
 235 Description
 236         Setup firmware to notify the host about a particular event.
 237         Counterpart to API 0xD5
 238 Param[0]
 239         Event: 0=Audio mode change between mono, (joint) stereo and dual channel.
 240         Event: 3=Decoder started
 241         Event: 4=Unknown: goes off 10-15 times per second while decoding.
 242         Event: 5=Some sync event: goes off once per frame.
 243 Param[1]
 244         Notification 0=disabled, 1=enabled
 245 Param[2]
 246         Interrupt bit
 247 Param[3]
 248         Mailbox slot, -1 if no mailbox required.
 249
 250 -------------------------------------------------------------------------------
 251
 252 Name    CX2341X_DEC_SET_DISPLAY_BUFFERS
 253 Enum    24/0x18
 254 Description
 255         Number of display buffers. To decode all frames in reverse playback you
 256         must use nine buffers.
 257 Param[0]
 258         0=six buffers, 1=nine buffers
 259
 260 -------------------------------------------------------------------------------
 261
 262 Name    CX2341X_DEC_EXTRACT_VBI
 263 Enum    25/0x19
 264 Description
 265         Extracts VBI data
 266 Param[0]
 267         0=extract from extension & user data, 1=extract from private packets
 268 Result[0]
 269         VBI table location
 270 Result[1]
 271         VBI table size
 272
 273 -------------------------------------------------------------------------------
 274
 275 Name    CX2341X_DEC_SET_DECODER_SOURCE
 276 Enum    26/0x1A
 277 Description
 278         Selects decoder source. Ensure that the parameters passed to this
 279         API match the encoder settings.
 280 Param[0]
 281         Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host
 282 Param[1]
 283         YUV picture width
 284 Param[2]
 285         YUV picture height
 286 Param[3]
 287         Bitmap: see Param[0] of API 0xBD
 288
 289 -------------------------------------------------------------------------------
 290
 291 Name    CX2341X_DEC_SET_PREBUFFERING
 292 Enum    30/0x1E
 293 Description
 294         Decoder prebuffering, when enabled up to 128KB are buffered for
 295         streams <8mpbs or 640KB for streams >8mbps
 296 Param[0]
 297         0=off, 1=on