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