1.\" $NetBSD: wsdisplay.9,v 1.11 2002/10/14 13:43:37 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd June 22, 2002 38.Dt WSDISPLAY 9 39.Os 40.Sh NAME 41.Nm wsdisplay , 42.Nm wsdisplay_switchtoconsole , 43.Nm wsdisplay_cnattach , 44.Nm wsdisplaydevprint , 45.Nm wsemuldisplaydevprint 46.Nd wscons display support 47.Sh SYNOPSIS 48.Fd #include \*[Lt]dev/wscons/wsconsio.h\*[Gt] 49.Fd #include \*[Lt]dev/wscons/wsdisplayvar.h\*[Gt] 50.Fd #include \*[Lt]dev/wscons/wsemulvar.h\*[Gt] 51.Fd #include \*[Lt]dev/wscons/wsemul_vt100var.h\*[Gt] 52.Ft void 53.Fn wsdisplay_switchtoconsole "" 54.Ft void 55.Fn wsdisplay_cnattach "const struct wsscreen_descr *type" "void *cookie" \ 56"int ccol" "int crow" "long defattr" 57.Ft void 58.Fn wsemul_xxx_cnattach "const struct wsscreen_descr *type" "void *cookie" \ 59"int ccol" "int crow" "long defattr" 60.Ft int 61.Fn wsdisplaydevprint "void *aux" "const char *pnp" 62.Ft int 63.Fn wsemuldisplaydevprint "void * aux" "const char *pnp" 64.Sh DESCRIPTION 65The 66.Nm 67module is a component of the 68.Xr wscons 9 69framework to provide machine-independent display support. 70Most of the support is provided by the 71.Xr wsdisplay 4 72device driver, which must be a child of the hardware device driver. 73.Pp 74The wscons display interface is complicated by the fact that there are 75two different interfaces. 76The first interface corresponds to the simple bit-mapped display which 77doesn't provide terminal-emulation and console facilities. 78The second interface provides machine-independent terminal emulation 79for displays that can support glass-tty terminal emulations. 80These are character-oriented displays, with row and column numbers 81starting at zero in the upper left hand corner of the screen. 82Display drivers which cannot emulate terminals use the first interface. 83In most cases, the low-level hardware driver can use the 84.Xr rasops 9 85interface to provide enough support to allow glass-tty terminal 86emulation. 87If the display is not the console, terminal emulation does not make 88sense and the display operates using the bit-mapped interface. 89.Pp 90The wscons framework allows concurrent displays to be active. 91It also provides support for multiple screens for each display and 92therefore allows a virtual terminal on each screen. 93Multiple terminal emulations and fonts can be active at the same 94time allowing different emulations and fonts for each screen. 95.Pp 96Font manipulation facilities for the terminal emulation interface are 97available through the 98.Xr wsfont 9 99module. 100.Sh DATA TYPES 101Display drivers providing support for wscons displays will make use 102of the following data types: 103.Bl -tag -width compact 104.It Fa struct wsdisplay_accessops 105A structure used to specify the display access functions invoked by 106userland program which require direct device access, such as X11. 107All displays must provide this structure and pass it to the 108.Xr wsdisplay 4 109child device. 110It has the following members: 111.Bd -literal 112 int (*ioctl)(void *v, u_long cmd, caddr_t data, 113 int flag, struct proc *p); 114 paddr_t (*mmap)(void *v, off_t off, int prot); 115 int (*alloc_screen)(void *, 116 const struct wsscreen_descr *, void **, 117 int *, int *, long *); 118 void (*free_screen)(void *, void *); 119 int (*show_screen)(void *, void *, int, 120 void (*)(), void *); 121 int (*load_font)(void *, void *, 122 struct wsdisplay_font *); 123 void (*pollc)(void *, int); 124.Ed 125.Pp 126The 127.Fa ioctl 128member defines the function to be called to perform display-specific 129ioctl calls. 130The 131.Fa mmap 132member defines the function for mapping a part of the display device 133into user address space. 134The 135.Fa alloc_screen 136member defines a function for allocating a new screen which can be 137used as a virtual terminal. 138The 139.Fa free_screen 140member defines a function for de-allocating a screen. 141The 142.Fa show_screen 143member defines a function for mapping a screen onto the physical 144display. 145This function is used for between switching screens. 146The 147.Fa load_font 148member defines a function for loading a new font into the display. 149The 150.Fa pollc 151member defines a function for polling the console. 152.Pp 153There is a 154.Fa void * 155cookie provided by the display driver associated with these 156functions, which is passed to them when they are invoked. 157.It Fa struct wsdisplaydev_attach_args 158A structure used to attach the 159.Xr wsdisplay 4 160child device for the simple bit-mapped interface. 161If the full terminal-emulation interface is to be used, then 162.Em struct wsemuldisplaydev_attach_args 163should be used instead. 164It has the following members: 165.Bd -literal 166 const struct wsdisplay_accessops *accessops; 167 void *accesscookie; 168.Ed 169.It Fa struct wsemuldisplaydev_attach_args 170A structure used to attach the 171.Xr wsdisplay 4 172child device for the full terminal emulation interface. 173If the simple bit-mapped interface is to be used, then 174.Em struct wsdisplaydev_attach_args 175should be used instead. 176It has the following members: 177.Bd -literal 178 int console; 179 const struct wsscreen_list *scrdata; 180 const struct wsdisplay_accessops *accessops; 181 void *accesscookie; 182.Ed 183.It Fa struct wsdisplay_emulops 184A structure used to specify the display emulation functions. 185All displays intending to provide terminal emulation must provide 186this structure and pass it to the 187.Xr wsdisplay 4 188child device. 189It has the following members: 190.Bd -literal 191 void (*cursor)(void *c, int on, int row, int col); 192 int (*mapchar)(void *, int, unsigned int *); 193 void (*putchar)(void *c, int row, int col, 194 u_int uc, long attr); 195 void (*copycols)(void *c, int row, int srccol, 196 int dstcol, int ncols); 197 void (*erasecols)(void *c, int row, int startcol, 198 int ncols, long); 199 void (*copyrows)(void *c, int srcrow, int dstrow, 200 int nrows); 201 void (*eraserows)(void *c, int row, int nrows, long); 202 int (*allocattr)(void *c, int fg, int bg, int flags, 203 long *); 204.Ed 205.Pp 206There is a 207.Fa void * 208cookie provided by the display driver associated with these 209functions, which is passed to them when they are invoked. 210.It Fa struct wsscreen_descr 211A structure passed to wscons by the display driver to describe a 212screen. 213All displays which can operate as a console must provide this structure 214and pass it to the 215.Xr wsdisplay 4 216child device. 217It contains the following members: 218.Bd -literal 219 char *name; 220 int ncols, nrows; 221 const struct wsdisplay_emulops *textops; 222 int fontwidth, fontheight; 223 int capabilities; 224.Ed 225.Pp 226The 227.Em capabilities 228member is a set of flags describing the screen capabilities. 229It can contain the following flags: 230.Pp 231.Bl -tag -offset indent -width WSSCREEN_UNDERLINE -compact 232.It WSSCREEN_WSCOLORS 233minimal color capability 234.It WSSCREEN_REVERSE 235can display reversed 236.It WSSCREEN_HILIT 237can highlight (however) 238.It WSSCREEN_BLINK 239can blink 240.It WSSCREEN_UNDERLINE 241can underline 242.El 243.It Fa struct wsscreen_list 244A structure passed to wscons by the display driver to tell about its 245capabilities. 246It contains the following members: 247.Bd -literal 248 int nscreens; 249 const struct wsscreen_descr **screens; 250.Ed 251.It Fa struct wscons_syncops 252A structure passed to wscons by the display driver describing the 253interface for external screen switching/process synchronization. 254This structure is optional and only required by displays operating 255with terminal emulation and intending to support multiple screens. 256It contains the following members: 257.Bd -literal 258 int (*detach)(void *, int, void (*)(), void *); 259 int (*attach)(void *, int, void (*)(), void *); 260 int (*check)(void *); 261 void (*destroy)(void *); 262.Ed 263.El 264.Sh FUNCTIONS 265.Bl -tag -width compact 266.It Fn wsdisplay_switchtoconsole "" 267Switch the console display to its first screen. 268.It Fn wsdisplay_cnattach "type" "cookie" "ccol" "crow" "defattr" 269Attach this display as the console input by specifying the number of 270columns 271.Fa ccol 272and number of rows 273.Fa crows . 274The argument 275.Fa defattr 276specifies the default attribute (color) for the console. 277.It Fn wsemul_xxx_cnattach "type" "cookie" "ccol" "crow" "defattr" 278Attach this display as the console with terminal emulation described 279by the 280.Em xxx 281and specifying the number of columns 282.Fa ccol 283and number of rows 284.Fa crows . 285The argument 286.Fa defattr 287specifies the default attribute (color) for the console. 288Different terminal emulations can be active at the same time on one display. 289.It Fn wsdisplaydevprint "aux" "pnp" 290The default wsdisplay printing routine used by 291.Fn config_found . 292(see 293.Xr autoconf 9 ) . 294.It Fn wsemuldisplaydevprint "aux" "pnp" 295The default wsemul printing routine used by 296.Fn config_found . 297(see 298.Xr autoconf 9 ) . 299.El 300.Sh AUTOCONFIGURATION 301Display drivers which want to utilize the wsdisplay module must be a 302parent to the 303.Xr wsdisplay 4 304device and provide an attachment interface. 305To attach the 306.Xr wsdisplay 4 307device, the display driver must allocate and populate a 308.Fa wsdisplaydev_attach_args 309structure with the supported operations and callbacks and call 310.Fn config_found 311to perform the attach (see 312.Xr autoconf 9 ) . 313.Pp 314Display drivers which want to utilize the wscons terminal emulation 315module must be a parent to the 316.Xr wsdisplay 4 317device and provide a 318.Fa wsemuldisplaydev_attach_args 319structure instead of the standard 320.Fa wsdisplaydev_attach_args 321to 322.Fn config_found 323to perform the attach. 324If the display is not the console the attachment is the same 325as wsdisplaydev_attach_args. 326.Sh OPERATION 327If the display belongs to the system console, it must describe the 328default screen by invoking 329.Fn wsdisplay_cnattach 330at console attach time. 331.Pp 332All display manipulation is performed by the wscons interface by using 333the callbacks defined in the 334.Em wsdisplay_accessops 335structure. 336The 337.Fn ioctl 338function is called by the wscons interface to perform display-specific 339ioctl operations (see 340.Xr ioctl 2 ) . 341The argument 342.Fa cmd 343to the 344.Fn ioctl 345function specifies the specific command to perform using the data 346.Fa data . 347Valid commands are listed in 348.Pa sys/dev/wscons/wsconsio.h 349and documented in 350.Xr wsdisplay 4 . 351Operations for terminal emulation are performed using the callbacks 352defined in the 353.Em wsdisplay_emulops 354structure. 355.Sh CODE REFERENCES 356This section describes places within the 357.Nx 358source tree where actual code implementing or utilizing the 359machine-independent wscons subsystem can be found. 360All pathnames are relative to 361.Pa /usr/src . 362.Pp 363The wscons subsystem is implemented within the directory 364.Pa sys/dev/wscons . 365The 366.Nm 367module itself is implemented within the file 368.Pa sys/dev/wscons/wsdisplay.c . 369The terminal emulation support 370is implemented within the files 371.Pa sys/dev/wscons/wsemul_* . 372.Xr ioctl 2 373operations are listed in 374.Pa sys/dev/wscons/wsconsio.h . 375.Sh SEE ALSO 376.Xr ioctl 2 , 377.Xr wsdisplay 4 , 378.Xr autoconf 9 , 379.Xr driver 9 , 380.Xr intro 9 , 381.Xr rasops 9 , 382.Xr wsfont 9 , 383.Xr wskbd 9 , 384.Xr wsmouse 9 385