Documentation/fb/cyblafb/usage

   1 CyBlaFB is a framebuffer driver for the Cyberblade/i1 graphics core integrated
   2 into the VIA Apollo PLE133 (aka vt8601) south bridge. It is developed and
   3 tested using a VIA EPIA 5000 board.
   4
   5 Cyblafb - compiled into the kernel or as a module?
   6 ==================================================
   7
   8 You might compile cyblafb either as a module or compile it permanently into the
   9 kernel.
  10
  11 Unless you have a real reason to do so you should not compile both vesafb and
  12 cyblafb permanently into the kernel. It's possible and it helps during the
  13 developement cycle, but it's useless and will at least block some otherwise
  14 usefull memory for ordinary users.
  15
  16 Selecting Modes
  17 ===============
  18
  19         Startup Mode
  20         ============
  21
  22         First of all, you might use the "vga=???" boot parameter as it is
  23         documented in vesafb.txt and svga.txt. Cyblafb will detect the video
  24         mode selected and will use the geometry and timings found by
  25         inspecting the hardware registers.
  26
  27                 video=cyblafb vga=0x317
  28
  29         Alternatively you might use a combination of the mode, ref and bpp
  30         parameters. If you compiled the driver into the kernel, add something
  31         like this to the kernel command line:
  32
  33                 video=cyblafb:1280x1024,bpp=16,ref=50 ...
  34
  35         If you compiled the driver as a module, the same mode would be
  36         selected by the following command:
  37
  38                 modprobe cyblafb mode=1280x1024 bpp=16 ref=50 ...
  39
  40         None of the modes possible to select as startup modes are affected by
  41         the problems described at the end of the next subsection.
  42
  43         Mode changes using fbset
  44         ========================
  45
  46         You might use fbset to change the video mode, see "man fbset". Cyblafb
  47         generally does assume that you know what you are doing. But it does
  48         some checks, especially those that are needed to prevent you from
  49         damaging your hardware.
  50
  51                 - only 8, 16, 24 and 32 bpp video modes are accepted
  52                 - interlaced video modes are not accepted
  53                 - double scan video modes are not accepted
  54                 - if a flat panel is found, cyblafb does not allow you
  55                   to program a resolution higher than the physical
  56                   resolution of the flat panel monitor
  57                 - cyblafb does not allow xres to differ from xres_virtual
  58                 - cyblafb does not allow vclk to exceed 230 MHz. As 32 bpp
  59                   and (currently) 24 bit modes use a doubled vclk internally,
  60                   the dotclock limit as seen by fbset is 115 MHz for those
  61                   modes and 230 MHz for 8 and 16 bpp modes.
  62
  63         Any request that violates the rules given above will be ignored and
  64         fbset will return an error.
  65
  66         If you program a virtual y resolution higher than the hardware limit,
  67         cyblafb will silently decrease that value to the highest possible
  68         value.
  69
  70         Attempts to disable acceleration are ignored.
  71
  72         Some video modes that should work do not work as expected. If you use
  73         the standard fb.modes, fbset 640x480-60 will program that mode, but
  74         you will see a vertical area, about two characters wide, with only
  75         much darker characters than the other characters on the screen.
  76         Cyblafb does allow that mode to be set, as it does not violate the
  77         official specifications. It would need a lot of code to reliably sort
  78         out all invalid modes, playing around with the margin values will
  79         give a valid mode quickly. And if cyblafb would detect such an invalid
  80         mode, should it silently alter the requested values or should it
  81         report an error? Both options have some pros and cons. As stated
  82         above, none of the startup modes are affected, and if you set
  83         verbosity to 1 or higher, cyblafb will print the fbset command that
  84         would be needed to program that mode using fbset.
  85
  86
  87 Other Parameters
  88 ================
  89
  90
  91 crt             don't autodetect, assume monitor connected to
  92                 standard VGA connector
  93
  94 fp              don't autodetect, assume flat panel display
  95                 connected to flat panel monitor interface
  96
  97 nativex         inform driver about native x resolution of
  98                 flat panel monitor connected to special
  99                 interface (should be autodetected)
 100
 101 stretch         stretch image to adapt low resolution modes to
 102                 higer resolutions of flat panel monitors
 103                 connected to special interface
 104
 105 center          center image to adapt low resolution modes to
 106                 higer resolutions of flat panel monitors
 107                 connected to special interface
 108
 109 memsize         use if autodetected memsize is wrong ...
 110                 should never be necessary
 111
 112 nopcirr         disable PCI read retry
 113 nopciwr         disable PCI write retry
 114 nopcirb         disable PCI read bursts
 115 nopciwb         disable PCI write bursts
 116
 117 bpp             bpp for specified modes
 118                 valid values: 8 || 16 || 24 || 32
 119
 120 ref             refresh rate for specified mode
 121                 valid values: 50 <= ref <= 85
 122
 123 mode            640x480 or 800x600 or 1024x768 or 1280x1024
 124                 if not specified, the startup mode will be detected
 125                 and used, so you might also use the vga=??? parameter
 126                 described in vesafb.txt. If you do not specify a mode,
 127                 bpp and ref parameters are ignored.
 128
 129 verbosity       0 is the default, increase to at least 2 for every
 130                 bug report!
 131
 132 vesafb          allows cyblafb to be loaded after vesafb has been
 133                 loaded. See sections "Module unloading ...".
 134
 135
 136 Development hints
 137 =================
 138
 139 It's much faster do compile a module and to load the new version after
 140 unloading the old module than to compile a new kernel and to reboot. So if you
 141 try to work on cyblafb, it might be a good idea to use cyblafb as a module.
 142 In real life, fast often means dangerous, and that's also the case here. If
 143 you introduce a serious bug when cyblafb is compiled into the kernel, the
 144 kernel will lock or oops with a high probability before the file system is
 145 mounted, and the danger for your data is low. If you load a broken own version
 146 of cyblafb on a running system, the danger for the integrity of the file
 147 system is much higher as you might need a hard reset afterwards. Decide
 148 yourself.
 149
 150 Module unloading, the vfb method
 151 ================================
 152
 153 If you want to unload/reload cyblafb using the virtual framebuffer, you need
 154 to enable vfb support in the kernel first. After that, load the modules as
 155 shown below:
 156
 157         modprobe vfb vfb_enable=1
 158         modprobe fbcon
 159         modprobe cyblafb
 160         fbset -fb /dev/fb1 1280x1024-60 -vyres 2662
 161         con2fb /dev/fb1 /dev/tty1
 162         ...
 163
 164 If you now made some changes to cyblafb and want to reload it, you might do it
 165 as show below:
 166
 167         con2fb /dev/fb0 /dev/tty1
 168         ...
 169         rmmod cyblafb
 170         modprobe cyblafb
 171         con2fb /dev/fb1 /dev/tty1
 172         ...
 173
 174 Of course, you might choose another mode, and most certainly you also want to
 175 map some other /dev/tty* to the real framebuffer device. You might also choose
 176 to compile fbcon as a kernel module or place it permanently in the kernel.
 177
 178 I do not know of any way to unload fbcon, and fbcon will prevent the
 179 framebuffer device loaded first from unloading. [If there is a way, then
 180 please add a description here!]
 181
 182 Module unloading, the vesafb method
 183 ===================================
 184
 185 Configure the kernel:
 186
 187         <*> Support for frame buffer devices
 188         [*]   VESA VGA graphics support
 189         <M>   Cyberblade/i1 support
 190
 191 Add e.g. "video=vesafb:ypan vga=0x307" to the kernel parameters. The ypan
 192 parameter is important, choose any vga parameter you like as long as it is
 193 a graphics mode.
 194
 195 After booting, load cyblafb without any mode and bpp parameter and assign
 196 cyblafb to individual ttys using con2fb, e.g.:
 197
 198         modprobe cyblafb vesafb=1
 199         con2fb /dev/fb1 /dev/tty1
 200
 201 Unloading cyblafb works without problems after you assign vesafb to all
 202 ttys again, e.g.:
 203
 204         con2fb /dev/fb0 /dev/tty1
 205         rmmod cyblafb
 206