Ioctl Requests visual_io(7I)
NAME
visual_io - Solaris VISUAL I/O control operations
SYNOPSIS
#include
DESCRIPTION
The Solaris VISUAL environment defines a small set of ioctls for controlling graphics and imaging devices.The VIS_GETIDENTIFIER ioctl is mandatory and must be imple-
mented in device drivers for graphics devices using theSolaris VISUAL environment. The VIS_GETIDENTIFIER ioctl is
defined to return a device identifier from the devicedriver. This identifier must be a uniquely-defined string.
There are two additional sets of ioctls. One supports mouse tracking via hardware cursor operations. Use of this set is optional, however, if a graphics device has hardware cursorsupport and implements these ioctls, the mouse tracking per-
formance is improved. The remaining set supports the device acting as the system console device. Use of this set isoptional, but if a graphics device is to be used as the sys-
tem console device, it must implement these ioctls.The VISUAL environment also defines interfaces for non-ioctl
entry points into the driver that the Solaris operating environment calls when it is running in standalone mode(for example, when using a stand-alone debugger, entering
the PROM monitor, or when the system panicking). These arealso known as Polled I/O entry points, which operate under an explicit set of restrictions, described below. IOCTLS
VIS_GETIDENTIFIER This ioctl() returns an identifier
string to uniquely identify a device used in the Solaris VISUAL environment. This is a mandatory ioctl and must return a unique string. We suggest that the name be formed as. VIS_GETIDENTIFIER takes a
vis_identifier structure as its parame-
ter. This structure has the form:#define VIS_MAXNAMELEN 128
struct vis_identifier {
SunOS 5.11 Last change: 28 Oct 2009 1
Ioctl Requests visual_io(7I)
char name[VIS_MAXNAMELEN];
};VIS_GETCURSOR These ioctls fetch and set various cur-
VIS_SETCURSOR sor attributes, using the vis_cursor
structure.struct vis_cursorpos {
short x; /* cursor x coordinate */ short y; /* cursor y coordinate */ };struct vis_cursorcmap {
int version; /* version */ int reserved; unsigned char *red; /* red color map elements */ unsigned char *green;/* green color map elements */ unsigned char *blue; /* blue color map elements */ };#define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */
#define VIS_CURSOR_SETPOSITION 0x02 /* set cursor position */
#define VIS_CURSOR_SETHOTSPOT 0x04 /* set cursor hot spot */
#define VIS_CURSOR_SETCOLORMAP 0x08 /* set cursor colormap */
#define VIS_CURSOR_SETSHAPE 0x10 /* set cursor shape */
#define VIS_CURSOR_SETALL \
(VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \
VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \
VIS_CURSOR_SETSHAPE)
struct vis_cursor {
short set; /* what to set */ short enable; /* cursor on/off */struct vis_cursorpos pos; /* cursor position */
struct vis_cursorpos hot; /* cursor hot spot */
struct vis_cursorcmap cmap; /* color map info */
struct vis_cursorpos size; /* cursor bitmap size */
char *image; /* cursor image bits */ char *mask; /* cursor mask bits */ };The vis_cursorcmap structure should contain pointers to two
elements, specifying the red, green, and blue values for foreground and background.VIS_SETCURSORPOS
VIS_MOVECURSOR
SunOS 5.11 Last change: 28 Oct 2009 2
Ioctl Requests visual_io(7I)
These ioctls fetch and move the currentcursor position, using the vis_cursorpos
structure. Console Optional Ioctls The following ioctl sets are used by graphics drivers that are part of the system console device. All of the ioctls must be implemented to be a console device. In addition, if the system does not have a prom or the prom goes away during boot, the special standalone ioctls (listed below) must also be implemented. The coordinate system for the console device places 0,0 at the upper left corner of the device, with rows increasing toward the bottom of the device and columns increasing from left to right.VIS_PUTCMAP Set or get color map entries.
VIS_GETCMAP
The argument is a pointer to a vis_cmap structure, which
contains the following fields:struct vis_cmap {
int index; int count;uchar_t *red;
uchar_t *green;
uchar_t *blue;
} index is the starting index in the color map where you want to start setting or getting color map entries. count is the number of color map entries to set or get. It also is the size of the red, green, and blue color arrays. *red, *green, and *blue are pointers to unsigned character arrays which contain the color map info to set or where the color map info is placed on a get.VIS_DEVINIT Initializes the graphics driver as a console
device.SunOS 5.11 Last change: 28 Oct 2009 3
Ioctl Requests visual_io(7I)
The argument is a pointer to a vis_devinit structure. The
graphics driver is expected to allocate any local state information needed to be a console device and fill in this structure.struct vis_devinit {
int version;screen_size_t width;
screen_size_t height;
screen_size_t linebytes;
unit_t size;
int depth; short mode;struct vis_polledio *polledio;
vis_modechg_cb_t modechg_cb;
struct vis_modechg_arg *modechg_arg;
}; version is the version of this structure and should be setto VIS_CONS_REV.
width and height are the width and height of the device. Ifmode (see below) is VIS_TEXT then width and height are the
number of characters wide and high of the device. If mode isVIS_PIXEL then width and height are the number of pixels
wide and high of the device. linebytes is the number of bytes per line of the device. size is the total size of the device in pixels. depth is the pixel depth in device bits. Currently supported depths are: 1, 4, 8 and 24.mode is the mode of the device. Either VIS_PIXEL (data to
be displayed is in bitmap format) or VIS_TEXT (data to be
displayed is in ascii format).polledio is used to pass the address of the structure con-
taining the standalone mode polled I/O entry points to the device driver back to the terminal emulator. The
vis_polledio interfaces are described in the Console Stan-
dalone Entry Points section of this manpage. These entry points are where the operating system enters the driver whenSunOS 5.11 Last change: 28 Oct 2009 4
Ioctl Requests visual_io(7I)
the system is running in standalone mode. These functionsperform identically to the VIS_CONSDISPLAY, VIS_CONSCURSOR
and VIS_CONSCOPY ioctls, but are called directly by the
Solaris operating environment and must operate under a very strict set of assumptions.modechg_cb is a callback function passed from the terminal
emulator to the framebuffer driver which the frame-buffer
driver must call whenever a video mode change event occurs that changes the screen height, width or depth. The callbacktakes two arguments, an opaque handle, modechg_arg, and the
address of a vis_devinit struct containing the new video
mode information.modechg_arg is an opaque handle passed from the terminal
emulator to the driver, which the driver must pass back tothe terminal emulator as an argument to the modechg_cb func-
tion when the driver notifies the terminal emulator of a video mode change.VIS_DEVFINI Tells the graphics driver that it is no
longer the system console device. There is no argument to this ioctl. The driver is expected to free any locally kept state information related to the console.VIS_CONSCURSOR Describes the size and placement of the
cursor on the screen. The graphics driver is expected to display or hide the cursor at the indicated position.The argument is a pointer to a vis_conscursor structure
which contains the following fields:struct vis_conscursor {
screen_pos_t row;
screen_pos_t col;
screen_size_t width;
screen_size_t height
color_t fg_color;
color_t bg_color;
short action; };SunOS 5.11 Last change: 28 Oct 2009 5
Ioctl Requests visual_io(7I)
row and col are the first row and column (upper left corner of the cursor). width and height are the width and height of the cursor.If mode in the VIS_DEVINIT ioctl is set to VIS_PIXEL, then
col, row, width and height are in pixels. If mode in theVIS_DEVINIT ioctl was set to VIS_TEXT, then col, row, width
and height are in characters.fg_color and bg_color are the foreground and background
color map indexes to use when the action (see below) is setto VIS_DISPLAY_CURSOR.
action indicates whether to display or hide the cursor. Itis set to either VIS_HIDE_CURSOR or VIS_DISPLAY_CURSOR.
VIS_CONSDISPLAY Display data on the graphics device. The
graphics driver is expected to displaythe data contained in the vis_display
structure at the specified position on the console.The vis_display structure contains the following fields:
struct vis_display {
screen_pos_t row;
screen_pos_t col;
screen_size_t width;
screen_size_t height;
uchar_t *data;
color_t fg_color;
color_t bg_color;
}; row and col specify at which starting row and column thedate is to be displayed. If mode in the VIS_DEVINIT ioctl
was set to VIS_TEXT, row and col are defined to be a char-
acter offset from the starting position of the console dev-
ice. If mode in the VIS_DEVINIT ioctl was set to VIS_PIXEL,
row and col are defined to be a pixel offset from the starting position of the console device.SunOS 5.11 Last change: 28 Oct 2009 6
Ioctl Requests visual_io(7I)
width and height specify the size of the data to bedisplayed. If mode in the VIS_DEVINIT ioctl was set to
VIS_TEXT, width and height define the size of data as a
rectangle that is width characters wide and height charac-
ters high. If mode in the VIS_DEVINIT ioctl was set to
VIS_PIXEL, width and height define the size of data as a
rectangle that is width pixels wide and height pixels high.*data is a pointer to the data to be displayed on the con-
sole device. If mode in the VIS_DEVINIT ioctl was set to
VIS_TEXT, data is an array of ASCII characters to be
displayed on the console device. The driver must break these characters up appropriately and display it in the retangle defined by row, col, width, and height. If mode in theVIS_DEVINIT ioctl was set to VIS_PIXEL, data is an array of
bitmap data to be displayed on the console device. The driver must break this data up appropriately and display it in the retangle defined by row, col, width, and height.The fg_color and bg_color fields define the foreground and
background color map indexes to use when displaying thedata. fb_color is used for on pixels and bg_color is used
for off pixels.VIS_CONSCOPY Copy data from one location on the device to
another. The driver is expected to copy the specified data. The source data should not be modified. Any modifications to the source data should be as a side effect of the copy destination overlapping the copy source.The argument is a pointer to a vis_copy structure which
contains the following fields:struct vis_copy {
screen_pos_t s_row;
screen_pos_t s_col;
screen_pos_t e_row;
screen_pos_t e_col;
screen_pos_t t_row;
screen_pos_t t_col;
short direction; };s_row, s_col, e_row, and e_col define the source rectangle
of the copy. s_row and s_col are the upper left corner of
SunOS 5.11 Last change: 28 Oct 2009 7
Ioctl Requests visual_io(7I)
the source rectangle. e_row and e_col are the lower right
corner of the source rectangle. If mode in the VIS_DEVINIT
ioctl() was set to VIS_TEXT, s_row, s_col, e_row, and e_col
are defined to be character offsets from the starting posi-
tion of the console device. If mode in the VIS_DEVINIT ioctl
was set to VIS_PIXEL, s_row, s_col, e_row, and e_col are
defined to be pixel offsets from the starting position of the console device.t_row and t_col define the upper left corner of the destina-
tion rectangle of the copy. The entire rectangle is copiedto this location. If mode in the VIS_DEVINIT ioctl was set
to VIS_TEXT, t_row, and t_col are defined to be character
offsets from the starting position of the console device.If mode in the VIS_DEVINIT ioctl was set to VIS_PIXEL,
t_row, and t_col are defined to be pixel offsets from the
starting position of the console device. direction specifies which way to do the copy. If directionis VIS_COPY_FORWARD the graphics driver should copy data
from position (s_row, s_col) in the source rectangle to
position (t_row, t_col) in the destination rectangle. If
direction is VIS_COPY_BACKWARDS the graphics driver should
copy data from position (e_row, e_col) in the source rectan-
gle to position (t_row+(e_row-s_row), t_col+(e_col-s_col))
in the destination rectangle.Console Standalone Entry Points (Polled I/O Interfaces) Console standalone entry points are necessary only if the
driver is implementing console-compatible extensions. All
console vectored standalone entry points must be implementedalong with all console-related ioctls if the console exten-
sion is implemented.struct vis_polledio {
struct vis_polledio_arg *arg;
void (*display)(vis_polledio_arg *, struct vis_consdisplay *);
void (*copy)(vis_polledio_arg *, struct vis_conscopy *);
void (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
};The vis_polledio structure is passed from the driver to the
Solaris operating environment, conveying the entry pointaddresses of three functions which perform the same opera-
tions of their similarly named ioctl counterparts. The rendering parameters for each entry point are derived from the same structure passed as the respective ioctl. See the Console Optional Ioctls section of this manpage for anSunOS 5.11 Last change: 28 Oct 2009 8
Ioctl Requests visual_io(7I)
explanation of the specific function each of the entry points, display(), copy() and cursor() are required to implement. In addition to performing the prescribed function of their ioctl counterparts, the standalone vectors operate in a special context and must adhere to a strict set ofrules. The polled I/O vectors are called directly whenever the system is quisced (running in a limited context) and must send output to the display. Standalone mode describes
the state in which the system is running in single-threaded
mode and only one processor is active. Solaris operating environment services are stopped, along with all other threads on the system, prior to entering any of the polledI/O interfaces. The polled I/O vectors are called when the system is running in a standalone debugger, when executing the PROM monitor (OBP) or when panicking. The following restrictions must be observed in the polled
I/O functions: 1. The driver must not allocate memory. 2. The driver must not wait on mutexes. 3. The driver must not wait for interrupts. 4. The driver must not call any DDI or LDI services. 5. The driver must not call any system services.
The system is single-threaded when calling these functions,
meaning that all other threads are effectively halted.Single-threading makes mutexes (which cannot be held) easier
to deal with, so long as the driver does not disturb anyshared state. See Writing Device Drivers for more informa-
tion about implementing polled I/O entry points.
SEE ALSO
ioctl(2) Writing Device Drivers NOTES On SPARC systems, compatible drivers supporting the kernelterminal emulator should export the tem-support DDI
property.tem-support indicates that the driver supports the
kernel terminal emulator. By exporting tem-support it's pos-
sible to avoid premature handling of an incompatible driver.SunOS 5.11 Last change: 28 Oct 2009 9
Ioctl Requests visual_io(7I)
tem-support This DDI property, set to 1, means driver is
compatible with the console kernel framebuffer interface.SunOS 5.11 Last change: 28 Oct 2009 10