418 lines
12 KiB
Groff
418 lines
12 KiB
Groff
.\" $NetBSD: wsdisplay.4,v 1.18 2003/02/19 00:36:24 bjh21 Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999 Matthias Drochner.
|
|
.\" Copyright (c) 2002 Ben Harris.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd June 22, 2002
|
|
.Os
|
|
.Dt WSDISPLAY 4
|
|
.Sh NAME
|
|
.Nm wsdisplay
|
|
.Nd generic display device support in wscons
|
|
.Sh SYNOPSIS
|
|
.Cd wsdisplay* at ega? console ?
|
|
(EGA display on ISA)
|
|
.Cd wsdisplay* at vga? console ?
|
|
(VGA display on ISA or PCI)
|
|
.Cd wsdisplay* at pcdisplay? console ?
|
|
(generic PC (ISA) display)
|
|
.Cd wsdisplay* at tga? console ?
|
|
(DEC TGA display, alpha only)
|
|
.Cd wsdisplay* at pfb? console ?
|
|
(PCI framebuffer, bebox only)
|
|
.Cd wsdisplay0 at ofb? console ?
|
|
(Open Firmware framebuffer, macppc only)
|
|
.Cd wsdisplay* at nextdisplay? console ?
|
|
(NeXT display)
|
|
.Cd wsdisplay0 at smg0
|
|
(VAXstation small monochrome display)
|
|
.Cd wsdisplay* at ... kbdmux N
|
|
.Cd options WSDISPLAY_DEFAULTSCREENS=N
|
|
.Cd options WSDISPLAY_CHARFUNCS
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver is an abstraction layer for display devices within the
|
|
.Xr wscons 4
|
|
framework. It attaches to the hardware specific display device
|
|
driver and and makes it available as text terminal or graphics
|
|
interface.
|
|
.Pp
|
|
A display device can have the ability to display characters on it
|
|
(without help of an X server), either directly by hardware or through
|
|
software putting pixel data into the display memory.
|
|
Such displays are called
|
|
.Dq emulating ,
|
|
the
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
The
|
|
.Em console
|
|
locator in the configuration line refers to the device's use as 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 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
|
|
.Dq emulating
|
|
display devices are usable as console.)
|
|
.Pp
|
|
The
|
|
.Em kbdmux
|
|
locator in the configuration line refers to the
|
|
.Xr wsmux 4
|
|
that will be used to get keyboard events. If this locator is -1 no
|
|
mux will be used.
|
|
.Pp
|
|
The logical unit of an independent contents displayed on a display
|
|
(sometimes referred to as
|
|
.Dq virtual terminal
|
|
) is called a
|
|
.Dq screen
|
|
here. If the underlying device driver supports it, multiple screens can
|
|
be used on one display. (As of this writing, only the
|
|
.Xr vga 4
|
|
and the
|
|
.Tn VAX
|
|
.Dq smg
|
|
display drivers provide this ability.)
|
|
Screens have different minor device numbers and separate tty instances.
|
|
One screen possesses the
|
|
.Dq 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
|
|
.Tn CTRL-ALT-F Ns Ar n )
|
|
or an ioctl command issued by a user program.
|
|
Screens are created and deleted through the
|
|
.Pa /dev/ttyEcfg
|
|
control device (preferably using the
|
|
.Xr wsconscfg 8
|
|
utility). Alternatively, the compile-time option
|
|
.Dv WSDISPLAY_DEFAULTSCREENS Ns = Ns Ar n
|
|
will also create (at autoconfiguration time)
|
|
.Ar n
|
|
initial screens of the display driver's default type with
|
|
the system's default terminal emulator.
|
|
.Sh IOCTLS
|
|
The following
|
|
.Xr ioctl 2
|
|
calls are provided by the
|
|
.Nm
|
|
driver or by devices which use it. Their definitions are found in
|
|
.Aq Pa dev/wscons/wsconsio.h .
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_GTYPE Pq Li int
|
|
Retrieve the type of the display. The list of types is in
|
|
.Aq Pa dev/wscons/wsconsio.h .
|
|
.It Dv WSDISPLAYIO_GINFO Pq Li "struct wsdisplay_fbinfo"
|
|
Retrieve basic information about a framebuffer display.
|
|
The returned structure is as follows:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_fbinfo {
|
|
u_int height;
|
|
u_int width;
|
|
u_int depth;
|
|
u_int cmsize;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va height
|
|
and
|
|
.Va width
|
|
members are counted in pixels. The
|
|
.Va depth
|
|
member indicates the number of bits per pixel, and
|
|
.Va cmsize
|
|
indicates the number of color map entries accessible through
|
|
.Dv WSDISPLAYIO_GETCMAP
|
|
and
|
|
.Dv WSDISPLAYIO_PUTCMAP .
|
|
This call is likely to be unavailable on text-only displays.
|
|
.It Dv WSDISPLAYIO_GETCMAP Pq Li "struct wsdisplay_cmap"
|
|
Retrieve the current color map from the display. This call needs the
|
|
following structure set up beforehand:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_cmap {
|
|
u_int index;
|
|
u_int count;
|
|
u_char *red;
|
|
u_char *green;
|
|
u_char *blue;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va index
|
|
and
|
|
.Va count
|
|
members specify the range of color map entries to retrieve. The
|
|
.Va red ,
|
|
.Va green ,
|
|
and
|
|
.Va blue
|
|
members should each point to an array of
|
|
.Va count
|
|
.Li u_char Ns s .
|
|
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.
|
|
.It Dv WSDISPLAYIO_PUTCMAP Pq Li "struct wsdisplay_cmap"
|
|
Change the display's color map. The argument structure is the same as for
|
|
.Dv WSDISPLAYIO_GETCMAP ,
|
|
but
|
|
.Va red ,
|
|
.Va green ,
|
|
and
|
|
.Va 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.
|
|
.It Dv WSDISPLAYIO_GVIDEO Pq Li int
|
|
Get the current state of the display's video output. Possible values are:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_VIDEO_OFF
|
|
The display is blanked.
|
|
.It Dv WSDISPLAYIO_VIDEO_ON
|
|
The display is enabled.
|
|
.El
|
|
.It Dv WSDISPLAYIO_SVIDEO Pq Li int
|
|
Set the state of the display's video output. See
|
|
.Dv WSDISPLAYIO_GVIDEO
|
|
above for possible values.
|
|
.It Dv WSDISPLAYIO_GCURPOS Pq Li "struct wsdisplay_curpos"
|
|
Retrieve the current position of the hardware cursor. The returned structure
|
|
is as follows:
|
|
.Bd -literal -offset indent
|
|
struct wsdisplay_curpos {
|
|
u_int x, y;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va x
|
|
and
|
|
.Va 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.
|
|
.It Dv WSDISPLAYOP_SCURPOS Pq Li "struct wsdisplay_curpos"
|
|
Set the current cursor position. The argument structure, and its semantics,
|
|
are the same as for
|
|
.Dv WSDISPLAYIO_GCURPOS .
|
|
This call is not avilable on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYIO_GCURMAX Pq Li "struct wsdisplay_curpos"
|
|
Retrieve the maximum size of cursor supported by the display. The
|
|
.Va x
|
|
and
|
|
.Va 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.
|
|
.It Dv WSDISPLAYIO_GCURSOR Pq Li "struct wsdisplay_cursor"
|
|
Retrieve some or all of the hardware cursor's attributes. The argument
|
|
structure is as follows:
|
|
.Bd -literal -offset indent
|
|
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;
|
|
};
|
|
.Pp
|
|
.Ed
|
|
The
|
|
.Va which
|
|
member indicates which of the values the application requires to be returned.
|
|
It should contain the logical OR of the following flags:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCUR
|
|
Get
|
|
.Va enable ,
|
|
which indicates whether the cursor is currently displayed (non-zero) or
|
|
not (zero).
|
|
.It Dv WSDISPLAYIO_CURSOR_DOPOS
|
|
Get
|
|
.Va pos ,
|
|
which indicates the current position of the cursor on the display, as
|
|
would be returned by
|
|
.Dv WSDISPLAYIO_GCURPOS .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOHOT
|
|
Get
|
|
.Va hot ,
|
|
which indicates the location of the
|
|
.Dq 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.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCMAP
|
|
Get
|
|
.Va cmap ,
|
|
which indicates the current cursor color map.
|
|
Unlike in a call to
|
|
.Dv WSDISPLAYIO_GETCMAP ,
|
|
.Va cmap
|
|
here need not have its
|
|
.Va index
|
|
and
|
|
.Va count
|
|
members initialized. They will be set to 0 and 2 respectively by the call.
|
|
This means that
|
|
.Va cmap . Ns Va red ,
|
|
.Va cmap . Ns Va green ,
|
|
and
|
|
.Va cmap . Ns Va blue
|
|
must each point to at least enough space to hold two
|
|
.Li u_char Ns s .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOSHAPE
|
|
Get
|
|
.Va size , image ,
|
|
and
|
|
.Va 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.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOALL
|
|
Get all of the above.
|
|
.El
|
|
.Pp
|
|
The device may elect to return information that was not requested by the user,
|
|
so those elements of
|
|
.Li "struct wsdisplay_cursor"
|
|
which are pointers should be initialized to
|
|
.Dv NULL
|
|
if not otherwise used.
|
|
This call is not available on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYIO_SCURSOR Pq Li "struct wsdisplay_cursor"
|
|
Set some or all of the hardware cursor's attributes. The argument structure
|
|
is the same as for
|
|
.Dv WSDISPLAYIO_GCURSOR .
|
|
The
|
|
.Va which
|
|
member specifies which attributes of the cursor are to be changed.
|
|
It should contain the logical OR of the following flags:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCUR
|
|
If
|
|
.Va enable
|
|
is zero, hide the cursor. Otherwise, display it.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOPOS
|
|
Set the cursor's position on the display to
|
|
.Va pos ,
|
|
the same as
|
|
.Dv WSDISPLAYIO_SCURPOS .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOHOT
|
|
Set the
|
|
.Dq hot spot
|
|
of the cursor, as defined above, to
|
|
.Va hot .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOCMAP
|
|
Set some or all of the cursor color map based on
|
|
.Va cmap .
|
|
The
|
|
.Va index
|
|
and
|
|
.Va count
|
|
elements of
|
|
.Va cmap
|
|
indicate which color map entries to set, and the entries themselves come from
|
|
.Va cmap . Ns Va red ,
|
|
.Va cmap . Ns Va green ,
|
|
and
|
|
.Va cmap . Ns Va blue .
|
|
.It Dv WSDISPLAYIO_CURSOR_DOSHAPE
|
|
Set the cursor shape from
|
|
.Va size , image ,
|
|
and
|
|
.Va mask .
|
|
See above for their meanings.
|
|
.It Dv WSDISPLAYIO_CURSOR_DOALL
|
|
Do all of the above.
|
|
.El
|
|
.Pp
|
|
This call is not available on displays without a hardware cursor.
|
|
.It Dv WSDISPLAYIO_GMODE Pq Li u_int
|
|
Get the current mode of the display. Possible results include:
|
|
.Bl -tag -width Dv
|
|
.It Dv WSDISPLAYIO_MODE_EMUL
|
|
The display is in emulating (text) mode.
|
|
.It Dv WSDISPLAYIO_MODE_MAPPED
|
|
The display is in mapped (graphics) mode.
|
|
.El
|
|
.Pp
|
|
.It Dv WSDISPLAYIO_SMODE Pq Li u_int
|
|
Set the current mode of the display. For possible arguments, see
|
|
.Dv WSDISPLAYIO_GMODE .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -item
|
|
.It
|
|
.Pa /dev/ttyE*
|
|
Terminal devices (per screen).
|
|
.It
|
|
.Pa /dev/ttyEcfg
|
|
Control device.
|
|
.It
|
|
.Pa /dev/ttyEstat
|
|
Status device.
|
|
.It
|
|
.Pa /usr/include/dev/wscons/wsconsio.h
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ioctl 2 ,
|
|
.Xr ega 4 ,
|
|
.Xr pcdisplay 4 ,
|
|
.Xr tty 4 ,
|
|
.Xr vga 4 ,
|
|
.Xr wscons 4 ,
|
|
.Xr wsconscfg 8 ,
|
|
.Xr wsconsctl 8 ,
|
|
.Xr wsfontload 8 ,
|
|
.Xr wsdisplay 9
|
|
.Sh BUGS
|
|
The
|
|
.Nm
|
|
code currently limits the number of screens on one display to 8.
|
|
.Pp
|
|
The terms
|
|
.Dq wscons
|
|
and
|
|
.Dq wsdisplay
|
|
are not cleanly distinguished in the code and in manual pages.
|
|
.Pp
|
|
.Dq non-emulating
|
|
display devices are not tested.
|