1visual_io(7I) Ioctl Requests visual_io(7I)
2
6 visual_io - Solaris VISUAL I/O control operations
7
9 #include <sys/visual_io.h>
10
13 The Solaris VISUAL environment defines a small set of ioctls for con‐
14 trolling graphics and imaging devices.
15 The VIS_GETIDENTIFIER ioctl is mandatory and must be implemented in
18 device drivers for graphics devices using the Solaris VISUAL environ‐
19 ment. The VIS_GETIDENTIFIER ioctl is defined to return a device identi‐
20 fier from the device driver. This identifier must be a uniquely-defined
21 string.
22 There are two additional sets of ioctls. One supports mouse tracking
25 via hardware cursor operations. Use of this set is optional, however,
26 if a graphics device has hardware cursor support and implements these
27 ioctls, the mouse tracking performance is improved. The remaining set
28 supports the device acting as the system console device. Use of this
29 set is optional, but if a graphics device is to be used as the system
30 console device, it must implement these ioctls.
31 The VISUAL environment also defines interfaces for non-ioctl entry
34 points into the driver that the Solaris operating environment calls
35 when it is running in standalone mode (for example, when using a
36 stand-alone debugger, entering the PROM monitor, or when the system
37 panicking). These are also known as "Polled I/O" entry points, which
38 operate under an an explicit set of restrictions, described below.
39
41 VIS_GETIDENTIFIER This ioctl() returns an identifier string to
42 uniquely identify a device used in the Solaris
43 VISUAL environment. This is a mandatory ioctl and
44 must return a unique string. We suggest that the
45 name be formed as <companysymbol><devicetype>. For
46 example, the cgsix driver returns SUNWcg6.
47 VIS_GETIDENTIFIER takes a vis_identifier structure
49 as its parameter. This structure has the form:
50 #define VIS_MAXNAMELEN 128
52 struct vis_identifier {
53 char name[VIS_MAXNAMELEN];
54 };
55 VIS_GETCURSOR These ioctls fetch and set various cursor
59 VIS_SETCURSOR attributes, using the vis_cursor structure.
60 struct vis_cursorpos {
62 short x; /* cursor x coordinate */
63 short y; /* cursor y coordinate */
64 };
65 struct vis_cursorcmap {
67 int version; /* version */
68 int reserved;
69 unsigned char *red; /* red color map elements */
70 unsigned char *green;/* green color map elements */
71 unsigned char *blue; /* blue color map elements */
72 };
73 #define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */
75 #define VIS_CURSOR_SETPOSITION 0x02 /* set cursor position */
76 #define VIS_CURSOR_SETHOTSPOT 0x04 /* set cursor hot spot */
77 #define VIS_CURSOR_SETCOLORMAP 0x08 /* set cursor colormap */
78 #define VIS_CURSOR_SETSHAPE 0x10 /* set cursor shape */
79 #define VIS_CURSOR_SETALL \
80 (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \
81 VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \
82 VIS_CURSOR_SETSHAPE)
83 struct vis_cursor {
85 short set; /* what to set */
86 short enable; /* cursor on/off */
87 struct vis_cursorpos pos; /* cursor position */
88 struct vis_cursorpos hot; /* cursor hot spot */
89 struct vis_cursorcmap cmap; /* color map info */
90 struct vis_cursorpos size; /* cursor bitmap size */
91 char *image; /* cursor image bits */
92 char *mask; /* cursor mask bits */
93 };
94 The vis_cursorcmap structure should contain pointers to two elements,
99 specifying the red, green, and blue values for foreground and back‐
100 ground.
101 VIS_SETCURSORPOS These ioctls fetch and move the current cursor
103 VIS_MOVECURSOR position, using the vis_cursorpos structure.
104 Console Optional Ioctls
107 The following ioctl sets are used by graphics drivers that are part of
108 the system console device. All of the ioctls must be implemented to be
109 a console device. In addition, if the system does not have a prom or
110 the prom goes away during boot, the special standalone ioctls (listed
111 below) must also be implemented.
112 The coordinate system for the console device places 0,0 at the upper
115 left corner of the device, with rows increasing toward the bottom of
116 the device and columns increasing from left to right.
117 VIS_PUTCMAP Set or get color map entries.
119 VIS_GETCMAP
120 The argument is a pointer to a vis_cmap structure, which contains the
123 following fields:
124 struct vis_cmap {
126 int index;
127 int count;
128 uchar_t *red;
129 uchar_t *green;
130 uchar_t *blue;
131 }
132 index is the starting index in the color map where you want to start
136 setting or getting color map entries.
137 count is the number of color map entries to set or get. It also is the
140 size of the red, green, and blue color arrays.
141 *red, *green, and *blue are pointers to unsigned character arrays which
144 contain the color map info to set or where the color map info is placed
145 on a get.
146 VIS_DEVINIT Initializes the graphics driver as a console device.
148 The argument is a pointer to a vis_devinit structure. The graphics
152 driver is expected to allocate any local state information needed to be
153 a console device and fill in this structure.
154 struct vis_devinit {
156 int version;
157 screen_size_t width;
158 screen_size_t height;
159 screen_size_t linebytes;
160 unit_t size;
161 int depth;
162 short mode;
163 struct vis_polledio *polledio;
164 vis_modechg_cb_t modechg_cb;
165 struct vis_modechg_arg *modechg_arg;
166 };
167 version is the version of this structure and should be set to
171 VIS_CONS_REV.
172 width and height are the width and height of the device. If mode (see
175 below) is VIS_TEXT then width and height are the number of characters
176 wide and high of the device. If mode is VIS_PIXEL then width and height
177 are the number of pixels wide and high of the device.
178 linebytes is the number of bytes per line of the device.
181 size is the total size of the device in pixels.
184 depth is the pixel depth in device bits. Currently supported depths
187 are: 1, 4, 8 and 24.
188 mode is the mode of the device. Either VIS_PIXEL (data to be displayed
191 is in bitmap format) or VIS_TEXT (data to be displayed is in ascii for‐
192 mat).
193 polledio is used to pass the address of the structure containing the
196 standalone mode polled I/O entry points to the device driver back to
197 the terminal emulator. The vis_polledio interfaces are described in the
198 Console Standalone Entry Points section of this manpage. These entry
199 points are where the operating system enters the driver when the system
200 is running in standalone mode. These functions perform identically to
201 the VIS_CONSDISPLAY, VIS_CONSCURSOR and VIS_CONSCOPY ioctls, but are
202 called directly by the Solaris operating environment and must operate
203 under a very strict set of assumptions.
204 modechg_cb is a callback function passed from the terminal emulator to
207 the framebuffer driver which the frame-buffer driver must call whenever
208 a video mode change event occurs that changes the screen height, width
209 or depth. The callback takes two arguments, an opaque handle, mod‐
210 echg_arg, and the address of a vis_devinit struct containing the new
211 video mode information.
212 modechg_arg is an opaque handle passed from the terminal emulator to
215 the driver, which the driver must pass back to the terminal emulator as
216 an argument to the modechg_cb function when the driver notifies the
217 terminal emulator of a video mode change.
218 VIS_DEVFINI Tells the graphics driver that it is no longer the
220 system console device. There is no argument to this
221 ioctl. The driver is expected to free any locally
222 kept state information related to the console.
223 VIS_CONSCURSOR Describes the size and placement of the cursor on the
226 screen. The graphics driver is expected to display or
227 hide the cursor at the indicated position.
228 The argument is a pointer to a vis_conscursor structure which contains
232 the following fields:
233 struct vis_conscursor {
235 screen_pos_t row;
236 screen_pos_t col;
237 screen_size_t width;
238 screen_size_t height
239 color_t fg_color;
240 color_t bg_color;
241 short action;
242 };
243 row and col are the first row and column (upper left corner of the cur‐
247 sor).
248 width and height are the width and height of the cursor.
251 If mode in the VIS_DEVINIT ioctl is set to VIS_PIXEL, then col, row,
254 width and height are in pixels. If mode in the VIS_DEVINIT ioctl was
255 set to VIS_TEXT, then col, row, width and height are in characters.
256 fg_color and bg_color are the foreground and background color map
259 indexes to use when the action (see below) is set to VIS_DISPLAY_CUR‐
260 SOR.
261 action indicates whether to display or hide the cursor. It is set to
264 either VIS_HIDE_CURSOR or VIS_DISPLAY_CURSOR.
265 VIS_CONSDISPLAY Display data on the graphics device. The graphics
267 driver is expected to display the data contained in
268 the vis_display structure at the specified position
269 on the console.
270 The vis_display structure contains the following fields:
274 struct vis_display {
276 screen_pos_t row;
277 screen_pos_t col;
278 screen_size_t width;
279 screen_size_t height;
280 uchar_t *data;
281 color_t fg_color;
282 color_t bg_color;
283 };
284 row and col specify at which starting row and column the date is to be
288 displayed. If mode in the VIS_DEVINIT ioctl was set to VIS_TEXT, row
289 and col are defined to be a character offset from the starting posi‐
290 tion of the console device. If mode in the VIS_DEVINIT ioctl was set to
291 VIS_PIXEL, row and col are defined to be a pixel offset from the
292 starting position of the console device.
293 width and height specify the size of the data to be displayed. If mode
296 in the VIS_DEVINIT ioctl was set to VIS_TEXT, width and height define
297 the size of data as a rectangle that is width characters wide and
298 height characters high. If mode in the VIS_DEVINIT ioctl was set to
299 VIS_PIXEL, width and height define the size of data as a rectangle
300 that is width pixels wide and height pixels high.
301 *data is a pointer to the data to be displayed on the console device.
304 If mode in the VIS_DEVINIT ioctl was set to VIS_TEXT, data is an array
305 of ASCII characters to be displayed on the console device. The driver
306 must break these characters up appropriately and display it in the
307 retangle defined by row, col, width, and height. If mode in the
308 VIS_DEVINIT ioctl was set to VIS_PIXEL, data is an array of bitmap data
309 to be displayed on the console device. The driver must break this data
310 up appropriately and display it in the retangle defined by row, col,
311 width, and height.
312 The fg_color and bg_color fields define the foreground and background
315 color map indexes to use when displaying the data. fb_color is used for
316 "on" pixels and bg_color is used for "off" pixels.
317 VIS_CONSCOPY Copy data from one location on the device to another.
319 The driver is expected to copy the specified data. The
320 source data should not be modified. Any modifications
321 to the source data should be as a side effect of the
322 copy destination overlapping the copy source.
323 The argument is a pointer to a vis_copy structure which contains the
327 following fields:
328 struct vis_copy {
330 screen_pos_t s_row;
331 screen_pos_t s_col;
332 screen_pos_t e_row;
333 screen_pos_t e_col;
334 screen_pos_t t_row;
335 screen_pos_t t_col;
336 short direction;
337 };
338 s_row, s_col, e_row, and e_col define the source rectangle of the copy.
342 s_row and s_col are the upper left corner of the source rectangle.
343 e_row and e_col are the lower right corner of the source rectangle. If
344 mode in the VIS_DEVINIT ioctl() was set to VIS_TEXT, s_row, s_col,
345 e_row, and e_col are defined to be character offsets from the starting
346 position of the console device. If mode in the VIS_DEVINIT ioctl was
347 set to VIS_PIXEL, s_row, s_col, e_row, and e_col are defined to be
348 pixel offsets from the starting position of the console device.
349 t_row and t_col define the upper left corner of the destination rectan‐
352 gle of the copy. The entire rectangle is copied to this location. If
353 mode in the VIS_DEVINIT ioctl was set to VIS_TEXT, t_row, and t_col are
354 defined to be character offsets from the starting position of the con‐
355 sole device. If mode in the VIS_DEVINIT ioctl was set to VIS_PIXEL,
356 t_row, and t_col are defined to be pixel offsets from the starting
357 position of the console device.
358 direction specifies which way to do the copy. If direction is
361 VIS_COPY_FORWARD the graphics driver should copy data from position
362 (s_row, s_col) in the source rectangle to position (t_row, t_col) in
363 the destination rectangle. If direction is VIS_COPY_BACKWARDS the
364 graphics driver should copy data from position (e_row, e_col) in the
365 source rectangle to position (t_row+(e_row-s_row), t_col+(e_col-s_col))
366 in the destination rectangle.
367 Console Standalone Entry Points (Polled I/O Interfaces)
369 Console standalone entry points are necessary only if the driver is
370 implementing console-compatible extensions. All console vectored stand‐
371 alone entry points must be implemented along with all console-related
372 ioctls if the console extension is implemented.
373 struct vis_polledio {
375 struct vis_polledio_arg *arg;
376 void (*display)(vis_polledio_arg *, struct vis_consdisplay *);
377 void (*copy)(vis_polledio_arg *, struct vis_conscopy *);
378 void (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
379 };
380 The vis_polledio structure is passed from the driver to the Solaris
384 operating environment, conveying the entry point addresses of three
385 functions which perform the same operations of their similarly named
386 ioctl counterparts. The rendering parameters for each entry point are
387 derived from the same structure passed as the respective ioctl. See the
388 Console Optional Ioctls section of this manpage for an explanation of
389 the specific function each of the entry points, display(), copy() and
390 cursor() are required to implement. In addition to performing the pre‐
391 scribed function of their ioctl counterparts, the standalone vectors
392 operate in a special context and must adhere to a strict set of rules.
393 The polled I/O vectors are called directly whenever the system is
394 quisced (running in a limited context) and must send output to the dis‐
395 play. Standalone mode describes the state in which the system is run‐
396 ning in single-threaded mode and only one processor is active. Solaris
397 operating environment services are stopped, along with all other
398 threads on the system, prior to entering any of the polled I/O inter‐
399 faces. The polled I/O vectors are called when the system is running in
400 a standalone debugger, when executing the PROM monitor (OBP) or when
401 panicking.
402 The following restrictions must be observed in the polled I/O func‐
405 tions:
406 1. The driver must not allocate memory.
408 2. The driver must not wait on mutexes.
410 3. The driver must not wait for interrupts.
412 4. The driver must not call any DDI or LDI services.
414 5. The driver must not call any system services.
416 The system is single-threaded when calling these functions, meaning
419 that all other threads are effectively halted. Single-threading makes
420 mutexes (which cannot be held) easier to deal with, so long as the
421 driver does not disturb any shared state. See Writing Device Drivers
422 for more information about implementing polled I/O entry points.
423
425 ioctl(2)
426 Writing Device Drivers
429
431 On SPARC systems, compatible drivers supporting the kernel terminal
432 emulator should export the tem-support DDI property.tem-support indi‐
433 cates that the driver supports the kernel terminal emulator. By export‐
434 ing tem-support it's possible to avoid premature handling of an incom‐
435 patible driver.
436 tem-support This DDI property, set to 1, means driver is compatible
438 with the console kernel
439 framebuffer interface.
440SunOS 5.11 14 Oct 2005 visual_io(7I)