linux/Documentation/video4linux/pxa_camera.txt
<<
>>
Prefs
   1                              PXA-Camera Host Driver
   2                              ======================
   3
   4Constraints
   5-----------
   6  a) Image size for YUV422P format
   7     All YUV422P images are enforced to have width x height % 16 = 0.
   8     This is due to DMA constraints, which transfers only planes of 8 byte
   9     multiples.
  10
  11
  12Global video workflow
  13---------------------
  14  a) QCI stopped
  15     Initialy, the QCI interface is stopped.
  16     When a buffer is queued (pxa_videobuf_ops->buf_queue), the QCI starts.
  17
  18  b) QCI started
  19     More buffers can be queued while the QCI is started without halting the
  20     capture.  The new buffers are "appended" at the tail of the DMA chain, and
  21     smoothly captured one frame after the other.
  22
  23     Once a buffer is filled in the QCI interface, it is marked as "DONE" and
  24     removed from the active buffers list. It can be then requeud or dequeued by
  25     userland application.
  26
  27     Once the last buffer is filled in, the QCI interface stops.
  28
  29  c) Capture global finite state machine schema
  30
  31      +----+                             +---+  +----+
  32      | DQ |                             | Q |  | DQ |
  33      |    v                             |   v  |    v
  34    +-----------+                     +------------------------+
  35    |   STOP    |                     | Wait for capture start |
  36    +-----------+         Q           +------------------------+
  37+-> | QCI: stop | ------------------> | QCI: run               | <------------+
  38|   | DMA: stop |                     | DMA: stop              |              |
  39|   +-----------+             +-----> +------------------------+              |
  40|                            /                            |                   |
  41|                           /             +---+  +----+   |                   |
  42|capture list empty        /              | Q |  | DQ |   | QCI Irq EOF       |
  43|                         /               |   v  |    v   v                   |
  44|   +--------------------+             +----------------------+               |
  45|   | DMA hotlink missed |             |    Capture running   |               |
  46|   +--------------------+             +----------------------+               |
  47|   | QCI: run           |     +-----> | QCI: run             | <-+           |
  48|   | DMA: stop          |    /        | DMA: run             |   |           |
  49|   +--------------------+   /         +----------------------+   | Other     |
  50|     ^                     /DMA still            |               | channels  |
  51|     | capture list       /  running             | DMA Irq End   | not       |
  52|     | not empty         /                       |               | finished  |
  53|     |                  /                        v               | yet       |
  54|   +----------------------+           +----------------------+   |           |
  55|   |  Videobuf released   |           |  Channel completed   |   |           |
  56|   +----------------------+           +----------------------+   |           |
  57+-- | QCI: run             |           | QCI: run             | --+           |
  58    | DMA: run             |           | DMA: run             |               |
  59    +----------------------+           +----------------------+               |
  60               ^                      /           |                           |
  61               |          no overrun /            | overrun                   |
  62               |                    /             v                           |
  63    +--------------------+         /   +----------------------+               |
  64    |  Frame completed   |        /    |     Frame overran    |               |
  65    +--------------------+ <-----+     +----------------------+ restart frame |
  66    | QCI: run           |             | QCI: stop            | --------------+
  67    | DMA: run           |             | DMA: stop            |
  68    +--------------------+             +----------------------+
  69
  70    Legend: - each box is a FSM state
  71            - each arrow is the condition to transition to another state
  72            - an arrow with a comment is a mandatory transition (no condition)
  73            - arrow "Q" means : a buffer was enqueued
  74            - arrow "DQ" means : a buffer was dequeued
  75            - "QCI: stop" means the QCI interface is not enabled
  76            - "DMA: stop" means all 3 DMA channels are stopped
  77            - "DMA: run" means at least 1 DMA channel is still running
  78
  79DMA usage
  80---------
  81  a) DMA flow
  82     - first buffer queued for capture
  83       Once a first buffer is queued for capture, the QCI is started, but data
  84       transfer is not started. On "End Of Frame" interrupt, the irq handler
  85       starts the DMA chain.
  86     - capture of one videobuffer
  87       The DMA chain starts transferring data into videobuffer RAM pages.
  88       When all pages are transferred, the DMA irq is raised on "ENDINTR" status
  89     - finishing one videobuffer
  90       The DMA irq handler marks the videobuffer as "done", and removes it from
  91       the active running queue
  92       Meanwhile, the next videobuffer (if there is one), is transferred by DMA
  93     - finishing the last videobuffer
  94       On the DMA irq of the last videobuffer, the QCI is stopped.
  95
  96  b) DMA prepared buffer will have this structure
  97
  98     +------------+-----+---------------+-----------------+
  99     | desc-sg[0] | ... | desc-sg[last] | finisher/linker |
 100     +------------+-----+---------------+-----------------+
 101
 102     This structure is pointed by dma->sg_cpu.
 103     The descriptors are used as follows :
 104      - desc-sg[i]: i-th descriptor, transferring the i-th sg
 105        element to the video buffer scatter gather
 106      - finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN
 107      - linker: has ddadr= desc-sg[0] of next video buffer, dcmd=0
 108
 109     For the next schema, let's assume d0=desc-sg[0] .. dN=desc-sg[N],
 110     "f" stands for finisher and "l" for linker.
 111     A typical running chain is :
 112
 113         Videobuffer 1         Videobuffer 2
 114     +---------+----+---+  +----+----+----+---+
 115     | d0 | .. | dN | l |  | d0 | .. | dN | f |
 116     +---------+----+-|-+  ^----+----+----+---+
 117                      |    |
 118                      +----+
 119
 120     After the chaining is finished, the chain looks like :
 121
 122         Videobuffer 1         Videobuffer 2         Videobuffer 3
 123     +---------+----+---+  +----+----+----+---+  +----+----+----+---+
 124     | d0 | .. | dN | l |  | d0 | .. | dN | l |  | d0 | .. | dN | f |
 125     +---------+----+-|-+  ^----+----+----+-|-+  ^----+----+----+---+
 126                      |    |                |    |
 127                      +----+                +----+
 128                                           new_link
 129
 130  c) DMA hot chaining timeslice issue
 131
 132     As DMA chaining is done while DMA _is_ running, the linking may be done
 133     while the DMA jumps from one Videobuffer to another. On the schema, that
 134     would be a problem if the following sequence is encountered :
 135
 136      - DMA chain is Videobuffer1 + Videobuffer2
 137      - pxa_videobuf_queue() is called to queue Videobuffer3
 138      - DMA controller finishes Videobuffer2, and DMA stops
 139      =>
 140         Videobuffer 1         Videobuffer 2
 141     +---------+----+---+  +----+----+----+---+
 142     | d0 | .. | dN | l |  | d0 | .. | dN | f |
 143     +---------+----+-|-+  ^----+----+----+-^-+
 144                      |    |                |
 145                      +----+                +-- DMA DDADR loads DDADR_STOP
 146
 147      - pxa_dma_add_tail_buf() is called, the Videobuffer2 "finisher" is
 148        replaced by a "linker" to Videobuffer3 (creation of new_link)
 149      - pxa_videobuf_queue() finishes
 150      - the DMA irq handler is called, which terminates Videobuffer2
 151      - Videobuffer3 capture is not scheduled on DMA chain (as it stopped !!!)
 152
 153         Videobuffer 1         Videobuffer 2         Videobuffer 3
 154     +---------+----+---+  +----+----+----+---+  +----+----+----+---+
 155     | d0 | .. | dN | l |  | d0 | .. | dN | l |  | d0 | .. | dN | f |
 156     +---------+----+-|-+  ^----+----+----+-|-+  ^----+----+----+---+
 157                      |    |                |    |
 158                      +----+                +----+
 159                                           new_link
 160                                          DMA DDADR still is DDADR_STOP
 161
 162      - pxa_camera_check_link_miss() is called
 163        This checks if the DMA is finished and a buffer is still on the
 164        pcdev->capture list. If that's the case, the capture will be restarted,
 165        and Videobuffer3 is scheduled on DMA chain.
 166      - the DMA irq handler finishes
 167
 168     Note: if DMA stops just after pxa_camera_check_link_miss() reads DDADR()
 169     value, we have the guarantee that the DMA irq handler will be called back
 170     when the DMA will finish the buffer, and pxa_camera_check_link_miss() will
 171     be called again, to reschedule Videobuffer3.
 172
 173--
 174Author: Robert Jarzmik <robert.jarzmik@free.fr>
 175
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.