Ioctl Requests visualio(7I)
NAME
visualio - 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 VISGETIDENTIFIER ioctl is mandatory and must be imple-
mented in device drivers for graphics devices using the
Solaris VISUAL environment. The VISGETIDENTIFIER 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 per-
formance 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 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 are
also known as "Polled I/O" entry points, which operate under
an an explicit set of restrictions, described below.
IOCTLS
VISGETIDENTIFIER 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
. For exam-
ple, the cgsix driver returns SUNWcg6.
VISGETIDENTIFIER takes a
visidentifier structure as its parame-
ter. This structure has the form:
#define VISMAXNAMELEN 128
SunOS 5.11 Last change: 14 Oct 2005 1
Ioctl Requests visualio(7I)
struct visidentifier {
char name[VISMAXNAMELEN];
};
VISGETCURSOR These ioctls fetch and set various cur-
VISETCURSOR sor attributes, using the viscursor
structure.
struct viscursorpos {
short x; /* cursor x coordinate */
short y; /* cursor y coordinate */
};
struct viscursorcmap {
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 VISCURSORSETCURSOR 0x01 /* set cursor */
#define VISCURSORSETPOSITION 0x02 /* set cursor position */
#define VISCURSORSETHOTSPOT 0x04 /* set cursor hot spot */
#define VISCURSORSETCOLORMAP 0x08 /* set cursor colormap */
#define VISCURSORSETSHAPE 0x10 /* set cursor shape */
#define VISCURSORSETAL \
(VISCURSORSETCURSOR VISCURSORSETPOSITION \
VISCURSORSETHOTSPOT VISCURSORSETCOLORMAP \
VISCURSORSETSHAPE)
struct viscursor {
short set; /* what to set */
short enable; /* cursor on/off */
struct viscursorpos pos; /* cursor position */
struct viscursorpos hot; /* cursor hot spot */
struct viscursorcmap cmap; /* color map info */
struct viscursorpos size; /* cursor bitmap size */
char *image; /* cursor image bits */
char *mask; /* cursor mask bits */
};
The viscursorcmap structure should contain pointers to two
elements, specifying the red, green, and blue values for
foreground and background.
SunOS 5.11 Last change: 14 Oct 2005 2
Ioctl Requests visualio(7I)
VISETCURSORPOS These ioctls fetch and move the current
VISMOVECURSOR cursor position, using the viscursorpos
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.
VISPUTCMAP Set or get color map entries.
VISGETCMAP
The argument is a pointer to a viscmap structure, which
contains the following fields:
struct viscmap {
int index;
int count;
uchart *red;
uchart *green;
uchart *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.
VISDEVINIT Initializes the graphics driver as a console
device.
SunOS 5.11 Last change: 14 Oct 2005 3
Ioctl Requests visualio(7I)
The argument is a pointer to a visdevinit structure. The
graphics driver is expected to allocate any local state
information needed to be a console device and fill in this
structure.
struct visdevinit {
int version;
screensizet width;
screensizet height;
screensizet linebytes;
unitt size;
int depth;
short mode;
struct vispolledio *polledio;
vismodechgcbt modechgcb;
struct vismodechgarg *modechgarg;
};
version is the version of this structure and should be set
to VISCONSREV.
width and height are the width and height of the device. If
mode (see below) is VISTEXT then width and height are the
number of characters wide and high of the device. If mode is
VISPIXEL 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 VISPIXEL (data to
be displayed is in bitmap format) or VISTEXT (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
vispolledio 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 when
SunOS 5.11 Last change: 14 Oct 2005 4
Ioctl Requests visualio(7I)
the system is running in standalone mode. These functions
perform identically to the VISCONSDISPLAY, VISCONSCURSOR
and VISCONSCOPY ioctls, but are called directly by the
Solaris operating environment and must operate under a very
strict set of assumptions.
modechgcb 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, modechgarg, and the
address of a visdevinit struct containing the new video
mode information.
modechgarg 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 modechgcb func-
tion when the driver notifies the terminal emulator of a
video mode change.
VISDEVFINI 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.
VISCONSCURSOR 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 visconscursor structure
which contains the following fields:
struct visconscursor {
screenpost row;
screenpost col;
screensizet width;
screensizet height
colort fgcolor;
colort bgcolor;
short action;
};
SunOS 5.11 Last change: 14 Oct 2005 5
Ioctl Requests visualio(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 VISDEVINIT ioctl is set to VISPIXEL, then
col, row, width and height are in pixels. If mode in the
VISDEVINIT ioctl was set to VISTEXT, then col, row, width
and height are in characters.
fgcolor and bgcolor are the foreground and background
color map indexes to use when the action (see below) is set
to VISDISPLAYCURSOR.
action indicates whether to display or hide the cursor. It
is set to either VISHIDECURSOR or VISDISPLAYCURSOR.
VISCONSDISPLAY Display data on the graphics device. The
graphics driver is expected to display
the data contained in the visdisplay
structure at the specified position on
the console.
The visdisplay structure contains the following fields:
struct visdisplay {
screenpost row;
screenpost col;
screensizet width;
screensizet height;
uchart *data;
colort fgcolor;
colort bgcolor;
};
row and col specify at which starting row and column the
date is to be displayed. If mode in the VISDEVINIT ioctl
was set to VISTEXT, row and col are defined to be a char-
acter offset from the starting position of the console dev-
ice. If mode in the VISDEVINIT ioctl was set to VISPIXEL,
row and col are defined to be a pixel offset from the
starting position of the console device.
SunOS 5.11 Last change: 14 Oct 2005 6
Ioctl Requests visualio(7I)
width and height specify the size of the data to be
displayed. If mode in the VISDEVINIT ioctl was set to
VISTEXT, 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 VISDEVINIT ioctl was set to
VISPIXEL, 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 VISDEVINIT ioctl was set to
VISTEXT, data is an array of ASCI 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 the
VISDEVINIT ioctl was set to VISPIXEL, 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 fgcolor and bgcolor fields define the foreground and
background color map indexes to use when displaying the
data. fbcolor is used for "on" pixels and bgcolor is used
for "off" pixels.
VISCONSCOPY 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 viscopy structure which
contains the following fields:
struct viscopy {
screenpost srow;
screenpost scol;
screenpost erow;
screenpost ecol;
screenpost trow;
screenpost tcol;
short direction;
};
srow, scol, erow, and ecol define the source rectangle
of the copy. srow and scol are the upper left corner of
SunOS 5.11 Last change: 14 Oct 2005 7
Ioctl Requests visualio(7I)
the source rectangle. erow and ecol are the lower right
corner of the source rectangle. If mode in the VISDEVINIT
ioctl() was set to VISTEXT, srow, scol, erow, and ecol
are defined to be character offsets from the starting posi-
tion of the console device. If mode in the VISDEVINIT ioctl
was set to VISPIXEL, srow, scol, erow, and ecol are
defined to be pixel offsets from the starting position of
the console device.
trow and tcol define the upper left corner of the destina-
tion rectangle of the copy. The entire rectangle is copied
to this location. If mode in the VISDEVINIT ioctl was set
to VISTEXT, trow, and tcol are defined to be character
offsets from the starting position of the console device.
If mode in the VISDEVINIT ioctl was set to VISPIXEL,
trow, and tcol 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 VISCOPYFORWARD the graphics driver should copy data
from position (srow, scol) in the source rectangle to
position (trow, tcol) in the destination rectangle. If
direction is VISCOPYBACKWARDS the graphics driver should
copy data from position (erow, ecol) in the source rectan-
gle to position (trow](erow-srow), tcol](ecol-scol))
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 exten-
sion is implemented.
struct vispolledio {
struct vispolledioarg *arg;
void (*display)(vispolledioarg *, struct visconsdisplay *);
void (*copy)(vispolledioarg *, struct visconscopy *);
void (*cursor)(vispolledioarg *, struct visconscursor *);
};
The vispolledio structure is passed from the driver to the
Solaris operating environment, conveying the entry point
addresses 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 an
SunOS 5.11 Last change: 14 Oct 2005 8
Ioctl Requests visualio(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 of
rules. 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 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 DI 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 informa-
tion about implementing polled I/O entry points.
SEE ALSO
ioctl(2)
Writing Device Drivers
NOTES
On SPARC systems, compatible drivers supporting the kernel
terminal emulator should export the tem-support DI
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: 14 Oct 2005 9
Ioctl Requests visualio(7I)
tem-support This DI property, set to 1, means driver is
compatible with the console
kernel framebuffer interface.
SunOS 5.11 Last change: 14 Oct 2005 10
|
