Annotation of wikisrc/tutorials/x11/how_to_use_wsfb_uefi_bios_framebuffer.md, revision 1.1
1.1 ! nia 1: How to use Xorg's wsfb display driver with a UEFI/BIOS framebuffer, and change its resolution
! 2: =============================================================================================
! 3:
! 4: ### Background
! 5: [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.)
! 6:
! 7: `wsdisplay(4)` can run on top of:
! 8:
! 9: 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)
! 10: 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).
! 11:
! 12: ### Using `wsfb`
! 13: ### Step 1: Configuring `Xorg`
! 14: Use this `wsfb.conf` Xorg config fragment:
! 15:
! 16: ```
! 17: Section "Device"
! 18: Identifier "Card0"
! 19: Driver "wsfb"
! 20: EndSection
! 21: ```
! 22:
! 23: 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`:
! 24: ```
! 25: $ fgrep directory /var/log/Xorg.0.log
! 26: [ 72.697] (==) Using config directory: "/usr/local/etc/X11/xorg.conf.d"
! 27: [ 72.697] (==) Using system config directory "/usr/local/share/X11/xorg.conf.d"
! 28: ```
! 29:
! 30: 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.
! 31:
! 32: 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.
! 33:
! 34: ### Step 2: Setting a better display mode.
! 35: 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:
! 36: List avaibable video modes first:
! 37: ```
! 38: > gop list
! 39: 0: 1366x768 BGRR pitch 1376 bpp 32
! 40: 1: 640x480 BGRR pitch 640 bpp 32
! 41: *2: 800x600 BGRR pitch 800 bpp 32
! 42: 3: 1024x768 BGRR pitch 1024 bpp 32
! 43: >
! 44: ```
! 45: 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.
! 46:
! 47: Choose the best mode, which is generally mode `0`:
! 48: ```
! 49: > gop 0
! 50: >
! 51: ```
! 52: 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.)
! 53:
! 54: If you have/use BIOS instead of UEFI, you can try the `vesa` command instead of `gop`:
! 55:
! 56: ```
! 57: > vesa list
! 58: ...
! 59: > vesa 0xhhh
! 60: >
! 61: ```
! 62: 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.
! 63:
! 64: This is what `dmesg` will show, if you've disabled DRM (see below), or don't have it:
! 65: ```
! 66: $ dmesg | fgrep genfb
! 67: [ 1.015430] genfb0 at pci0 dev 2 function 0: vendor 8086 product 0166 (rev. 0x09)
! 68: [ 1.015430] genfb0: framebuffer at 0xe0000000, size 1366x768, depth 32, stride 5504
! 69: [ 1.015430] genfb0: shadow framebuffer enabled, size 4128 KB
! 70: [ 1.015430] wsdisplay0 at genfb0 kbdmux 1: console (default, vt100 emulation), using wskbd0
! 71: [ 1.015430] drm at genfb0 not configured
! 72: ```
! 73: The resolution, depth and stride are all OK. And inside the Xorg server:
! 74: ```
! 75: $ xdpyinfo | fgrep -B1 -A1 resolution
! 76: dimensions: 1366x768 pixels (310x174 millimeters)
! 77: resolution: 112x112 dots per inch
! 78: depths (7): 24, 1, 4, 8, 15, 16, 32
! 79: $ xrandr
! 80: xrandr: Failed to get size of gamma for output default
! 81: Screen 0: minimum 1366 x 768, current 1366 x 768, maximum 1366 x 768
! 82: default connected 1366x768+0+0 0mm x 0mm
! 83: 1366x768 0.00*
! 84: $
! 85: ```
! 86:
! 87: ### Limitations
! 88: 1. No OpenGL hardware acceleration - on x86 and aarch64, llvmpipe (a parallel CPU-based just-in-time renderer) will be used instead
! 89: 2. No X Display Power Management Signaling
! 90: 3. No X video extension (used for accelerated video playback)
! 91: 4. No DRI
! 92:
! 93: #### Extra: How to disable built-in DRM driver using kernel's `userconf` manager
! 94:
! 95: For testing, or if running `wsfb` on top of the DRM graphics driver does not work--it mostly should, actually).
! 96:
! 97: At the bootloader prompt, pass the `-c` flag to the kernel:
! 98: ```
! 99: > boot -c
! 100: ```
! 101: The kernel will display a few lines, then immediately drop into the `userconf` prompt:
! 102: ```
! 103: uc> list # list all devs; look for your drmkms entry
! 104: uc> disable i915drmkms # disable Intel DRM
! 105: uc> quit
! 106: ```
! 107: 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:
! 108: ```
! 109: > userconf disable i915drmkms
! 110: ```
! 111: You can of course, add `userconf` commands also to `boot.conf`
! 112:
! 113: #### Minimal `wsfb(4)` config fragment `/etc/X11/xorg.conf.d/wsfb.conf`
! 114: ```
! 115: Section "Device"
! 116: Identifier "Card0"
! 117: Driver "wsfb"
! 118: EndSection
! 119: ```
! 120:
! 121: #### Minimal `wsfb(4)` `/etc/X11/xorg.conf` created using `X -configure`, and then changing the graphics device driver (`Section "Device"`) from `intel` to `wsfb`
! 122:
! 123: ```
! 124: Section "ServerLayout"
! 125: Identifier "X.org Configured"
! 126: Screen 0 "Screen0" 0 0
! 127: InputDevice "Mouse0" "CorePointer"
! 128: InputDevice "Keyboard0" "CoreKeyboard"
! 129: EndSection
! 130:
! 131: Section "Files"
! 132: ModulePath "/usr/X11R7/lib/modules"
! 133: FontPath "/usr/X11R7/lib/X11/fonts/misc/"
! 134: FontPath "/usr/X11R7/lib/X11/fonts/TTF/"
! 135: FontPath "/usr/X11R7/lib/X11/fonts/Type1/"
! 136: FontPath "/usr/X11R7/lib/X11/fonts/75dpi/"
! 137: FontPath "/usr/X11R7/lib/X11/fonts/100dpi/"
! 138: EndSection
! 139:
! 140: Section "Module"
! 141: Load "dri"
! 142: Load "dri2"
! 143: Load "glx"
! 144: Load "shadow"
! 145: EndSection
! 146:
! 147: Section "InputDevice"
! 148: Identifier "Keyboard0"
! 149: Driver "kbd"
! 150: EndSection
! 151:
! 152: Section "InputDevice"
! 153: Identifier "Mouse0"
! 154: Driver "mouse"
! 155: Option "Protocol" "wsmouse"
! 156: Option "Device" "/dev/wsmouse"
! 157: Option "ZAxisMapping" "4 5 6 7"
! 158: EndSection
! 159:
! 160: Section "Monitor"
! 161: Identifier "Monitor0"
! 162: VendorName "Monitor Vendor"
! 163: ModelName "Monitor Model"
! 164: EndSection
! 165:
! 166: Section "Device"
! 167: Identifier "Card0"
! 168: Driver "wsfb"
! 169: EndSection
! 170:
! 171: Section "Screen"
! 172: Identifier "Screen0"
! 173: Device "Card0"
! 174: Monitor "Monitor0"
! 175: SubSection "Display"
! 176: Viewport 0 0
! 177: Depth 1
! 178: EndSubSection
! 179: SubSection "Display"
! 180: Viewport 0 0
! 181: Depth 4
! 182: EndSubSection
! 183: SubSection "Display"
! 184: Viewport 0 0
! 185: Depth 8
! 186: EndSubSection
! 187: SubSection "Display"
! 188: Viewport 0 0
! 189: Depth 15
! 190: EndSubSection
! 191: SubSection "Display"
! 192: Viewport 0 0
! 193: Depth 16
! 194: EndSubSection
! 195: SubSection "Display"
! 196: Viewport 0 0
! 197: Depth 24
! 198: EndSubSection
! 199: EndSection
! 200: ```
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb