share/man/man9/vcons.9

   1 .\" $NetBSD: vcons.9,v 1.1 2006/02/12 23:06:43 macallan Exp $
   2 .\"
   3 .\" Copyright (c) 2006 Michael Lorenz
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd February 12, 2006
  28 .Dt VCONS 9
  29 .Os
  30 .Sh NAME
  31 .Nm vcons
  32 .Nd generic virtual console framework
  33 .Sh SYNOPSIS
  34 .In wscons/wsdisplay_vconsvar.h
  35 .Ft int
  36 .Fn vcons_init "struct vcons_data *vd" "void *cookie" \
  37 "struct wsscreen_descr *desc" "struct wsdisplay_accessops *accops"
  38 .Ft int
  39 .Fn vcons_init_screen "struct vcons_data *vd" "struct vcons_screen *scr" \
  40 "int exists" "long *defattr"
  41 .Ft void
  42 .Fn vcons_redraw_screen "struct vcons_screen *scr"
  43 .Sh DESCRIPTION
  44 These functions are used to setup and control the generic virtual
  45 console framework.
  46 .Pp
  47 .\"
  48 The
  49 .Fn vcons_init
  50 function initializes the framework, it needs to be called for each
  51 driver that's going to use
  52 .Nm .
  53 .Pp
  54 .Fn vcons_init_screen
  55 adds a virtual screen to a display.
  56 .Pp
  57 .Fn vcons_redraw_screen
  58 redraws a screen.
  59 A driver should call it when returning to terminal emulation mode,
  60 for instance when X exits.
  61 .Pp
  62 .\"
  63 .Vt struct vcons_data
  64 contains all information needed to manage virtual consoles on a display,
  65 usually it will be a member of the driver's softc.
  66 .Pp
  67 .Vt struct vcons_screen
  68 describes a virtual screen.
  69 .Sh USAGE
  70 .\"
  71 To use vcons with a driver it needs to be initialized by calling
  72 .Fn vcons_init ,
  73 usually in the driver's attach function.
  74 .Bl -tag -width cookieXX
  75 .It Fa vd
  76 should be a pointer to the driver's
  77 .Vt struct vcons_data .
  78 .It Fa cookie
  79 should be a pointer to the driver's softc.
  80 .It Fa desc
  81 should point to a
  82 .Vt struct wsscreen_descr
  83 describing the default screen type for this display.
  84 .It Fa accops
  85 points to the driver's
  86 .Vt struct wsdisplay_accessops
  87 so
  88 .Fn vcons_init
  89 can fill it in with its own implementations of
  90 .Fn alloc_screen ,
  91 .Fn free_screen ,
  92 and
  93 .Fn show_screen .
  94 .El
  95 .Pp
  96 A driver should however provide its own
  97 .Fn ioctl
  98 and
  99 .Fn mmap
 100 implementations.
 101 Both will receive a pointer to the driver's
 102 .Vt struct vcons_data
 103 as first parameter.
 104 .Pp
 105 After initialization the driver needs to provide a callback function that
 106 will be called whenever a screen is added.
 107 Its purpose is to set up the
 108 .Vt struct rasops_info
 109 describing the screen.
 110 After that the drawing methods in
 111 .Vt struct rasops_info
 112 will be replaced with wrappers which call the original drawing functions
 113 (which may or may not be provided by the driver) only when the respective
 114 screen is visible.
 115 To add a virtual screen the driver one should call
 116 .Fn vcons_init_screen
 117 which will call the callback function described above, allocate storage for
 118 characters and attributes based on whatever the callback set up in
 119 .Vt struct rasops_info ,
 120 and add the screen to a list kept in
 121 .Vt struct vcons_data .
 122 .Pp
 123 The callback needs to have this form:
 124 .Pp
 125 .Ft void
 126 .Fn init_screen "void *cookie" "struct vcons_screen *scr" "int existing" \
 127 "long *defattr"
 128 .Pp
 129 and should be stored in the
 130 .Va init_screen
 131 member found in
 132 .Vt struct vcons_data .
 133 The arguments are:
 134 .Bl -tag -width cookieXX
 135 .It Fa cookie
 136 is the cookie passed to
 137 .Fn vcons_init
 138 .It Fa scr
 139 points to the
 140 .Vt struct vcons_screen
 141 being added, its
 142 .Va scr_ri
 143 member, a
 144 .Vt struct rasops_info ,
 145 needs to be filled in.
 146 .It Fa existing
 147 is non-zero if the screen already exists and is only added to the list.
 148 .It Fa defattr
 149 points to the screen's default text attribute.
 150 It's filled in by
 151 .Fn vcons_init_screen
 152 by calling the
 153 .Fn alloc_attr
 154 method found in
 155 .Vt struct rasops_info .
 156 .El
 157 .Pp
 158 When attaching a
 159 .Xr wsdisplay 9
 160 the
 161 .Va accesscookie
 162 member of the
 163 .Vt struct wsemuldisplaydev_attach_args
 164 passed to
 165 .Fn config_found
 166 needs to be a pointer to the driver's
 167 .Vt struct vcons_data .
 168 .Pp
 169 The following members of
 170 .Vt struct vcons_screen
 171 may be of interest to drivers:
 172 .Bl -tag -width scr_cookieXX
 173 .It Va scr_ri
 174 contains the
 175 .Vt struct rasops_info
 176 describing the screen's geometry, access methods and so on.
 177 .It Va scr_cookie
 178 the value passed as cookie to
 179 .Fn vcons_init .
 180 Usually the driver's softc.
 181 .It Va scr_vd
 182 the driver's
 183 .Vt struct vcons_data .
 184 .It Va scr_flags
 185 can be zero or any combination of:
 186 .Bl -tag -width XXXXXXXXXXXXXXXXXXXXXX -compact
 187 .It Dv VCONS_NO_REDRAW
 188 don't call
 189 .Fn vcons_redraw_screen
 190 when this screen becomes visible.
 191 .It Dv VCONS_SCREEN_IS_STATIC
 192 don't
 193 .Xr free 9
 194 this screen's
 195 .Vt struct vcons_screen
 196 in
 197 .Fn free_screen
 198 - useful if the screen has been statically allocated.
 199 .El
 200 .It Va scr_status
 201 currently contains only one flag,
 202 .Dv VCONS_IS_VISIBLE ,
 203 which is set when the screen is visible.
 204 .El
 205 .Sh SEE ALSO
 206 .Xr wscons 4 ,
 207 .Xr wsdisplay 4