April 15, 2006 WSDISPLAY 9

### NAME

wsdisplay, wsdisplay_switchtoconsole, wsdisplay_cnattach, wsdisplaydevprint, wsemuldisplaydevprint - wscons display support

### SYNOPSIS

```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

The wsdisplay module is a component of the wscons(9) framework to provide machine-independent display support. Most of the support is provided by the wsdisplay(4) device driver, which must be a child of the hardware device driver.

The wscons display interface is complicated by the fact that there are two different interfaces. The first interface corresponds to the simple bit-mapped display which doesn't provide terminal-emulation and console facilities. 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 which 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. If the display is not the console, terminal emulation does not make sense and the display operates using the bit-mapped interface.

The wscons framework allows concurrent displays to be active. It also provides support for multiple screens for each display and therefore allows 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.

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:

```struct` `wsdisplay_accessops`
  A structure used to specify the display access functions invoked by userland program which 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 between switching 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. If the full terminal-emulation interface is to be used, then struct wsemuldisplaydev_attach_args should be used instead. It has the following members: `

              const struct wsdisplay_accessops *accessops;
              void *accesscookie;

  `

```struct` `wsemuldisplaydev_attach_args`
  A structure used to attach the wsdisplay(4) child device for the full terminal emulation interface. If the simple bit-mapped interface is to be used, then struct wsdisplaydev_attach_args should be used instead. It has the following members: `

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

  `

```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

wsdisplay_switchtoconsole(````)
  Switch the console display to its first screen.

wsdisplay_cnattach(```type``, cookie``, ccol``, crow``, defattr`)
  Attach this display as the console input by specifying the number of columns ```ccol` and number of rows ```crows`. The argument ```defattr` specifies the default attribute (color) for the console.

wsemul_xxx_cnattach(```type``, cookie``, ccol``, crow``, defattr`)
  Attach this display as the console with terminal emulation described by the xxx and specifying the number of columns ```ccol` and number of rows ```crows`. The argument ```defattr` specifies the default attribute (color) for the console. Different terminal emulations can be active at the same time on one display.

wsdisplaydevprint(```aux``, pnp`)
  The default wsdisplay printing routine used by config_found(``). (see autoconf(9)).

wsemuldisplaydevprint(```aux``, pnp`)
  The default wsemul printing routine used by config_found(``). (see autoconf(9)).

### AUTOCONFIGURATION

Display drivers which want to use the wsdisplay module must be a parent to the wsdisplay(4) device and provide an attachment interface. To attach the wsdisplay(4) device, the display driver must allocate and populate a ```wsdisplaydev_attach_args` structure with the supported operations and callbacks and call config_found(``) to perform the attach (see autoconf(9)).

Display drivers which want to use the wscons terminal emulation module must be a parent to the wsdisplay(4) device and provide a ```wsemuldisplaydev_attach_args` structure instead of the standard ```wsdisplaydev_attach_args` to config_found(``) to perform the attach. If the display is not the console the attachment is the same as wsdisplaydev_attach_args.

### OPERATION

If the display belongs to the system console, it must describe the default screen by invoking wsdisplay_cnattach(``) at console attach time.

All display manipulation is performed by the wscons interface by using the callbacks defined in the wsdisplay_accessops structure. The ioctl(``) function is called by the wscons interface to perform display-specific ioctl operations (see ioctl(2)). The argument ```cmd` to the ioctl(``) function specifies the specific command to perform using the data ```data`. Valid commands are listed in ```sys/dev/wscons/wsconsio.h` and documented in wsdisplay(4). Operations for terminal emulation are performed using the callbacks defined in the wsdisplay_emulops structure.

### CODE REFERENCES

This section describes places within the NetBSD source tree where actual code implementing or using the machine-independent wscons subsystem can be found. All pathnames are relative to ```/usr/src`.

The wscons subsystem is implemented within the directory ```sys/dev/wscons`. The wsdisplay module itself is implemented within the file ```sys/dev/wscons/wsdisplay.c`. The terminal emulation support is implemented within the files ```sys/dev/wscons/wsemul_*`. 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)