File:  [NetBSD Developer Wiki] / wikisrc / tutorials / x11 / how_to_use_wsfb_uefi_bios_framebuffer.md
Revision 1.3: download - view: text, annotated - select for diffs
Fri Jul 16 09:36:24 2021 UTC (4 months, 1 week ago) by wiki
Branches: MAIN
CVS tags: HEAD
auto

    1: [[!meta title="How to use Xorg's wsfb display driver with a UEFI/BIOS framebuffer, and change its resolution"]]
    2: [[!toc levels=3]]
    3: 
    4: Background
    5: ----------
    6: [wsfb(4)](https://man.netbsd.org/wsfb.4) is the Xorg graphics driver for the NetBSD [wsdisplay(4)](https://man.netbsd.org/wsdisplay.4) framebuffer device. `wsdisplay(4)`, similar to Linux's `/dev/fb` devices, provide access to _non-accelerated_ framebuffers, which are provided by _almost all_ modern cards. Most, if not all, _modern_ graphics cards provide what's called a _linear_ framebuffer: a chunk of memory where contiguous address locations map onto adjacent (X, Y) _pixels_. For example, assuming a 32 bits-per-pixel colour depth display, memory location `fbmem + 0` will hold the pixel at position (0,0); `fbmem + 4` corresponds to the pixel at (1, 0), and so on. (We'll skip the complication known as `stride` or `line_length` here.)
    7: 
    8: `wsdisplay(4)` can run on top of: 
    9: 
   10: 1. `genfb(4)`, the Generic PCI VGA framebuffer device (provided by UEFI or BIOS on x86), and other simple software framebuffers provided by hardware or firmware (e.g. simplefb on ARM)
   11: 2. the accelerated [`drm(4)`](https://man.netbsd.org/drm.4) graphics devices (in `/dev/dri/card?`--which `wsfb` will use as a plain framebuffer).
   12: 
   13: Using `wsfb`
   14: ------------
   15: ### Step 1: Configuring `Xorg`
   16: Use this `wsfb.conf` Xorg config fragment:
   17:  
   18: ```
   19: Section "Device"
   20: 	Identifier  "Card0"
   21: 	Driver      "wsfb"
   22: EndSection
   23: ```
   24: 
   25: That is all that is needed. Xorg will autoconfigure everything else. Make sure you dump the `wsfb.conf` file into the correct Xorg config. directory. `/etc/X11/xorg.conf.d/` is the correct location for the Xorg in base. If you've installed the `modular-xorg` package, then the path will need change. Use this command to find your `config directory`:
   26: 
   27: ```
   28: $ fgrep directory /var/log/Xorg.0.log
   29: [    72.697] (==) Using config directory: "/usr/local/etc/X11/xorg.conf.d"
   30: [    72.697] (==) Using system config directory "/usr/local/share/X11/xorg.conf.d"
   31: ```
   32: 
   33: If your DRM kernel driver has loaded OK and is active, then it will have configured your graphics card with the best resolution for your screen and you can just run `X` right away (this wil be X with `wsfb` on `drmkms`, minus the DRM-provided accelerations). You don't need Step 2.
   34: 
   35: If you don't have a DRM driver, or if you can't load it, then if you start `X` now, you'll most probably get the bog-standard 1024x768x32 screen resolution provided by `genfb`, which might be OK, but, is not ideal. As the `wsfb`/`wsdisplay`/`genfb` combo. doesn't let you change resolutions on the fly (`xrandr`, for instance, doesn't work), we'll have to set a better resolution elsewhere: in the bootloader.
   36: 
   37: ### Step 2: Setting a better display mode.
   38: Reboot, then at the bootloader menu, choose the option to get to the bootloader prompt. Here, on UEFI systems, we use the `gop` (Graphics Output Protocol) command like this:
   39: 
   40: List available video modes first:
   41: 
   42: ```
   43: > gop list
   44:  0: 1366x768 BGRR pitch 1376 bpp 32
   45:  1: 640x480 BGRR pitch 640 bpp 32
   46: *2: 800x600 BGRR pitch 800 bpp 32
   47:  3: 1024x768 BGRR pitch 1024 bpp 32
   48: >
   49: ```
   50: 
   51: The `*` indicates the (safe) mode that the bootloader will use by default. Note that on my laptop, mode `0` has a pitch (aka stride) of 1376 pixels. This means that on my graphics card (Asus X202E laptop), the framebuffer is _linear_, but, **not** fully contiguous. The 10 unusable pixels at the end of each row have to taken into account, or else, you'll be treated to a characteristic jagged, streaky display.
   52: 
   53: Choose the best mode, which is generally mode `0`:
   54: 
   55: ```
   56: > gop 0
   57: >
   58: ```
   59: 
   60: The screen resolution will switch immediately. (And hopefully, your display won't go blank, which, these days, usually indicates a graphics card/BIOS/UEFI/whatever that doesn't implement the published standards correctly.)
   61: 
   62: If you have/use BIOS instead of UEFI, you can try the `vesa` command instead of `gop`:
   63: 
   64: ```
   65: > vesa list
   66: ...
   67: > vesa 0xhhh
   68: >
   69: ```
   70: 
   71: If the mode you've chosen works, then you can add that `gop 0` or `vesa mode` command to `boot.cfg` so that it is activated automatically.
   72: 
   73: This is what `dmesg` will show, if you've disabled DRM (see below), or don't have it:
   74: 
   75: ```
   76: $ dmesg | fgrep genfb
   77: [     1.015430] genfb0 at pci0 dev 2 function 0: vendor 8086 product 0166 (rev. 0x09)
   78: [     1.015430] genfb0: framebuffer at 0xe0000000, size 1366x768, depth 32, stride 5504
   79: [     1.015430] genfb0: shadow framebuffer enabled, size 4128 KB
   80: [     1.015430] wsdisplay0 at genfb0 kbdmux 1: console (default, vt100 emulation), using wskbd0
   81: [     1.015430] drm at genfb0 not configured
   82: ```
   83: 
   84: The resolution, depth and stride are all OK. And inside the Xorg server:
   85: 
   86: ```
   87: $ xdpyinfo | fgrep -B1 -A1 resolution
   88:   dimensions:    1366x768 pixels (310x174 millimeters)
   89:   resolution:    112x112 dots per inch
   90:   depths (7):    24, 1, 4, 8, 15, 16, 32
   91: $ xrandr
   92: xrandr: Failed to get size of gamma for output default
   93: Screen 0: minimum 1366 x 768, current 1366 x 768, maximum 1366 x 768
   94: default connected 1366x768+0+0 0mm x 0mm
   95:    1366x768       0.00* 
   96: $
   97: ```
   98: 
   99: Limitations
  100: -----------
  101: 1. No OpenGL hardware acceleration - on x86 and aarch64, llvmpipe (a parallel CPU-based just-in-time renderer) will be used instead
  102: 2. No X Display Power Management Signaling
  103: 3. No X video extension (used for accelerated video playback)
  104: 4. No DRI
  105: 
  106: ## Extra: How to disable built-in DRM driver using kernel's `userconf` manager
  107: 
  108: For testing, or if running `wsfb` on top of the DRM graphics driver does not work--it mostly should, actually).
  109: 
  110: At the bootloader prompt, pass the `-c` flag to the kernel:
  111: 
  112: ```
  113: > boot -c
  114: ```
  115: 
  116: The kernel will display a few lines, then immediately drop into the `userconf` prompt:
  117: 
  118: ```
  119: uc> list                        # list all devs; look for your drmkms entry
  120: uc> disable i915drmkms          # disable Intel DRM
  121: uc> quit
  122: ```
  123: 
  124: Once you've determined the device name using `userconf`, or, by trawling through the GENERIC kernel config file, you can disable the device using the bootloader like this:
  125: 
  126: ```
  127: > userconf disable i915drmkms
  128: ```
  129: 
  130: You can of course, add `userconf` commands also to `boot.conf`
  131: 
  132: ## Minimal `wsfb(4)` config fragment `/etc/X11/xorg.conf.d/wsfb.conf`
  133: 
  134: ```
  135: Section "Device"
  136: 	Identifier  "Card0"
  137: 	Driver      "wsfb"
  138: EndSection
  139: ```
  140: 
  141: ## Minimal `wsfb(4)` `/etc/X11/xorg.conf`
  142: 
  143: Created using `X -configure`, and then changing the graphics device driver (`Section "Device"`) from `intel` to `wsfb`
  144: 
  145: ```
  146: Section "ServerLayout"
  147: 	Identifier     "X.org Configured"
  148: 	Screen      0  "Screen0" 0 0
  149: 	InputDevice    "Mouse0" "CorePointer"
  150: 	InputDevice    "Keyboard0" "CoreKeyboard"
  151: EndSection
  152: 
  153: Section "Files"
  154: 	ModulePath   "/usr/X11R7/lib/modules"
  155: 	FontPath     "/usr/X11R7/lib/X11/fonts/misc/"
  156: 	FontPath     "/usr/X11R7/lib/X11/fonts/TTF/"
  157: 	FontPath     "/usr/X11R7/lib/X11/fonts/Type1/"
  158: 	FontPath     "/usr/X11R7/lib/X11/fonts/75dpi/"
  159: 	FontPath     "/usr/X11R7/lib/X11/fonts/100dpi/"
  160: EndSection
  161: 
  162: Section "Module"
  163: 	Load  "dri"
  164: 	Load  "dri2"
  165: 	Load  "glx"
  166: 	Load  "shadow"
  167: EndSection
  168: 
  169: Section "InputDevice"
  170: 	Identifier  "Keyboard0"
  171: 	Driver      "kbd"
  172: EndSection
  173: 
  174: Section "InputDevice"
  175: 	Identifier  "Mouse0"
  176: 	Driver      "mouse"
  177: 	Option	    "Protocol" "wsmouse"
  178: 	Option	    "Device" "/dev/wsmouse"
  179: 	Option	    "ZAxisMapping" "4 5 6 7"
  180: EndSection
  181: 
  182: Section "Monitor"
  183: 	Identifier   "Monitor0"
  184: 	VendorName   "Monitor Vendor"
  185: 	ModelName    "Monitor Model"
  186: EndSection
  187: 
  188: Section "Device"
  189: 	Identifier  "Card0"
  190: 	Driver      "wsfb"
  191: EndSection
  192: 
  193: Section "Screen"
  194: 	Identifier "Screen0"
  195: 	Device     "Card0"
  196: 	Monitor    "Monitor0"
  197: 	SubSection "Display"
  198: 		Viewport   0 0
  199: 		Depth     1
  200: 	EndSubSection
  201: 	SubSection "Display"
  202: 		Viewport   0 0
  203: 		Depth     4
  204: 	EndSubSection
  205: 	SubSection "Display"
  206: 		Viewport   0 0
  207: 		Depth     8
  208: 	EndSubSection
  209: 	SubSection "Display"
  210: 		Viewport   0 0
  211: 		Depth     15
  212: 	EndSubSection
  213: 	SubSection "Display"
  214: 		Viewport   0 0
  215: 		Depth     16
  216: 	EndSubSection
  217: 	SubSection "Display"
  218: 		Viewport   0 0
  219: 		Depth     24
  220: 	EndSubSection
  221: EndSection
  222: ```

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb