1.\" $NetBSD: wsdisplay.9,v 1.6 2002/03/10 18:39:42 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 October 7, 2001 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. Most of the 70support 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. The first interface corresponds to the 76simple bit-mapped display which doesn't provide terminal-emulation and 77console facilities. The second interface provides machine-independent 78terminal emulation for displays that can support glass-tty terminal 79emulations. These are character-oriented displays, with row and 80column numbers starting at zero in the upper left hand corner of the 81screen. Display drivers which cannot emulate terminals use the first 82interface. In most cases, the low-level hardware driver can use the 83.Xr rasops 9 84interface to provide enough support to allow glass-tty terminal 85emulation. If the display is not the console, terminal emulation does 86not make sense and the display operates using the bit-mapped 87interface. 88.Pp 89The wscons framework allows concurrent displays to be active. It also 90provides support for multiple screens for each display and therefore 91allows a virtual terminal on each screen. Multiple terminal 92emulations and fonts can be active at the same time allowing different 93emulations and fonts for each screen. 94.Pp 95Font manipulation facilities for the terminal emulation interface are 96available through the 97.Xr wsfont 9 98module. 99.Sh DATA TYPES 100Display drivers providing support for wscons displays will make use 101of the following data types: 102.Bl -tag -width compact 103.It Fa struct wsdisplay_accessops 104A structure used to specify the display access functions invoked by 105userland program which require direct device access, such as X11. All 106displays must provide this structure and pass it to the 107.Xr wsdisplay 4 108child device. It has the following members: 109.Bd -literal 110 int (*ioctl)(void *v, u_long cmd, caddr_t data, 111 int flag, struct proc *p); 112 paddr_t (*mmap)(void *v, off_t off, int prot); 113 int (*alloc_screen)(void *, 114 const struct wsscreen_descr *, void **, 115 int *, int *, long *); 116 void (*free_screen)(void *, void *); 117 int (*show_screen)(void *, void *, int, 118 void (*)(), void *); 119 int (*load_font)(void *, void *, 120 struct wsdisplay_font *); 121 void (*pollc)(void *, int); 122.Ed 123.Pp 124The 125.Fa ioctl 126member defines the function to be called to perform display-specific 127ioctl calls. The 128.Fa mmap 129member defines the function for mapping a part of the display device 130into user address space. The 131.Fa alloc_screen 132member defines a function for allocating a new screen which can be 133used as a virtual terminal. The 134.Fa free_screen 135member defines a function for de-allocating a screen. The 136.Fa show_screen 137member defines a function for mapping a screen onto the physical 138display. This function is used for between switching screens. The 139.Fa load_font 140member defines a function for loading a new font into the display. 141The 142.Fa pollc 143member defines a function for polling the console. 144.Pp 145There is a 146.Fa void * 147cookie provided by the display driver associated with these 148functions, which is passed to them when they are invoked. 149.It Fa struct wsdisplaydev_attach_args 150A structure used to attach the 151.Xr wsdisplay 4 152child device for the simple bit-mapped interface. If the full 153terminal-emulation interface is to be used, then 154.Em struct wsemuldisplaydev_attach_args 155should be used instead. It has the following members: 156.Bd -literal 157 const struct wsdisplay_accessops *accessops; 158 void *accesscookie; 159.Ed 160.It Fa struct wsemuldisplaydev_attach_args 161A structure used to attach the 162.Xr wsdisplay 4 163child device for the full terminal emulation interface. If the simple 164bit-mapped interface is to be used, then 165.Em struct wsdisplaydev_attach_args 166should be used instead. It has the following members: 167.Bd -literal 168 int console; 169 const struct wsscreen_list *scrdata; 170 const struct wsdisplay_accessops *accessops; 171 void *accesscookie; 172.Ed 173.It Fa struct wsdisplay_emulops 174A structure used to specify the display emulation functions. All 175displays intending to provide terminal emulation must must provide 176this structure and pass it to the 177.Xr wsdisplay 4 178child device. It has the following members: 179.Bd -literal 180 void (*cursor)(void *c, int on, int row, int col); 181 int (*mapchar)(void *, int, unsigned int *); 182 void (*putchar)(void *c, int row, int col, 183 u_int uc, long attr); 184 void (*copycols)(void *c, int row, int srccol, 185 int dstcol, int ncols); 186 void (*erasecols)(void *c, int row, int startcol, 187 int ncols, long); 188 void (*copyrows)(void *c, int srcrow, int dstrow, 189 int nrows); 190 void (*eraserows)(void *c, int row, int nrows, long); 191 int (*alloc_attr)(void *c, int fg, int bg, int flags, 192 long *); 193.Ed 194.Pp 195There is a 196.Fa void * 197cookie provided by the display driver associated with these 198functions, which is passed to them when they are invoked. 199.It Fa struct wsscreen_descr 200A structure passed to wscons by the display driver to describe a 201screen. All displays which can operate as a console must provide this 202structure and pass it to the 203.Xr wsdisplay 4 204child device. It contains the following members: 205.Bd -literal 206 char *name; 207 int ncols, nrows; 208 const struct wsdisplay_emulops *textops; 209 int fontwidth, fontheight; 210 int capabilities; 211.Ed 212.Pp 213The 214.Em capabilities 215member is a set of flags describing the screen capabilities. It can 216contain the following flags: 217.Pp 218.Bl -tag -offset indent -width WSSCREEN_UNDERLINE -compact 219.It WSSCREEN_WSCOLORS 220minimal color capability 221.It WSSCREEN_REVERSE 222can display reversed 223.It WSSCREEN_HILIT 224can highlight (however) 225.It WSSCREEN_BLINK 226can blink 227.It WSSCREEN_UNDERLINE 228can underline 229.El 230.It Fa struct wsscreen_list 231A structure passed to wscons by the display driver to tell about its 232capabilities. It contains the following members: 233.Bd -literal 234 int nscreens; 235 const struct wsscreen_descr **screens; 236.Ed 237.It Fa struct wscons_syncops 238A structure passed to wscons by the display driver describing the 239interface for external screen switching/process synchronization. 240This structure is optional and only required by displays operating 241with terminal emulation and intending to support multiple screens. It 242contains the following members: 243.Bd -literal 244 int (*detach)(void *, int, void (*)(), void *); 245 int (*attach)(void *, int, void (*)(), void *); 246 int (*check)(void *); 247 void (*destroy)(void *); 248.Ed 249.El 250.Sh FUNCTIONS 251.Bl -tag -width compact 252.It Fn wsdisplay_switchtoconsole "" 253Switch the console display to its first screen. 254.It Fn wsdisplay_cnattach "type" "cookie" "ccol" "crow" "defattr" 255Attach this display as the console input by specifying the number of 256columns 257.Fa ccol 258and number of rows 259.Fa crows . 260The argument 261.Fa defattr 262specifies the default attribute (color) for the console. 263.It Fn wsemul_xxx_cnattach "type" "cookie" "ccol" "crow" "defattr" 264Attach this display as the console with terminal emulation described 265by the 266.Em xxx 267and specifying the number of columns 268.Fa ccol 269and number of rows 270.Fa crows . 271The argument 272.Fa defattr 273specifies the default attribute (color) for the console. Different 274terminal emulations can be active at the same time on one display. 275.It Fn wsdisplaydevprint "aux" "pnp" 276The default wsdisplay printing routine used by 277.Fn config_found . 278(see 279.Xr autoconf 9 ) . 280.It Fn wsemuldisplaydevprint "aux" "pnp" 281The default wsemul printing routine used by 282.Fn config_found . 283(see 284.Xr autoconf 9 ) . 285.El 286.Sh AUTOCONFIGURATION 287Display drivers which want to utilize the wsdisplay module must be a 288parent to the 289.Xr wsdisplay 4 290device and provide an attachment interface. To attach the 291.Xr wsdisplay 4 292device, the display driver must allocate and populate a 293.Fa wsdisplaydev_attach_args 294structure with the supported operations and callbacks and call 295.Fn config_found 296to perform the attach (see 297.Xr autoconf 9 ) . 298.Pp 299Display drivers which want to utilize the wscons terminal emulation 300module must be a parent to the 301.Xr wsdisplay 4 302device and provide a 303.Fa wsemuldisplaydev_attach_args 304structure instead of the standard 305.Fa wsdisplaydev_attach_args 306to 307.Fn config_found 308to perform the attach. If the display is not the console the 309attachment is the same as wsdisplaydev_attach_args. 310.Sh OPERATION 311If the display belongs to the system console, it must describe the 312default screen by invoking 313.Fn wsdisplay_cnattach 314at console attach time. 315.Pp 316All display manipulation is performed by the wscons interface by using 317the callbacks defined in the 318.Em wsdisplay_accessops 319structure. The 320.Fn ioctl 321function is called by the wscons interface to perform display-specific 322ioctl operations (see 323.Xr ioctl 2 ) . 324The argument 325.Fa cmd to the 326.Fn ioctl 327function specifies the specific command to perform using the data 328data. Valid commands are listed in 329.Pa sys/dev/wscons/wsconsio.h . 330Operations for terminal emulation are performed using the callbacks 331defined in the 332.Em wsdisplay_emulops 333structure. 334.Sh CODE REFERENCES 335This section describes places within the 336.Nx 337source tree where actual code implementing or utilizing the 338machine-independent wscons subsystem can be found. All pathnames are 339relative to 340.Pa /usr/src . 341.Pp 342The wscons subsystem is implemented within the directory 343.Pa sys/dev/wscons . 344The 345.Nm 346module itself is implemented within the file 347.Pa sys/dev/wscons/wsdisplay.c . 348The terminal emulation support 349is implemented within the files 350.Pa sys/dev/wscons/wsemul_* . 351.Xr ioctl 2 352operations are listed in 353.Pa sys/dev/wscons/wsconsio.h . 354.Sh SEE ALSO 355.Xr ioctl 2 , 356.Xr autoconf 9 , 357.Xr driver 9 , 358.Xr intro 9 , 359.Xr rasops 9 , 360.Xr wsfont 9 , 361.Xr wskbd 9 , 362.Xr wsmouse 9 363