1.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved 2.\" Copyright 2018, Joyent, Inc. 3.\" The contents of this file are subject to the terms of the 4.\" Common Development and Distribution License (the "License"). 5.\" You may not use this file except in compliance with the License. 6.\" 7.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 8.\" or http://www.opensolaris.org/os/licensing. 9.\" See the License for the specific language governing permissions 10.\" and limitations under the License. 11.\" 12.\" When distributing Covered Code, include this CDDL HEADER in each 13.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 14.\" If applicable, add the following below this CDDL HEADER, with the 15.\" fields enclosed by brackets "[]" replaced with your own identifying 16.\" information: Portions Copyright [yyyy] [name of copyright owner] 17.Dd August 31, 2018 18.Dt VISUAL_IO 4I 19.Os 20.Sh NAME 21.Nm visual_io 22.Nd illumos VISUAL I/O control operations 23.Sh SYNOPSIS 24.In sys/visual_io.h 25.Sh DESCRIPTION 26The illumos VISUAL environment defines a small set of ioctls for controlling 27graphics and imaging devices. 28.Pp 29The 30.Dv VIS_GETIDENTIFIER 31ioctl is mandatory and must be implemented in 32device drivers for graphics devices using the illumos VISUAL environment. 33The 34.Dv VIS_GETIDENTIFIER 35ioctl is defined to return a device identifier from the device driver. 36This identifier must be a uniquely-defined string. 37.Pp 38There are two additional sets of ioctls. 39One supports mouse tracking via hardware cursor operations. 40Use of this set is optional, however, if a graphics 41device has hardware cursor support and implements these ioctls, the mouse 42tracking performance is improved. 43The remaining set supports the device acting 44as the system console device. 45Use of this set is optional, but if a graphics device is to be used as the 46system console device, it must implement these ioctls. 47.Pp 48The VISUAL environment also defines interfaces for non-ioctl entry points into 49the driver that the illumos operating environment calls when it is running in 50standalone mode (for example, when using a stand-alone debugger, entering 51the PROM monitor, or when the system panicking). 52These are also known as 53.Dq Polled I/O 54entry points, which operate under an an explicit set of restrictions, described below. 55.Sh IOCTLS 56.Bl -tag -width VIS_GETIDENTIFIER -compact 57.It Dv VIS_GETIDENTIFIER 58This 59.Xr ioctl 2 60returns an identifier string to uniquely identify a device 61used in the illumos VISUAL environment. 62This is a mandatory ioctl and must return a unique string. 63We suggest that the name be formed as 64.Ao companysymbol Ac Ns Ao devicetype Ac . 65For example, the 66.Xr cgsix 4D 67driver 68returns 69.Sy SUNWcg6 . 70.Pp 71.Dv VIS_GETIDENTIFIER 72takes a 73.Vt vis_identifier 74structure as its parameter. 75This structure has the form: 76.Bd -literal -offset 2n 77#define VIS_MAXNAMELEN 128 78struct vis_identifier { 79 char name[VIS_MAXNAMELEN]; 80}; 81.Ed 82.Pp 83.It Dv VIS_GETCURSOR 84.It Dv VIS_SETCURSOR 85These ioctls fetch and set various cursor attributes, using the 86.Vt vis_cursor 87structure. 88.Bd -literal -offset 2n 89struct vis_cursorpos { 90 short x; /* cursor x coordinate */ 91 short y; /* cursor y coordinate */ 92}; 93 94struct vis_cursorcmap { 95 int version; /* version */ 96 int reserved; 97 /* red color map elements */ 98 unsigned char *red; 99 /* green color map elements */ 100 unsigned char *green; 101 /* blue color map elements */ 102 unsigned char *blue; 103}; 104 105#define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */ 106 /* set cursor position */ 107#define VIS_CURSOR_SETPOSITION 0x02 108 /* set cursur hot spot */ 109#define VIS_CURSOR_SETHOTSPOT 0x04 110 /* set cursor colormap */ 111#define VIS_CURSOR_SETCOLORMAP 0x08 112 /* set cursor shape */ 113#define VIS_CURSOR_SETSHAPE 0x10 114#define VIS_CURSOR_SETALL \e 115 (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \e 116 VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \e 117 VIS_CURSOR_SETSHAPE) 118 119struct vis_cursor { 120 short set; /* what to set */ 121 short enable; /* cursor on/off */ 122 struct vis_cursorpos pos; /* cursor position */ 123 struct vis_cursorpos hot; /* cursor hot spot */ 124 struct vis_cursorcmap cmap; /* color map info */ 125 /* cursor bitmap size */ 126 struct vis_cursorpos size; 127 char *image; /* cursor image bits */ 128 char *mask; /* cursor mask bits */ 129}; 130.Ed 131.Pp 132The 133.Vt vis_cursorcmap 134structure should contain pointers to two elements, 135specifying the red, green, and blue values for foreground and background. 136.Pp 137.It Dv VIS_SETCURSORPOS 138.It Dv VIS_MOVECURSOR 139These ioctls fetch and move the current cursor position, using the 140.Vt vis_cursorpos 141structure. 142.El 143.Ss "Console Optional Ioctls" 144The following ioctl sets are used by graphics drivers that are part of the 145system console device. 146All of the ioctls must be implemented to be a console device. 147In addition, if the system does not have a prom or the prom goes away 148during boot, the special standalone ioctls (listed below) must also be 149implemented. 150.Pp 151The coordinate system for the console device places 0,0 at the upper left 152corner of the device, with rows increasing toward the bottom of the device and 153columns increasing from left to right. 154.Pp 155.Bl -tag -width VIS_CONSDISPLAY -compact -offset 2n 156.It Dv VIS_PUTCMAP 157.It Dv VIS_GETCMAP 158Set or get color map entries. 159.Pp 160The argument is a pointer to a 161.Vt vis_cmap 162structure, which contains the 163following fields: 164.Bd -literal -offset 2n 165struct vis_cmap { 166 int index; 167 int count; 168 uchar_t *red; 169 uchar_t *green; 170 uchar_t *blue; 171} 172.Ed 173.Pp 174.Fa index 175is the starting index in the color map where you want to start 176setting or getting color map entries. 177.Pp 178.Fa count 179is the number of color map entries to set or get. 180It also is the 181size of the 182.Fa red , 183.Fa green , 184and 185.Fa blue 186color arrays. 187.Pp 188.Fa *red , 189.Fa *green , 190and 191.Fa *blue 192are pointers to unsigned character arrays which contain the color map info to 193set or where the color map info is placed on a get. 194.Pp 195.It Dv VIS_DEVINIT 196Initializes the graphics driver as a console device. 197.Pp 198The argument is a pointer to a 199.Vt vis_devinit 200structure. 201The graphics driver 202is expected to allocate any local state information needed to be a console 203device and fill in this structure. 204.Bd -literal -offset 2n 205struct vis_devinit { 206 int version; 207 screen_size_t width; 208 screen_size_t height; 209 screen_size_t linebytes; 210 unit_t size; 211 int depth; 212 short mode; 213 struct vis_polledio *polledio; 214 vis_modechg_cb_t modechg_cb; 215 struct vis_modechg_arg *modechg_arg; 216}; 217.Ed 218.Pp 219.Fa version 220is the version of this structure and should be set to 221.Dv VIS_CONS_REV . 222.Pp 223.Fa width 224and 225.Fa height 226are the width and height of the device. 227If 228.Fa mode 229(see below) is 230.Dv VIS_TEXT 231then 232.Fa width 233and 234.Fa height 235are the number of characters wide and high of the device. 236If 237.Fa mode 238is 239.Dv VIS_PIXEL 240then 241.Fa width 242and 243.Fa height 244are the number of pixels wide and high of the device. 245.Pp 246.Fa linebytes 247is the number of bytes per line of the device. 248.Pp 249.Fa size 250is the total size of the device in pixels. 251.Pp 252.Fa depth 253is the pixel depth in device bits. 254Currently supported depths are: 255.Sy 1 , 256.Sy 4 , 257.Sy 8 258and 259.Sy 24 . 260.Pp 261.Fa mode 262is the mode of the device. 263Either 264.Dv VIS_PIXEL 265(data to be displayed is in bitmap format) or 266.Dv VIS_TEXT 267(data to be displayed is in ascii format). 268.Pp 269.Fa polledio 270is used to pass the address of the structure containing the 271standalone mode polled I/O entry points to the device driver back to the 272terminal emulator. 273The 274.Vt vis_polledio 275interfaces are described in the 276Console Standalone Entry Points section of this manpage. 277These entry points are where the operating system enters the driver when the 278system is running in standalone mode. 279These functions perform identically to the 280.Dv VIS_CONSDISPLAY , 281.Dv VIS_CONSCURSOR , 282and 283.Dv VIS_CONSCOPY 284ioctls, but are called directly by the illumos 285operating environment and must operate under a very strict set of assumptions. 286.Pp 287.Fa modechg_cb 288is a callback function passed from the terminal emulator to 289the framebuffer driver which the frame-buffer driver must call whenever a video 290mode change event occurs that changes the screen height, width or depth. 291The callback takes two arguments, an opaque handle, 292.Fa modechg_arg , 293and the address of a 294.Vt vis_devinit 295struct containing the new video mode information. 296.Pp 297.Fa modechg_arg 298is an opaque handle passed from the terminal emulator to the 299driver, which the driver must pass back to the terminal emulator as an argument 300to the 301.Fa modechg_cb 302function when the driver notifies the terminal emulator of a video mode change. 303.Pp 304.It Dv VIS_DEVFINI 305Tells the graphics driver that it is no longer the system console device. 306There is no argument to this ioctl. 307The driver is expected to free any locally kept 308state information related to the console. 309.Pp 310.It Dv VIS_CONSCURSOR 311Describes the size and placement of the cursor on the screen. 312The graphics 313driver is expected to display or hide the cursor at the indicated position. 314.Pp 315The argument is a pointer to a 316.Vt vis_conscursor 317structure which contains 318the following fields: 319.Bd -literal -offset 2n 320struct vis_conscursor { 321 screen_pos_t row; 322 screen_pos_t col; 323 screen_size_t width; 324 screen_size_t height 325 color_t fg_color; 326 color_t bg_color; 327 short action; 328}; 329.Ed 330.Pp 331.Fa row 332and 333.Fa col 334are the first row and column (upper left corner of the cursor). 335.Pp 336.Fa width 337and 338.Fa height 339are the width and height of the cursor. 340.Pp 341If 342.Fa mode 343in the 344.Dv VIS_DEVINIT 345ioctl is set to 346.Dv VIS_PIXEL , 347then 348.Fa col , 349.Fa row , 350.Fa width 351and 352.Fa height 353are in pixels. 354If 355.Fa mode 356in the 357.Dv VIS_DEVINIT 358ioctl was set to 359.Dv VIS_TEXT , 360then 361.Fa col , 362.Fa row , 363.Fa width 364and 365.Fa height 366are in characters. 367.Pp 368.Fa fg_color 369and 370.Fa bg_color 371are the foreground and background color map 372indexes to use when the 373.Fa action 374(see below) is set to 375.Dv VIS_DISPLAY_CURSOR . 376.Pp 377.Fa action 378indicates whether to display or hide the cursor. 379It is set to either 380.Dv VIS_HIDE_CURSOR 381or 382.Dv VIS_DISPLAY_CURSOR . 383.Pp 384.It Dv VIS_CONSDISPLAY 385Display data on the graphics device. 386The graphics driver is expected to display the data contained in the 387.Vt vis_display 388structure at the specified position on the console. 389.Pp 390The 391.Vt vis_display 392structure contains the following fields: 393.Bd -literal -offset 2n 394struct vis_display { 395 screen_pos_t row; 396 screen_pos_t col; 397 screen_size_t width; 398 screen_size_t height; 399 uchar_t *data; 400 color_t fg_color; 401 color_t bg_color; 402}; 403.Ed 404.Pp 405.Fa row 406and 407.Fa col 408specify at which starting row and column the date is to be displayed. 409If 410.Fa mode 411in the 412.Dv VIS_DEVINIT 413ioctl was set to 414.Dv VIS_TEXT , 415.Fa row 416and 417.Fa col 418are defined to be a character offset 419from the starting position of the console device. 420If 421.Fa mode 422in the 423.Dv VIS_DEVINIT 424ioctl was set to 425.Dv VIS_PIXEL , 426.Fa row 427and 428.Fa col 429are defined to be a pixel offset from the starting position of the console 430device. 431.Pp 432.Fa width 433and 434.Fa height 435specify the size of the 436.Fa data 437to be displayed. 438If 439.Fa mode 440in the 441.Dv VIS_DEVINIT 442ioctl was set to 443.Dv VIS_TEXT , 444.Fa width 445and 446.Fa height 447define the size of 448.Fa data 449as rectangle that is 450.Fa width 451characters wide and 452.Fa height 453characters high. 454If 455.Fa mode 456in the 457.Dv VIS_DEVINIT 458ioctl was set to 459.Dv VIS_PIXEL , 460.Fa width 461and 462.Fa height 463define the size of 464.Fa data 465as a rectangle that is 466.Fa width 467pixels wide and 468.Fa height 469pixels high. 470.Pp 471.Fa *data 472is a pointer to the data to be displayed on the console device. 473If 474.Fa mode 475in the 476.Dv VIS_DEVINIT 477ioctl was set to 478.Dv VIS_TEXT , 479.Fa data 480is an array of 481.Sy ASCII 482characters to be displayed on the console device. 483The driver must break these characters up appropriately and display it in the 484rectangle defined by 485.Fa row , 486.Fa col , 487.Fa width , 488and 489.Fa height . 490If 491.Fa mode 492in the 493.Dv VIS_DEVINIT 494ioctl was set to 495.Dv VIS_PIXEL , 496.Fa data 497is an array of bitmap data to be displayed on the console device. 498The driver must break this data up appropriately and display it in the retangle 499defined by 500.Fa row , 501.Fa col , 502.Fa width , 503and 504.Fa height . 505.Pp 506The 507.Fa fg_color 508and 509.Fa bg_color 510fields define the foreground and 511background color map indexes to use when displaying the data. 512.Fa fb_color 513is used for 514.Dq on 515pixels and 516.Fa bg_color 517is used for 518.Dq off 519pixels. 520.Pp 521.It Dv VIS_CONSCOPY 522Copy data from one location on the device to another. 523The driver is expected to copy the specified data. 524The source data should not be modified. 525Any modifications to the source data should be as a side effect of the copy 526destination overlapping the copy source. 527.Pp 528The argument is a pointer to a 529.Vt vis_copy 530structure which contains the following fields: 531.Bd -literal -offset 2n 532struct vis_copy { 533 screen_pos_t s_row; 534 screen_pos_t s_col; 535 screen_pos_t e_row; 536 screen_pos_t e_col; 537 screen_pos_t t_row; 538 screen_pos_t t_col; 539 short direction; 540}; 541.Ed 542.Pp 543.Fa s_row , 544.Fa s_col , 545.Fa e_row , 546and 547.Fa e_col 548define the source rectangle of the copy. 549.Fa s_row 550and 551.Fa s_col 552are the upper left corner of the source rectangle. 553.Fa e_row 554and 555.Fa e_col 556are the lower right corner of the source rectangle. 557If 558.Fa mode 559in the 560.Dv VIS_DEVINIT 561.Fn ioctl 562was set to 563.Dv VIS_TEXT , 564.Fa s_row , 565.Fa s_col , 566.Fa e_row , 567and 568.Fa e_col 569are defined to be character offsets from the starting position of the console 570device. 571If 572.Fa mode 573in the 574.Dv VIS_DEVINIT 575.Fn ioctl 576was set to 577.Dv VIS_PIXEL , 578.Fa s_row , 579.Fa s_col , 580.Fa e_row , 581and 582.Fa e_col 583are 584defined to be pixel offsets from the starting position of the console device. 585.Pp 586.Fa t_row 587and 588.Fa t_col 589define the upper left corner of the destination rectangle of the copy. 590The entire rectangle is copied to this location. 591If 592.Fa mode 593in the 594.Dv VIS_DEVINIT 595ioctl was set to 596.Dv VIS_TEXT , 597.Fa t_row , 598and 599.Fa t_col 600are defined to be character offsets from the 601starting position of the console device. 602If 603.Fa mode 604in the 605.Dv VIS_DEVINIT 606ioctl was set to 607.Dv VIS_PIXEL , 608.Fa t_row , 609and 610.Fa t_col 611are defined to be pixel offsets from the starting position of the 612onssole device. 613.Pp 614.Fa direction 615specifies which way to do the copy. 616If direction is 617.Dv VIS_COPY_FORWARD 618the graphics driver should copy data from position 619.Po 620.Fa s_row , 621.Fa s_col 622.Pc 623in the source rectangle to position 624.Po 625.Fa t_row , 626.Fa t_col 627.Pc 628in the destination rectangle. 629If direction is 630.Dv VIS_COPY_BACKWARDS 631the graphics driver should copy data from position 632.Po 633.Fa e_row , 634.Fa e_col 635.Pc 636in the source rectangle to position 637.Po 638.Fa t_row Ns + Ns 639.Po 640.Fa e_row Ns \- Ns 641.Fa s_row 642.Pc , 643.Fa t_col Ns + Ns 644.Po 645.Fa e_col Ns \- Ns 646.Fa s_col 647.Pc 648.Pc 649in the destination rectangle. 650.El 651.Ss "Console Standalone Entry Points (Polled I/O Interfaces)" 652Console standalone entry points are necessary only if the driver is 653implementing console-compatible extensions. 654All console vectored standalone 655entry points must be implemented along with all console-related ioctls if the 656console extension is implemented. 657.Bd -literal -offset 2n 658struct vis_polledio { 659 struct vis_polledio_arg *arg; 660 void (*display)(vis_polledio_arg *, struct vis_consdisplay *); 661 void (*copy)(vis_polledio_arg *, struct vis_conscopy *); 662 void (*cursor)(vis_polledio_arg *, struct vis_conscursor *); 663}; 664.Ed 665.Pp 666The 667.Vt vis_polledio 668structure is passed from the driver to the illumos 669operating environment, conveying the entry point addresses of three functions 670which perform the same operations of their similarly named ioctl counterparts. 671The rendering parameters for each entry point are derived from the same 672structure passed as the respective ioctl. 673See the 674.Sx "Console Optional Ioctls" 675section of this manpage for an explanation of the specific function each of the 676entry points, 677.Fn display , 678.Fn copy , 679and 680.Fn cursor 681are required to implement. 682In 683addition to performing the prescribed function of their ioctl counterparts, the 684standalone vectors operate in a special context and must adhere to a strict set 685of rules. 686The polled I/O vectors are called directly whenever the system is 687quisced (running in a limited context) and must send output to the display. 688Standalone mode describes the state in which the system is running in 689single-threaded mode and only one processor is active. 690illumos operating 691environment services are stopped, along with all other threads on the system, 692prior to entering any of the polled I/O interfaces. 693The polled I/O vectors are 694called when the system is running in a standalone debugger, when executing the 695PROM monitor (OBP) or when panicking. 696.Pp 697The following restrictions must be observed in the polled I/O functions: 698.Bl -enum -offset indent 699.It 700The driver must not allocate memory. 701.It 702The driver must not wait on mutexes. 703.It 704The driver must not wait for interrupts. 705.It 706The driver must not call any DDI or LDI services. 707.It 708The driver must not call any system services. 709.El 710.Pp 711The system is single-threaded when calling these functions, meaning that all 712other threads are effectively halted. 713Single-threading makes mutexes (which 714cannot be held) easier to deal with, so long as the driver does not disturb any 715shared state. 716See 717.%T Writing Device Drivers 718for more information about implementing polled I/O entry points. 719.Sh SEE ALSO 720.Xr ioctl 2 721.Rs 722.%T Writing Device Drivers 723.Re 724.Sh NOTES 725On SPARC systems, compatible drivers supporting the kernel terminal emulator 726should export the 727.Sy tem-support 728DDI property. 729.Sy tem-support 730indicates that the driver supports the kernel terminal emulator. 731By exporting 732.Sy tem-support 733it's possible to avoid premature handling of an incompatible driver. 734.Bl -tag -width tem-support 735.It Sy tem-support 736This DDI property, set to 1, means driver is compatible with the console 737kernel framebuffer interface. 738.El 739