1.. SPDX-License-Identifier: GPL-2.0
2
3PXA-Camera Host Driver
4======================
5
6Author: Robert Jarzmik <robert.jarzmik@free.fr>
7
8Constraints
9-----------
10
11a) 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
17Global video workflow
18---------------------
19
20a) QCI stopped
21   Initially, the QCI interface is stopped.
22   When a buffer is queued, start_streaming is called and the QCI starts.
23
24b) 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
35c) 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
87DMA usage
88---------
89
90a) 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
105b) 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
113This structure is pointed by dma->sg_cpu.
114The 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
121For the next schema, let's assume d0=desc-sg[0] .. dN=desc-sg[N],
122"f" stands for finisher and "l" for linker.
123A 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
134After 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
146c) DMA hot chaining timeslice issue
147
148As DMA chaining is done while DMA _is_ running, the linking may be done
149while the DMA jumps from one Videobuffer to another. On the schema, that
150would 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.
195