uvesafb.rst 7.2 KB

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