[GitHub/mt8127/android_kernel_alcatel_ttab.git] / Documentation / video4linux / pxa_camera.txt

                              PXA-Camera Host Driver
                              ======================

Constraints
-----------
  a) Image size for YUV422P format
     All YUV422P images are enforced to have width x height % 16 = 0.
     This is due to DMA constraints, which transfers only planes of 8 byte
     multiples.


Global video workflow
---------------------
  a) QCI stopped
     Initialy, the QCI interface is stopped.
     When a buffer is queued (pxa_videobuf_ops->buf_queue), the QCI starts.

  b) QCI started
     More buffers can be queued while the QCI is started without halting the
     capture.  The new buffers are "appended" at the tail of the DMA chain, and
     smoothly captured one frame after the other.

     Once a buffer is filled in the QCI interface, it is marked as "DONE" and
     removed from the active buffers list. It can be then requeud or dequeued by
     userland application.

     Once the last buffer is filled in, the QCI interface stops.

  c) Capture global finite state machine schema

      +----+                             +---+  +----+
      | DQ |                             | Q |  | DQ |
      |    v                             |   v  |    v
    +-----------+                     +------------------------+
    |   STOP    |                     | Wait for capture start |
    +-----------+         Q           +------------------------+
+-> | QCI: stop | ------------------> | QCI: run               | <------------+
|   | DMA: stop |                     | DMA: stop              |              |
|   +-----------+             +-----> +------------------------+              |
|                            /                            |                   |
|                           /             +---+  +----+   |                   |
|capture list empty        /              | Q |  | DQ |   | QCI Irq EOF       |
|                         /               |   v  |    v   v                   |
|   +--------------------+             +----------------------+               |
|   | DMA hotlink missed |             |    Capture running   |               |
|   +--------------------+             +----------------------+               |
|   | QCI: run           |     +-----> | QCI: run             | <-+           |
|   | DMA: stop          |    /        | DMA: run             |   |           |
|   +--------------------+   /         +----------------------+   | Other     |
|     ^                     /DMA still            |               | channels  |
|     | capture list       /  running             | DMA Irq End   | not       |
|     | not empty         /                       |               | finished  |
|     |                  /                        v               | yet       |
|   +----------------------+           +----------------------+   |           |
|   |  Videobuf released   |           |  Channel completed   |   |           |
|   +----------------------+           +----------------------+   |           |
+-- | QCI: run             |           | QCI: run             | --+           |
    | DMA: run             |           | DMA: run             |               |
    +----------------------+           +----------------------+               |
               ^                      /           |                           |
               |          no overrun /            | overrun                   |
               |                    /             v                           |
    +--------------------+         /   +----------------------+               |
    |  Frame completed   |        /    |     Frame overran    |               |
    +--------------------+ <-----+     +----------------------+ restart frame |
    | QCI: run           |             | QCI: stop            | --------------+
    | DMA: run           |             | DMA: stop            |
    +--------------------+             +----------------------+

    Legend: - each box is a FSM state
            - each arrow is the condition to transition to another state
            - an arrow with a comment is a mandatory transition (no condition)
            - arrow "Q" means : a buffer was enqueued
            - arrow "DQ" means : a buffer was dequeued
            - "QCI: stop" means the QCI interface is not enabled
            - "DMA: stop" means all 3 DMA channels are stopped
            - "DMA: run" means at least 1 DMA channel is still running

