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         For all startup modes cyblafb chooses a virtual x resolution of 2048,
  44         the only exception is mode 1280x1024 in combination with 32 bpp. This
  45         allows ywrap scrolling for all those modes if rotation is 0 or 2, and
  46         also fast scrolling if rotation is 1 or 3. The default virtual y reso-
  47         lution is 4096 for bpp == 8, 2048 for bpp==16 and 1024 for bpp == 32,
  48         again with the only exception of 1280x1024 at 32 bpp.
  49
  50         Please do set your video memory size to 8 Mb in the Bios setup. Other
  51         values will work, but performace is decreased for a lot of modes.
  52
  53         Mode changes using fbset
  54         ========================
  55
  56         You might use fbset to change the video mode, see "man fbset". Cyblafb
  57         generally does assume that you know what you are doing. But it does
  58         some checks, especially those that are needed to prevent you from
  59         damaging your hardware.
  60
  61                 - only 8, 16, 24 and 32 bpp video modes are accepted
  62                 - interlaced video modes are not accepted
  63                 - double scan video modes are not accepted
  64                 - if a flat panel is found, cyblafb does not allow you
  65                   to program a resolution higher than the physical
  66                   resolution of the flat panel monitor
  67                 - cyblafb does not allow vclk to exceed 230 MHz. As 32 bpp
  68                   and (currently) 24 bit modes use a doubled vclk internally,
  69                   the dotclock limit as seen by fbset is 115 MHz for those
  70                   modes and 230 MHz for 8 and 16 bpp modes.
  71                 - cyblafb will allow you to select very high resolutions as
  72                   long as the hardware can be programmed to these modes. The
  73                   documented limit 1600x1200 is not enforced, but don't expect
  74                   perfect signal quality.
  75
  76         Any request that violates the rules given above will be either changed
  77         to something the hardware supports or an error value will be returned.
  78
  79         If you program a virtual y resolution higher than the hardware limit,
  80         cyblafb will silently decrease that value to the highest possible
  81         value. The same is true for a virtual x resolution that is not
  82         supported by the hardware. Cyblafb tries to adapt vyres first because
  83         vxres decides if ywrap scrolling is possible or not.
  84
  85         Attempts to disable acceleration are ignored, I believe that this is
  86         safe.
  87
  88         Some video modes that should work do not work as expected. If you use
  89         the standard fb.modes, fbset 640x480-60 will program that mode, but
  90         you will see a vertical area, about two characters wide, with only
  91         much darker characters than the other characters on the screen.
  92         Cyblafb does allow that mode to be set, as it does not violate the
  93         official specifications. It would need a lot of code to reliably sort
  94         out all invalid modes, playing around with the margin values will
  95         give a valid mode quickly. And if cyblafb would detect such an invalid
  96         mode, should it silently alter the requested values or should it
  97         report an error? Both options have some pros and cons. As stated
  98         above, none of the startup modes are affected, and if you set
  99         verbosity to 1 or higher, cyblafb will print the fbset command that
 100         would be needed to program that mode using fbset.
 101
 102
 103 Other Parameters
 104 ================
 105
 106
 107 crt             don't autodetect, assume monitor connected to
 108                 standard VGA connector
 109
 110 fp              don't autodetect, assume flat panel display
 111                 connected to flat panel monitor interface
 112
 113 nativex         inform driver about native x resolution of
 114                 flat panel monitor connected to special
 115                 interface (should be autodetected)
 116
 117 stretch         stretch image to adapt low resolution modes to
 118                 higer resolutions of flat panel monitors
 119                 connected to special interface
 120
 121 center          center image to adapt low resolution modes to
 122                 higer resolutions of flat panel monitors
 123                 connected to special interface
 124
 125 memsize         use if autodetected memsize is wrong ...
 126                 should never be necessary
 127
 128 nopcirr         disable PCI read retry
 129 nopciwr         disable PCI write retry
 130 nopcirb         disable PCI read bursts
 131 nopciwb         disable PCI write bursts
 132
 133 bpp             bpp for specified modes
 134                 valid values: 8 || 16 || 24 || 32
 135
 136 ref             refresh rate for specified mode
 137                 valid values: 50 <= ref <= 85
 138
 139 mode            640x480 or 800x600 or 1024x768 or 1280x1024
 140                 if not specified, the startup mode will be detected
 141                 and used, so you might also use the vga=??? parameter
 142                 described in vesafb.txt. If you do not specify a mode,
 143                 bpp and ref parameters are ignored.
 144
 145 verbosity       0 is the default, increase to at least 2 for every
 146                 bug report!
 147
 148 Development hints
 149 =================
 150
 151 It's much faster do compile a module and to load the new version after
 152 unloading the old module than to compile a new kernel and to reboot. So if you
 153 try to work on cyblafb, it might be a good idea to use cyblafb as a module.
 154 In real life, fast often means dangerous, and that's also the case here. If
 155 you introduce a serious bug when cyblafb is compiled into the kernel, the
 156 kernel will lock or oops with a high probability before the file system is
 157 mounted, and the danger for your data is low. If you load a broken own version
 158 of cyblafb on a running system, the danger for the integrity of the file
 159 system is much higher as you might need a hard reset afterwards. Decide
 160 yourself.
 161
 162 Module unloading, the vfb method
 163 ================================
 164
 165 If you want to unload/reload cyblafb using the virtual framebuffer, you need
 166 to enable vfb support in the kernel first. After that, load the modules as
 167 shown below:
 168
 169         modprobe vfb vfb_enable=1
 170         modprobe fbcon
 171         modprobe cyblafb
 172         fbset -fb /dev/fb1 1280x1024-60 -vyres 2662
 173         con2fb /dev/fb1 /dev/tty1
 174         ...
 175
 176 If you now made some changes to cyblafb and want to reload it, you might do it
 177 as show below:
 178
 179         con2fb /dev/fb0 /dev/tty1
 180         ...
 181         rmmod cyblafb
 182         modprobe cyblafb
 183         con2fb /dev/fb1 /dev/tty1
 184         ...
 185
 186 Of course, you might choose another mode, and most certainly you also want to
 187 map some other /dev/tty* to the real framebuffer device. You might also choose
 188 to compile fbcon as a kernel module or place it permanently in the kernel.
 189
 190 I do not know of any way to unload fbcon, and fbcon will prevent the
 191 framebuffer device loaded first from unloading. [If there is a way, then
 192 please add a description here!]
 193
 194 Module unloading, the vesafb method
 195 ===================================
 196
 197 Configure the kernel:
 198
 199         <*> Support for frame buffer devices
 200         [*]   VESA VGA graphics support
 201         <M>   Cyberblade/i1 support
 202
 203 Add e.g. "video=vesafb:ypan vga=0x307" to the kernel parameters. The ypan
 204 parameter is important, choose any vga parameter you like as long as it is
 205 a graphics mode.
 206
 207 After booting, load cyblafb without any mode and bpp parameter and assign
 208 cyblafb to individual ttys using con2fb, e.g.:
 209
 210         modprobe cyblafb
 211         con2fb /dev/fb1 /dev/tty1
 212
 213 Unloading cyblafb works without problems after you assign vesafb to all
 214 ttys again, e.g.:
 215
 216         con2fb /dev/fb0 /dev/tty1
 217         rmmod cyblafb