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 {

 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

 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

   1 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
   2 .\" Copyright 2018, Joyent, Inc.
   3 .\" Copyright 2020 Peter Tribble.
   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or http://www.opensolaris.org/os/licensing.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .Dd February 17, 2020
  19 .Dt VISUAL_IO 7I
  20 .Os
  21 .Sh NAME
  22 .Nm visual_io
  23 .Nd illumos VISUAL I/O control operations
  24 .Sh SYNOPSIS
  25 .In sys/visual_io.h
  26 .Sh DESCRIPTION
  27 The illumos VISUAL environment defines a small set of ioctls for controlling
  28 graphics and imaging devices.
  29 .Pp
  30 The
  31 .Dv VIS_GETIDENTIFIER
  32 ioctl is mandatory and must be implemented in
  33 device drivers for graphics devices using the illumos VISUAL environment.
  34 The
  35 .Dv VIS_GETIDENTIFIER
  36 ioctl is defined to return a device identifier from the device driver.
  37 This identifier must be a uniquely-defined string.
  38 .Pp
  39 There are two additional sets of ioctls.
  40 One supports mouse tracking via hardware cursor operations.
  41 Use of this set is optional, however, if a graphics
  42 device has hardware cursor support and implements these ioctls, the mouse
  43 tracking performance is improved.
  44 The remaining set supports the device acting
  45 as the system console device.
  46 Use of this set is optional, but if a graphics device is to be used as the
  47 system console device, it must implement these ioctls.
  48 .Pp
  49 The VISUAL environment also defines interfaces for non-ioctl entry points into
  50 the driver that the illumos operating environment calls when it is running in
  51 standalone mode (for example, when using a stand-alone debugger, entering
  52 the PROM monitor, or when the system panicking).
  53 These are also known as
  54 .Dq Polled I/O
  55 entry points, which operate under an explicit set of restrictions, described below.
  56 .Sh IOCTLS
  57 .Bl -tag -width VIS_GETIDENTIFIER -compact
  58 .It Dv VIS_GETIDENTIFIER
  59 This
  60 .Xr ioctl 2
  61 returns an identifier string to uniquely identify a device
  62 used in the illumos VISUAL environment.
  63 This is a mandatory ioctl and must return a unique string.
  64 We suggest that the name be formed as
  65 .Ao companysymbol Ac Ns Ao devicetype Ac .





  66 .Pp
  67 .Dv VIS_GETIDENTIFIER
  68 takes a
  69 .Vt vis_identifier
  70 structure as its parameter.
  71 This structure has the form:
  72 .Bd -literal -offset 2n
  73 #define VIS_MAXNAMELEN 128
  74 struct vis_identifier {
  75        char name[VIS_MAXNAMELEN];
  76 };
  77 .Ed
  78 .Pp
  79 .It Dv VIS_GETCURSOR
  80 .It Dv VIS_SETCURSOR
  81 These ioctls fetch and set various cursor attributes, using the
  82 .Vt vis_cursor
  83 structure.
  84 .Bd -literal -offset 2n
  85 struct vis_cursorpos {

 588 .Fa mode
 589 in the
 590 .Dv VIS_DEVINIT
 591 ioctl was set to
 592 .Dv VIS_TEXT ,
 593 .Fa t_row ,
 594 and
 595 .Fa t_col
 596 are defined to be character offsets from the
 597 starting position of the console device.
 598 If
 599 .Fa mode
 600 in the
 601 .Dv VIS_DEVINIT
 602 ioctl was set to
 603 .Dv VIS_PIXEL ,
 604 .Fa t_row ,
 605 and
 606 .Fa t_col
 607 are defined to be pixel offsets from the starting position of the
 608 console device.
 609 .Pp
 610 .Fa direction
 611 specifies which way to do the copy.
 612 If direction is
 613 .Dv VIS_COPY_FORWARD
 614 the graphics driver should copy data from position
 615 .Po
 616 .Fa s_row ,
 617 .Fa s_col
 618 .Pc
 619 in the source rectangle to position
 620 .Po
 621 .Fa t_row ,
 622 .Fa t_col
 623 .Pc
 624 in the destination rectangle.
 625 If direction is
 626 .Dv VIS_COPY_BACKWARDS
 627 the graphics driver should copy data from position
 628 .Po

 663 .Vt vis_polledio
 664 structure is passed from the driver to the illumos
 665 operating environment, conveying the entry point addresses of three functions
 666 which perform the same operations of their similarly named ioctl counterparts.
 667 The rendering parameters for each entry point are derived from the same
 668 structure passed as the respective ioctl.
 669 See the
 670 .Sx "Console Optional Ioctls"
 671 section of this manpage for an explanation of the specific function each of the
 672 entry points,
 673 .Fn display ,
 674 .Fn copy ,
 675 and
 676 .Fn cursor
 677 are required to implement.
 678 In
 679 addition to performing the prescribed function of their ioctl counterparts, the
 680 standalone vectors operate in a special context and must adhere to a strict set
 681 of rules.
 682 The polled I/O vectors are called directly whenever the system is
 683 quiesced (running in a limited context) and must send output to the display.
 684 Standalone mode describes the state in which the system is running in
 685 single-threaded mode and only one processor is active.
 686 illumos operating
 687 environment services are stopped, along with all other threads on the system,
 688 prior to entering any of the polled I/O interfaces.
 689 The polled I/O vectors are
 690 called when the system is running in a standalone debugger, when executing the
 691 PROM monitor (OBP) or when panicking.
 692 .Pp
 693 The following restrictions must be observed in the polled I/O functions:
 694 .Bl -enum -offset indent
 695 .It
 696 The driver must not allocate memory.
 697 .It
 698 The driver must not wait on mutexes.
 699 .It
 700 The driver must not wait for interrupts.
 701 .It
 702 The driver must not call any DDI or LDI services.
 703 .It