Documentation/media/v4l-drivers/pxa_camera.rst

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