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