visual_io(7I) Ioctl Requests visual_io(7I)
NAME
visual_io - Solaris VISUAL I/O control operations
SYNOPSIS
#include <sys/visual_io.h>
DESCRIPTION
The Solaris VISUAL environment defines a small set of ioctl()s for controlling graphics and imaging devices.
One ioctl(), VIS_GETIDENTIFIER, is mandatory, and must be implemented in device drivers for graphics devices using the Solaris VISUAL envi-
ronment. The VIS_GETIDENTIFIER ioctl() is defined to return a device identifier from the device driver. This identifier must be a
uniquely-defined string.
Two other sets of ioctl()ls exist. One set supports mouse tracking via hardware cursor operations. These are optional, but if a graphics
device has hardware cursor support and implements these ioctl()s the mouse tracking performance will be improved.
The other set supports the device being the system console device. These are optional, but if a graphics device is to be used as the system
console device, it must implement these ioctl()s.
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 <companysymbol><devicetype>. For example, the cgsix
driver returns SUNWcg6.
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 ioctl()s 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;
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
These ioctl()s fetch and move the current cursor position, using the vis_cursorpos structure.
Console optional ioctls
The following set of ioctl()s are used by graphics drivers that are to be part of the system console device. All of the ioctl()s 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 stand-
alone ioctl()ls (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;
};
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 char-
acters 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 it bits of the device. Currently supported depths are: 1, 4, 8 and 24.
mode is the mode of the device. One of VIS_PIXEL (data to be displayed is in bitmap format) or VIS_TEXT (data to be displayed is in
ascii format).
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_CONS_MODE_CHANGE
Tells the graphics driver that the framebuffer resolution has been reset by the user program. The framebuffer is expected to reload any
state information that it is keeping.
The argument to this ioctl() is private to the user program and the device driver. That is, the user program may wish to directly
change the framebuffer mode and then just use this ioctl() to notify the graphics driver or it may pass mode change information along
to the graphics driver and have it do the mode change.
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 {
int version;
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;
};
version is set to VIS_CURSOR_VERSION and should be check by the driver. If the version does not match, the driver should reject this
ioctl().
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() was 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_DIS-
PLAY_CURSOR.
action is whether to display or hide the cursor. It is set to one of: 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 {
int version;
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;
};
version is set to VIS_DISPLAY_VERSION and should be check by the driver. If the version does not match, the driver should reject this
ioctl().
row and col specify the starting row and column to display the data at. 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 a 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 dis-
play it in the retangle 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 {
int version
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;
};
version is set to VIS_COPY_VERSION and should be check by the driver. If the version does not match, the driver should reject this
ioctl().
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 rectan-
gle. 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 posi-
tion 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.
The next set of console ioctl()s are used on systems which don't have a prom. Normally, standalones use the system prom to display charac-
ters on the system console device. On systems without a prom, standalones use the kernel drivers to display characters on the system con-
sole device. When implementing these ioctl()s, you can not use any of the locking primitives or the copy routines from the DDI. Further-
more other DDI services may or may not work and should be avoided.
VIS_STAND_CONSCURSOR
Should perform the same tasks as VIS_CONSCURSOR except that it must follow the above restrictions. It takes in as an argument a
vis_cursor structure.
VIS_STAND_CONSDISPLAY
Should perform the same tasks as VIS_CONSDISPLAY except that it must follow the above restrictions. It takes in as an argument a
vis_display structure.
VIS_STAND_CONSCOPY
Should perform the same tasks as VIS_CONSCOPY except that it must follow the above restrictions. It takes in as an argument a vis_copy
structure.
SEE ALSO
ioctl(2)
SunOS 5.10 4 Mar 2004 visual_io(7I)