1.\" $NetBSD: vcons.9,v 1.2 2006/02/13 19:57:58 wiz 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 44These functions are used to setup and control the generic virtual 45console framework. 46.Pp 47.\" 48The 49.Fn vcons_init 50function initializes the framework, it needs to be called for each 51driver that's going to use 52.Nm . 53.Pp 54.Fn vcons_init_screen 55adds a virtual screen to a display. 56.Pp 57.Fn vcons_redraw_screen 58redraws a screen. 59A driver should call it when returning to terminal emulation mode, 60for instance when X exits. 61.Pp 62.\" 63.Vt struct vcons_data 64contains all information needed to manage virtual consoles on a display, 65usually it will be a member of the driver's softc. 66.Pp 67.Vt struct vcons_screen 68describes a virtual screen. 69.Sh USAGE 70.\" 71To use vcons with a driver it needs to be initialized by calling 72.Fn vcons_init , 73usually in the driver's attach function. 74.Bl -tag -width cookieXX 75.It Fa vd 76should be a pointer to the driver's 77.Vt struct vcons_data . 78.It Fa cookie 79should be a pointer to the driver's softc. 80.It Fa desc 81should point to a 82.Vt struct wsscreen_descr 83describing the default screen type for this display. 84.It Fa accops 85points to the driver's 86.Vt struct wsdisplay_accessops 87so 88.Fn vcons_init 89can fill it in with its own implementations of 90.Fn alloc_screen , 91.Fn free_screen , 92and 93.Fn show_screen . 94.El 95.Pp 96A driver should however provide its own 97.Fn ioctl 98and 99.Fn mmap 100implementations. 101Both will receive a pointer to the driver's 102.Vt struct vcons_data 103as first parameter. 104.Pp 105After initialization the driver needs to provide a callback function that 106will be called whenever a screen is added. 107Its purpose is to set up the 108.Vt struct rasops_info 109describing the screen. 110After that the drawing methods in 111.Vt struct rasops_info 112will 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 114screen is visible. 115To add a virtual screen the driver one should call 116.Fn vcons_init_screen 117which will call the callback function described above, allocate storage for 118characters and attributes based on whatever the callback set up in 119.Vt struct rasops_info , 120and add the screen to a list kept in 121.Vt struct vcons_data . 122.Pp 123The 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 129and should be stored in the 130.Va init_screen 131member found in 132.Vt struct vcons_data . 133The arguments are: 134.Bl -tag -width cookieXX 135.It Fa cookie 136is the cookie passed to 137.Fn vcons_init 138.It Fa scr 139points to the 140.Vt struct vcons_screen 141being added, its 142.Va scr_ri 143member, a 144.Vt struct rasops_info , 145needs to be filled in. 146.It Fa existing 147is non-zero if the screen already exists and is only added to the list. 148.It Fa defattr 149points to the screen's default text attribute. 150It's filled in by 151.Fn vcons_init_screen 152by calling the 153.Fn alloc_attr 154method found in 155.Vt struct rasops_info . 156.El 157.Pp 158When attaching a 159.Xr wsdisplay 9 160the 161.Va accesscookie 162member of the 163.Vt struct wsemuldisplaydev_attach_args 164passed to 165.Fn config_found 166needs to be a pointer to the driver's 167.Vt struct vcons_data . 168.Pp 169The following members of 170.Vt struct vcons_screen 171may be of interest to drivers: 172.Bl -tag -width scr_cookieXX 173.It Va scr_ri 174contains the 175.Vt struct rasops_info 176describing the screen's geometry, access methods and so on. 177.It Va scr_cookie 178the value passed as cookie to 179.Fn vcons_init . 180Usually the driver's softc. 181.It Va scr_vd 182the driver's 183.Vt struct vcons_data . 184.It Va scr_flags 185can be zero or any combination of: 186.Bl -tag -width XXXXXXXXXXXXXXXXXXXXXX -compact 187.It Dv VCONS_NO_REDRAW 188don't call 189.Fn vcons_redraw_screen 190when this screen becomes visible. 191.It Dv VCONS_SCREEN_IS_STATIC 192don't 193.Xr free 9 194this screen's 195.Vt struct vcons_screen 196in 197.Fn free_screen 198- useful if the screen has been statically allocated. 199.El 200.It Va scr_status 201currently contains only one flag, 202.Dv VCONS_IS_VISIBLE , 203which is set when the screen is visible. 204.El 205.Sh SEE ALSO 206.Xr wscons 4 , 207.Xr wsdisplay 4 208