WSDISPLAY(4)

💖 WSDISPLAY(4) 💖

Okay so welcome to the WSDISPLAY(4) page in the Kernel Interfaces Manual, bestie. This is the whole vibe: generic display device support in wscons, and yes, we're keeping every single detail. No cap.

📛 NAME

wsdisplay — generic display device support in wscons

🌈 SYNOPSIS 🌈

wsdisplay* at ega? console ?
(EGA display on ISA)
wsdisplay* at vga? console ?
(VGA display on ISA or PCI)
wsdisplay* at pcdisplay? console ?
(generic PC (ISA) display)
wsdisplay* at tga? console ?
(DEC TGA display, alpha only)
wsdisplay* at pfb? console ?
(PCI framebuffer, bebox only)
wsdisplay0 at ofb? console ?
(Open Firmware framebuffer, macppc only)
wsdisplay* at nextdisplay? console ?
(NeXT display)
wsdisplay0 at smg0
(VAXstation small monochrome display)
wsdisplay* at ... kbdmux N

options WSDISPLAY_BORDER_COLOR=WSCOL_XXX
options WSDISPLAY_CUSTOM_BORDER
options WSDISPLAY_CUSTOM_OUTPUT
options WSDISPLAY_DEFAULTSCREENS=N
options WSDISPLAY_SCROLLSUPPORT

💬 DESCRIPTION 💬

The wsdisplay driver is, like, the abstraction layer for display devices inside the wscons(4) framework. It attaches to the hardware-specific display device driver and makes that display available as a text terminal or graphics interface. Main character energy, honestly.

A display device can have the ability to display characters on it — without the help of an X server — either directly by hardware or through software putting pixel data into the display memory. Such displays are called “emulating”, and the wsdisplay driver will connect a terminal emulation module and provide a tty-like software interface. In contrary, non-emulating displays can only be used by special programs like X servers.

The console locator in the configuration line refers to the device's use as the output part of the operating system console. A device specification containing a positive value here will only match if the device is in use as the system console. (The console device selection in early system startup is not influenced.) This way, the console device can be connected to a known wsdisplay device instance. (Naturally, only “emulating” display devices are usable as console.)

The kbdmux locator in the configuration line refers to the wsmux(4) that will be used to get keyboard events. If this locator is -1 no mux will be used.

The logical unit of independent contents displayed on a display (sometimes referred to as “virtual terminal”) is called a “screen” here. If the underlying device driver supports it, multiple screens can be used on one display. (As of this writing, only the vga(4) and the VAX “smg” display drivers provide this ability.) Screens have different minor device numbers and separate tty instances. One screen possesses the “focus”, this means it is visible and its tty device will get the keyboard input. (In some cases — if no screen is set up or if a screen was just deleted — it is possible that no focus is present at all.) The focus can be switched by either special keyboard input (⟨Ctrl⟩⟨Alt⟩⟨Fn⟩, ⟨Stop⟩⟨Fn⟩ on Sun hardware, ⟨Command⟩⟨Fn⟩ on ADB keyboards) or an ioctl command issued by a user program. Screens are created and deleted through the /dev/ttyEcfg control device (preferably using the wsconscfg(8) utility). Alternatively, the compile-time option WSDISPLAY_DEFAULTSCREENS=n will also create (at autoconfiguration time) n initial screens of the display driver's default type with the system's default terminal emulator.

⚙️ Kernel options ⚙️

The following kernel options are available to configure the behavior of the wsdisplay driver:

• options WSDISPLAY_BORDER_COLOR=WSCOL_XXX — Sets the border color at boot time. Possible values are defined in src/sys/dev/wscons/wsdisplayvar.h. Defaults to WSCOL_BLACK.
• options WSDISPLAY_CUSTOM_BORDER — Enables the WSDISPLAYIO_GBORDER and WSDISPLAYIO_SBORDER ioctls, which allow the customization of the border color from userland (after boot). See wsconsctl(8).
• options WSDISPLAY_CUSTOM_OUTPUT — Enables the WSDISPLAYIO_GMSGATTRS and WSDISPLAYIO_SMSGATTRS ioctls, which allow the customization of the console output and kernel messages from userland (after boot). See wsconsctl(8).
• options WSDISPLAY_DEFAULTSCREENS=N — Sets the number of virtual screens to allocate at boot time. Useful for small root filesystems where the wsconscfg(8) utility is not wanted.
• options WSDISPLAY_SCROLLSUPPORT — Enables scrolling support. The key combinations are ⟨Left Shift⟩⟨Page Up⟩ and ⟨Left Shift⟩⟨Page Down⟩ by default. Please note that this function may not work under the system console and is available depending on the framebuffer you are using.

Scroll support is giving “it depends on your framebuffer,” bestie — not every setup is gonna slay here.

🎛️ Ioctls 🎛️

The following ioctl(2) calls are provided by the wsdisplay driver or by devices which use it. Their definitions are found in <dev/wscons/wsconsio.h>.

• WSDISPLAYIO_GTYPE (int) — Retrieve the type of the display. The list of types is in <dev/wscons/wsconsio.h>.
• WSDISPLAYIO_GET_FBINFO (struct wsdisplayio_fbinfo) — Retrieve extended information about a framebuffer display, including the framebuffer's pixel packing layout. The returned structure is as follows:

struct wsdisplayio_fbinfo {
        uint64_t fbi_fbsize;
        uint64_t fbi_fboffset;
        uint32_t fbi_width;
        uint32_t fbi_height;
        uint32_t fbi_stride;
        uint32_t fbi_bitsperpixel;
        uint32_t fbi_pixeltype;
        union _fbi_subtype {
                struct _fbi_rgbmasks {
                        uint32_t red_offset;
                        uint32_t red_size;
                        uint32_t green_offset;
                        uint32_t green_size;
                        uint32_t blue_offset;
                        uint32_t blue_size;
                        uint32_t alpha_offset;
                        uint32_t alpha_size;
                } fbi_rgbmasks;
                struct _fbi_cmapinfo {
                        uint32_t cmap_entries;
                } fbi_cmapinfo;
        } fbi_subtype;
        uint32_t fbi_flags;
};

For a “true colour” display, the fbi_pixeltype field contains WSFB_RGB and the fbi_rgbmasks field contains the pixel packing layout. For a colour indexed display, the fbi_pixeltype field contains WSFB_CI and the fbi_cmapinfo field contains the number of color map entries.

• WSDISPLAYIO_GINFO (struct wsdisplay_fbinfo) — Retrieve basic information about a framebuffer display. The returned structure is as follows:

struct wsdisplay_fbinfo {
        u_int   height;
        u_int   width;
        u_int   depth;
        u_int   cmsize;
};

The height and width members are counted in pixels. The depth member indicates the number of bits per pixel, and cmsize indicates the number of color map entries accessible through WSDISPLAYIO_GETCMAP and WSDISPLAYIO_PUTCMAP. This call is likely to be unavailable on text-only displays.

• WSDISPLAYIO_GETCMAP (struct wsdisplay_cmap) — Retrieve the current color map from the display. This call needs the following structure set up beforehand:

struct wsdisplay_cmap {
        u_int   index;
        u_int   count;
        u_char  *red;
        u_char  *green;
        u_char  *blue;
};

The index and count members specify the range of color map entries to retrieve. The red, green, and blue members should each point to an array of count u_chars. On return, these will be filled in with the appropriate entries from the color map. On all displays that support this call, values range from 0 for minimum intensity to 255 for maximum intensity, even if the display does not use eight bits internally to represent intensity.

• WSDISPLAYIO_PUTCMAP (struct wsdisplay_cmap) — Change the display's color map. The argument structure is the same as for WSDISPLAYIO_GETCMAP, but red, green, and blue are taken as pointers to the values to use to set the color map. This call is not available on displays with fixed color maps.
• WSDISPLAYIO_GVIDEO (int) — Get the current state of the display's video output. Possible values are:
  • WSDISPLAYIO_VIDEO_OFF — The display is blanked.
  • WSDISPLAYIO_VIDEO_ON — The display is enabled.
• WSDISPLAYIO_SVIDEO (int) — Set the state of the display's video output. See WSDISPLAYIO_GVIDEO above for possible values.
• WSDISPLAYIO_GCURPOS (struct wsdisplay_curpos) — Retrieve the current position of the hardware cursor. The returned structure is as follows:

struct wsdisplay_curpos {
        u_int x, y;
};

The x and y members count the number of pixels right and down, respectively, from the top-left corner of the display to the hot spot of the cursor. This call is not available on displays without a hardware cursor.

