Print this page
10562 Convert visual_io(7I) to mandoc

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man7i/visual_io.7i
          +++ new/usr/src/man/man7i/visual_io.7i
   1      -'\" te
   2    1  .\" 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
        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
  19   27  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
       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
  30   41  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
       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
  37   48  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
       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
  61   77  #define VIS_MAXNAMELEN 128
  62   78  struct vis_identifier {
  63   79         char name[VIS_MAXNAMELEN];
  64   80  };
  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
       81 +.Ed
       82 +.Pp
       83 +.It Dv VIS_GETCURSOR
       84 +.It Dv VIS_SETCURSOR
  80   85  These ioctls fetch and set various cursor attributes, using the
  81      -\fBvis_cursor\fR structure.
  82      -.sp
  83      -.in +2
  84      -.nf
       86 +.Vt vis_cursor
       87 +structure.
       88 +.Bd -literal -offset 2n
  85   89  struct vis_cursorpos {
  86      -           short        x;           /* cursor x coordinate */
  87      -           short        y;           /* cursor y coordinate */
       90 +   short x; /* cursor x coordinate */
       91 +   short y; /* cursor y coordinate */
  88   92  };
  89   93  
  90   94  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 */
       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;
  96  103  };
  97  104  
  98  105  #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 */
      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
 103  114  #define VIS_CURSOR_SETALL       \e
 104  115      (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \e
 105  116      VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \e
 106  117      VIS_CURSOR_SETSHAPE)
 107  118  
 108  119  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 */
      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 */
 117  129  };
 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,
      130 +.Ed
      131 +.Pp
      132 +The
      133 +.Vt vis_cursorcmap
      134 +structure should contain pointers to two elements,
 126  135  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
      136 +.Pp
      137 +.It Dv VIS_SETCURSORPOS
      138 +.It Dv VIS_MOVECURSOR
 137  139  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
      140 +.Vt vis_cursorpos
      141 +structure.
      142 +.El
      143 +.Ss "Console Optional Ioctls"
 144  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
      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
 147  148  during boot, the special standalone ioctls (listed below) must also be
 148  149  implemented.
 149      -.sp
 150      -.LP
      150 +.Pp
 151  151  The coordinate system for the console device places 0,0 at the upper left
 152  152  corner of the device, with rows increasing toward the bottom of the device and
 153  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
      154 +.Pp
      155 +.Bl -tag -width VIS_CONSDISPLAY -compact -offset 2n
      156 +.It Dv VIS_PUTCMAP
      157 +.It Dv VIS_GETCMAP
 164  158  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
      159 +.Pp
      160 +The argument is a pointer to a
      161 +.Vt vis_cmap
      162 +structure, which contains the
 170  163  following fields:
 171      -.sp
 172      -.in +2
 173      -.nf
      164 +.Bd -literal -offset 2n
 174  165  struct vis_cmap {
 175      -    int index;
 176      -    int count;
      166 +    int         index;
      167 +    int         count;
 177  168      uchar_t     *red;
 178  169      uchar_t     *green;
 179  170      uchar_t     *blue;
 180  171  }
 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
      172 +.Ed
      173 +.Pp
      174 +.Fa index
      175 +is the starting index in the color map where you want to start
 187  176  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
      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
 203  196  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
      197 +.Pp
      198 +The argument is a pointer to a
      199 +.Vt vis_devinit
      200 +structure.
      201 +The graphics driver
 209  202  is expected to allocate any local state information needed to be a console
 210  203  device and fill in this structure.
 211      -.sp
 212      -.in +2
 213      -.nf
      204 +.Bd -literal -offset 2n
 214  205  struct vis_devinit {
 215  206      int  version;
 216  207      screen_size_t  width;
 217  208      screen_size_t  height;
 218  209      screen_size_t  linebytes;
 219      -    unit_t      size;
 220      -    int    depth;
 221      -    short  mode;
      210 +    unit_t         size;
      211 +    int            depth;
      212 +    short          mode;
 222  213      struct vis_polledio    *polledio;
 223  214      vis_modechg_cb_t       modechg_cb;
 224  215      struct vis_modechg_arg *modechg_arg;
 225  216  };
 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
      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
 258  271  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
      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
 264  285  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
      286 +.Pp
      287 +.Fa modechg_cb
      288 +is a callback function passed from the terminal emulator to
 268  289  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
      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
 275  299  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
      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
 286  308  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
      309 +.Pp
      310 +.It Dv VIS_CONSCURSOR
      311 +Describes the size and placement of the cursor on the screen.
      312 +The graphics
 296  313  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
      314 +.Pp
      315 +The argument is a pointer to a
      316 +.Vt vis_conscursor
      317 +structure which contains
 302  318  the following fields:
 303      -.sp
 304      -.in +2
 305      -.nf
      319 +.Bd -literal -offset 2n
 306  320  struct vis_conscursor {
 307  321      screen_pos_t   row;
 308  322      screen_pos_t   col;
 309  323      screen_size_t  width;
 310  324      screen_size_t  height
 311  325      color_t        fg_color;
 312  326      color_t        bg_color;
 313  327      short          action;
 314  328  };
 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
      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
 357  394  struct vis_display {
 358  395      screen_pos_t   row;
 359  396      screen_pos_t   col;
 360  397      screen_size_t  width;
 361  398      screen_size_t  height;
 362  399      uchar_t        *data;
 363  400      color_t        fg_color;
 364  401      color_t        bg_color;
 365  402  };
 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
      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
 377  430  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.
      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.
 396  498  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
      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
 412  526  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
      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
 422  532  struct vis_copy {
 423  533      screen_pos_t  s_row;
 424  534      screen_pos_t  s_col;
 425  535      screen_pos_t  e_row;
 426  536      screen_pos_t  e_col;
 427  537      screen_pos_t  t_row;
 428  538      screen_pos_t  t_col;
 429  539      short         direction;
 430  540  };
 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
      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)"
 468  652  Console standalone entry points are necessary only if the driver is
 469      -implementing console-compatible extensions. All console vectored standalone
      653 +implementing console-compatible extensions.
      654 +All console vectored standalone
 470  655  entry points must be implemented along with all console-related ioctls if the
 471  656  console extension is implemented.
 472      -.sp
 473      -.in +2
 474      -.nf
      657 +.Bd -literal -offset 2n
 475  658  struct vis_polledio {
 476  659      struct vis_polledio_arg *arg;
 477  660      void    (*display)(vis_polledio_arg *, struct vis_consdisplay *);
 478  661      void    (*copy)(vis_polledio_arg *, struct vis_conscopy *);
 479  662      void    (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
 480  663  };
 481      -.fi
 482      -.in -2
 483      -
 484      -.sp
 485      -.LP
 486      -The \fBvis_polledio\fR structure is passed from the driver to the Solaris
      664 +.Ed
      665 +.Pp
      666 +The
      667 +.Vt vis_polledio
      668 +structure is passed from the driver to the illumos
 487  669  operating environment, conveying the entry point addresses of three functions
 488  670  which perform the same operations of their similarly named ioctl counterparts.
 489  671  The rendering parameters for each entry point are derived from the same
 490      -structure passed as the respective ioctl. See the Console Optional Ioctls
      672 +structure passed as the respective ioctl.
      673 +See the
      674 +.Sx "Console Optional Ioctls"
 491  675  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
      676 +entry points,
      677 +.Fn display ,
      678 +.Fn copy ,
      679 +and
      680 +.Fn cursor
      681 +are required to implement.
      682 +In
 493  683  addition to performing the prescribed function of their ioctl counterparts, the
 494  684  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
      685 +of rules.
      686 +The polled I/O vectors are called directly whenever the system is
 496  687  quisced (running in a limited context) and must send output to the display.
 497  688  Standalone mode describes the state in which the system is running in
 498      -single-threaded mode and only one processor is active.  Solaris operating
      689 +single-threaded mode and only one processor is active.
      690 +illumos operating
 499  691  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
      692 +prior to entering any of the polled I/O interfaces.
      693 +The polled I/O vectors are
 501  694  called when the system is running in a standalone debugger, when executing the
 502  695  PROM monitor (OBP) or when panicking.
 503      -.sp
 504      -.LP
      696 +.Pp
 505  697  The following restrictions must be observed in the polled I/O functions:
 506      -.RS +4
 507      -.TP
 508      -1.
      698 +.Bl -enum -offset indent
      699 +.It
 509  700  The driver must not allocate memory.
 510      -.RE
 511      -.RS +4
 512      -.TP
 513      -2.
      701 +.It
 514  702  The driver must not wait on mutexes.
 515      -.RE
 516      -.RS +4
 517      -.TP
 518      -3.
      703 +.It
 519  704  The driver must not wait for interrupts.
 520      -.RE
 521      -.RS +4
 522      -.TP
 523      -4.
      705 +.It
 524  706  The driver must not call any DDI or LDI services.
 525      -.RE
 526      -.RS +4
 527      -.TP
 528      -5.
      707 +.It
 529  708  The driver must not call any system services.
 530      -.RE
 531      -.sp
 532      -.LP
      709 +.El
      710 +.Pp
 533  711  The system is single-threaded when calling these functions, meaning that all
 534      -other threads are effectively halted. Single-threading makes mutexes (which
      712 +other threads are effectively halted.
      713 +Single-threading makes mutexes (which
 535  714  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
      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
 548  725  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
      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
 559  736  This DDI property, set to 1, means driver is compatible with the console
 560  737  kernel framebuffer interface.
 561      -.RE
 562      -
      738 +.El
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX