1==========================================================
2uvesafb - A Generic Driver for VBE2+ compliant video cards
3==========================================================
4
51. Requirements
6---------------
7
8uvesafb should work with any video card that has a Video BIOS compliant
9with the VBE 2.0 standard.
10
11Unlike other drivers, uvesafb makes use of a userspace helper called
12v86d.  v86d is used to run the x86 Video BIOS code in a simulated and
13controlled environment.  This allows uvesafb to function on arches other
14than x86.  Check the v86d documentation for a list of currently supported
15arches.
16
17v86d source code can be downloaded from the following website:
18
19  https://github.com/mjanusz/v86d
20
21Please refer to the v86d documentation for detailed configuration and
22installation instructions.
23
24Note that the v86d userspace helper has to be available at all times in
25order for uvesafb to work properly.  If you want to use uvesafb during
26early boot, you will have to include v86d into an initramfs image, and
27either compile it into the kernel or use it as an initrd.
28
292. Caveats and limitations
30--------------------------
31
32uvesafb is a _generic_ driver which supports a wide variety of video
33cards, but which is ultimately limited by the Video BIOS interface.
34The 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
473. Configuration
48----------------
49
50uvesafb can be compiled either as a module, or directly into the kernel.
51In both cases it supports the same set of configuration options, which
52are 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
58Accepted options:
59
60======= =========================================================
61ypan    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
67ywrap   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
72redraw  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
77used a parameter of the scroll option, e.g. scroll=ypan.)
78
79=========== ====================================================================
80vgapal      Use the standard VGA registers for palette changes.
81
82pmipal      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
86mtrr: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
95nomtrr      Do not use memory type range registers.
96
97vremap:n
98            Remap 'n' MiB of video RAM.  If 0 or not specified, remap memory
99            according to video mode.
100
101vtotal: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
109vbemode: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
118nocrtc      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
125noedid      Do not try to fetch and use EDID-provided modes.
126
127noblank     Disable hardware blanking.
128
129v86d: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
135Additionally, the following parameters may be provided.  They all override the
136EDID-provided values and BIOS defaults.  Refer to your monitor's specs to get
137the correct values for maxhf, maxvf and maxclk for your hardware.
138
139=========== ======================================
140maxhf:n     Maximum horizontal frequency (in kHz).
141maxvf:n     Maximum vertical frequency (in Hz).
142maxclk:n    Maximum pixel clock (in MHz).
143=========== ======================================
144
1454. The sysfs interface
146----------------------
147
148uvesafb provides several sysfs nodes for configurable parameters and
149additional information.
150
151Driver 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
160Device 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
1765. Miscellaneous
177----------------
178
179Uvesafb will set a video mode with the default refresh rate and timings
180from 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.
189