Annotation of wikisrc/tutorials/x11/how_to_use_wsfb_uefi_bios_framebuffer.md, revision 1.3

1.3     ! wiki        1: [[!meta title="How to use Xorg's wsfb display driver with a UEFI/BIOS framebuffer, and change its resolution"]]
        !             2: [[!toc levels=3]]
1.2       nia         3: 
1.3     ! wiki        4: Background
        !             5: ----------
1.1       nia         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: 
1.3     ! wiki       13: Using `wsfb`
        !            14: ------------
1.1       nia        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`:
1.3     ! wiki       26: 
1.1       nia        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:
1.3     ! wiki       39: 
        !            40: List available video modes first:
        !            41: 
1.1       nia        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: ```
1.3     ! wiki       50: 
1.1       nia        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`:
1.3     ! wiki       54: 
1.1       nia        55: ```
                     56: > gop 0
                     57: >
                     58: ```
1.3     ! wiki       59: 
1.1       nia        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: ```
1.3     ! wiki       70: 
1.1       nia        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:
1.3     ! wiki       74: 
1.1       nia        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: ```
1.3     ! wiki       83: 
1.1       nia        84: The resolution, depth and stride are all OK. And inside the Xorg server:
1.3     ! wiki       85: 
1.1       nia        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: 
1.3     ! wiki       99: Limitations
        !           100: -----------
1.1       nia       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: 
1.3     ! wiki      106: ## Extra: How to disable built-in DRM driver using kernel's `userconf` manager
1.1       nia       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:
1.3     ! wiki      111: 
1.1       nia       112: ```
                    113: > boot -c
                    114: ```
1.3     ! wiki      115: 
1.1       nia       116: The kernel will display a few lines, then immediately drop into the `userconf` prompt:
1.3     ! wiki      117: 
1.1       nia       118: ```
                    119: uc> list                        # list all devs; look for your drmkms entry
                    120: uc> disable i915drmkms          # disable Intel DRM
                    121: uc> quit
                    122: ```
1.3     ! wiki      123: 
1.1       nia       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:
1.3     ! wiki      125: 
1.1       nia       126: ```
                    127: > userconf disable i915drmkms
                    128: ```
1.3     ! wiki      129: 
1.1       nia       130: You can of course, add `userconf` commands also to `boot.conf`
                    131: 
1.3     ! wiki      132: ## Minimal `wsfb(4)` config fragment `/etc/X11/xorg.conf.d/wsfb.conf`
        !           133: 
1.1       nia       134: ```
                    135: Section "Device"
                    136:        Identifier  "Card0"
                    137:        Driver      "wsfb"
                    138: EndSection
                    139: ```
                    140: 
1.3     ! wiki      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`
1.1       nia       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