Documentation/fb/cyblafb/usage - kernel/msm - Gitiles

 CyBlaFB is a framebuffer driver for the Cyberblade/i1 graphics core integrated
 into the VIA Apollo PLE133 (aka vt8601) south bridge. It is developed and
 tested using a VIA EPIA 5000 board.

 Cyblafb - compiled into the kernel or as a module?
 ==================================================

 You might compile cyblafb either as a module or compile it permanently into the
 kernel.

 Unless you have a real reason to do so you should not compile both vesafb and
 cyblafb permanently into the kernel. It's possible and it helps during the
 developement cycle, but it's useless and will at least block some otherwise
 usefull memory for ordinary users.

 Selecting Modes
 ===============

 	Startup Mode
 	============

 	First of all, you might use the "vga=???" boot parameter as it is
 	documented in vesafb.txt and svga.txt. Cyblafb will detect the video
 	mode selected and will use the geometry and timings found by
 	inspecting the hardware registers.

 		video=cyblafb vga=0x317

 	Alternatively you might use a combination of the mode, ref and bpp
 	parameters. If you compiled the driver into the kernel, add something
 	like this to the kernel command line:

 		video=cyblafb:1280x1024,bpp=16,ref=50 ...

 	If you compiled the driver as a module, the same mode would be
 	selected by the following command:

 		modprobe cyblafb mode=1280x1024 bpp=16 ref=50 ...

 	None of the modes possible to select as startup modes are affected by
 	the problems described at the end of the next subsection.

 	For all startup modes cyblafb chooses a virtual x resolution of 2048,
 	the only exception is mode 1280x1024 in combination with 32 bpp. This
 	allows ywrap scrolling for all those modes if rotation is 0 or 2, and
 	also fast scrolling if rotation is 1 or 3. The default virtual y reso-
 	lution is 4096 for bpp == 8, 2048 for bpp==16 and 1024 for bpp == 32,
 	again with the only exception of 1280x1024 at 32 bpp.

 	Please do set your video memory size to 8 Mb in the Bios setup. Other
 	values will work, but performace is decreased for a lot of modes.

 	Mode changes using fbset
 	========================

 	You might use fbset to change the video mode, see "man fbset". Cyblafb
 	generally does assume that you know what you are doing. But it does
 	some checks, especially those that are needed to prevent you from
 	damaging your hardware.

 		- only 8, 16, 24 and 32 bpp video modes are accepted
 		- interlaced video modes are not accepted
 		- double scan video modes are not accepted
 		- if a flat panel is found, cyblafb does not allow you
 		  to program a resolution higher than the physical
 		  resolution of the flat panel monitor
 		- cyblafb does not allow vclk to exceed 230 MHz. As 32 bpp
 		  and (currently) 24 bit modes use a doubled vclk internally,
 		  the dotclock limit as seen by fbset is 115 MHz for those
 		  modes and 230 MHz for 8 and 16 bpp modes.
 		- cyblafb will allow you to select very high resolutions as
 		  long as the hardware can be programmed to these modes. The
 		  documented limit 1600x1200 is not enforced, but don't expect
 		  perfect signal quality.

 	Any request that violates the rules given above will be either changed
 	to something the hardware supports or an error value will be returned.

 	If you program a virtual y resolution higher than the hardware limit,
 	cyblafb will silently decrease that value to the highest possible
 	value. The same is true for a virtual x resolution that is not
 	supported by the hardware. Cyblafb tries to adapt vyres first because
 	vxres decides if ywrap scrolling is possible or not.

 	Attempts to disable acceleration are ignored, I believe that this is
 	safe.

 	Some video modes that should work do not work as expected. If you use
 	the standard fb.modes, fbset 640x480-60 will program that mode, but
 	you will see a vertical area, about two characters wide, with only
 	much darker characters than the other characters on the screen.
 	Cyblafb does allow that mode to be set, as it does not violate the
 	official specifications. It would need a lot of code to reliably sort
 	out all invalid modes, playing around with the margin values will
 	give a valid mode quickly. And if cyblafb would detect such an invalid
 	mode, should it silently alter the requested values or should it
 	report an error? Both options have some pros and cons. As stated
 	above, none of the startup modes are affected, and if you set
 	verbosity to 1 or higher, cyblafb will print the fbset command that
 	would be needed to program that mode using fbset.


 Other Parameters
 ================


 crt		don't autodetect, assume monitor connected to
 		standard VGA connector

 fp		don't autodetect, assume flat panel display
 		connected to flat panel monitor interface

 nativex 	inform driver about native x resolution of
 		flat panel monitor connected to special
 		interface (should be autodetected)

 stretch 	stretch image to adapt low resolution modes to
 		higer resolutions of flat panel monitors
 		connected to special interface

 center		center image to adapt low resolution modes to
 		higer resolutions of flat panel monitors
 		connected to special interface

 memsize 	use if autodetected memsize is wrong ...
 		should never be necessary

 nopcirr 	disable PCI read retry
 nopciwr 	disable PCI write retry
 nopcirb 	disable PCI read bursts
 nopciwb 	disable PCI write bursts

 bpp		bpp for specified modes
 		valid values: 8 || 16 || 24 || 32

 ref		refresh rate for specified mode
 		valid values: 50 <= ref <= 85

 mode		640x480 or 800x600 or 1024x768 or 1280x1024
 		if not specified, the startup mode will be detected
 		and used, so you might also use the vga=??? parameter
 		described in vesafb.txt. If you do not specify a mode,
 		bpp and ref parameters are ignored.

 verbosity	0 is the default, increase to at least 2 for every
 		bug report!

 Development hints
 =================

 It's much faster do compile a module and to load the new version after
 unloading the old module than to compile a new kernel and to reboot. So if you
 try to work on cyblafb, it might be a good idea to use cyblafb as a module.
 In real life, fast often means dangerous, and that's also the case here. If
 you introduce a serious bug when cyblafb is compiled into the kernel, the
 kernel will lock or oops with a high probability before the file system is
 mounted, and the danger for your data is low. If you load a broken own version
 of cyblafb on a running system, the danger for the integrity of the file
 system is much higher as you might need a hard reset afterwards. Decide
 yourself.

 Module unloading, the vfb method
 ================================

 If you want to unload/reload cyblafb using the virtual framebuffer, you need
 to enable vfb support in the kernel first. After that, load the modules as
 shown below:

 	modprobe vfb vfb_enable=1
 	modprobe fbcon
 	modprobe cyblafb
 	fbset -fb /dev/fb1 1280x1024-60 -vyres 2662
 	con2fb /dev/fb1 /dev/tty1
 	...

 If you now made some changes to cyblafb and want to reload it, you might do it
 as show below:

 	con2fb /dev/fb0 /dev/tty1
 	...
 	rmmod cyblafb
 	modprobe cyblafb
 	con2fb /dev/fb1 /dev/tty1
 	...

 Of course, you might choose another mode, and most certainly you also want to
 map some other /dev/tty* to the real framebuffer device. You might also choose
 to compile fbcon as a kernel module or place it permanently in the kernel.

 I do not know of any way to unload fbcon, and fbcon will prevent the
 framebuffer device loaded first from unloading. [If there is a way, then
 please add a description here!]

 Module unloading, the vesafb method
 ===================================

 Configure the kernel:

 	<*> Support for frame buffer devices
 	[*]   VESA VGA graphics support
 	<M>   Cyberblade/i1 support

 Add e.g. "video=vesafb:ypan vga=0x307" to the kernel parameters. The ypan
 parameter is important, choose any vga parameter you like as long as it is
 a graphics mode.

 After booting, load cyblafb without any mode and bpp parameter and assign
 cyblafb to individual ttys using con2fb, e.g.:

 	modprobe cyblafb
 	con2fb /dev/fb1 /dev/tty1

 Unloading cyblafb works without problems after you assign vesafb to all
 ttys again, e.g.:

 	con2fb /dev/fb0 /dev/tty1
 	rmmod cyblafb
	CyBlaFB is a framebuffer driver for the Cyberblade/i1 graphics core integrated
	into the VIA Apollo PLE133 (aka vt8601) south bridge. It is developed and
	tested using a VIA EPIA 5000 board.

	Cyblafb - compiled into the kernel or as a module?
	==================================================

	You might compile cyblafb either as a module or compile it permanently into the
	kernel.

	Unless you have a real reason to do so you should not compile both vesafb and
	cyblafb permanently into the kernel. It's possible and it helps during the
	developement cycle, but it's useless and will at least block some otherwise
	usefull memory for ordinary users.

	Selecting Modes
	===============

	Startup Mode
	============

	First of all, you might use the "vga=???" boot parameter as it is
	documented in vesafb.txt and svga.txt. Cyblafb will detect the video
	mode selected and will use the geometry and timings found by
	inspecting the hardware registers.

	video=cyblafb vga=0x317

	Alternatively you might use a combination of the mode, ref and bpp
	parameters. If you compiled the driver into the kernel, add something
	like this to the kernel command line:

	video=cyblafb:1280x1024,bpp=16,ref=50 ...

	If you compiled the driver as a module, the same mode would be
	selected by the following command:

	modprobe cyblafb mode=1280x1024 bpp=16 ref=50 ...

	None of the modes possible to select as startup modes are affected by
	the problems described at the end of the next subsection.

	For all startup modes cyblafb chooses a virtual x resolution of 2048,
	the only exception is mode 1280x1024 in combination with 32 bpp. This
	allows ywrap scrolling for all those modes if rotation is 0 or 2, and
	also fast scrolling if rotation is 1 or 3. The default virtual y reso-
	lution is 4096 for bpp == 8, 2048 for bpp==16 and 1024 for bpp == 32,
	again with the only exception of 1280x1024 at 32 bpp.

	Please do set your video memory size to 8 Mb in the Bios setup. Other
	values will work, but performace is decreased for a lot of modes.

	Mode changes using fbset
	========================

	You might use fbset to change the video mode, see "man fbset". Cyblafb
	generally does assume that you know what you are doing. But it does
	some checks, especially those that are needed to prevent you from
	damaging your hardware.

	- only 8, 16, 24 and 32 bpp video modes are accepted
	- interlaced video modes are not accepted
	- double scan video modes are not accepted
	- if a flat panel is found, cyblafb does not allow you
	to program a resolution higher than the physical
	resolution of the flat panel monitor
	- cyblafb does not allow vclk to exceed 230 MHz. As 32 bpp
	and (currently) 24 bit modes use a doubled vclk internally,
	the dotclock limit as seen by fbset is 115 MHz for those
	modes and 230 MHz for 8 and 16 bpp modes.
	- cyblafb will allow you to select very high resolutions as
	long as the hardware can be programmed to these modes. The
	documented limit 1600x1200 is not enforced, but don't expect
	perfect signal quality.

	Any request that violates the rules given above will be either changed
	to something the hardware supports or an error value will be returned.

	If you program a virtual y resolution higher than the hardware limit,
	cyblafb will silently decrease that value to the highest possible
	value. The same is true for a virtual x resolution that is not
	supported by the hardware. Cyblafb tries to adapt vyres first because
	vxres decides if ywrap scrolling is possible or not.

	Attempts to disable acceleration are ignored, I believe that this is
	safe.

	Some video modes that should work do not work as expected. If you use
	the standard fb.modes, fbset 640x480-60 will program that mode, but
	you will see a vertical area, about two characters wide, with only
	much darker characters than the other characters on the screen.
	Cyblafb does allow that mode to be set, as it does not violate the
	official specifications. It would need a lot of code to reliably sort
	out all invalid modes, playing around with the margin values will
	give a valid mode quickly. And if cyblafb would detect such an invalid
	mode, should it silently alter the requested values or should it
	report an error? Both options have some pros and cons. As stated
	above, none of the startup modes are affected, and if you set
	verbosity to 1 or higher, cyblafb will print the fbset command that
	would be needed to program that mode using fbset.


	Other Parameters
	================


	crt don't autodetect, assume monitor connected to
	standard VGA connector

	fp don't autodetect, assume flat panel display
	connected to flat panel monitor interface

	nativex inform driver about native x resolution of
	flat panel monitor connected to special
	interface (should be autodetected)

	stretch stretch image to adapt low resolution modes to
	higer resolutions of flat panel monitors
	connected to special interface

	center center image to adapt low resolution modes to
	higer resolutions of flat panel monitors
	connected to special interface

	memsize use if autodetected memsize is wrong ...
	should never be necessary

	nopcirr disable PCI read retry
	nopciwr disable PCI write retry
	nopcirb disable PCI read bursts
	nopciwb disable PCI write bursts

	bpp bpp for specified modes
	valid values: 8 \|\| 16 \|\| 24 \|\| 32

	ref refresh rate for specified mode
	valid values: 50 <= ref <= 85

	mode 640x480 or 800x600 or 1024x768 or 1280x1024
	if not specified, the startup mode will be detected
	and used, so you might also use the vga=??? parameter
	described in vesafb.txt. If you do not specify a mode,
	bpp and ref parameters are ignored.

	verbosity 0 is the default, increase to at least 2 for every
	bug report!

	Development hints
	=================

	It's much faster do compile a module and to load the new version after
	unloading the old module than to compile a new kernel and to reboot. So if you
	try to work on cyblafb, it might be a good idea to use cyblafb as a module.
	In real life, fast often means dangerous, and that's also the case here. If
	you introduce a serious bug when cyblafb is compiled into the kernel, the
	kernel will lock or oops with a high probability before the file system is
	mounted, and the danger for your data is low. If you load a broken own version
	of cyblafb on a running system, the danger for the integrity of the file
	system is much higher as you might need a hard reset afterwards. Decide
	yourself.

	Module unloading, the vfb method
	================================

	If you want to unload/reload cyblafb using the virtual framebuffer, you need
	to enable vfb support in the kernel first. After that, load the modules as
	shown below:

	modprobe vfb vfb_enable=1
	modprobe fbcon
	modprobe cyblafb
	fbset -fb /dev/fb1 1280x1024-60 -vyres 2662
	con2fb /dev/fb1 /dev/tty1
	...

	If you now made some changes to cyblafb and want to reload it, you might do it
	as show below:

	con2fb /dev/fb0 /dev/tty1
	...
	rmmod cyblafb
	modprobe cyblafb
	con2fb /dev/fb1 /dev/tty1
	...

	Of course, you might choose another mode, and most certainly you also want to
	map some other /dev/tty* to the real framebuffer device. You might also choose
	to compile fbcon as a kernel module or place it permanently in the kernel.

	I do not know of any way to unload fbcon, and fbcon will prevent the
	framebuffer device loaded first from unloading. [If there is a way, then
	please add a description here!]

	Module unloading, the vesafb method
	===================================

	Configure the kernel:

	<*> Support for frame buffer devices
	[*] VESA VGA graphics support
	<M> Cyberblade/i1 support

	Add e.g. "video=vesafb:ypan vga=0x307" to the kernel parameters. The ypan
	parameter is important, choose any vga parameter you like as long as it is
	a graphics mode.

	After booting, load cyblafb without any mode and bpp parameter and assign
	cyblafb to individual ttys using con2fb, e.g.:

	modprobe cyblafb
	con2fb /dev/fb1 /dev/tty1

	Unloading cyblafb works without problems after you assign vesafb to all
	ttys again, e.g.:

	con2fb /dev/fb0 /dev/tty1
	rmmod cyblafb