About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / arm / OMAP / DSS


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

1	OMAP2/3 Display Subsystem
2	-------------------------
3	
4	This is an almost total rewrite of the OMAP FB driver in drivers/video/omap
5	(let's call it DSS1). The main differences between DSS1 and DSS2 are DSI,
6	TV-out and multiple display support, but there are lots of small improvements
7	also.
8	
9	The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB,
10	panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live
11	currently side by side, you can choose which one to use.
12	
13	Features
14	--------
15	
16	Working and tested features include:
17	
18	- MIPI DPI (parallel) output
19	- MIPI DSI output in command mode
20	- MIPI DBI (RFBI) output
21	- SDI output
22	- TV output
23	- All pieces can be compiled as a module or inside kernel
24	- Use DISPC to update any of the outputs
25	- Use CPU to update RFBI or DSI output
26	- OMAP DISPC planes
27	- RGB16, RGB24 packed, RGB24 unpacked
28	- YUV2, UYVY
29	- Scaling
30	- Adjusting DSS FCK to find a good pixel clock
31	- Use DSI DPLL to create DSS FCK
32	
33	Tested boards include:
34	- OMAP3 SDP board
35	- Beagle board
36	- N810
37	
38	omapdss driver
39	--------------
40	
41	The DSS driver does not itself have any support for Linux framebuffer, V4L or
42	such like the current ones, but it has an internal kernel API that upper level
43	drivers can use.
44	
45	The DSS driver models OMAP's overlays, overlay managers and displays in a
46	flexible way to enable non-common multi-display configuration. In addition to
47	modelling the hardware overlays, omapdss supports virtual overlays and overlay
48	managers. These can be used when updating a display with CPU or system DMA.
49	
50	omapdss driver support for audio
51	--------------------------------
52	There exist several display technologies and standards that support audio as
53	well. Hence, it is relevant to update the DSS device driver to provide an audio
54	interface that may be used by an audio driver or any other driver interested in
55	the functionality.
56	
57	The audio_enable function is intended to prepare the relevant
58	IP for playback (e.g., enabling an audio FIFO, taking in/out of reset
59	some IP, enabling companion chips, etc). It is intended to be called before
60	audio_start. The audio_disable function performs the reverse operation and is
61	intended to be called after audio_stop.
62	
63	While a given DSS device driver may support audio, it is possible that for
64	certain configurations audio is not supported (e.g., an HDMI display using a
65	VESA video timing). The audio_supported function is intended to query whether
66	the current configuration of the display supports audio.
67	
68	The audio_config function is intended to configure all the relevant audio
69	parameters of the display. In order to make the function independent of any
70	specific DSS device driver, a struct omap_dss_audio is defined. Its purpose
71	is to contain all the required parameters for audio configuration. At the
72	moment, such structure contains pointers to IEC-60958 channel status word
73	and CEA-861 audio infoframe structures. This should be enough to support
74	HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958.
75	
76	The audio_enable/disable, audio_config and audio_supported functions could be
77	implemented as functions that may sleep. Hence, they should not be called
78	while holding a spinlock or a readlock.
79	
80	The audio_start/audio_stop function is intended to effectively start/stop audio
81	playback after the configuration has taken place. These functions are designed
82	to be used in an atomic context. Hence, audio_start should return quickly and be
83	called only after all the needed resources for audio playback (audio FIFOs,
84	DMA channels, companion chips, etc) have been enabled to begin data transfers.
85	audio_stop is designed to only stop the audio transfers. The resources used
86	for playback are released using audio_disable.
87	
88	The enum omap_dss_audio_state may be used to help the implementations of
89	the interface to keep track of the audio state. The initial state is _DISABLED;
90	then, the state transitions to _CONFIGURED, and then, when it is ready to
91	play audio, to _ENABLED. The state _PLAYING is used when the audio is being
92	rendered.
93	
94	
95	Panel and controller drivers
96	----------------------------
97	
98	The drivers implement panel or controller specific functionality and are not
99	usually visible to users except through omapfb driver.  They register
100	themselves to the DSS driver.
101	
102	omapfb driver
103	-------------
104	
105	The omapfb driver implements arbitrary number of standard linux framebuffers.
106	These framebuffers can be routed flexibly to any overlays, thus allowing very
107	dynamic display architecture.
108	
109	The driver exports some omapfb specific ioctls, which are compatible with the
110	ioctls in the old driver.
111	
112	The rest of the non standard features are exported via sysfs. Whether the final
113	implementation will use sysfs, or ioctls, is still open.
114	
115	V4L2 drivers
116	------------
117	
118	V4L2 is being implemented in TI.
119	
120	From omapdss point of view the V4L2 drivers should be similar to framebuffer
121	driver.
122	
123	Architecture
124	--------------------
125	
126	Some clarification what the different components do:
127	
128	    - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the
129	      pixel data for the image. Framebuffer has width and height and color
130	      depth.
131	    - Overlay defines where the pixels are read from and where they go on the
132	      screen. The overlay may be smaller than framebuffer, thus displaying only
133	      part of the framebuffer. The position of the overlay may be changed if
134	      the overlay is smaller than the display.
135	    - Overlay manager combines the overlays in to one image and feeds them to
136	      display.
137	    - Display is the actual physical display device.
138	
139	A framebuffer can be connected to multiple overlays to show the same pixel data
140	on all of the overlays. Note that in this case the overlay input sizes must be
141	the same, but, in case of video overlays, the output size can be different. Any
142	framebuffer can be connected to any overlay.
143	
144	An overlay can be connected to one overlay manager. Also DISPC overlays can be
145	connected only to DISPC overlay managers, and virtual overlays can be only
146	connected to virtual overlays.
147	
148	An overlay manager can be connected to one display. There are certain
149	restrictions which kinds of displays an overlay manager can be connected:
150	
151	    - DISPC TV overlay manager can be only connected to TV display.
152	    - Virtual overlay managers can only be connected to DBI or DSI displays.
153	    - DISPC LCD overlay manager can be connected to all displays, except TV
154	      display.
155	
156	Sysfs
157	-----
158	The sysfs interface is mainly used for testing. I don't think sysfs
159	interface is the best for this in the final version, but I don't quite know
160	what would be the best interfaces for these things.
161	
162	The sysfs interface is divided to two parts: DSS and FB.
163	
164	/sys/class/graphics/fb? directory:
165	mirror		0=off, 1=on
166	rotate		Rotation 0-3 for 0, 90, 180, 270 degrees
167	rotate_type	0 = DMA rotation, 1 = VRFB rotation
168	overlays	List of overlay numbers to which framebuffer pixels go
169	phys_addr	Physical address of the framebuffer
170	virt_addr	Virtual address of the framebuffer
171	size		Size of the framebuffer
172	
173	/sys/devices/platform/omapdss/overlay? directory:
174	enabled		0=off, 1=on
175	input_size	width,height (ie. the framebuffer size)
176	manager		Destination overlay manager name
177	name
178	output_size	width,height
179	position	x,y
180	screen_width	width
181	global_alpha   	global alpha 0-255 0=transparent 255=opaque
182	
183	/sys/devices/platform/omapdss/manager? directory:
184	display				Destination display
185	name
186	alpha_blending_enabled		0=off, 1=on
187	trans_key_enabled		0=off, 1=on
188	trans_key_type			gfx-destination, video-source
189	trans_key_value			transparency color key (RGB24)
190	default_color			default background color (RGB24)
191	
192	/sys/devices/platform/omapdss/display? directory:
193	ctrl_name	Controller name
194	mirror		0=off, 1=on
195	update_mode	0=off, 1=auto, 2=manual
196	enabled		0=off, 1=on
197	name
198	rotate		Rotation 0-3 for 0, 90, 180, 270 degrees
199	timings		Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw)
200			When writing, two special timings are accepted for tv-out:
201			"pal" and "ntsc"
202	panel_name
203	tear_elim	Tearing elimination 0=off, 1=on
204	output_type	Output type (video encoder only): "composite" or "svideo"
205	
206	There are also some debugfs files at <debugfs>/omapdss/ which show information
207	about clocks and registers.
208	
209	Examples
210	--------
211	
212	The following definitions have been made for the examples below:
213	
214	ovl0=/sys/devices/platform/omapdss/overlay0
215	ovl1=/sys/devices/platform/omapdss/overlay1
216	ovl2=/sys/devices/platform/omapdss/overlay2
217	
218	mgr0=/sys/devices/platform/omapdss/manager0
219	mgr1=/sys/devices/platform/omapdss/manager1
220	
221	lcd=/sys/devices/platform/omapdss/display0
222	dvi=/sys/devices/platform/omapdss/display1
223	tv=/sys/devices/platform/omapdss/display2
224	
225	fb0=/sys/class/graphics/fb0
226	fb1=/sys/class/graphics/fb1
227	fb2=/sys/class/graphics/fb2
228	
229	Default setup on OMAP3 SDP
230	--------------------------
231	
232	Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI
233	and TV-out are not in use. The columns from left to right are:
234	framebuffers, overlays, overlay managers, displays. Framebuffers are
235	handled by omapfb, and the rest by the DSS.
236	
237	FB0 --- GFX  -\            DVI
238	FB1 --- VID1 --+- LCD ---- LCD
239	FB2 --- VID2 -/   TV ----- TV
240	
241	Example: Switch from LCD to DVI
242	----------------------
243	
244	w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1`
245	h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1`
246	
247	echo "0" > $lcd/enabled
248	echo "" > $mgr0/display
249	fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
250	# at this point you have to switch the dvi/lcd dip-switch from the omap board
251	echo "dvi" > $mgr0/display
252	echo "1" > $dvi/enabled
253	
254	After this the configuration looks like:
255	
256	FB0 --- GFX  -\         -- DVI
257	FB1 --- VID1 --+- LCD -/   LCD
258	FB2 --- VID2 -/   TV ----- TV
259	
260	Example: Clone GFX overlay to LCD and TV
261	-------------------------------
262	
263	w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1`
264	h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1`
265	
266	echo "0" > $ovl0/enabled
267	echo "0" > $ovl1/enabled
268	
269	echo "" > $fb1/overlays
270	echo "0,1" > $fb0/overlays
271	
272	echo "$w,$h" > $ovl1/output_size
273	echo "tv" > $ovl1/manager
274	
275	echo "1" > $ovl0/enabled
276	echo "1" > $ovl1/enabled
277	
278	echo "1" > $tv/enabled
279	
280	After this the configuration looks like (only relevant parts shown):
281	
282	FB0 +-- GFX  ---- LCD ---- LCD
283	     \- VID1 ---- TV  ---- TV
284	
285	Misc notes
286	----------
287	
288	OMAP FB allocates the framebuffer memory using the standard dma allocator. You
289	can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma
290	allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase
291	the global memory area for CMA.
292	
293	Using DSI DPLL to generate pixel clock it is possible produce the pixel clock
294	of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI.
295	
296	Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB
297	does not support mirroring.
298	
299	VRFB rotation requires much more memory than non-rotated framebuffer, so you
300	probably need to increase your vram setting before using VRFB rotation. Also,
301	many applications may not work with VRFB if they do not pay attention to all
302	framebuffer parameters.
303	
304	Kernel boot arguments
305	---------------------
306	
307	omapfb.mode=<display>:<mode>[,...]
308		- Default video mode for specified displays. For example,
309		  "dvi:800x400MR-24@60".  See drivers/video/modedb.c.
310		  There are also two special modes: "pal" and "ntsc" that
311		  can be used to tv out.
312	
313	omapfb.vram=<fbnum>:<size>[@<physaddr>][,...]
314		- VRAM allocated for a framebuffer. Normally omapfb allocates vram
315		  depending on the display size. With this you can manually allocate
316		  more or define the physical address of each framebuffer. For example,
317		  "1:4M" to allocate 4M for fb1.
318	
319	omapfb.debug=<y|n>
320		- Enable debug printing. You have to have OMAPFB debug support enabled
321		  in kernel config.
322	
323	omapfb.test=<y|n>
324		- Draw test pattern to framebuffer whenever framebuffer settings change.
325		  You need to have OMAPFB debug support enabled in kernel config.
326	
327	omapfb.vrfb=<y|n>
328		- Use VRFB rotation for all framebuffers.
329	
330	omapfb.rotate=<angle>
331		- Default rotation applied to all framebuffers.
332		  0 - 0 degree rotation
333		  1 - 90 degree rotation
334		  2 - 180 degree rotation
335		  3 - 270 degree rotation
336	
337	omapfb.mirror=<y|n>
338		- Default mirror for all framebuffers. Only works with DMA rotation.
339	
340	omapdss.def_disp=<display>
341		- Name of default display, to which all overlays will be connected.
342		  Common examples are "lcd" or "tv".
343	
344	omapdss.debug=<y|n>
345		- Enable debug printing. You have to have DSS debug support enabled in
346		  kernel config.
347	
348	TODO
349	----
350	
351	DSS locking
352	
353	Error checking
354	- Lots of checks are missing or implemented just as BUG()
355	
356	System DMA update for DSI
357	- Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
358	  to skip the empty byte?)
359	
360	OMAP1 support
361	- Not sure if needed
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog