WSDISPLAY(9)

okay bestie, welcome to WSDISPLAY(9) from the Kernel Developer's Manual — this is the wscons display support page, and it is lowkey a whole universe. buckle up 🎢

💖 NAME 💖

Here’s the cast, all repping wscons display support:

• wsdisplay
• wsdisplay_switchtoconsole
• wsdisplay_cnattach
• wsdisplaydevprint
• wsemuldisplaydevprint

📜 SYNOPSIS 📜

#include <dev/wscons/wsconsio.h>
#include <dev/wscons/wsdisplayvar.h>
#include <dev/wscons/wsemulvar.h>
#include <dev/wscons/wsemul_vt100var.h>

void
wsdisplay_switchtoconsole();

void
wsdisplay_cnattach(const struct wsscreen_descr *type, void *cookie,
    int ccol, int crow, long defattr);

void
wsemul_xxx_cnattach(const struct wsscreen_descr *type, void *cookie,
    int ccol, int crow, long defattr);

int
wsdisplaydevprint(void *aux, const char *pnp);

int
wsemuldisplaydevprint(void * aux, const char *pnp);

✨ DESCRIPTION ✨

okay so the wsdisplay module is a component of the wscons(9) framework, and its whole job is providing machine-independent display support. most of the actual support comes from the wsdisplay(4) device driver, which absolutely must be a child of the hardware device driver. no cap. 🫶

the wscons display interface is complicated because — plot twist — there are two different interfaces. 😭

the first interface is for the simple bit-mapped display that does not provide terminal-emulation and console facilities. it’s giving raw display energy.

the second interface provides machine-independent terminal emulation for displays that can support glass-tty terminal emulations. these are character-oriented displays, with row and column numbers starting at zero in the upper left hand corner of the screen. display drivers that cannot emulate terminals use the first interface. in most cases, the low-level hardware driver can use the rasops(9) interface to provide enough support to allow glass-tty terminal emulation. and if the display is not the console, terminal emulation does not make sense, so the display operates using the bit-mapped interface. periodt. 💅

the wscons framework allows concurrent displays to be active. it also provides support for multiple screens for each display, which means a virtual terminal on each screen. multiple terminal emulations and fonts can be active at the same time, allowing different emulations and fonts for each screen. iconique. 🌈

font manipulation facilities for the terminal emulation interface are available through the wsfont(9) module.

---

🧸 DATA TYPES 🧸

display drivers providing support for wscons displays will make use of the following data types, bestie. this is the structural lore. 💀

🌟 struct wsdisplay_accessops 🌟

a structure used to specify the display access functions invoked by userland programs that require direct device access, such as X11. all displays must provide this structure and pass it to the wsdisplay(4) child device. it has the following members:

int     (*ioctl)(void *v, void *vs, u_long cmd,
                void *data, int flag, struct lwp *l);
paddr_t (*mmap)(void *v, void *vs, off_t off, int prot);
int     (*alloc_screen)(void *,
                const struct wsscreen_descr *, void **,
                int *, int *, long *);
void    (*free_screen)(void *, void *);
int     (*show_screen)(void *, void *, int,
                void (*)(), void *);
int     (*load_font)(void *, void *,
                struct wsdisplay_font *);
void    (*pollc)(void *, int);
void    (*scroll)(void *, void *, int);

the ioctl member defines the function to be called to perform display-specific ioctl calls. the mmap member defines the function for mapping a part of the display device into user address space. the alloc_screen member defines a function for allocating a new screen which can be used as a virtual terminal. the free_screen member defines a function for de-allocating a screen. the show_screen member defines a function for mapping a screen onto the physical display — this function is used for switching between screens. the load_font member defines a function for loading a new font into the display. the pollc member defines a function for polling the console. the scroll member defines a function for scrolling the contents of the display. 🔥

there is a void * cookie provided by the display driver associated with these functions, which is passed to them when they are invoked.

the void *vs cookie, passed to ioctl() and mmap(), points to the virtual screen on which these operations were executed.

🌟 struct wsdisplaydev_attach_args 🌟

a structure used to attach the wsdisplay(4) child device for the simple bit-mapped interface. it has the following members:

const struct wsdisplay_accessops *accessops;
void *accesscookie;

if the full terminal-emulation interface is to be used, then struct wsemuldisplaydev_attach_args should be used instead.

🌟 struct wsemuldisplaydev_attach_args 🌟

a structure used to attach the wsdisplay(4) child device for the full terminal emulation interface. it has the following members:

int console;
const struct wsscreen_list *scrdata;
const struct wsdisplay_accessops *accessops;
void *accesscookie;

if the simple bit-mapped interface is to be used, then struct wsdisplaydev_attach_args should be used instead.

🌟 struct wsdisplay_emulops 🌟

a structure used to specify the display emulation functions. all displays intending to provide terminal emulation must provide this structure and pass it to the wsdisplay(4) child device. it has the following members:

void    (*cursor)(void *c, int on, int row, int col);
int     (*mapchar)(void *, int, unsigned int *);
void    (*putchar)(void *c, int row, int col,
                u_int uc, long attr);
void    (*copycols)(void *c, int row, int srccol,
                int dstcol, int ncols);
void    (*erasecols)(void *c, int row, int startcol,
                int ncols, long);
void    (*copyrows)(void *c, int srcrow, int dstrow,
                int nrows);
void    (*eraserows)(void *c, int row, int nrows, long);
int     (*allocattr)(void *c, int fg, int bg, int flags,
                long *);
void    (*replaceattr)(void *c, long oldattr,
                long newattr);

the cursor member defines a function for painting (or unpainting, depending on the on parameter) the cursor at the specified position. the mapchar member defines a function for changing the character mapped at a given position in the character table. the putchar member defines a function for writing a character on the screen, given its position and attribute. the copycols member defines a function for copying a set of columns within the same line. the erasecols member defines a function for clearing a set of columns in a line, filling the space with the given attribute. the copyrows member defines a function for copying a set of complete rows. the eraserows member defines a function for clearing a set of complete rows, filling the space with the given attribute. the allocattr member defines a function for converting an attribute specification given by its foreground color, background color and flags, to the internal representation used by the underlying graphics driver. the replaceattr member defines a function for replacing an attribute by another one across the whole visible part of the screen; this function is optional. 💅

there is a void * cookie provided by the display driver associated with these functions, which is passed to them when they are invoked.

🌟 struct wsscreen_descr 🌟

a structure passed to wscons by the display driver to describe a screen. all displays which can operate as a console must provide this structure and pass it to the wsdisplay(4) child device. it contains the following members:

char *name;
int ncols, nrows;
const struct wsdisplay_emulops *textops;
int fontwidth, fontheight;
int capabilities;

the capabilities member is a set of flags describing the screen capabilities. it can contain the following flags:

• WSSCREEN_WSCOLORS — minimal color capability
• WSSCREEN_REVERSE — can display reversed
• WSSCREEN_HILIT — can highlight (however)
• WSSCREEN_BLINK — can blink
• WSSCREEN_UNDERLINE — can underline

🌟 struct wsscreen_list 🌟

a structure passed to wscons by the display driver to tell about its capabilities. it contains the following members:

int nscreens;
const struct wsscreen_descr **screens;

🌟 struct wscons_syncops 🌟

a structure passed to wscons by the display driver describing the interface for external screen switching/process synchronization. this structure is optional and only required by displays operating with terminal emulation and intending to support multiple screens. it contains the following members:

int     (*detach)(void *, int, void (*)(), void *);
int     (*attach)(void *, int, void (*)(), void *);
int     (*check)(void *);
void    (*destroy)(void *);

✨ FUNCTIONS ✨

okay so here's the function lineup, bestie — every single one, no skips 💅

• wsdisplay_switchtoconsole() — switches the console display over to its first screen. that's it. that's the whole vibe 🖥️
• wsdisplay_cnattach(type, cookie, ccol, crow, defattr) — attaches this display as the console input by telling it the number of columns ccol and number of rows crows. the defattr argument is the default attribute (that's the color, bb 🌈) for the console.
• wsemul_xxx_cnattach(type, cookie, ccol, crow, defattr) — same deal but with terminal emulation, described by the xxx part of the name ✨ you pass the number of columns ccol and number of rows crows, and defattr is the default attribute (color) for the console. and here's the iconic bit: different terminal emulations can be active at the same time on one display — yes, plural, simultaneously, she's multitasking 💅
• wsdisplaydevprint(aux, pnp) — the default wsdisplay printing routine, the one config_found() reaches for (peep autoconf(9)). 🫶
• wsemuldisplaydevprint(aux, pnp) — the default wsemul printing routine, also used by config_found() (also autoconf(9)). matching set, we love a coordinated moment 🎀

---

🌸 AUTOCONFIGURATION 🌸

so if you're a display driver and you wanna use the wsdisplay module, you must be a parent to the wsdisplay(4) device and provide an attachment interface. that's the price of admission, no cap.

to actually attach the wsdisplay(4) device, your display driver has to allocate and populate a wsdisplaydev_attach_args structure — with all the supported operations and callbacks in it — and then call config_found() to make the attach happen (see autoconf(9)). 🛠️

now, display drivers that want to use the wscons terminal emulation module are still parents to the wsdisplay(4) device, but they hand config_found() a wsemuldisplaydev_attach_args structure instead of the standard wsdisplaydev_attach_args. glow-up, but make it struct ✨

tiny but crucial detail: if the display is not the console, the attachment is exactly the same as wsdisplaydev_attach_args. so don't overthink it — non-console displays live that standard life 💀

---

🔥 OPERATION 🔥

if the display belongs to the system console, it has to describe the default screen by invoking wsdisplay_cnattach() at console attach time. required. non-negotiable. main character obligation 👑

all display manipulation is performed by the wscons interface using the callbacks defined in the wsdisplay_accessops structure. the ioctl() function gets called by the wscons interface to do display-specific ioctl operations (see ioctl(2)). the cmd argument to ioctl() says which specific command to run, using the data data. 📟

valid commands are listed in sys/dev/wscons/wsconsio.h and documented in wsdisplay(4) — go read both, iykyk. terminal emulation operations happen through the callbacks defined in the wsdisplay_emulops structure. 🧚

---

🦋 CODE REFERENCES 🦋

• the wscons subsystem lives in the directory sys/dev/wscons 📁
• the wsdisplay module itself is implemented in the file sys/dev/wscons/wsdisplay.c
• terminal emulation support is implemented in the files sys/dev/wscons/wsemul_* (that wildcard is doing so much work, love her)
• ioctl(2) operations are listed in sys/dev/wscons/wsconsio.h

---

💜 SEE ALSO 💜

ioctl(2), wsdisplay(4), autoconf(9), driver(9), intro(9), rasops(9), wsfont(9), wskbd(9), wsmouse(9)

---

and that's the whole page, bestie — you ate that 🍓 this one's from Debian, dated April 15, 2006, filed under WSDISPLAY(9). go forth and attach some displays, periodt 💖