[linux-block.git] / Documentation / fb / ep93xx-fb.rst

================================
Driver for EP93xx LCD controller
================================

The EP93xx LCD controller can drive both standard desktop monitors and
embedded LCD displays. If you have a standard desktop monitor then you
can use the standard Linux video mode database. In your board file::

	static struct ep93xxfb_mach_info some_board_fb_info = {
		.num_modes	= EP93XXFB_USE_MODEDB,
		.bpp		= 16,
	};

If you have an embedded LCD display then you need to define a video
mode for it as follows::

	static struct fb_videomode some_board_video_modes[] = {
		{
			.name		= "some_lcd_name",
			/* Pixel clock, porches, etc */
		},
	};

Note that the pixel clock value is in pico-seconds. You can use the
KHZ2PICOS macro to convert the pixel clock value. Most other values
are in pixel clocks. See Documentation/fb/framebuffer.rst for further
details.

The ep93xxfb_mach_info structure for your board should look like the
following::

	static struct ep93xxfb_mach_info some_board_fb_info = {
		.num_modes	= ARRAY_SIZE(some_board_video_modes),
		.modes		= some_board_video_modes,
		.default_mode	= &some_board_video_modes[0],
		.bpp		= 16,
	};

The framebuffer device can be registered by adding the following to
your board initialisation function::

	ep93xx_register_fb(&some_board_fb_info);

=====================
Video Attribute Flags
=====================

The ep93xxfb_mach_info structure has a flags field which can be used
to configure the controller. The video attributes flags are fully
documented in section 7 of the EP93xx users' guide. The following
flags are available:

=============================== ==========================================
EP93XXFB_PCLK_FALLING		Clock data on the falling edge of the
				pixel clock. The default is to clock
				data on the rising edge.

EP93XXFB_SYNC_BLANK_HIGH	Blank signal is active high. By
				default the blank signal is active low.

EP93XXFB_SYNC_HORIZ_HIGH	Horizontal sync is active high. By
				default the horizontal sync is active low.

EP93XXFB_SYNC_VERT_HIGH		Vertical sync is active high. By
				default the vertical sync is active high.
=============================== ==========================================

The physical address of the framebuffer can be controlled using the
following flags:

=============================== ======================================
EP93XXFB_USE_SDCSN0		Use SDCSn[0] for the framebuffer. This
				is the default setting.

EP93XXFB_USE_SDCSN1		Use SDCSn[1] for the framebuffer.

EP93XXFB_USE_SDCSN2		Use SDCSn[2] for the framebuffer.

EP93XXFB_USE_SDCSN3		Use SDCSn[3] for the framebuffer.
=============================== ======================================

==================
Platform callbacks
==================

The EP93xx framebuffer driver supports three optional platform
callbacks: setup, teardown and blank. The setup and teardown functions
are called when the framebuffer driver is installed and removed
respectively. The blank function is called whenever the display is
blanked or unblanked.

The setup and teardown devices pass the platform_device structure as
an argument. The fb_info and ep93xxfb_mach_info structures can be
obtained as follows::

	static int some_board_fb_setup(struct platform_device *pdev)
	{
		struct ep93xxfb_mach_info *mach_info = pdev->dev.platform_data;
		struct fb_info *fb_info = platform_get_drvdata(pdev);

		/* Board specific framebuffer setup */
	}

======================
Setting the video mode
======================

The video mode is set using the following syntax::

	video=XRESxYRES[-BPP][@REFRESH]

If the EP93xx video driver is built-in then the video mode is set on
the Linux kernel command line, for example::

	video=ep93xx-fb:800x600-16@60

If the EP93xx video driver is built as a module then the video mode is
set when the module is installed::

	modprobe ep93xx-fb video=320x240

==============
Screenpage bug
==============

At least on the EP9315 there is a silicon bug which causes bit 27 of
the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
an unofficial errata for this bug at::

	https://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2

By default the EP93xx framebuffer driver checks if the allocated physical
address has bit 27 set. If it does, then the memory is freed and an
error is returned. The check can be disabled by adding the following
option when loading the driver::

      ep93xx-fb.check_screenpage_bug=0

In some cases it may be possible to reconfigure your SDRAM layout to
avoid this bug. See section 13 of the EP93xx users' guide for details.
Commit	Line	Data
88017bda RM	1	================================
	2	Driver for EP93xx LCD controller
	3	================================
	4
	5	The EP93xx LCD controller can drive both standard desktop monitors and
	6	embedded LCD displays. If you have a standard desktop monitor then you
ab42b818	7	can use the standard Linux video mode database. In your board file::
88017bda RM	8
	9	static struct ep93xxfb_mach_info some_board_fb_info = {
	10	.num_modes = EP93XXFB_USE_MODEDB,
	11	.bpp = 16,
	12	};
	13
	14	If you have an embedded LCD display then you need to define a video
