1 VISUAL_IO(7I)                   Ioctl Requests                   VISUAL_IO(7I)
   3 NAME
   4      visual_io - illumos VISUAL I/O control operations
   7      #include <sys/visual_io.h>
  10      The illumos VISUAL environment defines a small set of ioctls for
  11      controlling graphics and imaging devices.
  13      The VIS_GETIDENTIFIER ioctl is mandatory and must be implemented in
  14      device drivers for graphics devices using the illumos VISUAL environment.
  15      The VIS_GETIDENTIFIER ioctl is defined to return a device identifier from
  16      the device driver.  This identifier must be a uniquely-defined string.
  18      There are two additional sets of ioctls.  One supports mouse tracking via
  19      hardware cursor operations.  Use of this set is optional, however, if a
  20      graphics device has hardware cursor support and implements these ioctls,
  21      the mouse tracking performance is improved.  The remaining set supports
  22      the device acting as the system console device.  Use of this set is
  23      optional, but if a graphics device is to be used as the system console
  24      device, it must implement these ioctls.
  26      The VISUAL environment also defines interfaces for non-ioctl entry points
  27      into the driver that the illumos operating environment calls when it is
  28      running in standalone mode (for example, when using a stand-alone
  29      debugger, entering the PROM monitor, or when the system panicking).
  30      These are also known as "Polled I/O" entry points, which operate under an
  31      explicit set of restrictions, described below.
  34      VIS_GETIDENTIFIER  This ioctl(2) returns an identifier string to uniquely
  35                         identify a device used in the illumos VISUAL
  36                         environment.  This is a mandatory ioctl and must
  37                         return a unique string.  We suggest that the name be
  38                         formed as <companysymbol><devicetype>.
  40                         VIS_GETIDENTIFIER takes a vis_identifier structure as
  41                         its parameter.  This structure has the form:
  43                           #define VIS_MAXNAMELEN 128
  44                           struct vis_identifier {
  45                                  char name[VIS_MAXNAMELEN];
  46                           };
  49      VIS_SETCURSOR      These ioctls fetch and set various cursor attributes,
  50                         using the vis_cursor structure.
  52                           struct vis_cursorpos {
  53                              short x; /* cursor x coordinate */
  54                              short y; /* cursor y coordinate */
  55                           };
  57                           struct vis_cursorcmap {
  58                               int version;          /* version */
  59                               int reserved;
  60                               /* red color map elements */
  61                               unsigned char *red;
  62                               /* green color map elements */
  63                               unsigned char *green;
  64                               /* blue color map elements */
  65                               unsigned char *blue;
  66                           };
  68                           #define VIS_CURSOR_SETCURSOR   0x01  /* set cursor */
  69                                   /* set cursor position */
  70                           #define VIS_CURSOR_SETPOSITION 0x02
  71                                   /* set cursur hot spot */
  72                           #define VIS_CURSOR_SETHOTSPOT  0x04
  73                                   /* set cursor colormap */
  74                           #define VIS_CURSOR_SETCOLORMAP 0x08
  75                                   /* set cursor shape */
  76                           #define VIS_CURSOR_SETSHAPE 0x10
  77                           #define VIS_CURSOR_SETALL       \
  78                               (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \
  79                               VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \
  80                               VIS_CURSOR_SETSHAPE)
  82                           struct vis_cursor {
  83                               short set;                  /* what to set */
  84                               short enable;               /* cursor on/off */
  85                               struct vis_cursorpos pos;   /* cursor position */
  86                               struct  vis_cursorpos hot;  /* cursor hot spot */
  87                               struct vis_cursorcmap cmap; /* color map info */
  88                               /* cursor bitmap size */
  89                               struct vis_cursorpos size;
  90                               char  *image;              /* cursor image bits */
  91                               char  *mask;               /* cursor mask bits */
  92                           };
  94                         The vis_cursorcmap structure should contain pointers
  95                         to two elements, specifying the red, green, and blue
  96                         values for foreground and background.
  99      VIS_MOVECURSOR     These ioctls fetch and move the current cursor
 100                         position, using the vis_cursorpos structure.
 102    Console Optional Ioctls
 103      The following ioctl sets are used by graphics drivers that are part of
 104      the system console device.  All of the ioctls must be implemented to be a
 105      console device.  In addition, if the system does not have a prom or the
 106      prom goes away during boot, the special standalone ioctls (listed below)
 107      must also be implemented.
 109      The coordinate system for the console device places 0,0 at the upper left
 110      corner of the device, with rows increasing toward the bottom of the
 111      device and columns increasing from left to right.
 113        VIS_PUTCMAP
 114        VIS_GETCMAP      Set or get color map entries.
 116                         The argument is a pointer to a vis_cmap structure,
 117                         which contains the following fields:
 119                           struct vis_cmap {
 120                               int         index;
 121                               int         count;
 122                               uchar_t     *red;
 123                               uchar_t     *green;
 124                               uchar_t     *blue;
 125                           }
 127                         index is the starting index in the color map where you
 128                         want to start setting or getting color map entries.
 130                         count is the number of color map entries to set or
 131                         get.  It also is the size of the red, green, and blue
 132                         color arrays.
 134                         *red, *green, and *blue are pointers to unsigned
 135                         character arrays which contain the color map info to
 136                         set or where the color map info is placed on a get.
 138        VIS_DEVINIT      Initializes the graphics driver as a console device.
 140                         The argument is a pointer to a vis_devinit structure.
 141                         The graphics driver is expected to allocate any local
 142                         state information needed to be a console device and
 143                         fill in this structure.
 145                           struct vis_devinit {
 146                               int  version;
 147                               screen_size_t  width;
 148                               screen_size_t  height;
 149                               screen_size_t  linebytes;
 150                               unit_t         size;
 151                               int            depth;
 152                               short          mode;
 153                               struct vis_polledio    *polledio;
 154                               vis_modechg_cb_t       modechg_cb;
 155                               struct vis_modechg_arg *modechg_arg;
 156                           };
 158                         version is the version of this structure and should be
 159                         set to VIS_CONS_REV.
 161                         width and height are the width and height of the
 162                         device.  If mode (see below) is VIS_TEXT then width
 163                         and height are the number of characters wide and high
 164                         of the device.  If mode is VIS_PIXEL then width and
 165                         height are the number of pixels wide and high of the
 166                         device.
 168                         linebytes is the number of bytes per line of the
 169                         device.
 171                         size is the total size of the device in pixels.
 173                         depth is the pixel depth in device bits.  Currently
 174                         supported depths are: 1, 4, 8 and 24.
 176                         mode is the mode of the device.  Either VIS_PIXEL
 177                         (data to be displayed is in bitmap format) or VIS_TEXT
 178                         (data to be displayed is in ascii format).
 180                         polledio is used to pass the address of the structure
 181                         containing the standalone mode polled I/O entry points
 182                         to the device driver back to the terminal emulator.
 183                         The vis_polledio interfaces are described in the
 184                         Console Standalone Entry Points section of this
 185                         manpage.  These entry points are where the operating
 186                         system enters the driver when the system is running in
 187                         standalone mode.  These functions perform identically
 188                         to the VIS_CONSDISPLAY, VIS_CONSCURSOR, and
 189                         VIS_CONSCOPY ioctls, but are called directly by the
 190                         illumos operating environment and must operate under a
 191                         very strict set of assumptions.
 193                         modechg_cb is a callback function passed from the
 194                         terminal emulator to the framebuffer driver which the
 195                         frame-buffer driver must call whenever a video mode
 196                         change event occurs that changes the screen height,
 197                         width or depth.  The callback takes two arguments, an
 198                         opaque handle, modechg_arg, and the address of a
 199                         vis_devinit struct containing the new video mode
 200                         information.
 202                         modechg_arg is an opaque handle passed from the
 203                         terminal emulator to the driver, which the driver must
 204                         pass back to the terminal emulator as an argument to
 205                         the modechg_cb function when the driver notifies the
 206                         terminal emulator of a video mode change.
 208        VIS_DEVFINI      Tells the graphics driver that it is no longer the
 209                         system console device.  There is no argument to this
 210                         ioctl.  The driver is expected to free any locally
 211                         kept state information related to the console.
 213        VIS_CONSCURSOR   Describes the size and placement of the cursor on the
 214                         screen.  The graphics driver is expected to display or
 215                         hide the cursor at the indicated position.
 217                         The argument is a pointer to a vis_conscursor
 218                         structure which contains the following fields:
 220                           struct vis_conscursor {
 221                               screen_pos_t   row;
 222                               screen_pos_t   col;
 223                               screen_size_t  width;
 224                               screen_size_t  height
 225                               color_t        fg_color;
 226                               color_t        bg_color;
 227                               short          action;
 228                           };
 230                         row and col are the first row and column (upper left
 231                         corner of the cursor).
 233                         width and height are the width and height of the
 234                         cursor.
 236                         If mode in the VIS_DEVINIT ioctl is set to VIS_PIXEL,
 237                         then col, row, width and height are in pixels.  If
 238                         mode in the VIS_DEVINIT ioctl was set to VIS_TEXT,
 239                         then col, row, width and height are in characters.
 241                         fg_color and bg_color are the foreground and
 242                         background color map indexes to use when the action
 243                         (see below) is set to VIS_DISPLAY_CURSOR.
 245                         action indicates whether to display or hide the
 246                         cursor.  It is set to either VIS_HIDE_CURSOR or
 247                         VIS_DISPLAY_CURSOR.
 249        VIS_CONSDISPLAY  Display data on the graphics device.  The graphics
 250                         driver is expected to display the data contained in
 251                         the vis_display structure at the specified position on
 252                         the console.
 254                         The vis_display structure contains the following
 255                         fields:
 257                           struct vis_display {
 258                               screen_pos_t   row;
 259                               screen_pos_t   col;
 260                               screen_size_t  width;
 261                               screen_size_t  height;
 262                               uchar_t        *data;
 263                               color_t        fg_color;
 264                               color_t        bg_color;
 265                           };
 267                         row and col specify at which starting row and column
 268                         the date is to be displayed.  If mode in the
 269                         VIS_DEVINIT ioctl was set to VIS_TEXT, row and col are
 270                         defined to be a character offset from the starting
 271                         position of the console device.  If mode in the
 272                         VIS_DEVINIT ioctl was set to VIS_PIXEL, row and col
 273                         are defined to be a pixel offset from the starting
 274                         position of the console device.
 276                         width and height specify the size of the data to be
 277                         displayed.  If mode in the VIS_DEVINIT ioctl was set
 278                         to VIS_TEXT, width and height define the size of data
 279                         as rectangle that is width characters wide and height
 280                         characters high.  If mode in the VIS_DEVINIT ioctl was
 281                         set to VIS_PIXEL, width and height define the size of
 282                         data as a rectangle that is width pixels wide and
 283                         height pixels high.
 285                         *data is a pointer to the data to be displayed on the
 286                         console device.  If mode in the VIS_DEVINIT ioctl was
 287                         set to VIS_TEXT, data is an array of ASCII characters
 288                         to be displayed on the console device.  The driver
 289                         must break these characters up appropriately and
 290                         display it in the rectangle defined by row, col,
 291                         width, and height.  If mode in the VIS_DEVINIT ioctl
 292                         was set to VIS_PIXEL, data is an array of bitmap data
 293                         to be displayed on the console device.  The driver
 294                         must break this data up appropriately and display it
 295                         in the retangle defined by row, col, width, and
 296                         height.
 298                         The fg_color and bg_color fields define the foreground
 299                         and background color map indexes to use when
 300                         displaying the data.  fb_color is used for "on" pixels
 301                         and bg_color is used for "off" pixels.
 303        VIS_CONSCOPY     Copy data from one location on the device to another.
 304                         The driver is expected to copy the specified data.
 305                         The source data should not be modified.  Any
 306                         modifications to the source data should be as a side
 307                         effect of the copy destination overlapping the copy
 308                         source.
 310                         The argument is a pointer to a vis_copy structure
 311                         which contains the following fields:
 313                           struct vis_copy {
 314                               screen_pos_t  s_row;
 315                               screen_pos_t  s_col;
 316                               screen_pos_t  e_row;
 317                               screen_pos_t  e_col;
 318                               screen_pos_t  t_row;
 319                               screen_pos_t  t_col;
 320                               short         direction;
 321                           };
 323                         s_row, s_col, e_row, and e_col define the source
 324                         rectangle of the copy.  s_row and s_col are the upper
 325                         left corner of the source rectangle.  e_row and e_col
 326                         are the lower right corner of the source rectangle.
 327                         If mode in the VIS_DEVINIT ioctl() was set to
 328                         VIS_TEXT, s_row, s_col, e_row, and e_col are defined
 329                         to be character offsets from the starting position of
 330                         the console device.  If mode in the VIS_DEVINIT
 331                         ioctl() was set to VIS_PIXEL, s_row, s_col, e_row, and
 332                         e_col are defined to be pixel offsets from the
 333                         starting position of the console device.
 335                         t_row and t_col define the upper left corner of the
 336                         destination rectangle of the copy.  The entire
 337                         rectangle is copied to this location.  If mode in the
 338                         VIS_DEVINIT ioctl was set to VIS_TEXT, t_row, and
 339                         t_col are defined to be character offsets from the
 340                         starting position of the console device.  If mode in
 341                         the VIS_DEVINIT ioctl was set to VIS_PIXEL, t_row, and
 342                         t_col are defined to be pixel offsets from the
 343                         starting position of the console device.
 345                         direction specifies which way to do the copy.  If
 346                         direction is VIS_COPY_FORWARD the graphics driver
 347                         should copy data from position (s_row, s_col) in the
 348                         source rectangle to position (t_row, t_col) in the
 349                         destination rectangle.  If direction is
 350                         VIS_COPY_BACKWARDS the graphics driver should copy
 351                         data from position (e_row, e_col) in the source
 352                         rectangle to position (t_row+(e_row-s_row),
 353                         t_col+(e_col-s_col)) in the destination rectangle.
 355    Console Standalone Entry Points  (Polled I/O Interfaces)
 356      Console standalone entry points are necessary only if the driver is
 357      implementing console-compatible extensions.  All console vectored
 358      standalone entry points must be implemented along with all console-
 359      related ioctls if the console extension is implemented.
 361        struct vis_polledio {
 362            struct vis_polledio_arg *arg;
 363            void    (*display)(vis_polledio_arg *, struct vis_consdisplay *);
 364            void    (*copy)(vis_polledio_arg *, struct vis_conscopy *);
 365            void    (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
 366        };
 368      The vis_polledio structure is passed from the driver to the illumos
 369      operating environment, conveying the entry point addresses of three
 370      functions which perform the same operations of their similarly named
 371      ioctl counterparts.  The rendering parameters for each entry point are
 372      derived from the same structure passed as the respective ioctl.  See the
 373      Console Optional Ioctls section of this manpage for an explanation of the
 374      specific function each of the entry points, display(), copy(), and
 375      cursor() are required to implement.  In addition to performing the
 376      prescribed function of their ioctl counterparts, the standalone vectors
 377      operate in a special context and must adhere to a strict set of rules.
 378      The polled I/O vectors are called directly whenever the system is
 379      quiesced (running in a limited context) and must send output to the
 380      display.  Standalone mode describes the state in which the system is
 381      running in single-threaded mode and only one processor is active.
 382      illumos operating environment services are stopped, along with all other
 383      threads on the system, prior to entering any of the polled I/O
 384      interfaces.  The polled I/O vectors are called when the system is running
 385      in a standalone debugger, when executing the PROM monitor (OBP) or when
 386      panicking.
 388      The following restrictions must be observed in the polled I/O functions:
 390            1.   The driver must not allocate memory.
 392            2.   The driver must not wait on mutexes.
 394            3.   The driver must not wait for interrupts.
 396            4.   The driver must not call any DDI or LDI services.
 398            5.   The driver must not call any system services.
 400      The system is single-threaded when calling these functions, meaning that
 401      all other threads are effectively halted.  Single-threading makes mutexes
 402      (which cannot be held) easier to deal with, so long as the driver does
 403      not disturb any shared state.  See Writing Device Drivers for more
 404      information about implementing polled I/O entry points.
 407      ioctl(2)
 409      Writing Device Drivers.
 411 NOTES
 412      On SPARC systems, compatible drivers supporting the kernel terminal
 413      emulator should export the tem-support DDI property.  tem-support
 414      indicates that the driver supports the kernel terminal emulator.  By
 415      exporting tem-support it's possible to avoid premature handling of an
 416      incompatible driver.
 418      tem-support  This DDI property, set to 1, means driver is compatible with
 419                   the console kernel framebuffer interface.
 421 illumos                        February 17, 2020                       illumos