Documentation/video4linux/cx2341x/fw-dma.txt

   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
  25 Flow
  26 ====
  27
  28 This section describes, in general, the order of events when handling DMA
  29 transfers. Detailed information follows this section.
  30
  31 - The card raises the Encoder interrupt.
  32 - The driver reads the transfer type, offset and size from Mailbox #10.
  33 - The driver constructs the scatter-gather array from enough free dma buffers
  34   to cover the size.
  35 - The driver schedules the DMA transfer via the ScheduleDMAtoHost API call.
  36 - The card raises the DMA Complete interrupt.
  37 - The driver checks the DMA status register for any errors.
  38 - The driver post-processes the newly transferred buffers.
  39
  40 NOTE! It is possible that the Encoder and DMA Complete interrupts get raised
  41 simultaneously. (End of the last, start of the next, etc.)
  42
  43 Mailbox #10
  44 ===========
  45
  46 The Flags, Command, Return Value and Timeout fields are ignored.
  47
  48 Name:       Mailbox #10
  49 Results[0]: Type: 0: MPEG.
  50 Results[1]: Offset: The position relative to the card's memory space.
  51 Results[2]: Size: The exact number of bytes to transfer.
  52
  53 My speculation is that since the StartCapture API has a capture type of "RAW"
  54 available, that the type field will have other values that correspond to YUV
  55 and PCM data.
  56
  57 Scatter-Gather Array
  58 ====================
  59
  60 The scatter-gather array is a contiguously allocated block of memory that
  61 tells the card the source and destination of each data-block to transfer.
  62 Card "addresses" are derived from the offset supplied by Mailbox #10. Host
  63 addresses are the physical memory location of the target DMA buffer.
  64
  65 Each S-G array element is a struct of three 32-bit words. The first word is
  66 the source address, the second is the destination address. Both take up the
  67 entire 32 bits. The lowest 16 bits of the third word is the transfer byte
  68 count. The high-bit of the third word is the "last" flag. The last-flag tells
  69 the card to raise the DMA_DONE interrupt. From hard personal experience, if
  70 you forget to set this bit, the card will still "work" but the stream will
  71 most likely get corrupted.
  72
  73 The transfer count must be a multiple of 256. Therefore, the driver will need
  74 to track how much data in the target buffer is valid and deal with it
  75 accordingly.
  76
  77 Array Element:
  78
  79 - 32-bit Source Address
  80 - 32-bit Destination Address
  81 - 16-bit reserved (high bit is the last flag)
  82 - 16-bit byte count
  83
  84 DMA Transfer Status
  85 ===================
  86
  87 Register 0x0004 holds the DMA Transfer Status:
  88
  89 Bit
  90 4   Scatter-Gather array error
  91 3   DMA write error
  92 2   DMA read error
  93 1   write completed
  94 0   read completed