208 lines
5.7 KiB
Groff
208 lines
5.7 KiB
Groff
.\" $NetBSD: vcons.9,v 1.2 2006/02/13 19:57:58 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2006 Michael Lorenz
|
|
.\" 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 February 12, 2006
|
|
.Dt VCONS 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm vcons
|
|
.Nd generic virtual console framework
|
|
.Sh SYNOPSIS
|
|
.In wscons/wsdisplay_vconsvar.h
|
|
.Ft int
|
|
.Fn vcons_init "struct vcons_data *vd" "void *cookie" \
|
|
"struct wsscreen_descr *desc" "struct wsdisplay_accessops *accops"
|
|
.Ft int
|
|
.Fn vcons_init_screen "struct vcons_data *vd" "struct vcons_screen *scr" \
|
|
"int exists" "long *defattr"
|
|
.Ft void
|
|
.Fn vcons_redraw_screen "struct vcons_screen *scr"
|
|
.Sh DESCRIPTION
|
|
These functions are used to setup and control the generic virtual
|
|
console framework.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn vcons_init
|
|
function initializes the framework, it needs to be called for each
|
|
driver that's going to use
|
|
.Nm .
|
|
.Pp
|
|
.Fn vcons_init_screen
|
|
adds a virtual screen to a display.
|
|
.Pp
|
|
.Fn vcons_redraw_screen
|
|
redraws a screen.
|
|
A driver should call it when returning to terminal emulation mode,
|
|
for instance when X exits.
|
|
.Pp
|
|
.\"
|
|
.Vt struct vcons_data
|
|
contains all information needed to manage virtual consoles on a display,
|
|
usually it will be a member of the driver's softc.
|
|
.Pp
|
|
.Vt struct vcons_screen
|
|
describes a virtual screen.
|
|
.Sh USAGE
|
|
.\"
|
|
To use vcons with a driver it needs to be initialized by calling
|
|
.Fn vcons_init ,
|
|
usually in the driver's attach function.
|
|
.Bl -tag -width cookieXX
|
|
.It Fa vd
|
|
should be a pointer to the driver's
|
|
.Vt struct vcons_data .
|
|
.It Fa cookie
|
|
should be a pointer to the driver's softc.
|
|
.It Fa desc
|
|
should point to a
|
|
.Vt struct wsscreen_descr
|
|
describing the default screen type for this display.
|
|
.It Fa accops
|
|
points to the driver's
|
|
.Vt struct wsdisplay_accessops
|
|
so
|
|
.Fn vcons_init
|
|
can fill it in with its own implementations of
|
|
.Fn alloc_screen ,
|
|
.Fn free_screen ,
|
|
and
|
|
.Fn show_screen .
|
|
.El
|
|
.Pp
|
|
A driver should however provide its own
|
|
.Fn ioctl
|
|
and
|
|
.Fn mmap
|
|
implementations.
|
|
Both will receive a pointer to the driver's
|
|
.Vt struct vcons_data
|
|
as first parameter.
|
|
.Pp
|
|
After initialization the driver needs to provide a callback function that
|
|
will be called whenever a screen is added.
|
|
Its purpose is to set up the
|
|
.Vt struct rasops_info
|
|
describing the screen.
|
|
After that the drawing methods in
|
|
.Vt struct rasops_info
|
|
will be replaced with wrappers which call the original drawing functions
|
|
(which may or may not be provided by the driver) only when the respective
|
|
screen is visible.
|
|
To add a virtual screen the driver one should call
|
|
.Fn vcons_init_screen
|
|
which will call the callback function described above, allocate storage for
|
|
characters and attributes based on whatever the callback set up in
|
|
.Vt struct rasops_info ,
|
|
and add the screen to a list kept in
|
|
.Vt struct vcons_data .
|
|
.Pp
|
|
The callback needs to have this form:
|
|
.Pp
|
|
.Ft void
|
|
.Fn init_screen "void *cookie" "struct vcons_screen *scr" "int existing" \
|
|
"long *defattr"
|
|
.Pp
|
|
and should be stored in the
|
|
.Va init_screen
|
|
member found in
|
|
.Vt struct vcons_data .
|
|
The arguments are:
|
|
.Bl -tag -width cookieXX
|
|
.It Fa cookie
|
|
is the cookie passed to
|
|
.Fn vcons_init
|
|
.It Fa scr
|
|
points to the
|
|
.Vt struct vcons_screen
|
|
being added, its
|
|
.Va scr_ri
|
|
member, a
|
|
.Vt struct rasops_info ,
|
|
needs to be filled in.
|
|
.It Fa existing
|
|
is non-zero if the screen already exists and is only added to the list.
|
|
.It Fa defattr
|
|
points to the screen's default text attribute.
|
|
It's filled in by
|
|
.Fn vcons_init_screen
|
|
by calling the
|
|
.Fn alloc_attr
|
|
method found in
|
|
.Vt struct rasops_info .
|
|
.El
|
|
.Pp
|
|
When attaching a
|
|
.Xr wsdisplay 9
|
|
the
|
|
.Va accesscookie
|
|
member of the
|
|
.Vt struct wsemuldisplaydev_attach_args
|
|
passed to
|
|
.Fn config_found
|
|
needs to be a pointer to the driver's
|
|
.Vt struct vcons_data .
|
|
.Pp
|
|
The following members of
|
|
.Vt struct vcons_screen
|
|
may be of interest to drivers:
|
|
.Bl -tag -width scr_cookieXX
|
|
.It Va scr_ri
|
|
contains the
|
|
.Vt struct rasops_info
|
|
describing the screen's geometry, access methods and so on.
|
|
.It Va scr_cookie
|
|
the value passed as cookie to
|
|
.Fn vcons_init .
|
|
Usually the driver's softc.
|
|
.It Va scr_vd
|
|
the driver's
|
|
.Vt struct vcons_data .
|
|
.It Va scr_flags
|
|
can be zero or any combination of:
|
|
.Bl -tag -width XXXXXXXXXXXXXXXXXXXXXX -compact
|
|
.It Dv VCONS_NO_REDRAW
|
|
don't call
|
|
.Fn vcons_redraw_screen
|
|
when this screen becomes visible.
|
|
.It Dv VCONS_SCREEN_IS_STATIC
|
|
don't
|
|
.Xr free 9
|
|
this screen's
|
|
.Vt struct vcons_screen
|
|
in
|
|
.Fn free_screen
|
|
- useful if the screen has been statically allocated.
|
|
.El
|
|
.It Va scr_status
|
|
currently contains only one flag,
|
|
.Dv VCONS_IS_VISIBLE ,
|
|
which is set when the screen is visible.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr wscons 4 ,
|
|
.Xr wsdisplay 4
|