Print this page
10562 Convert visual_io(7I) to mandoc
   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH VISUAL_IO 7I "Oct 14, 2005"
   7 .SH NAME
   8 visual_io \- Solaris VISUAL I/O control operations
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB#include <sys/visual_io.h>\fR
  13 .fi
  14 
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The Solaris VISUAL environment defines a small set of ioctls for controlling









  19 graphics and imaging devices.
  20 .sp
  21 .LP
  22 The \fBVIS_GETIDENTIFIER\fR ioctl is mandatory and must be implemented in
  23 device drivers for graphics devices using the Solaris VISUAL environment. The
  24 \fBVIS_GETIDENTIFIER\fR ioctl is defined to return a device identifier from the
  25 device driver. This identifier must be a uniquely-defined string.
  26 .sp
  27 .LP
  28 There are two additional sets of ioctls. One supports mouse tracking via
  29 hardware cursor operations. Use of this set is optional, however, if a graphics



  30 device has hardware cursor support and implements these ioctls, the mouse
  31 tracking performance is improved. The remaining set supports the device acting
  32 as the system console device. Use of this set is optional, but if a graphics
  33 device is to be used as the system console device, it must implement these
  34 ioctls.
  35 .sp
  36 .LP
  37 The VISUAL environment also defines interfaces for non-ioctl entry points into
  38 the driver that the Solaris operating environment calls when it is running in
  39 standalone  mode (for example, when using a stand-alone  debugger, entering
  40 the  PROM  monitor, or when the system panicking). These are also known as
  41 "Polled I/O" entry points, which operate under an an explicit set of
  42 restrictions, described below.
  43 .SH IOCTLS
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBVIS_GETIDENTIFIER\fR\fR
  48 .ad
  49 .RS 21n
  50 This \fBioctl()\fR returns an identifier string to uniquely identify a device
  51 used in the Solaris VISUAL environment.  This is a mandatory ioctl and must
  52 return a unique string. We suggest that the name be formed as
  53 \fI<companysymbol><devicetype>\fR\&. For example, the \fBcgsix\fR driver
  54 returns \fBSUNWcg6\fR.
  55 .sp
  56 \fBVIS_GETIDENTIFIER\fR takes a \fBvis_identifier\fR structure as its
  57 parameter.  This structure has the form:
  58 .sp
  59 .in +2
  60 .nf





  61 #define VIS_MAXNAMELEN 128
  62 struct vis_identifier {
  63        char name[VIS_MAXNAMELEN];
  64 };
  65 .fi
  66 .in -2
  67 
  68 .RE
  69 
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBVIS_GETCURSOR\fR\fR
  74 .ad
  75 .br
  76 .na
  77 \fB\fBVIS_SETCURSOR\fR\fR
  78 .ad
  79 .RS 21n
  80 These ioctls fetch and set various cursor attributes, using the
  81 \fBvis_cursor\fR structure.
  82 .sp
  83 .in +2
  84 .nf
  85 struct vis_cursorpos {
  86            short        x;           /* cursor x coordinate */
  87            short        y;           /* cursor y coordinate */
  88 };
  89 
  90 struct vis_cursorcmap {
  91           int   version;                 /* version */
  92           int   reserved;
  93           unsigned char *red;  /* red color map elements */
  94           unsigned char *green;/* green color map elements */
  95           unsigned char *blue; /* blue color map elements */



  96 };
  97 
  98 #define VIS_CURSOR_SETCURSOR   0x01  /* set cursor */
  99 #define VIS_CURSOR_SETPOSITION 0x02  /* set cursor position */
 100 #define VIS_CURSOR_SETHOTSPOT  0x04  /* set cursor hot spot */
 101 #define VIS_CURSOR_SETCOLORMAP 0x08  /* set cursor colormap */
 102 #define VIS_CURSOR_SETSHAPE 0x10     /* set cursor shape */




 103 #define VIS_CURSOR_SETALL       \e
 104     (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \e
 105     VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \e
 106     VIS_CURSOR_SETSHAPE)
 107 
 108 struct vis_cursor {
 109     short set;                    /* what to set */
 110     short enable;                 /* cursor on/off */
 111     struct vis_cursorpos pos;     /* cursor position */
 112     struct  vis_cursorpos hot;    /* cursor hot spot */
 113     struct vis_cursorcmap cmap;   /* color map info */
 114     struct vis_cursorpos size;    /* cursor bitmap size */

 115     char  *image;                 /* cursor image bits */
 116     char  *mask;                  /* cursor mask bits */
 117 };
 118 .fi
 119 .in -2
 120 
 121 .RE
 122 
 123 .sp
 124 .LP
 125 The \fBvis_cursorcmap\fR structure should contain pointers to two elements,
 126 specifying the red, green, and blue values for foreground and background.
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBVIS_SETCURSORPOS\fR\fR
 131 .ad
 132 .br
 133 .na
 134 \fB\fBVIS_MOVECURSOR\fR\fR
 135 .ad
 136 .RS 20n
 137 These ioctls fetch and move the current cursor position, using the
 138 \fBvis_cursorpos\fR structure.
 139 .RE
 140 
 141 .SS "Console Optional Ioctls"
 142 .sp
 143 .LP
 144 The following ioctl sets are used by graphics drivers that are part of the
 145 system console device. All of the ioctls must be implemented to be a  console
 146 device.  In addition, if the system does not have a prom or the prom goes away

 147 during boot, the special standalone ioctls (listed below) must also be
 148 implemented.
 149 .sp
 150 .LP
 151 The coordinate system for the console device places 0,0 at the upper left
 152 corner of the device, with rows increasing toward the bottom of the device and
 153 columns increasing from left to right.
 154 .sp
 155 .ne 2
 156 .na
 157 \fBVIS_PUTCMAP\fR
 158 .ad
 159 .br
 160 .na
 161 \fB\fBVIS_GETCMAP\fR\fR
 162 .ad
 163 .RS 15n
 164 Set or get color map entries.
 165 .RE
 166 
 167 .sp
 168 .LP
 169 The argument is a pointer to a \fBvis_cmap\fR structure, which contains the
 170 following fields:
 171 .sp
 172 .in +2
 173 .nf
 174 struct vis_cmap {
 175     int index;
 176     int count;
 177     uchar_t     *red;
 178     uchar_t     *green;
 179     uchar_t     *blue;
 180 }
 181 .fi
 182 .in -2
 183 
 184 .sp
 185 .LP
 186 \fBindex\fR is the starting index in the color map where you want to start
 187 setting or getting color map entries.
 188 .sp
 189 .LP
 190 \fBcount\fR is the number of color map entries to set or get.  It also is the
 191 size of the \fBred\fR, \fBgreen\fR, and \fBblue\fR color arrays.
 192 .sp
 193 .LP
 194 \fB*red\fR, \fB*green\fR, and \fB*blue\fR are pointers to unsigned character
 195 arrays which contain the color map info to set or where the color map info is
 196 placed on a get.
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBVIS_DEVINIT\fR\fR
 201 .ad
 202 .RS 15n




 203 Initializes the graphics driver as a console device.
 204 .RE
 205 
 206 .sp
 207 .LP
 208 The argument is a pointer to a \fBvis_devinit\fR structure. The graphics driver
 209 is expected to allocate any local state information needed to be a console
 210 device and fill in this structure.
 211 .sp
 212 .in +2
 213 .nf
 214 struct vis_devinit {
 215     int  version;
 216     screen_size_t  width;
 217     screen_size_t  height;
 218     screen_size_t  linebytes;
 219     unit_t      size;
 220     int    depth;
 221     short  mode;
 222     struct vis_polledio    *polledio;
 223     vis_modechg_cb_t       modechg_cb;
 224     struct vis_modechg_arg *modechg_arg;
 225 };
 226 .fi
 227 .in -2
 228 
 229 .sp
 230 .LP
 231 \fBversion\fR is the version of this structure and should be set to
 232 \fBVIS_CONS_REV\fR.
 233 .sp
 234 .LP
 235 \fBwidth\fR and \fBheight\fR are the width and height of the device.  If
 236 \fBmode\fR (see below) is \fBVIS_TEXT\fR then \fBwidth\fR and \fBheight\fR are
 237 the number of characters wide and high of the device. If \fBmode\fR is
 238 \fBVIS_PIXEL\fR then \fBwidth\fR and \fBheight\fR are the number of pixels wide
 239 and high of the device.
 240 .sp
 241 .LP
 242 \fBlinebytes\fR is the number of bytes per line of the device.
 243 .sp
 244 .LP
 245 \fBsize\fR is the total size of the device in pixels.
 246 .sp
 247 .LP
 248 \fBdepth\fR is the pixel depth in device bits. Currently supported depths are:
 249 \fB1\fR, \fB4\fR, \fB8\fR and \fB24\fR.
 250 .sp
 251 .LP
 252 \fBmode\fR is the mode of the device.  Either \fBVIS_PIXEL\fR (data to be
 253 displayed is in bitmap format) or \fBVIS_TEXT\fR (data to be displayed is in
 254 ascii format).
 255 .sp
 256 .LP
 257 \fBpolledio\fR is used to pass the address of the structure containing the






















 258 standalone mode polled I/O entry points to the device driver back to the
 259 terminal emulator. The \fBvis_polledio\fR interfaces are described in the
 260 Console Standalone Entry Points section of this manpage. These entry points are
 261 where the operating system enters the driver when the system is running in
 262 standalone mode. These functions perform identically to the VIS_CONSDISPLAY,
 263 VIS_CONSCURSOR and VIS_CONSCOPY ioctls, but are called directly by the Solaris








 264 operating environment and must operate under a very strict set of assumptions.
 265 .sp
 266 .LP
 267 \fBmodechg_cb\fR is a callback function passed from the terminal emulator to
 268 the framebuffer driver which the frame-buffer driver must call whenever a video
 269 mode change event occurs that changes the screen height, width or depth. The
 270 callback takes two arguments, an opaque handle, \fBmodechg_arg\fR, and the
 271 address of a vis_devinit struct containing the new video mode information.
 272 .sp
 273 .LP
 274 \fBmodechg_arg\fR is an opaque handle passed from the terminal emulator to the



 275 driver, which the driver must pass back to the terminal emulator as an argument
 276 to the \fBmodechg_cb\fR function when the driver notifies the terminal emulator
 277 of a video mode change.
 278 .sp
 279 .ne 2
 280 .na
 281 \fB\fBVIS_DEVFINI\fR\fR
 282 .ad
 283 .RS 18n
 284 Tells the graphics driver that it is no longer the system console device. There
 285 is no argument to this ioctl. The driver is expected to free any locally kept
 286 state information related to the console.
 287 .RE
 288 
 289 .sp
 290 .ne 2
 291 .na
 292 \fB\fBVIS_CONSCURSOR\fR\fR
 293 .ad
 294 .RS 18n
 295 Describes the size and placement of the cursor on the screen. The graphics
 296 driver is expected to display or hide the cursor at the indicated position.
 297 .RE
 298 
 299 .sp
 300 .LP
 301 The argument is a pointer to a \fBvis_conscursor\fR structure which contains
 302 the following fields:
 303 .sp
 304 .in +2
 305 .nf
 306 struct vis_conscursor {
 307     screen_pos_t   row;
 308     screen_pos_t   col;
 309     screen_size_t  width;
 310     screen_size_t  height
 311     color_t        fg_color;
 312     color_t        bg_color;
 313     short          action;
 314 };
 315 .fi
 316 .in -2
 317 
 318 .sp
 319 .LP
 320 \fBrow\fR and \fBcol\fR are the first row and column (upper left corner of the
 321 cursor).
 322 .sp
 323 .LP
 324 \fBwidth\fR and \fBheight\fR are the width and height of the cursor.
 325 .sp
 326 .LP
 327 If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl is set to \fBVIS_PIXEL\fR, then
 328 \fBcol\fR, \fBrow\fR, \fBwidth\fR and \fBheight\fR are in pixels. If \fBmode\fR
 329 in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, then \fBcol\fR,
 330 \fBrow\fR, \fBwidth\fR and \fBheight\fR are in characters.
 331 .sp
 332 .LP
 333 \fBfg_color\fR and \fBbg_color\fR are the foreground and background color map
 334 indexes to use when  the \fBaction\fR (see below) is set to
 335 \fBVIS_DISPLAY_CURSOR\fR.
 336 .sp
 337 .LP
 338 \fBaction\fR indicates whether to display or hide the cursor.  It is set to
 339 either \fBVIS_HIDE_CURSOR\fR or \fBVIS_DISPLAY_CURSOR\fR.
 340 .sp
 341 .ne 2
 342 .na
 343 \fB\fBVIS_CONSDISPLAY\fR\fR
 344 .ad
 345 .RS 19n
 346 Display data on the graphics device. The graphics driver is expected to display
 347 the data contained in the  \fBvis_display\fR structure at the specified
 348 position on the console.
 349 .RE
 350 
 351 .sp
 352 .LP
 353 The \fBvis_display\fR structure contains the following fields:
 354 .sp
 355 .in +2
 356 .nf























 357 struct vis_display {
 358     screen_pos_t   row;
 359     screen_pos_t   col;
 360     screen_size_t  width;
 361     screen_size_t  height;
 362     uchar_t        *data;
 363     color_t        fg_color;
 364     color_t        bg_color;
 365 };
 366 .fi
 367 .in -2
 368 
 369 .sp
 370 .LP
 371 \fBrow\fR and \fBcol\fR specify at which starting row and column the date is to
 372 be displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
 373 \fBVIS_TEXT\fR, \fBrow\fR and  \fBcol\fR are defined to be a character offset
 374 from the starting  position of the console device. If \fBmode\fR in the
 375 \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBrow\fR and  \fBcol\fR
















 376 are defined to be a pixel offset from the starting position of  the console
 377 device.
 378 .sp
 379 .LP
 380 \fBwidth\fR and \fBheight\fR specify the size of the  \fBdata\fR to be
 381 displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
 382 \fBVIS_TEXT\fR, \fBwidth\fR and \fBheight\fR define the size of  \fBdata\fR as
 383 a rectangle that is \fBwidth\fR characters wide and \fBheight\fR characters
 384 high. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR,
 385 \fBwidth\fR and \fBheight\fR define the size of  \fBdata\fR as a rectangle that
 386 is \fBwidth\fR pixels wide and \fBheight\fR pixels high.
 387 .sp
 388 .LP
 389 \fB*data\fR is a pointer to the data to be displayed on the console device. If
 390 \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, \fBdata\fR
 391 is an array of \fBASCII\fR characters to be displayed on the console device.






































 392 The driver must break these characters up appropriately and display it in  the
 393 retangle defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR. If
 394 \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR,
 395 \fBdata\fR is an array of bitmap data to be displayed on the console device.











 396 The driver must break this data up appropriately and display it in the retangle
 397 defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR.
 398 .sp
 399 .LP
 400 The \fBfg_color\fR and \fBbg_color\fR fields define the foreground and
 401 background color map indexes to use when displaying the data. \fBfb_color\fR is
 402 used for "on" pixels and \fBbg_color\fR is used for "off" pixels.
 403 .sp
 404 .ne 2
 405 .na
 406 \fB\fBVIS_CONSCOPY\fR\fR
 407 .ad
 408 .RS 16n
 409 Copy data from one location on the device to another.  The driver is expected
 410 to copy the specified data.  The source data should not be modified. Any
 411 modifications to the source data should be as a side effect of the copy












 412 destination overlapping the copy source.
 413 .RE
 414 
 415 .sp
 416 .LP
 417 The argument is a pointer to a  \fBvis_copy\fR structure which contains the
 418 following fields:
 419 .sp
 420 .in +2
 421 .nf
 422 struct vis_copy {
 423     screen_pos_t  s_row;
 424     screen_pos_t  s_col;
 425     screen_pos_t  e_row;
 426     screen_pos_t  e_col;
 427     screen_pos_t  t_row;
 428     screen_pos_t  t_col;
 429     short         direction;
 430 };
 431 .fi
 432 .in -2
 433 
 434 .sp
 435 .LP
 436 \fBs_row\fR, \fBs_col\fR, \fBe_row\fR, and \fBe_col\fR define the source
 437 rectangle of the copy. \fBs_row\fR and \fBs_col\fR are the upper left corner of
 438 the source rectangle. \fBe_row\fR and \fBe_col\fR are the lower right corner of
 439 the source rectangle. If \fBmode\fR in the \fBVIS_DEVINIT\fR \fBioctl()\fR was
 440 set to \fBVIS_TEXT\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR


















 441 are defined to be character offsets from the starting  position of the console
 442 device. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
 443 \fBVIS_PIXEL\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR are












 444 defined to be pixel offsets from the starting  position of the console device.
 445 .sp
 446 .LP
 447 \fBt_row\fR and \fBt_col\fR define the upper left corner of the destination
 448 rectangle of the copy. The entire rectangle is copied to this location. If
 449 \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR,
 450 \fBt_row\fR, and \fBt_col\fR are defined to be character offsets from the
 451 starting  position of the console device.   If \fBmode\fR in the
 452 \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBt_row\fR, and
 453 \fBt_col\fR are defined to be pixel offsets from the starting  position of the
 454 console device.
 455 .sp
 456 .LP
 457 \fBdirection\fR specifies which way to do the copy.  If direction is
 458 \fBVIS_COPY_FORWARD\fR the graphics driver should copy data from position
 459 (\fBs_row\fR, \fBs_col\fR) in the source rectangle to position (\fBt_row\fR,
 460 \fBt_col\fR) in the destination rectangle. If direction is
 461 \fBVIS_COPY_BACKWARDS\fR the graphics driver should copy data from position
 462 (\fBe_row\fR, \fBe_col\fR) in the source rectangle to position
 463 \fB(t_row+(e_row-s_row)\fR, \fBt_col+(e_col-s_col))\fR in the destination
 464 rectangle.
 465 .SS "Console Standalone Entry Points  (Polled I/O Interfaces)"
 466 .sp
 467 .LP












































 468 Console standalone entry points are necessary only if the driver is
 469 implementing console-compatible extensions. All console vectored standalone

 470 entry points must be implemented along with all console-related ioctls if the
 471 console extension is implemented.
 472 .sp
 473 .in +2
 474 .nf
 475 struct vis_polledio {
 476     struct vis_polledio_arg *arg;
 477     void    (*display)(vis_polledio_arg *, struct vis_consdisplay *);
 478     void    (*copy)(vis_polledio_arg *, struct vis_conscopy *);
 479     void    (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
 480 };
 481 .fi
 482 .in -2
 483 
 484 .sp
 485 .LP
 486 The \fBvis_polledio\fR structure is passed from the driver to the Solaris
 487 operating environment, conveying the entry point addresses of three functions
 488 which perform the same operations of their similarly named ioctl counterparts.
 489 The rendering parameters for each entry point are derived from the same
 490 structure passed as the respective ioctl. See the Console Optional Ioctls


 491 section of this manpage for an explanation of the specific function each of the
 492 entry points, display(), copy() and cursor() are required to implement. In






 493 addition to performing the prescribed function of their ioctl counterparts, the
 494 standalone vectors operate in a special context and must adhere to a strict set
 495 of rules. The polled I/O vectors are called directly whenever the system is

 496 quisced (running in a limited context) and must send output to the display.
 497 Standalone mode describes the state in which the system is running in
 498 single-threaded mode and only one processor is active.  Solaris operating

 499 environment services are stopped, along with all other threads on the system,
 500 prior to entering any of the polled I/O interfaces. The polled I/O vectors are

 501 called when the system is running in a standalone debugger, when executing the
 502 PROM monitor (OBP) or when panicking.
 503 .sp
 504 .LP
 505 The following restrictions must be observed in the polled I/O functions:
 506 .RS +4
 507 .TP
 508 1.
 509 The driver must not allocate memory.
 510 .RE
 511 .RS +4
 512 .TP
 513 2.
 514 The driver must not wait on mutexes.
 515 .RE
 516 .RS +4
 517 .TP
 518 3.
 519 The driver must not wait for interrupts.
 520 .RE
 521 .RS +4
 522 .TP
 523 4.
 524 The driver must not call any DDI or LDI services.
 525 .RE
 526 .RS +4
 527 .TP
 528 5.
 529 The driver must not call any system services.
 530 .RE
 531 .sp
 532 .LP
 533 The system is single-threaded when calling these functions, meaning that all
 534 other threads are effectively halted. Single-threading makes mutexes (which

 535 cannot be held) easier to deal with, so long as the driver does not disturb any
 536 shared state. See \fIWriting Device Drivers\fR for more information about
 537 implementing polled I/O entry points.
 538 .SH SEE ALSO
 539 .sp
 540 .LP
 541 \fBioctl\fR(2)
 542 .sp
 543 .LP
 544 \fIWriting Device Drivers\fR
 545 .SH NOTES
 546 .sp
 547 .LP
 548 On SPARC systems, compatible drivers supporting the kernel terminal emulator
 549 should export the \fBtem-support\fR DDI property.\fBtem-support\fR indicates
 550 that the driver supports the kernel terminal emulator. By exporting
 551 \fBtem-support\fR it's possible to avoid premature handling of an incompatible
 552 driver.
 553 .sp
 554 .ne 2
 555 .na
 556 \fBtem-support\fR
 557 .ad
 558 .RS 15n
 559 This DDI property, set to 1, means driver is compatible with the console
 560 kernel framebuffer interface.
 561 .RE
 562 

   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 7I
  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
  26 The illumos VISUAL environment defines a small set of ioctls for controlling
  27 graphics and imaging devices.
  28 .Pp
  29 The
  30 .Dv VIS_GETIDENTIFIER
  31 ioctl is mandatory and must be implemented in
  32 device drivers for graphics devices using the illumos VISUAL environment.
  33 The
  34 .Dv VIS_GETIDENTIFIER
  35 ioctl is defined to return a device identifier from the device driver.
  36 This identifier must be a uniquely-defined string.
  37 .Pp
  38 There are two additional sets of ioctls.
  39 One supports mouse tracking via hardware cursor operations.
  40 Use of this set is optional, however, if a graphics
  41 device has hardware cursor support and implements these ioctls, the mouse
  42 tracking performance is improved.
  43 The remaining set supports the device acting
  44 as the system console device.
  45 Use of this set is optional, but if a graphics device is to be used as the
  46 system console device, it must implement these ioctls.
  47 .Pp
  48 The VISUAL environment also defines interfaces for non-ioctl entry points into
  49 the driver that the illumos operating environment calls when it is running in
  50 standalone mode (for example, when using a stand-alone debugger, entering
  51 the PROM monitor, or when the system panicking).
  52 These are also known as
  53 .Dq Polled I/O
  54 entry 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
  58 This
  59 .Xr ioctl 2
  60 returns an identifier string to uniquely identify a device
  61 used in the illumos VISUAL environment.
  62 This is a mandatory ioctl and must return a unique string.
  63 We suggest that the name be formed as
  64 .Ao companysymbol Ac Ns Ao devicetype Ac .
  65 For example, the
  66 .Xr cgsix 7D
  67 driver
  68 returns
  69 .Sy SUNWcg6 .
  70 .Pp
  71 .Dv VIS_GETIDENTIFIER
  72 takes a
  73 .Vt vis_identifier
  74 structure as its parameter.
  75 This structure has the form:
  76 .Bd -literal -offset 2n
  77 #define VIS_MAXNAMELEN 128
  78 struct vis_identifier {
  79        char name[VIS_MAXNAMELEN];
  80 };
  81 .Ed
  82 .Pp
  83 .It Dv VIS_GETCURSOR
  84 .It Dv VIS_SETCURSOR











  85 These ioctls fetch and set various cursor attributes, using the
  86 .Vt vis_cursor
  87 structure.
  88 .Bd -literal -offset 2n

  89 struct vis_cursorpos {
  90    short x; /* cursor x coordinate */
  91    short y; /* cursor y coordinate */
  92 };
  93 
  94 struct 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 
 119 struct 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
 132 The
 133 .Vt vis_cursorcmap
 134 structure should contain pointers to two elements,



 135 specifying the red, green, and blue values for foreground and background.
 136 .Pp
 137 .It Dv VIS_SETCURSORPOS
 138 .It Dv VIS_MOVECURSOR







 139 These ioctls fetch and move the current cursor position, using the
 140 .Vt vis_cursorpos
 141 structure.
 142 .El
 143 .Ss "Console Optional Ioctls"


 144 The following ioctl sets are used by graphics drivers that are part of the
 145 system console device.
 146 All of the ioctls must be implemented to be a console device.
 147 In addition, if the system does not have a prom or the prom goes away
 148 during boot, the special standalone ioctls (listed below) must also be
 149 implemented.
 150 .Pp

 151 The coordinate system for the console device places 0,0 at the upper left
 152 corner of the device, with rows increasing toward the bottom of the device and
 153 columns 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






 158 Set or get color map entries.
 159 .Pp
 160 The argument is a pointer to a
 161 .Vt vis_cmap
 162 structure, which contains the

 163 following fields:
 164 .Bd -literal -offset 2n


 165 struct 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
 175 is the starting index in the color map where you want to start


 176 setting or getting color map entries.
 177 .Pp
 178 .Fa count
 179 is the number of color map entries to set or get.
 180 It also is the
 181 size of the
 182 .Fa red ,
 183 .Fa green ,
 184 and
 185 .Fa blue
 186 color arrays.
 187 .Pp
 188 .Fa *red ,
 189 .Fa *green ,
 190 and
 191 .Fa *blue
 192 are pointers to unsigned character arrays which contain the color map info to
 193 set or where the color map info is placed on a get.
 194 .Pp
 195 .It Dv VIS_DEVINIT
 196 Initializes the graphics driver as a console device.
 197 .Pp
 198 The argument is a pointer to a
 199 .Vt vis_devinit
 200 structure.
 201 The graphics driver
 202 is expected to allocate any local state information needed to be a console
 203 device and fill in this structure.
 204 .Bd -literal -offset 2n


 205 struct 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
 220 is the version of this structure and should be set to
 221 .Dv VIS_CONS_REV .
 222 .Pp
 223 .Fa width
 224 and
 225 .Fa height
 226 are the width and height of the device.
 227 If
 228 .Fa mode
 229 (see below) is
 230 .Dv VIS_TEXT
 231 then
 232 .Fa width
 233 and
 234 .Fa height
 235 are the number of characters wide and high of the device.
 236 If
 237 .Fa mode
 238 is
 239 .Dv VIS_PIXEL
 240 then
 241 .Fa width
 242 and
 243 .Fa height
 244 are the number of pixels wide and high of the device.
 245 .Pp
 246 .Fa linebytes
 247 is the number of bytes per line of the device.
 248 .Pp
 249 .Fa size
 250 is the total size of the device in pixels.
 251 .Pp
 252 .Fa depth
 253 is the pixel depth in device bits.
 254 Currently supported depths are:
 255 .Sy 1 ,
 256 .Sy 4 ,
 257 .Sy 8
 258 and
 259 .Sy 24 .
 260 .Pp
 261 .Fa mode
 262 is the mode of the device.
 263 Either
 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
 270 is used to pass the address of the structure containing the
 271 standalone mode polled I/O entry points to the device driver back to the
 272 terminal emulator.
 273 The
 274 .Vt vis_polledio
 275 interfaces are described in the
 276 Console Standalone Entry Points section of this manpage.
 277 These entry points are where the operating system enters the driver when the
 278 system is running in standalone mode.
 279 These functions perform identically to the
 280 .Dv VIS_CONSDISPLAY ,
 281 .Dv VIS_CONSCURSOR ,
 282 and
 283 .Dv VIS_CONSCOPY
 284 ioctls, but are called directly by the illumos
 285 operating environment and must operate under a very strict set of assumptions.
 286 .Pp
 287 .Fa modechg_cb
 288 is a callback function passed from the terminal emulator to
 289 the framebuffer driver which the frame-buffer driver must call whenever a video
 290 mode change event occurs that changes the screen height, width or depth.
 291 The callback takes two arguments, an opaque handle,
 292 .Fa modechg_arg ,
 293 and the address of a
 294 .Vt vis_devinit
 295 struct containing the new video mode information.
 296 .Pp
 297 .Fa modechg_arg
 298 is an opaque handle passed from the terminal emulator to the
 299 driver, which the driver must pass back to the terminal emulator as an argument
 300 to the
 301 .Fa modechg_cb
 302 function when the driver notifies the terminal emulator of a video mode change.
 303 .Pp
 304 .It Dv VIS_DEVFINI
 305 Tells the graphics driver that it is no longer the system console device.
 306 There is no argument to this ioctl.
 307 The driver is expected to free any locally kept


 308 state information related to the console.
 309 .Pp
 310 .It Dv VIS_CONSCURSOR
 311 Describes the size and placement of the cursor on the screen.
 312 The graphics





 313 driver is expected to display or hide the cursor at the indicated position.
 314 .Pp
 315 The argument is a pointer to a
 316 .Vt vis_conscursor
 317 structure which contains

 318 the following fields:
 319 .Bd -literal -offset 2n


 320 struct 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
 332 and
 333 .Fa col
 334 are the first row and column (upper left corner of the cursor).
 335 .Pp
 336 .Fa width
 337 and
 338 .Fa height
 339 are the width and height of the cursor.
 340 .Pp
 341 If
 342 .Fa mode
 343 in the
 344 .Dv VIS_DEVINIT
 345 ioctl is set to
 346 .Dv VIS_PIXEL ,
 347 then
 348 .Fa col ,
 349 .Fa row ,
 350 .Fa width
 351 and
 352 .Fa height
 353 are in pixels.
 354 If
 355 .Fa mode
 356 in the
 357 .Dv VIS_DEVINIT
 358 ioctl was set to
 359 .Dv VIS_TEXT ,
 360 then
 361 .Fa col ,
 362 .Fa row ,
 363 .Fa width
 364 and
 365 .Fa height
 366 are in characters.
 367 .Pp
 368 .Fa fg_color
 369 and
 370 .Fa bg_color
 371 are the foreground and background color map
 372 indexes to use when the
 373 .Fa action
 374 (see below) is set to
 375 .Dv VIS_DISPLAY_CURSOR .
 376 .Pp
 377 .Fa action
 378 indicates whether to display or hide the cursor.
 379 It is set to either
 380 .Dv VIS_HIDE_CURSOR
 381 or
 382 .Dv VIS_DISPLAY_CURSOR .
 383 .Pp
 384 .It Dv VIS_CONSDISPLAY
 385 Display data on the graphics device.
 386 The graphics driver is expected to display the data contained in the
 387 .Vt vis_display
 388 structure at the specified position on the console.
 389 .Pp
 390 The
 391 .Vt vis_display
 392 structure contains the following fields:
 393 .Bd -literal -offset 2n
 394 struct 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
 406 and
 407 .Fa col
 408 specify at which starting row and column the date is to be displayed.
 409 If
 410 .Fa mode
 411 in the
 412 .Dv VIS_DEVINIT
 413 ioctl was set to
 414 .Dv VIS_TEXT ,
 415 .Fa row
 416 and
 417 .Fa col
 418 are defined to be a character offset
 419 from the starting position of the console device.
 420 If
 421 .Fa mode
 422 in the
 423 .Dv VIS_DEVINIT
 424 ioctl was set to
 425 .Dv VIS_PIXEL ,
 426 .Fa row
 427 and
 428 .Fa col
 429 are defined to be a pixel offset from the starting position of the console
 430 device.
 431 .Pp
 432 .Fa width
 433 and
 434 .Fa height
 435 specify the size of the
 436 .Fa data
 437 to be displayed.
 438 If
 439 .Fa mode
 440 in the
 441 .Dv VIS_DEVINIT
 442 ioctl was set to
 443 .Dv VIS_TEXT ,
 444 .Fa width
 445 and
 446 .Fa height
 447 define the size of
 448 .Fa data
 449 as rectangle that is
 450 .Fa width
 451 characters wide and
 452 .Fa height
 453 characters high.
 454 If
 455 .Fa mode
 456 in the
 457 .Dv VIS_DEVINIT
 458 ioctl was set to
 459 .Dv VIS_PIXEL ,
 460 .Fa width
 461 and
 462 .Fa height
 463 define the size of
 464 .Fa data
 465 as a rectangle that is
 466 .Fa width
 467 pixels wide and
 468 .Fa height
 469 pixels high.
 470 .Pp
 471 .Fa *data
 472 is a pointer to the data to be displayed on the console device.
 473 If
 474 .Fa mode
 475 in the
 476 .Dv VIS_DEVINIT
 477 ioctl was set to
 478 .Dv VIS_TEXT ,
 479 .Fa data
 480 is an array of
 481 .Sy ASCII
 482 characters to be displayed on the console device.
 483 The driver must break these characters up appropriately and display it in the
 484 rectangle defined by
 485 .Fa row ,
 486 .Fa col ,
 487 .Fa width ,
 488 and
 489 .Fa height .
 490 If
 491 .Fa mode
 492 in the
 493 .Dv VIS_DEVINIT
 494 ioctl was set to
 495 .Dv VIS_PIXEL ,
 496 .Fa data
 497 is an array of bitmap data to be displayed on the console device.
 498 The driver must break this data up appropriately and display it in the retangle
 499 defined by
 500 .Fa row ,
 501 .Fa col ,
 502 .Fa width ,
 503 and
 504 .Fa height .
 505 .Pp
 506 The
 507 .Fa fg_color
 508 and
 509 .Fa bg_color
 510 fields define the foreground and
 511 background color map indexes to use when displaying the data.
 512 .Fa fb_color
 513 is used for
 514 .Dq on
 515 pixels and
 516 .Fa bg_color
 517 is used for
 518 .Dq off
 519 pixels.
 520 .Pp
 521 .It Dv VIS_CONSCOPY
 522 Copy data from one location on the device to another.
 523 The driver is expected to copy the specified data.
 524 The source data should not be modified.
 525 Any modifications to the source data should be as a side effect of the copy
 526 destination overlapping the copy source.
 527 .Pp
 528 The argument is a pointer to a
 529 .Vt vis_copy
 530 structure which contains the following fields:
 531 .Bd -literal -offset 2n




 532 struct 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 ,
 546 and
 547 .Fa e_col
 548 define the source rectangle of the copy.
 549 .Fa s_row
 550 and
 551 .Fa s_col
 552 are the upper left corner of the source rectangle.
 553 .Fa e_row
 554 and
 555 .Fa e_col
 556 are the lower right corner of the source rectangle.
 557 If
 558 .Fa mode
 559 in the
 560 .Dv VIS_DEVINIT
 561 .Fn ioctl
 562 was set to
 563 .Dv VIS_TEXT ,
 564 .Fa s_row ,
 565 .Fa s_col ,
 566 .Fa e_row ,
 567 and
 568 .Fa e_col
 569 are defined to be character offsets from the starting position of the console
 570 device.
 571 If
 572 .Fa mode
 573 in the
 574 .Dv VIS_DEVINIT
 575 .Fn ioctl
 576 was set to
 577 .Dv VIS_PIXEL ,
 578 .Fa s_row ,
 579 .Fa s_col ,
 580 .Fa e_row ,
 581 and
 582 .Fa e_col
 583 are
 584 defined to be pixel offsets from the starting position of the console device.
 585 .Pp
 586 .Fa t_row
 587 and
 588 .Fa t_col
 589 define the upper left corner of the destination rectangle of the copy.
 590 The entire rectangle is copied to this location.
 591 If
 592 .Fa mode
 593 in the
 594 .Dv VIS_DEVINIT
 595 ioctl was set to
 596 .Dv VIS_TEXT ,
 597 .Fa t_row ,
 598 and
 599 .Fa t_col
 600 are defined to be character offsets from the
 601 starting position of the console device.
 602 If
 603 .Fa mode
 604 in the
 605 .Dv VIS_DEVINIT
 606 ioctl was set to
 607 .Dv VIS_PIXEL ,
 608 .Fa t_row ,
 609 and
 610 .Fa t_col
 611 are defined to be pixel offsets from the starting position of the
 612 onssole device.
 613 .Pp
 614 .Fa direction
 615 specifies which way to do the copy.
 616 If direction is
 617 .Dv VIS_COPY_FORWARD
 618 the graphics driver should copy data from position
 619 .Po
 620 .Fa s_row ,
 621 .Fa s_col
 622 .Pc
 623 in the source rectangle to position
 624 .Po
 625 .Fa t_row ,
 626 .Fa t_col
 627 .Pc
 628 in the destination rectangle.
 629 If direction is
 630 .Dv VIS_COPY_BACKWARDS
 631 the graphics driver should copy data from position
 632 .Po
 633 .Fa e_row ,
 634 .Fa e_col
 635 .Pc
 636 in 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
 649 in the destination rectangle.
 650 .El
 651 .Ss "Console Standalone Entry Points  (Polled I/O Interfaces)"
 652 Console standalone entry points are necessary only if the driver is
 653 implementing console-compatible extensions.
 654 All console vectored standalone
 655 entry points must be implemented along with all console-related ioctls if the
 656 console extension is implemented.
 657 .Bd -literal -offset 2n


 658 struct 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
 666 The
 667 .Vt vis_polledio
 668 structure is passed from the driver to the illumos

 669 operating environment, conveying the entry point addresses of three functions
 670 which perform the same operations of their similarly named ioctl counterparts.
 671 The rendering parameters for each entry point are derived from the same
 672 structure passed as the respective ioctl.
 673 See the
 674 .Sx "Console Optional Ioctls"
 675 section of this manpage for an explanation of the specific function each of the
 676 entry points,
 677 .Fn display ,
 678 .Fn copy ,
 679 and
 680 .Fn cursor
 681 are required to implement.
 682 In
 683 addition to performing the prescribed function of their ioctl counterparts, the
 684 standalone vectors operate in a special context and must adhere to a strict set
 685 of rules.
 686 The polled I/O vectors are called directly whenever the system is
 687 quisced (running in a limited context) and must send output to the display.
 688 Standalone mode describes the state in which the system is running in
 689 single-threaded mode and only one processor is active.
 690 illumos operating
 691 environment services are stopped, along with all other threads on the system,
 692 prior to entering any of the polled I/O interfaces.
 693 The polled I/O vectors are
 694 called when the system is running in a standalone debugger, when executing the
 695 PROM monitor (OBP) or when panicking.
 696 .Pp

 697 The following restrictions must be observed in the polled I/O functions:
 698 .Bl -enum -offset indent
 699 .It

 700 The driver must not allocate memory.
 701 .It



 702 The driver must not wait on mutexes.
 703 .It



 704 The driver must not wait for interrupts.
 705 .It



 706 The driver must not call any DDI or LDI services.
 707 .It



 708 The driver must not call any system services.
 709 .El
 710 .Pp

 711 The system is single-threaded when calling these functions, meaning that all
 712 other threads are effectively halted.
 713 Single-threading makes mutexes (which
 714 cannot be held) easier to deal with, so long as the driver does not disturb any
 715 shared state.
 716 See
 717 .%T Writing Device Drivers
 718 for 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


 725 On SPARC systems, compatible drivers supporting the kernel terminal emulator
 726 should export the
 727 .Sy tem-support
 728 DDI property.
 729 .Sy tem-support
 730 indicates that the driver supports the kernel terminal emulator.
 731 By exporting
 732 .Sy tem-support
 733 it's possible to avoid premature handling of an incompatible driver.
 734 .Bl -tag -width tem-support
 735 .It Sy tem-support
 736 This DDI property, set to 1, means driver is compatible with the console
 737 kernel framebuffer interface.
 738 .El