[deliverable/linux.git] / Documentation / video4linux / cx2341x / fw-dma.txt

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.

Note: the hardware expects little-endian data ('intel format').

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 18 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
- 14-bit reserved (high bit is the last flag)
- 18-bit byte count

DMA Transfer Status
===================

Register 0x0004 holds the DMA Transfer Status:

Bit
0   read completed
1   write completed
2   DMA read error
3   DMA write error
4   Scatter-Gather array error
Commit	Line	Data
447d6fb8 MCC	1	This page describes the structures and procedures used by the cx2341x DMA
	2	engine.
	3
	4	Introduction
	5	============
	6
	7	The cx2341x PCI interface is busmaster capable. This means it has a DMA
	8	engine to efficiently transfer large volumes of data between the card and main
	9	memory without requiring help from a CPU. Like most hardware, it must operate
	10	on contiguous physical memory. This is difficult to come by in large quantities
	11	on virtual memory machines.
	12
	13	Therefore, it also supports a technique called "scatter-gather". The card can
	14	transfer multiple buffers in one operation. Instead of allocating one large
	15	contiguous buffer, the driver can allocate several smaller buffers.
	16
	17	In practice, I've seen the average transfer to be roughly 80K, but transfers
	18	above 128K were not uncommon, particularly at startup. The 128K figure is
	19	important, because that is the largest block that the kernel can normally
	20	allocate. Even still, 128K blocks are hard to come by, so the driver writer is
	21	urged to choose a smaller block size and learn the scatter-gather technique.
	22
	23	Mailbox #10 is reserved for DMA transfer information.
	24
a63ad325 HV	25	Note: the hardware expects little-endian data ('intel format').
a63ad325 HV	26
447d6fb8 MCC	27	Flow
	28	====
	29
	30	This section describes, in general, the order of events when handling DMA
	31	transfers. Detailed information follows this section.
	32
	33	- The card raises the Encoder interrupt.
	34	- The driver reads the transfer type, offset and size from Mailbox #10.
	35	- The driver constructs the scatter-gather array from enough free dma buffers
	36	to cover the size.
	37	- The driver schedules the DMA transfer via the ScheduleDMAtoHost API call.
	38	- The card raises the DMA Complete interrupt.
	39	- The driver checks the DMA status register for any errors.
	40	- The driver post-processes the newly transferred buffers.
	41
	42	NOTE! It is possible that the Encoder and DMA Complete interrupts get raised
	43	simultaneously. (End of the last, start of the next, etc.)
	44
	45	Mailbox #10
	46	===========
	47
	48	The Flags, Command, Return Value and Timeout fields are ignored.
	49
	50	Name: Mailbox #10
	51	Results[0]: Type: 0: MPEG.
	52	Results[1]: Offset: The position relative to the card's memory space.
	53	Results[2]: Size: The exact number of bytes to transfer.
	54
	55	My speculation is that since the StartCapture API has a capture type of "RAW"
	56	available, that the type field will have other values that correspond to YUV
	57	and PCM data.
	58
	59	Scatter-Gather Array
	60	====================
	61
	62	The scatter-gather array is a contiguously allocated block of memory that
	63	tells the card the source and destination of each data-block to transfer.
	64	Card "addresses" are derived from the offset supplied by Mailbox #10. Host
	65	addresses are the physical memory location of the target DMA buffer.
	66
	67	Each S-G array element is a struct of three 32-bit words. The first word is
	68	the source address, the second is the destination address. Both take up the
a63ad325	69	entire 32 bits. The lowest 18 bits of the third word is the transfer byte
447d6fb8 MCC	70	count. The high-bit of the third word is the "last" flag. The last-flag tells
	71	the card to raise the DMA_DONE interrupt. From hard personal experience, if
	72	you forget to set this bit, the card will still "work" but the stream will
	73	most likely get corrupted.
	74
	75	The transfer count must be a multiple of 256. Therefore, the driver will need
	76	to track how much data in the target buffer is valid and deal with it
	77	accordingly.
	78
	79	Array Element:
	80
	81	- 32-bit Source Address
	82	- 32-bit Destination Address
a63ad325 HV	83	- 14-bit reserved (high bit is the last flag)
a63ad325 HV	84	- 18-bit byte count
447d6fb8 MCC	85
	86	DMA Transfer Status
	87	===================
	88
	89	Register 0x0004 holds the DMA Transfer Status:
	90
	91	Bit
447d6fb8	92	0 read completed
a63ad325 HV	93	1 write completed
	94	2 DMA read error
	95	3 DMA write error
	96	4 Scatter-Gather array error