Documentation/media/v4l-drivers/pxa_camera.rst

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