Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


WSDISPLAY(4)                 Device Drivers Manual                WSDISPLAY(4)

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 an abstraction layer for display devices within
     the wscons(4) framework.  It attaches to the hardware specific display
     device driver and makes it available as a text terminal or graphics
     interface.

     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", 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 an 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 (typically
     <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.

   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.

     WSDISPLAYIO_GCURMAX (struct wsdisplay_curpos)
                   Retrieve the maximum size of cursor supported by the
                   display.  The x and y members of the returned structure
                   indicate the maximum number of pixel rows and columns,
                   respectively, in a hardware cursor on this display.  This
                   call is not available on displays without a hardware
                   cursor.

     WSDISPLAYIO_GCURSOR (struct wsdisplay_cursor)
                   Retrieve some or all of the hardware cursor's attributes.
                   The argument structure is as follows:

                         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 indicates which of the values the
                   application requires to be returned.  It should contain the
                   logical OR of the following 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.

                   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.  This call is not available
                   on displays without a hardware cursor.

     WSDISPLAYIO_SCURSOR (struct wsdisplay_cursor)
                   Set 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.  It should contain the logical OR of the
                   following flags:

                   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.

                   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.

     WSDISPLAYIO_LINEBYTES (u_int)
                   Get the number of bytes per row, which may be the same as
                   the number of pixels.

     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 as follows:

                         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.

     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.

     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.

     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.

                         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.

                         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

SEE ALSO
     ioctl(2), pcdisplay(4), tty(4), vga(4), wscons(4), wsconscfg(8),
     wsconsctl(8), wsfontload(8), wsdisplay(9)

BUGS
     The wsdisplay code currently limits the number of screens on one display
     to 8.

     The terms "wscons" and "wsdisplay" are not cleanly distinguished in the
     code and in manual pages.

     "non-emulating" display devices are not tested.

NetBSD 10.99                     May 16, 2020                     NetBSD 10.99