uvesafb - A Generic Driver for VBE2+ compliant video cards

VBE 2.0과 v86d 요구 사항

`uvesafb`는 Video BIOS가 VBE 2.0 표준을 따르는 모든 비디오 카드에서 동작하도록 설계된 범용 드라이버입니다.

다른 드라이버와 달리 `v86d`라는 사용자 공간 helper를 사용합니다. `v86d`는 x86 Video BIOS 코드를 simulation되고 통제된 환경에서 실행하므로 `uvesafb`가 x86 이외 아키텍처에서도 동작할 수 있습니다. 현재 지원 아키텍처는 `v86d` 문서를 확인합니다.

소스는 `https://github.com/mjanusz/v86d`에서 받을 수 있으며 상세한 구성과 설치 방법도 `v86d` 문서를 따릅니다.

`uvesafb`가 올바르게 동작하려면 `v86d` helper가 항상 사용 가능해야 합니다. early boot에서 사용하려면 `v86d`를 initramfs image에 포함하고, uvesafb는 커널에 내장하거나 initrd로 사용해야 합니다.

==========================================================
uvesafb - A Generic Driver for VBE2+ compliant video cards
==========================================================

1. Requirements
---------------

uvesafb should work with any video card that has a Video BIOS compliant
with the VBE 2.0 standard.

Unlike other drivers, uvesafb makes use of a userspace helper called
v86d.  v86d is used to run the x86 Video BIOS code in a simulated and
controlled environment.  This allows uvesafb to function on arches other
than x86.  Check the v86d documentation for a list of currently supported
arches.

v86d source code can be downloaded from the following website:

  https://github.com/mjanusz/v86d

Please refer to the v86d documentation for detailed configuration and
installation instructions.

Note that the v86d userspace helper has to be available at all times in
order for uvesafb to work properly.  If you want to use uvesafb during
early boot, you will have to include v86d into an initramfs image, and
either compile it into the kernel or use it as an initrd.

범용 Video BIOS 경로의 한계

`uvesafb`는 다양한 카드를 지원하는 범용 드라이버지만 궁극적으로 Video BIOS interface에 제한됩니다. 어떤 acceleration도 제공하지 않습니다.

지원 video mode가 엄격하고 제한적이어서 환경의 native 또는 최적 해상도·주사율이 BIOS 목록에 없으면 사용할 수 없습니다. 대부분 BIOS가 4:3 aspect ratio에 제한되므로 widescreen panel에서 특히 문제가 됩니다.

refresh rate 조정은 VBE 3.0 compliant Video BIOS에서만 가능합니다. 많은 nVidia Video BIOS가 VBE 3.0 준수를 표시하면서 실제로는 refresh rate 설정을 무시한다는 점도 주의해야 합니다.

2. Caveats and limitations
--------------------------

uvesafb is a _generic_ driver which supports a wide variety of video
cards, but which is ultimately limited by the Video BIOS interface.
The most important limitations are:

- Lack of any type of acceleration.
- A strict and limited set of supported video modes.  Often the native
  or most optimal resolution/refresh rate for your setup will not work
  with uvesafb, simply because the Video BIOS doesn't support the
  video mode you want to use.  This can be especially painful with
  widescreen panels, where native video modes don't have the 4:3 aspect
  ratio, which is what most BIOS-es are limited to.
- Adjusting the refresh rate is only possible with a VBE 3.0 compliant
  Video BIOS.  Note that many nVidia Video BIOS-es claim to be VBE 3.0
  compliant, while they simply ignore any refresh rate settings.

내장·모듈 설정과 scrolling

`uvesafb`는 모듈이나 커널 내장으로 컴파일할 수 있고 두 형태 모두 같은 옵션을 지원합니다. 내장 예는 `video=uvesafb:1024x768-32,mtrr:3,ywrap`, 모듈 예는 `modprobe uvesafb mode_option=1024x768-32 mtrr=3 scroll=ywrap`입니다.

`ypan`은 VESA protected-mode interface로 display panning을 켭니다. 보이는 화면은 video memory의 창이며 시작 위치를 옮겨 console을 scroll합니다. x86에서만 가능하고 그 아키텍처의 기본값입니다.