• WSDISPLAYOP_SCURPOS (struct wsdisplay_curpos) — Set the current cursor position. The argument structure, and its semantics, are the same as for WSDISPLAYIO_GCURPOS. This call is not available on displays without a hardware cursor. (Yes, it's literally WSDISPLAYOP_SCURPOS in the page — not a typo I made, bestie.)

🌸 WSDISPLAYIO_GCURMAX (struct wsdisplay_curpos)

Okay so this one asks the display "bestie, how big can your cursor even get?" 💅 It retrieves the maximum size of cursor supported by the display. The x and y members of the returned structure tell you the maximum number of pixel rows and columns, respectively, in a hardware cursor on this display. Heads up though: this call is not available on displays without a hardware cursor. 🙈

🦋 WSDISPLAYIO_GCURSOR (struct wsdisplay_cursor)

This one grabs some or all of the hardware cursor's attributes, and the argument structure is giving main character energy:

struct wsdisplay_cursor {
        u_int   which;
        u_int   enable;
        struct wsdisplay_curpos pos;
        struct wsdisplay_curpos hot;
        struct wsdisplay_cmap cmap;
        struct wsdisplay_curpos size;
        u_char *image;
        u_char *mask;
};

The which member is literally you telling it which values you want back — it should contain the logical OR of these flags:

• WSDISPLAY_CURSOR_DOCUR — Get enable, which indicates whether the cursor is currently displayed (non-zero) or not (zero). 👀
• WSDISPLAY_CURSOR_DOPOS — Get pos, which indicates the current position of the cursor on the display, as would be returned by WSDISPLAYIO_GCURPOS.
• WSDISPLAY_CURSOR_DOHOT — Get hot, which indicates the location of the “hot spot” within the cursor. This is the point on the cursor whose position on the display is treated as being the position of the cursor by other calls. Its location is counted in pixels from the top-right corner of the cursor.
• WSDISPLAY_CURSOR_DOCMAP — Get cmap, which indicates the current cursor color map. Unlike in a call to WSDISPLAYIO_GETCMAP, cmap here need not have its index and count members initialized. They will be set to 0 and 2 respectively by the call. This means that cmap.red, cmap.green, and cmap.blue must each point to at least enough space to hold two u_chars. 🎀
• WSDISPLAY_CURSOR_DOSHAPE — Get size, image, and mask. These are, respectively, the dimensions of the cursor in pixels, the bitmap of set pixels in the cursor and the bitmap of opaque pixels in the cursor. The format in which these bitmaps are returned, and hence the amount of space that must be provided by the application, are device-dependent. 🔥
• WSDISPLAY_CURSOR_DOALL — Get all of the above. Slay, give me everything. ✨

Ngl, the device may elect to return information that was not requested by the user, so those elements of struct wsdisplay_cursor which are pointers should be initialized to NULL if not otherwise used. 🙏 And fr, this call is not available on displays without a hardware cursor.

💜 WSDISPLAYIO_SCURSOR (struct wsdisplay_cursor)

Now we're setting some or all of the hardware cursor's attributes. The argument structure is the same as for WSDISPLAYIO_GCURSOR. The which member specifies which attributes of the cursor are to be changed, and it should contain the logical OR of:

• WSDISPLAY_CURSOR_DOCUR — If enable is zero, hide the cursor. Otherwise, display it. 🫣
• WSDISPLAY_CURSOR_DOPOS — Set the cursor's position on the display to pos, the same as WSDISPLAYIO_SCURPOS.
• WSDISPLAY_CURSOR_DOHOT — Set the “hot spot” of the cursor, as defined above, to hot.
• WSDISPLAY_CURSOR_DOCMAP — Set some or all of the cursor color map based on cmap. The index and count elements of cmap indicate which color map entries to set, and the entries themselves come from cmap.red, cmap.green, and cmap.blue.
• WSDISPLAY_CURSOR_DOSHAPE — Set the cursor shape from size, image, and mask. See above for their meanings. 💅
• WSDISPLAY_CURSOR_DOALL — Do all of the above. Periodt.

Same deal as before: this call is not available on displays without a hardware cursor. 😭

🌈 WSDISPLAYIO_GMODE (u_int)

Get the current mode of the display. Possible results include:

• WSDISPLAYIO_MODE_EMUL — The display is in emulating (text) mode.
• WSDISPLAYIO_MODE_MAPPED — The display is in mapped (graphics) mode.
• WSDISPLAYIO_MODE_DUMBFB — The display is in mapped (frame buffer) mode.

⭐ WSDISPLAYIO_SMODE (u_int)

Set the current mode of the display. For possible arguments, see WSDISPLAYIO_GMODE. Easy. 💫

🍓 WSDISPLAYIO_LINEBYTES (u_int)

Get the number of bytes per row — which may be the same as the number of pixels. iykyk. 🎀

🧚 WSDISPLAYIO_GMSGATTRS (struct wsdisplay_msgattrs)

Get the attributes (colors and flags) used to print console messages, including separate fields for default output and kernel output. The returned structure is iconic:

struct wsdisplay_msgattrs {
        int default_attrs, default_bg, default_fg;
        int kernel_attrs, kernel_bg, kernel_fg;
};

The default_attrs and kernel_attrs variables are a combination of WSATTR_* bits, and specify the attributes used to draw messages. The default_bg, default_fg, kernel_bg and kernel_fg variables specify the colors used to print messages, being ‘_bg’ for the background and ‘_fg’ for the foreground; their values are one of all the WSCOL_* macros available. 🎨

🌸 WSDISPLAYIO_SMSGATTRS (struct wsdisplay_msgattrs)

Set the attributes (colors and flags) used to print console messages, including separate fields for default output and kernel output. The argument structure is the same as for WSDISPLAYIO_GMSGATTRS. Matching set, we love to see it. 🫶

🎀 WSDISPLAYIO_GBORDER (u_int)

Retrieve the color of the screen border. This number corresponds to an ANSI standard color.

🦋 WSDISPLAYIO_SBORDER (u_int)

Set the color of the screen border, if applicable. This number corresponds to an ANSI standard color. Not all drivers support this feature — so don't come for the driver if it doesn't. 💀

👑 WSDISPLAYIO_GETWSCHAR (struct wsdisplay_char)

Gets a single character from the screen, specified by its position. The structure used is as follows:

struct wsdisplay_char {
        int row, col;
        uint16_t letter;
        uint8_t background, foreground;
        char flags;
};

The row and col parameters are used as input; the rest of the structure is filled by the ioctl and is returned to you. letter is the ASCII code of the letter found at the specified position, background and foreground are its colors and flags is a combination of WSDISPLAY_CHAR_BRIGHT and/or WSDISPLAY_CHAR_BLINK. ✨

💜 WSDISPLAYIO_PUTWSCHAR (struct wsdisplay_char)

Puts a character on the screen. The structure has the same meaning as described in WSDISPLAY_GETWSCHAR, although all of its fields are treated as input. You're the one giving the info this time, main character behavior fr. 💅

🔥 WSDISPLAYIO_SSPLASH (u_int)

Toggle the splash screen. This call is only available with the SPLASHSCREEN kernel option. 🌈

🫶 WSDISPLAYIO_GET_EDID (struct wsdisplayio_edid_info)

Retrieve EDID data from a driver. The structure is:

struct wsdisplayio_edid_info {
        uint32_t buffer_size;
        uint32_t data_size;
        void *edid_data;
};

The caller is responsible for allocating a buffer of at least 128 bytes (the minimum size of an EDID block) and set data_size to its size. If the EDID block is bigger the call will fail with EAGAIN and the driver will set data_size to the required buffer size. Otherwise the EDID block will be written into the buffer pointed at by edid_data and data_size will be set to the number of bytes written. 😌

⭐ WSDISPLAYIO_SETVERSION (int)

Set the wscons_event protocol version. The default is 0 for binary compatibility. The latest version is always available as WSDISPLAYIO_EVENT_VERSION, and is currently 1. All new code should use a call similar to the below to ensure the correct version is returned — no cap, just do it:

int ver = WSDISPLAYIO_EVENT_VERSION;
if (ioctl(fd, WSDISPLAYIO_SETVERSION, &ver) == -1)
    err(EXIT_FAILURE, "cannot set version");

---

📁 FILES 📁

• /dev/ttyE* — Terminal devices (per screen).
• /dev/ttyEcfg — Control device.
• /dev/ttyEstat — Status device.
• /usr/include/dev/wscons/wsconsio.h — the header bestie, go read it. 💖

✨ SEE ALSO ✨

okay bestie so these are the other pages you're gonna wanna pull up while you're living in wsdisplay land 💅

• ioctl(2)
• pcdisplay(4)
• tty(4)
• vga(4)
• wscons(4)
• wsconscfg(8)
• wsconsctl(8)
• wsfontload(8)
• wsdisplay(9)

like, the whole friend group fr fr 🫶

---

💀 BUGS 💀

ngl, there are some things about this bad boy you should just know going in. no cap, they're real:

• The wsdisplay code currently limits the number of screens on one display to 8. that's the ceiling. that's the vibe check. eight is the max and there is no negotiating with it 😭
• The terms “wscons” and “wsdisplay” are not cleanly distinguished in the code and in manual pages. so if you're out here squinting like "wait which one are we even talking about rn" — same bestie, same 🙈 it's lowkey a whole mess.
• “Non-emulating” display devices are not tested. like, at all. so if that's your situation, you're kind of the main character of an untested code path and honestly? godspeed 🧚

lowkey iconic that they just... wrote the bugs down for us though. transparency queen behavior honestly 👑

---

and that's the whole page, bestie!! you made it to the end, I'm so proud of you 🎀 this gem came to you from Debian, dated May 16, 2020, and it's filed under WSDISPLAY(4) — go forth and flex your display driver knowledge, you absolute legend 🌈💜