Tribblix: manual page: visual

VISUAL_IO(4I) Ioctl Requests VISUAL_IO(4I)

NAME

visual_io - illumos VISUAL I/O control operations

SYNOPSIS

#include <sys/visual_io.h>

DESCRIPTION

The illumos VISUAL environment defines a small set of ioctls for
controlling graphics and imaging devices.

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.

IOCTLS

VIS_GETIDENTIFIER This ioctl(2) returns an identifier string to
uniquely identify a device used in the illumos
VISUAL environment. This is a mandatory ioctl and
must return a unique string. We suggest that the
name be formed as <companysymbol><devicetype>.

VIS_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_GETCURSOR
VIS_SETCURSOR These ioctls fetch and set various cursor
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;
/* 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 cursor 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_SETCURSORPOS
VIS_MOVECURSOR These ioctls fetch and move the current cursor
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
VIS_GETCMAP Set or get color map entries.

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.

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 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_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;
};

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_CONSDISPLAY Display data on the graphics device. The graphics
driver is expected to display the 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
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_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 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.

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 implemented along with all console-
related ioctls if the console extension 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 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:

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 any shared state. See Writing Device Drivers
for more information about implementing polled I/O entry points.

NOTES