ab42b818	15	mode for it as follows::
88017bda RM	16
	17	static struct fb_videomode some_board_video_modes[] = {
	18	{
	19	.name = "some_lcd_name",
	20	/* Pixel clock, porches, etc */
	21	},
	22	};
	23
	24	Note that the pixel clock value is in pico-seconds. You can use the
	25	KHZ2PICOS macro to convert the pixel clock value. Most other values
ab42b818	26	are in pixel clocks. See Documentation/fb/framebuffer.rst for further
88017bda RM	27	details.
	28
	29	The ep93xxfb_mach_info structure for your board should look like the
ab42b818	30	following::
88017bda RM	31
	32	static struct ep93xxfb_mach_info some_board_fb_info = {
	33	.num_modes = ARRAY_SIZE(some_board_video_modes),
	34	.modes = some_board_video_modes,
	35	.default_mode = &some_board_video_modes[0],
	36	.bpp = 16,
	37	};
	38
	39	The framebuffer device can be registered by adding the following to
ab42b818	40	your board initialisation function::
88017bda RM	41
	42	ep93xx_register_fb(&some_board_fb_info);
	43
	44	=====================
	45	Video Attribute Flags
	46	=====================
	47
	48	The ep93xxfb_mach_info structure has a flags field which can be used
	49	to configure the controller. The video attributes flags are fully
	50	documented in section 7 of the EP93xx users' guide. The following
	51	flags are available:
	52
ab42b818	53	=============================== ==========================================
88017bda RM	54	EP93XXFB_PCLK_FALLING Clock data on the falling edge of the
	55	pixel clock. The default is to clock
	56	data on the rising edge.
	57
	58	EP93XXFB_SYNC_BLANK_HIGH Blank signal is active high. By
	59	default the blank signal is active low.
	60
	61	EP93XXFB_SYNC_HORIZ_HIGH Horizontal sync is active high. By
	62	default the horizontal sync is active low.
	63
	64	EP93XXFB_SYNC_VERT_HIGH Vertical sync is active high. By
	65	default the vertical sync is active high.
ab42b818	66	=============================== ==========================================
88017bda RM	67
	68	The physical address of the framebuffer can be controlled using the
	69	following flags:
	70
ab42b818	71	=============================== ======================================
88017bda RM	72	EP93XXFB_USE_SDCSN0 Use SDCSn[0] for the framebuffer. This
	73	is the default setting.
	74
	75	EP93XXFB_USE_SDCSN1 Use SDCSn[1] for the framebuffer.
	76
	77	EP93XXFB_USE_SDCSN2 Use SDCSn[2] for the framebuffer.
	78
	79	EP93XXFB_USE_SDCSN3 Use SDCSn[3] for the framebuffer.
ab42b818	80	=============================== ======================================
88017bda RM	81
	82	==================
	83	Platform callbacks
	84	==================
	85
	86	The EP93xx framebuffer driver supports three optional platform
	87	callbacks: setup, teardown and blank. The setup and teardown functions
	88	are called when the framebuffer driver is installed and removed
	89	respectively. The blank function is called whenever the display is
	90	blanked or unblanked.
	91
	92	The setup and teardown devices pass the platform_device structure as
	93	an argument. The fb_info and ep93xxfb_mach_info structures can be
ab42b818	94	obtained as follows::
88017bda RM	95
	96	static int some_board_fb_setup(struct platform_device *pdev)
	97	{
	98	struct ep93xxfb_mach_info *mach_info = pdev->dev.platform_data;
	99	struct fb_info *fb_info = platform_get_drvdata(pdev);
	100
	101	/* Board specific framebuffer setup */
	102	}
	103
	104	======================
	105	Setting the video mode
	106	======================
	107
ab42b818	108	The video mode is set using the following syntax::
88017bda RM	109
	110	video=XRESxYRES[-BPP][@REFRESH]
	111
	112	If the EP93xx video driver is built-in then the video mode is set on
ab42b818	113	the Linux kernel command line, for example::
88017bda RM	114
	115	video=ep93xx-fb:800x600-16@60
	116
	117	If the EP93xx video driver is built as a module then the video mode is
ab42b818	118	set when the module is installed::
88017bda RM	119
	120	modprobe ep93xx-fb video=320x240
	121
	122	==============
	123	Screenpage bug
	124	==============
	125
	126	At least on the EP9315 there is a silicon bug which causes bit 27 of
	127	the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
ab42b818 MCC	128	an unofficial errata for this bug at::
ab42b818 MCC	129
7c7b2a35	130	https://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2
88017bda RM	131
	132	By default the EP93xx framebuffer driver checks if the allocated physical
	133	address has bit 27 set. If it does, then the memory is freed and an
	134	error is returned. The check can be disabled by adding the following
ab42b818	135	option when loading the driver::
88017bda RM	136
	137	ep93xx-fb.check_screenpage_bug=0
	138
	139	In some cases it may be possible to reconfigure your SDRAM layout to
	140	avoid this bug. See section 13 of the EP93xx users' guide for details.