Documentation/fb/uvesafb.rst

   1 ==========================================================
   2 uvesafb - A Generic Driver for VBE2+ compliant video cards
   3 ==========================================================
   4
   5 1. Requirements
   6 ---------------
   7
   8 uvesafb should work with any video card that has a Video BIOS compliant
   9 with the VBE 2.0 standard.
  10
  11 Unlike other drivers, uvesafb makes use of a userspace helper called
  12 v86d.  v86d is used to run the x86 Video BIOS code in a simulated and
  13 controlled environment.  This allows uvesafb to function on arches other
  14 than x86.  Check the v86d documentation for a list of currently supported
  15 arches.
  16
  17 v86d source code can be downloaded from the following website:
  18
  19   https://github.com/mjanusz/v86d
  20
  21 Please refer to the v86d documentation for detailed configuration and
  22 installation instructions.
  23
  24 Note that the v86d userspace helper has to be available at all times in
  25 order for uvesafb to work properly.  If you want to use uvesafb during
  26 early boot, you will have to include v86d into an initramfs image, and
  27 either compile it into the kernel or use it as an initrd.
  28
  29 2. Caveats and limitations
  30 --------------------------
  31
  32 uvesafb is a _generic_ driver which supports a wide variety of video
  33 cards, but which is ultimately limited by the Video BIOS interface.
  34 The most important limitations are:
  35
  36 - Lack of any type of acceleration.
  37 - A strict and limited set of supported video modes.  Often the native
  38   or most optimal resolution/refresh rate for your setup will not work
  39   with uvesafb, simply because the Video BIOS doesn't support the
  40   video mode you want to use.  This can be especially painful with
  41   widescreen panels, where native video modes don't have the 4:3 aspect
  42   ratio, which is what most BIOS-es are limited to.
  43 - Adjusting the refresh rate is only possible with a VBE 3.0 compliant
  44   Video BIOS.  Note that many nVidia Video BIOS-es claim to be VBE 3.0
  45   compliant, while they simply ignore any refresh rate settings.
  46
  47 3. Configuration
  48 ----------------
  49
  50 uvesafb can be compiled either as a module, or directly into the kernel.
  51 In both cases it supports the same set of configuration options, which
  52 are either given on the kernel command line or as module parameters, e.g.::
  53
  54  video=uvesafb:1024x768-32,mtrr:3,ywrap (compiled into the kernel)
  55
  56  # modprobe uvesafb mode_option=1024x768-32 mtrr=3 scroll=ywrap  (module)
  57
  58 Accepted options:
  59
  60 ======= =========================================================
  61 ypan    Enable display panning using the VESA protected mode
  62         interface.  The visible screen is just a window of the
  63         video memory, console scrolling is done by changing the
  64         start of the window.  This option is available on x86
  65         only and is the default option on that architecture.
  66
  67 ywrap   Same as ypan, but assumes your gfx board can wrap-around
  68         the video memory (i.e. starts reading from top if it
  69         reaches the end of video memory).  Faster than ypan.
  70         Available on x86 only.
  71
  72 redraw  Scroll by redrawing the affected part of the screen, this
  73         is the default on non-x86.
  74 ======= =========================================================
  75
  76 (If you're using uvesafb as a module, the above three options are
  77 used a parameter of the scroll option, e.g. scroll=ypan.)
  78
  79 =========== ====================================================================
  80 vgapal      Use the standard VGA registers for palette changes.
  81
  82 pmipal      Use the protected mode interface for palette changes.
  83             This is the default if the protected mode interface is
  84             available.  Available on x86 only.
  85
  86 mtrr:n      Setup memory type range registers for the framebuffer
  87             where n:
  88
  89                 - 0 - disabled (equivalent to nomtrr)
  90                 - 3 - write-combining (default)
  91
  92             Values other than 0 and 3 will result in a warning and will be
  93             treated just like 3.
  94
  95 nomtrr      Do not use memory type range registers.
  96
  97 vremap:n
  98             Remap 'n' MiB of video RAM.  If 0 or not specified, remap memory
  99             according to video mode.
 100
 101 vtotal:n    If the video BIOS of your card incorrectly determines the total
 102             amount of video RAM, use this option to override the BIOS (in MiB).
 103
 104 <mode>      The mode you want to set, in the standard modedb format.  Refer to
 105             modedb.txt for a detailed description.  When uvesafb is compiled as
 106             a module, the mode string should be provided as a value of the
 107             'mode_option' option.
 108
 109 vbemode:x   Force the use of VBE mode x.  The mode will only be set if it's
 110             found in the VBE-provided list of supported modes.
 111             NOTE: The mode number 'x' should be specified in VESA mode number
 112             notation, not the Linux kernel one (eg. 257 instead of 769).
 113             HINT: If you use this option because normal <mode> parameter does
 114             not work for you and you use a X server, you'll probably want to
 115             set the 'nocrtc' option to ensure that the video mode is properly
 116             restored after console <-> X switches.
 117
 118 nocrtc      Do not use CRTC timings while setting the video mode.  This option
 119             has any effect only if the Video BIOS is VBE 3.0 compliant.  Use it
 120             if you have problems with modes set the standard way.  Note that
 121             using this option implies that any refresh rate adjustments will
 122             be ignored and the refresh rate will stay at your BIOS default
 123             (60 Hz).
 124
 125 noedid      Do not try to fetch and use EDID-provided modes.
 126
 127 noblank     Disable hardware blanking.
 128
 129 v86d:path   Set path to the v86d executable. This option is only available as
 130             a module parameter, and not as a part of the video= string.  If you
 131             need to use it and have uvesafb built into the kernel, use
 132             uvesafb.v86d="path".
 133 =========== ====================================================================
 134
 135 Additionally, the following parameters may be provided.  They all override the
 136 EDID-provided values and BIOS defaults.  Refer to your monitor's specs to get
 137 the correct values for maxhf, maxvf and maxclk for your hardware.
 138
 139 =========== ======================================
 140 maxhf:n     Maximum horizontal frequency (in kHz).
 141 maxvf:n     Maximum vertical frequency (in Hz).
 142 maxclk:n    Maximum pixel clock (in MHz).
 143 =========== ======================================
 144
 145 4. The sysfs interface
 146 ----------------------
 147
 148 uvesafb provides several sysfs nodes for configurable parameters and
 149 additional information.
 150
 151 Driver attributes:
 152
 153 /sys/bus/platform/drivers/uvesafb
 154   v86d
 155     (default: /sbin/v86d)
 156
 157     Path to the v86d executable. v86d is started by uvesafb
 158     if an instance of the daemon isn't already running.
 159
 160 Device attributes:
 161
 162 /sys/bus/platform/drivers/uvesafb/uvesafb.0
 163   nocrtc
 164     Use the default refresh rate (60 Hz) if set to 1.
 165
 166   oem_product_name, oem_product_rev, oem_string, oem_vendor
 167     Information about the card and its maker.
 168
 169   vbe_modes
 170     A list of video modes supported by the Video BIOS along with their
 171     VBE mode numbers in hex.
 172
 173   vbe_version
 174     A BCD value indicating the implemented VBE standard.
 175
 176 5. Miscellaneous
 177 ----------------
 178
 179 Uvesafb will set a video mode with the default refresh rate and timings
 180 from the Video BIOS if you set pixclock to 0 in fb_var_screeninfo.
 181
 182
 183
 184  Michal Januszewski <spock@gentoo.org>
 185
 186  Last updated: 2017-10-10
 187
 188  Documentation of the uvesafb options is loosely based on vesafb.txt.