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