1.\" $NetBSD: wsdisplay.9,v 1.19 2006/04/15 17:54:34 jmmv 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.\" 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 April 15, 2006 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.In dev/wscons/wsconsio.h 49.In dev/wscons/wsdisplayvar.h 50.In dev/wscons/wsemulvar.h 51.In dev/wscons/wsemul_vt100var.h 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, void *vs, u_long cmd, 113 caddr_t data, int flag, struct lwp *l); 114 paddr_t (*mmap)(void *v, void *vs, 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 void (*scroll)(void *, void *, int); 125.Ed 126.Pp 127The 128.Fa ioctl 129member defines the function to be called to perform display-specific 130ioctl calls. 131The 132.Fa mmap 133member defines the function for mapping a part of the display device 134into user address space. 135The 136.Fa alloc_screen 137member defines a function for allocating a new screen which can be 138used as a virtual terminal. 139The 140.Fa free_screen 141member defines a function for de-allocating a screen. 142The 143.Fa show_screen 144member defines a function for mapping a screen onto the physical 145display. 146This function is used for between switching screens. 147The 148.Fa load_font 149member defines a function for loading a new font into the display. 150The 151.Fa pollc 152member defines a function for polling the console. 153The 154.Fa scroll 155member defines a function for scrolling the contents of the display. 156.Pp 157There is a 158.Fa void * 159cookie provided by the display driver associated with these 160functions, which is passed to them when they are invoked. 161.Pp 162The 163.Fa void *vs 164cookie, passed to 165.Fn ioctl 166and 167.Fn mmap , 168points to the virtual screen on which these operations were executed. 169.It Fa struct wsdisplaydev_attach_args 170A structure used to attach the 171.Xr wsdisplay 4 172child device for the simple bit-mapped interface. 173If the full terminal-emulation interface is to be used, then 174.Em struct wsemuldisplaydev_attach_args 175should be used instead. 176It has the following members: 177.Bd -literal 178 const struct wsdisplay_accessops *accessops; 179 void *accesscookie; 180.Ed 181.It Fa struct wsemuldisplaydev_attach_args 182A structure used to attach the 183.Xr wsdisplay 4 184child device for the full terminal emulation interface. 185If the simple bit-mapped interface is to be used, then 186.Em struct wsdisplaydev_attach_args 187should be used instead. 188It has the following members: 189.Bd -literal 190 int console; 191 const struct wsscreen_list *scrdata; 192 const struct wsdisplay_accessops *accessops; 193 void *accesscookie; 194.Ed 195.It Fa struct wsdisplay_emulops 196A structure used to specify the display emulation functions. 197All displays intending to provide terminal emulation must provide 198this structure and pass it to the 199.Xr wsdisplay 4 200child device. 201It has the following members: 202.Bd -literal 203 void (*cursor)(void *c, int on, int row, int col); 204 int (*mapchar)(void *, int, unsigned int *); 205 void (*putchar)(void *c, int row, int col, 206 u_int uc, long attr); 207 void (*copycols)(void *c, int row, int srccol, 208 int dstcol, int ncols); 209 void (*erasecols)(void *c, int row, int startcol, 210 int ncols, long); 211 void (*copyrows)(void *c, int srcrow, int dstrow, 212 int nrows); 213 void (*eraserows)(void *c, int row, int nrows, long); 214 int (*allocattr)(void *c, int fg, int bg, int flags, 215 long *); 216 void (*replaceattr)(void *c, long oldattr, 217 long newattr); 218.Ed 219.Pp 220The 221.Fa cursor 222member defines a function for painting (or unpainting, depending on the 223.Va on 224parameter) the cursor at the specified position. 225The 226.Fa mapchar 227member defines a function for changing the character mapped at a given 228position in the character table. 229The 230.Fa putchar 231member defines a function for writing a character on the screen, given 232its position and attribute. 233The 234.Fa copycols 235member defines a function for copying a set of columns within the same 236line. 237The 238.Fa erasecols 239member defines a function for clearing a set of columns in a line, 240filling the space with the given attribute. 241The 242.Fa copyrows 243member defines a function for copying a set of complete rows. 244The 245.Fa eraserows 246member defines a function for clearing a set of complete rows, 247filling the space with the given attribute. 248The 249.Fa allocattr 250member defines a function for converting an attribute specification 251given by its foreground color, background color and flags, to the 252internal representation used by the underlying graphics driver. 253The 254.Fa replaceattr 255member defines a function for replacing an attribute by another one 256across the whole visible part of the screen; this function is optional. 257.Pp 258There is a 259.Fa void * 260cookie provided by the display driver associated with these 261functions, which is passed to them when they are invoked. 262.It Fa struct wsscreen_descr 263A structure passed to wscons by the display driver to describe a 264screen. 265All displays which can operate as a console must provide this structure 266and pass it to the 267.Xr wsdisplay 4 268child device. 269It contains the following members: 270.Bd -literal 271 char *name; 272 int ncols, nrows; 273 const struct wsdisplay_emulops *textops; 274 int fontwidth, fontheight; 275 int capabilities; 276.Ed 277.Pp 278The 279.Em capabilities 280member is a set of flags describing the screen capabilities. 281It can contain the following flags: 282.Pp 283.Bl -tag -offset indent -width WSSCREEN_UNDERLINE -compact 284.It WSSCREEN_WSCOLORS 285minimal color capability 286.It WSSCREEN_REVERSE 287can display reversed 288.It WSSCREEN_HILIT 289can highlight (however) 290.It WSSCREEN_BLINK 291can blink 292.It WSSCREEN_UNDERLINE 293can underline 294.El 295.It Fa struct wsscreen_list 296A structure passed to wscons by the display driver to tell about its 297capabilities. 298It contains the following members: 299.Bd -literal 300 int nscreens; 301 const struct wsscreen_descr **screens; 302.Ed 303.It Fa struct wscons_syncops 304A structure passed to wscons by the display driver describing the 305interface for external screen switching/process synchronization. 306This structure is optional and only required by displays operating 307with terminal emulation and intending to support multiple screens. 308It contains the following members: 309.Bd -literal 310 int (*detach)(void *, int, void (*)(), void *); 311 int (*attach)(void *, int, void (*)(), void *); 312 int (*check)(void *); 313 void (*destroy)(void *); 314.Ed 315.El 316.Sh FUNCTIONS 317.Bl -tag -width compact 318.It Fn wsdisplay_switchtoconsole "" 319Switch the console display to its first screen. 320.It Fn wsdisplay_cnattach "type" "cookie" "ccol" "crow" "defattr" 321Attach this display as the console input by specifying the number of 322columns 323.Fa ccol 324and number of rows 325.Fa crows . 326The argument 327.Fa defattr 328specifies the default attribute (color) for the console. 329.It Fn wsemul_xxx_cnattach "type" "cookie" "ccol" "crow" "defattr" 330Attach this display as the console with terminal emulation described 331by the 332.Em xxx 333and specifying the number of columns 334.Fa ccol 335and number of rows 336.Fa crows . 337The argument 338.Fa defattr 339specifies the default attribute (color) for the console. 340Different terminal emulations can be active at the same time on one display. 341.It Fn wsdisplaydevprint "aux" "pnp" 342The default wsdisplay printing routine used by 343.Fn config_found . 344(see 345.Xr autoconf 9 ) . 346.It Fn wsemuldisplaydevprint "aux" "pnp" 347The default wsemul printing routine used by 348.Fn config_found . 349(see 350.Xr autoconf 9 ) . 351.El 352.Sh AUTOCONFIGURATION 353Display drivers which want to use the wsdisplay module must be a 354parent to the 355.Xr wsdisplay 4 356device and provide an attachment interface. 357To attach the 358.Xr wsdisplay 4 359device, the display driver must allocate and populate a 360.Fa wsdisplaydev_attach_args 361structure with the supported operations and callbacks and call 362.Fn config_found 363to perform the attach (see 364.Xr autoconf 9 ) . 365.Pp 366Display drivers which want to use the wscons terminal emulation 367module must be a parent to the 368.Xr wsdisplay 4 369device and provide a 370.Fa wsemuldisplaydev_attach_args 371structure instead of the standard 372.Fa wsdisplaydev_attach_args 373to 374.Fn config_found 375to perform the attach. 376If the display is not the console the attachment is the same 377as wsdisplaydev_attach_args. 378.Sh OPERATION 379If the display belongs to the system console, it must describe the 380default screen by invoking 381.Fn wsdisplay_cnattach 382at console attach time. 383.Pp 384All display manipulation is performed by the wscons interface by using 385the callbacks defined in the 386.Em wsdisplay_accessops 387structure. 388The 389.Fn ioctl 390function is called by the wscons interface to perform display-specific 391ioctl operations (see 392.Xr ioctl 2 ) . 393The argument 394.Fa cmd 395to the 396.Fn ioctl 397function specifies the specific command to perform using the data 398.Fa data . 399Valid commands are listed in 400.Pa sys/dev/wscons/wsconsio.h 401and documented in 402.Xr wsdisplay 4 . 403Operations for terminal emulation are performed using the callbacks 404defined in the 405.Em wsdisplay_emulops 406structure. 407.Sh CODE REFERENCES 408This section describes places within the 409.Nx 410source tree where actual code implementing or using the 411machine-independent wscons subsystem can be found. 412All pathnames are relative to 413.Pa /usr/src . 414.Pp 415The wscons subsystem is implemented within the directory 416.Pa sys/dev/wscons . 417The 418.Nm 419module itself is implemented within the file 420.Pa sys/dev/wscons/wsdisplay.c . 421The terminal emulation support 422is implemented within the files 423.Pa sys/dev/wscons/wsemul_* . 424.Xr ioctl 2 425operations are listed in 426.Pa sys/dev/wscons/wsconsio.h . 427.Sh SEE ALSO 428.Xr ioctl 2 , 429.Xr wsdisplay 4 , 430.Xr autoconf 9 , 431.Xr driver 9 , 432.Xr intro 9 , 433.Xr rasops 9 , 434.Xr wsfont 9 , 435.Xr wskbd 9 , 436.Xr wsmouse 9 437