DMA usage
---------
  a) DMA flow
     - first buffer queued for capture
       Once a first buffer is queued for capture, the QCI is started, but data
       transfer is not started. On "End Of Frame" interrupt, the irq handler
       starts the DMA chain.
     - capture of one videobuffer
       The DMA chain starts transferring data into videobuffer RAM pages.
       When all pages are transferred, the DMA irq is raised on "ENDINTR" status
     - finishing one videobuffer
       The DMA irq handler marks the videobuffer as "done", and removes it from
       the active running queue
       Meanwhile, the next videobuffer (if there is one), is transferred by DMA
     - finishing the last videobuffer
       On the DMA irq of the last videobuffer, the QCI is stopped.

  b) DMA prepared buffer will have this structure

     +------------+-----+---------------+-----------------+
     | desc-sg[0] | ... | desc-sg[last] | finisher/linker |
     +------------+-----+---------------+-----------------+

     This structure is pointed by dma->sg_cpu.
     The descriptors are used as follows :
      - desc-sg[i]: i-th descriptor, transferring the i-th sg
        element to the video buffer scatter gather
      - finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN
      - linker: has ddadr= desc-sg[0] of next video buffer, dcmd=0

     For the next schema, let's assume d0=desc-sg[0] .. dN=desc-sg[N],
     "f" stands for finisher and "l" for linker.
     A typical running chain is :

         Videobuffer 1         Videobuffer 2
     +---------+----+---+  +----+----+----+---+
     | d0 | .. | dN | l |  | d0 | .. | dN | f |
     +---------+----+-|-+  ^----+----+----+---+
                      |    |
                      +----+

     After the chaining is finished, the chain looks like :

         Videobuffer 1         Videobuffer 2         Videobuffer 3
     +---------+----+---+  +----+----+----+---+  +----+----+----+---+
     | d0 | .. | dN | l |  | d0 | .. | dN | l |  | d0 | .. | dN | f |
     +---------+----+-|-+  ^----+----+----+-|-+  ^----+----+----+---+
                      |    |                |    |
                      +----+                +----+
                                           new_link

  c) DMA hot chaining timeslice issue

     As DMA chaining is done while DMA _is_ running, the linking may be done
     while the DMA jumps from one Videobuffer to another. On the schema, that
     would be a problem if the following sequence is encountered :

      - DMA chain is Videobuffer1 + Videobuffer2
      - pxa_videobuf_queue() is called to queue Videobuffer3
      - DMA controller finishes Videobuffer2, and DMA stops
      =>
         Videobuffer 1         Videobuffer 2
     +---------+----+---+  +----+----+----+---+
     | d0 | .. | dN | l |  | d0 | .. | dN | f |
     +---------+----+-|-+  ^----+----+----+-^-+
                      |    |                |
                      +----+                +-- DMA DDADR loads DDADR_STOP

      - pxa_dma_add_tail_buf() is called, the Videobuffer2 "finisher" is
        replaced by a "linker" to Videobuffer3 (creation of new_link)
      - pxa_videobuf_queue() finishes
      - the DMA irq handler is called, which terminates Videobuffer2
      - Videobuffer3 capture is not scheduled on DMA chain (as it stopped !!!)

         Videobuffer 1         Videobuffer 2         Videobuffer 3
     +---------+----+---+  +----+----+----+---+  +----+----+----+---+
     | d0 | .. | dN | l |  | d0 | .. | dN | l |  | d0 | .. | dN | f |
     +---------+----+-|-+  ^----+----+----+-|-+  ^----+----+----+---+
                      |    |                |    |
                      +----+                +----+
                                           new_link
                                          DMA DDADR still is DDADR_STOP

      - pxa_camera_check_link_miss() is called
        This checks if the DMA is finished and a buffer is still on the
        pcdev->capture list. If that's the case, the capture will be restarted,
        and Videobuffer3 is scheduled on DMA chain.
      - the DMA irq handler finishes

     Note: if DMA stops just after pxa_camera_check_link_miss() reads DDADR()
     value, we have the guarantee that the DMA irq handler will be called back
     when the DMA will finish the buffer, and pxa_camera_check_link_miss() will
     be called again, to reschedule Videobuffer3.

--
Author: Robert Jarzmik <robert.jarzmik@free.fr>
Commit	Line	Data
256b0233 RJ	1	PXA-Camera Host Driver
	2	======================
	3
	4	Constraints
	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
	12	Global 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
56600093 RJ	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
256b0233 RJ	78
	79	DMA 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
25985edc LDM	87	The DMA chain starts transferring data into videobuffer RAM pages.
25985edc LDM	88	When all pages are transferred, the DMA irq is raised on "ENDINTR" status
256b0233 RJ	89	- finishing one videobuffer
	90	The DMA irq handler marks the videobuffer as "done", and removes it from
	91	the active running queue
25985edc	92	Meanwhile, the next videobuffer (if there is one), is transferred by DMA
256b0233 RJ	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 :
25985edc	104	- desc-sg[i]: i-th descriptor, transferring the i-th sg
256b0233 RJ	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	--
174	Author: Robert Jarzmik <robert.jarzmik@free.fr>