| VISUAL_IO(7I) | Ioctl Requests | VISUAL_IO(7I) |
visual_io —
#include <sys/visual_io.h>
The VIS_GETIDENTIFIER ioctl is mandatory
and must be implemented in device drivers for graphics devices using the
illumos VISUAL environment. The VIS_GETIDENTIFIER
ioctl is defined to return a device identifier from the device driver. 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 cursor support and implements these ioctls, the mouse tracking performance is improved. The remaining set supports the device acting as the system console device. Use of this set is optional, but if a graphics device is to be used as the system console device, it must implement these ioctls.
The VISUAL environment also defines interfaces for non-ioctl entry points into the driver that the illumos 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 are also known as “Polled I/O” entry points, which operate under an explicit set of restrictions, described below.
VIS_GETIDENTIFIERVIS_GETIDENTIFIER takes a
vis_identifier structure as its parameter. This
structure has the form:
#define VIS_MAXNAMELEN 128
struct vis_identifier {
char name[VIS_MAXNAMELEN];
};
VIS_GETCURSORVIS_SETCURSOR
struct vis_cursorpos {
short x; /* cursor x coordinate */
short y; /* cursor y coordinate */
};
struct vis_cursorcmap {
int version; /* version */
int reserved;
/* red color map elements */
unsigned char *red;
/* green color map elements */
unsigned char *green;
/* blue color map elements */
unsigned char *blue;
};
#define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */
/* set cursor position */
#define VIS_CURSOR_SETPOSITION 0x02
/* set cursur hot spot */
#define VIS_CURSOR_SETHOTSPOT 0x04
/* set cursor colormap */
#define VIS_CURSOR_SETCOLORMAP 0x08
/* set cursor shape */
#define VIS_CURSOR_SETSHAPE 0x10
#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 */
/* cursor bitmap size */
struct vis_cursorpos 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_SETCURSORPOSVIS_MOVECURSORThe 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_PUTCMAPVIS_GETCMAPThe 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_DEVINITThe 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 set to VIS_CONS_REV.
width and height
are the width and height of the device. If mode
(see below) is VIS_TEXT then
width and height are the
number of characters wide and high of the device. If
mode is VIS_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 containing 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 Standalone Entry Points section of this manpage. These entry
points are where the operating system enters the driver when the system
is running in standalone mode. These functions perform identically to
the VIS_CONSDISPLAY,
VIS_CONSCURSOR, and
VIS_CONSCOPY ioctls, but are called directly by
the illumos 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 callback takes 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 to the terminal emulator as an argument to the modechg_cb function when the driver notifies the terminal emulator of a video mode change.
VIS_DEVFINIVIS_CONSCURSORThe 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;
};
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 the VIS_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
set to VIS_DISPLAY_CURSOR.
action indicates whether to display or
hide the cursor. It is set to either
VIS_HIDE_CURSOR or
VIS_DISPLAY_CURSOR.
VIS_CONSDISPLAYThe 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 the date is to be displayed. If
mode in the VIS_DEVINIT
ioctl was set to VIS_TEXT,
row and col are defined to
be a character offset from the starting position of the console device.
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.
width and height
specify the size of the data to be displayed. If
mode in the VIS_DEVINIT
ioctl was set to VIS_TEXT,
width and height define the
size of data as rectangle that is
width characters wide and
height characters 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 console 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 rectangle defined by row,
col, width, and
height. If mode in the
VIS_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 the data. fb_color is used for “on” pixels and bg_color is used for “off” pixels.
VIS_CONSCOPYThe 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 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 position 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 destination rectangle of the copy.
The entire rectangle is copied to 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 direction is 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 rectangle to position
(t_row+(e_row-s_row),
t_col+(e_col-s_col))
in the destination rectangle.
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 illumos operating environment, conveying the entry point
addresses of three functions which perform the same operations 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 an 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 of rules. The polled I/O vectors are
called directly whenever the system is quiesced (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. illumos operating environment services are stopped,
along with all other threads on the system, prior to entering any of the
polled I/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:
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 any shared state. See Writing Device Drivers for more information about implementing polled I/O entry points.
Writing Device Drivers.
| February 17, 2020 | illumos |