`ywrap`은 `ypan`과 같지만 video memory 끝에 도달하면 처음부터 읽는 wraparound를 카드가 지원한다고 가정해 더 빠릅니다. 역시 x86 전용입니다. `redraw`는 영향받은 영역을 다시 그리며 non-x86의 기본값입니다.

모듈에서는 세 scrolling 방식이 `scroll=ypan`처럼 `scroll` option의 값으로 전달됩니다.

3. Configuration
----------------

uvesafb can be compiled either as a module, or directly into the kernel.
In both cases it supports the same set of configuration options, which
are either given on the kernel command line or as module parameters, e.g.::

 video=uvesafb:1024x768-32,mtrr:3,ywrap (compiled into the kernel)

 # modprobe uvesafb mode_option=1024x768-32 mtrr=3 scroll=ywrap  (module)

Accepted options:

======= =========================================================
ypan    Enable display panning using the VESA protected mode
        interface.  The visible screen is just a window of the
        video memory, console scrolling is done by changing the
        start of the window.  This option is available on x86
        only and is the default option on that architecture.

ywrap   Same as ypan, but assumes your gfx board can wrap-around
        the video memory (i.e. starts reading from top if it
        reaches the end of video memory).  Faster than ypan.
        Available on x86 only.

redraw  Scroll by redrawing the affected part of the screen, this
        is the default on non-x86.
======= =========================================================

(If you're using uvesafb as a module, the above three options are
used a parameter of the scroll option, e.g. scroll=ypan.)

palette·MTRR·mode·v86d 옵션

`vgapal`은 palette 변경에 표준 VGA register를 사용합니다. `pmipal`은 protected-mode interface를 사용하며 해당 interface가 있으면 기본이고 x86에서만 가능합니다.

`mtrr:n`은 framebuffer의 memory type range register를 설정합니다. 0은 비활성화로 `nomtrr`와 같고, 3은 write-combining이며 기본값입니다. 0과 3 이외의 값은 경고를 내고 3처럼 처리합니다. `nomtrr`는 MTRR을 사용하지 않습니다.

`vremap:n`은 video RAM n MiB를 remap합니다. 0이거나 생략하면 video mode에 따라 remap합니다. `vtotal:n`은 BIOS가 총 video RAM을 잘못 판단할 때 MiB 단위로 덮어씁니다.

`<mode>`는 표준 modedb 형식이며 자세한 설명은 `modedb.txt`를 참고합니다. 모듈에서는 문자열을 `mode_option` 값으로 전달합니다. `vbemode:x`는 VBE가 제공한 지원 목록에 있는 VBE mode x를 강제로 사용합니다. Linux kernel 표기가 아니라 VESA mode number 표기, 예를 들어 769가 아닌 257을 써야 합니다.

일반 `<mode>`가 실패해 `vbemode`를 사용하고 X server도 쓴다면 console과 X 사이 전환 후 mode를 복원하도록 `nocrtc`를 함께 쓰는 편이 좋습니다. `nocrtc`는 VBE 3.0 BIOS에서만 의미가 있고 CRTC timing을 사용하지 않습니다. refresh 조정은 무시되어 BIOS 기본 60 Hz를 유지합니다.

`noedid`는 EDID mode를 가져오거나 사용하지 않고, `noblank`는 hardware blanking을 끕니다. `v86d:path`는 `v86d` executable 경로를 정하는 모듈 전용 option입니다. 커널 내장에서는 `uvesafb.v86d="path"`를 사용합니다.

=========== ====================================================================
vgapal      Use the standard VGA registers for palette changes.

pmipal      Use the protected mode interface for palette changes.
            This is the default if the protected mode interface is
            available.  Available on x86 only.

mtrr:n      Setup memory type range registers for the framebuffer
            where n:

                - 0 - disabled (equivalent to nomtrr)
                - 3 - write-combining (default)

            Values other than 0 and 3 will result in a warning and will be
            treated just like 3.

nomtrr      Do not use memory type range registers.

vremap:n
            Remap 'n' MiB of video RAM.  If 0 or not specified, remap memory
            according to video mode.

vtotal:n    If the video BIOS of your card incorrectly determines the total
            amount of video RAM, use this option to override the BIOS (in MiB).

<mode>      The mode you want to set, in the standard modedb format.  Refer to
            modedb.txt for a detailed description.  When uvesafb is compiled as
            a module, the mode string should be provided as a value of the
            'mode_option' option.

