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