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