vbemode:x   Force the use of VBE mode x.  The mode will only be set if it's
            found in the VBE-provided list of supported modes.
            NOTE: The mode number 'x' should be specified in VESA mode number
            notation, not the Linux kernel one (eg. 257 instead of 769).
            HINT: If you use this option because normal <mode> parameter does
            not work for you and you use a X server, you'll probably want to
            set the 'nocrtc' option to ensure that the video mode is properly
            restored after console <-> X switches.

nocrtc      Do not use CRTC timings while setting the video mode.  This option
            has any effect only if the Video BIOS is VBE 3.0 compliant.  Use it
            if you have problems with modes set the standard way.  Note that
            using this option implies that any refresh rate adjustments will
            be ignored and the refresh rate will stay at your BIOS default
            (60 Hz).

noedid      Do not try to fetch and use EDID-provided modes.

noblank     Disable hardware blanking.

v86d:path   Set path to the v86d executable. This option is only available as
            a module parameter, and not as a part of the video= string.  If you
            need to use it and have uvesafb built into the kernel, use
            uvesafb.v86d="path".
=========== ====================================================================

monitor override와 sysfs 정보

`maxhf:n`, `maxvf:n`, `maxclk:n`은 EDID와 BIOS 기본값을 덮어씁니다. 각각 최대 horizontal frequency(kHz), 최대 vertical frequency(Hz), 최대 pixel clock(MHz)이며 monitor 사양에 맞는 값을 써야 합니다.

driver 속성 경로는 `/sys/bus/platform/drivers/uvesafb`입니다. 그 아래 `v86d`는 executable 경로이며 기본값은 `/sbin/v86d`입니다. daemon instance가 이미 실행 중이 아니면 `uvesafb`가 시작합니다.

device 속성은 `/sys/bus/platform/drivers/uvesafb/uvesafb.0` 아래에 있습니다. `nocrtc=1`은 기본 60 Hz를 사용합니다. `oem_product_name`, `oem_product_rev`, `oem_string`, `oem_vendor`는 카드와 제조사 정보를 제공합니다.

`vbe_modes`는 Video BIOS 지원 mode와 16진수 VBE mode number 목록이고, `vbe_version`은 구현된 VBE 표준을 나타내는 BCD 값입니다.

Additionally, the following parameters may be provided.  They all override the
EDID-provided values and BIOS defaults.  Refer to your monitor's specs to get
the correct values for maxhf, maxvf and maxclk for your hardware.

=========== ======================================
maxhf:n     Maximum horizontal frequency (in kHz).
maxvf:n     Maximum vertical frequency (in Hz).
maxclk:n    Maximum pixel clock (in MHz).
=========== ======================================

4. The sysfs interface
----------------------

uvesafb provides several sysfs nodes for configurable parameters and
additional information.

Driver attributes:

/sys/bus/platform/drivers/uvesafb
  v86d
    (default: /sbin/v86d)

    Path to the v86d executable. v86d is started by uvesafb
    if an instance of the daemon isn't already running.

Device attributes:

/sys/bus/platform/drivers/uvesafb/uvesafb.0
  nocrtc
    Use the default refresh rate (60 Hz) if set to 1.

  oem_product_name, oem_product_rev, oem_string, oem_vendor
    Information about the card and its maker.

  vbe_modes
    A list of video modes supported by the Video BIOS along with their
    VBE mode numbers in hex.

  vbe_version
    A BCD value indicating the implemented VBE standard.

기본 timing 동작과 문서 정보

`fb_var_screeninfo`에서 `pixclock`을 0으로 설정하면 `uvesafb`는 Video BIOS의 기본 refresh rate와 timing으로 video mode를 설정합니다.

작성자는 Michal Januszewski이고 마지막 갱신일은 2017-10-10입니다. `uvesafb` option 문서는 `vesafb.txt`를 느슨하게 바탕으로 작성되었습니다.

5. Miscellaneous
----------------

Uvesafb will set a video mode with the default refresh rate and timings
from the Video BIOS if you set pixclock to 0 in fb_var_screeninfo.



 Michal Januszewski <spock@gentoo.org>

 Last updated: 2017-10-10

 Documentation of the uvesafb options is loosely based on vesafb.txt.