GNU Linux-libre 4.19.264-gnu1
[releases.git] / Documentation / fb / uvesafb.txt
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 ypan    Enable display panning using the VESA protected mode
61         interface.  The visible screen is just a window of the
62         video memory, console scrolling is done by changing the
63         start of the window.  This option is available on x86
64         only and is the default option on that architecture.
65
66 ywrap   Same as ypan, but assumes your gfx board can wrap-around
67         the video memory (i.e. starts reading from top if it
68         reaches the end of video memory).  Faster than ypan.
69         Available on x86 only.
70
71 redraw  Scroll by redrawing the affected part of the screen, this
72         is the default on non-x86.
73
74 (If you're using uvesafb as a module, the above three options are
75  used a parameter of the scroll option, e.g. scroll=ypan.)
76
77 vgapal  Use the standard VGA registers for palette changes.
78
79 pmipal  Use the protected mode interface for palette changes.
80         This is the default if the protected mode interface is
81         available.  Available on x86 only.
82
83 mtrr:n  Setup memory type range registers for the framebuffer
84         where n:
85               0 - disabled (equivalent to nomtrr)
86               3 - write-combining (default)
87
88         Values other than 0 and 3 will result in a warning and will be
89         treated just like 3.
90
91 nomtrr  Do not use memory type range registers.
92
93 vremap:n
94         Remap 'n' MiB of video RAM.  If 0 or not specified, remap memory
95         according to video mode.
96
97 vtotal:n
98         If the video BIOS of your card incorrectly determines the total
99         amount of video RAM, use this option to override the BIOS (in MiB).
100
101 <mode>  The mode you want to set, in the standard modedb format.  Refer to
102         modedb.txt for a detailed description.  When uvesafb is compiled as
103         a module, the mode string should be provided as a value of the
104         'mode_option' option.
105
106 vbemode:x
107         Force the use of VBE mode x.  The mode will only be set if it's
108         found in the VBE-provided list of supported modes.
109         NOTE: The mode number 'x' should be specified in VESA mode number
110         notation, not the Linux kernel one (eg. 257 instead of 769).
111         HINT: If you use this option because normal <mode> parameter does
112         not work for you and you use a X server, you'll probably want to
113         set the 'nocrtc' option to ensure that the video mode is properly
114         restored after console <-> X switches.
115
116 nocrtc  Do not use CRTC timings while setting the video mode.  This option
117         has any effect only if the Video BIOS is VBE 3.0 compliant.  Use it
118         if you have problems with modes set the standard way.  Note that
119         using this option implies that any refresh rate adjustments will
120         be ignored and the refresh rate will stay at your BIOS default (60 Hz).
121
122 noedid  Do not try to fetch and use EDID-provided modes.
123
124 noblank Disable hardware blanking.
125
126 v86d:path
127         Set path to the v86d executable. This option is only available as
128         a module parameter, and not as a part of the video= string.  If you
129         need to use it and have uvesafb built into the kernel, use
130         uvesafb.v86d="path".
131
132 Additionally, the following parameters may be provided.  They all override the
133 EDID-provided values and BIOS defaults.  Refer to your monitor's specs to get
134 the correct values for maxhf, maxvf and maxclk for your hardware.
135
136 maxhf:n     Maximum horizontal frequency (in kHz).
137 maxvf:n     Maximum vertical frequency (in Hz).
138 maxclk:n    Maximum pixel clock (in MHz).
139
140 4. The sysfs interface
141 ----------------------
142
143 uvesafb provides several sysfs nodes for configurable parameters and
144 additional information.
145
146 Driver attributes:
147
148 /sys/bus/platform/drivers/uvesafb
149   - v86d (default: /sbin/v86d)
150     Path to the v86d executable. v86d is started by uvesafb
151     if an instance of the daemon isn't already running.
152
153 Device attributes:
154
155 /sys/bus/platform/drivers/uvesafb/uvesafb.0
156   - nocrtc
157     Use the default refresh rate (60 Hz) if set to 1.
158
159   - oem_product_name
160   - oem_product_rev
161   - oem_string
162   - oem_vendor
163     Information about the card and its maker.
164
165   - vbe_modes
166     A list of video modes supported by the Video BIOS along with their
167     VBE mode numbers in hex.
168
169   - vbe_version
170     A BCD value indicating the implemented VBE standard.
171
172 5. Miscellaneous
173 ----------------
174
175 Uvesafb will set a video mode with the default refresh rate and timings
176 from the Video BIOS if you set pixclock to 0 in fb_var_screeninfo.
177
178
179 --
180  Michal Januszewski <spock@gentoo.org>
181  Last updated: 2017-10-10
182
183  Documentation of the uvesafb options is loosely based on vesafb.txt.
184