1 '\" te
2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH VISUAL_IO 7I "Oct 14, 2005"
7 .SH NAME
8 visual_io \- Solaris VISUAL I/O control operations
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include <sys/visual_io.h>\fR
13 .fi
14
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The Solaris VISUAL environment defines a small set of ioctls for controlling
19 graphics and imaging devices.
20 .sp
21 .LP
22 The \fBVIS_GETIDENTIFIER\fR ioctl is mandatory and must be implemented in
23 device drivers for graphics devices using the Solaris VISUAL environment. The
24 \fBVIS_GETIDENTIFIER\fR ioctl is defined to return a device identifier from the
25 device driver. This identifier must be a uniquely-defined string.
26 .sp
27 .LP
28 There are two additional sets of ioctls. One supports mouse tracking via
29 hardware cursor operations. Use of this set is optional, however, if a graphics
30 device has hardware cursor support and implements these ioctls, the mouse
31 tracking performance is improved. The remaining set supports the device acting
32 as the system console device. Use of this set is optional, but if a graphics
33 device is to be used as the system console device, it must implement these
34 ioctls.
35 .sp
36 .LP
37 The VISUAL environment also defines interfaces for non-ioctl entry points into
38 the driver that the Solaris operating environment calls when it is running in
39 standalone mode (for example, when using a stand-alone debugger, entering
40 the PROM monitor, or when the system panicking). These are also known as
41 "Polled I/O" entry points, which operate under an an explicit set of
42 restrictions, described below.
43 .SH IOCTLS
44 .sp
45 .ne 2
46 .na
47 \fB\fBVIS_GETIDENTIFIER\fR\fR
48 .ad
49 .RS 21n
50 This \fBioctl()\fR returns an identifier string to uniquely identify a device
51 used in the Solaris VISUAL environment. This is a mandatory ioctl and must
52 return a unique string. We suggest that the name be formed as
53 \fI<companysymbol><devicetype>\fR\&. For example, the \fBcgsix\fR driver
54 returns \fBSUNWcg6\fR.
55 .sp
56 \fBVIS_GETIDENTIFIER\fR takes a \fBvis_identifier\fR structure as its
57 parameter. This structure has the form:
58 .sp
59 .in +2
60 .nf
61 #define VIS_MAXNAMELEN 128
62 struct vis_identifier {
63 char name[VIS_MAXNAMELEN];
64 };
65 .fi
66 .in -2
67
68 .RE
69
70 .sp
71 .ne 2
72 .na
73 \fB\fBVIS_GETCURSOR\fR\fR
74 .ad
75 .br
76 .na
77 \fB\fBVIS_SETCURSOR\fR\fR
78 .ad
79 .RS 21n
80 These ioctls fetch and set various cursor attributes, using the
81 \fBvis_cursor\fR structure.
82 .sp
83 .in +2
84 .nf
85 struct vis_cursorpos {
86 short x; /* cursor x coordinate */
87 short y; /* cursor y coordinate */
88 };
89
90 struct vis_cursorcmap {
91 int version; /* version */
92 int reserved;
93 unsigned char *red; /* red color map elements */
94 unsigned char *green;/* green color map elements */
95 unsigned char *blue; /* blue color map elements */
96 };
97
98 #define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */
99 #define VIS_CURSOR_SETPOSITION 0x02 /* set cursor position */
100 #define VIS_CURSOR_SETHOTSPOT 0x04 /* set cursor hot spot */
101 #define VIS_CURSOR_SETCOLORMAP 0x08 /* set cursor colormap */
102 #define VIS_CURSOR_SETSHAPE 0x10 /* set cursor shape */
103 #define VIS_CURSOR_SETALL \e
104 (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \e
105 VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \e
106 VIS_CURSOR_SETSHAPE)
107
108 struct vis_cursor {
109 short set; /* what to set */
110 short enable; /* cursor on/off */
111 struct vis_cursorpos pos; /* cursor position */
112 struct vis_cursorpos hot; /* cursor hot spot */
113 struct vis_cursorcmap cmap; /* color map info */
114 struct vis_cursorpos size; /* cursor bitmap size */
115 char *image; /* cursor image bits */
116 char *mask; /* cursor mask bits */
117 };
118 .fi
119 .in -2
120
121 .RE
122
123 .sp
124 .LP
125 The \fBvis_cursorcmap\fR structure should contain pointers to two elements,
126 specifying the red, green, and blue values for foreground and background.
127 .sp
128 .ne 2
129 .na
130 \fB\fBVIS_SETCURSORPOS\fR\fR
131 .ad
132 .br
133 .na
134 \fB\fBVIS_MOVECURSOR\fR\fR
135 .ad
136 .RS 20n
137 These ioctls fetch and move the current cursor position, using the
138 \fBvis_cursorpos\fR structure.
139 .RE
140
141 .SS "Console Optional Ioctls"
142 .sp
143 .LP
144 The following ioctl sets are used by graphics drivers that are part of the
145 system console device. All of the ioctls must be implemented to be a console
146 device. In addition, if the system does not have a prom or the prom goes away
147 during boot, the special standalone ioctls (listed below) must also be
148 implemented.
149 .sp
150 .LP
151 The coordinate system for the console device places 0,0 at the upper left
152 corner of the device, with rows increasing toward the bottom of the device and
153 columns increasing from left to right.
154 .sp
155 .ne 2
156 .na
157 \fBVIS_PUTCMAP\fR
158 .ad
159 .br
160 .na
161 \fB\fBVIS_GETCMAP\fR\fR
162 .ad
163 .RS 15n
164 Set or get color map entries.
165 .RE
166
167 .sp
168 .LP
169 The argument is a pointer to a \fBvis_cmap\fR structure, which contains the
170 following fields:
171 .sp
172 .in +2
173 .nf
174 struct vis_cmap {
175 int index;
176 int count;
177 uchar_t *red;
178 uchar_t *green;
179 uchar_t *blue;
180 }
181 .fi
182 .in -2
183
184 .sp
185 .LP
186 \fBindex\fR is the starting index in the color map where you want to start
187 setting or getting color map entries.
188 .sp
189 .LP
190 \fBcount\fR is the number of color map entries to set or get. It also is the
191 size of the \fBred\fR, \fBgreen\fR, and \fBblue\fR color arrays.
192 .sp
193 .LP
194 \fB*red\fR, \fB*green\fR, and \fB*blue\fR are pointers to unsigned character
195 arrays which contain the color map info to set or where the color map info is
196 placed on a get.
197 .sp
198 .ne 2
199 .na
200 \fB\fBVIS_DEVINIT\fR\fR
201 .ad
202 .RS 15n
203 Initializes the graphics driver as a console device.
204 .RE
205
206 .sp
207 .LP
208 The argument is a pointer to a \fBvis_devinit\fR structure. The graphics driver
209 is expected to allocate any local state information needed to be a console
210 device and fill in this structure.
211 .sp
212 .in +2
213 .nf
214 struct vis_devinit {
215 int version;
216 screen_size_t width;
217 screen_size_t height;
218 screen_size_t linebytes;
219 unit_t size;
220 int depth;
221 short mode;
222 struct vis_polledio *polledio;
223 vis_modechg_cb_t modechg_cb;
224 struct vis_modechg_arg *modechg_arg;
225 };
226 .fi
227 .in -2
228
229 .sp
230 .LP
231 \fBversion\fR is the version of this structure and should be set to
232 \fBVIS_CONS_REV\fR.
233 .sp
234 .LP
235 \fBwidth\fR and \fBheight\fR are the width and height of the device. If
236 \fBmode\fR (see below) is \fBVIS_TEXT\fR then \fBwidth\fR and \fBheight\fR are
237 the number of characters wide and high of the device. If \fBmode\fR is
238 \fBVIS_PIXEL\fR then \fBwidth\fR and \fBheight\fR are the number of pixels wide
239 and high of the device.
240 .sp
241 .LP
242 \fBlinebytes\fR is the number of bytes per line of the device.
243 .sp
244 .LP
245 \fBsize\fR is the total size of the device in pixels.
246 .sp
247 .LP
248 \fBdepth\fR is the pixel depth in device bits. Currently supported depths are:
249 \fB1\fR, \fB4\fR, \fB8\fR and \fB24\fR.
250 .sp
251 .LP
252 \fBmode\fR is the mode of the device. Either \fBVIS_PIXEL\fR (data to be
253 displayed is in bitmap format) or \fBVIS_TEXT\fR (data to be displayed is in
254 ascii format).
255 .sp
256 .LP
257 \fBpolledio\fR is used to pass the address of the structure containing the
258 standalone mode polled I/O entry points to the device driver back to the
259 terminal emulator. The \fBvis_polledio\fR interfaces are described in the
260 Console Standalone Entry Points section of this manpage. These entry points are
261 where the operating system enters the driver when the system is running in
262 standalone mode. These functions perform identically to the VIS_CONSDISPLAY,
263 VIS_CONSCURSOR and VIS_CONSCOPY ioctls, but are called directly by the Solaris
264 operating environment and must operate under a very strict set of assumptions.
265 .sp
266 .LP
267 \fBmodechg_cb\fR is a callback function passed from the terminal emulator to
268 the framebuffer driver which the frame-buffer driver must call whenever a video
269 mode change event occurs that changes the screen height, width or depth. The
270 callback takes two arguments, an opaque handle, \fBmodechg_arg\fR, and the
271 address of a vis_devinit struct containing the new video mode information.
272 .sp
273 .LP
274 \fBmodechg_arg\fR is an opaque handle passed from the terminal emulator to the
275 driver, which the driver must pass back to the terminal emulator as an argument
276 to the \fBmodechg_cb\fR function when the driver notifies the terminal emulator
277 of a video mode change.
278 .sp
279 .ne 2
280 .na
281 \fB\fBVIS_DEVFINI\fR\fR
282 .ad
283 .RS 18n
284 Tells the graphics driver that it is no longer the system console device. There
285 is no argument to this ioctl. The driver is expected to free any locally kept
286 state information related to the console.
287 .RE
288
289 .sp
290 .ne 2
291 .na
292 \fB\fBVIS_CONSCURSOR\fR\fR
293 .ad
294 .RS 18n
295 Describes the size and placement of the cursor on the screen. The graphics
296 driver is expected to display or hide the cursor at the indicated position.
297 .RE
298
299 .sp
300 .LP
301 The argument is a pointer to a \fBvis_conscursor\fR structure which contains
302 the following fields:
303 .sp
304 .in +2
305 .nf
306 struct vis_conscursor {
307 screen_pos_t row;
308 screen_pos_t col;
309 screen_size_t width;
310 screen_size_t height
311 color_t fg_color;
312 color_t bg_color;
313 short action;
314 };
315 .fi
316 .in -2
317
318 .sp
319 .LP
320 \fBrow\fR and \fBcol\fR are the first row and column (upper left corner of the
321 cursor).
322 .sp
323 .LP
324 \fBwidth\fR and \fBheight\fR are the width and height of the cursor.
325 .sp
326 .LP
327 If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl is set to \fBVIS_PIXEL\fR, then
328 \fBcol\fR, \fBrow\fR, \fBwidth\fR and \fBheight\fR are in pixels. If \fBmode\fR
329 in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, then \fBcol\fR,
330 \fBrow\fR, \fBwidth\fR and \fBheight\fR are in characters.
331 .sp
332 .LP
333 \fBfg_color\fR and \fBbg_color\fR are the foreground and background color map
334 indexes to use when the \fBaction\fR (see below) is set to
335 \fBVIS_DISPLAY_CURSOR\fR.
336 .sp
337 .LP
338 \fBaction\fR indicates whether to display or hide the cursor. It is set to
339 either \fBVIS_HIDE_CURSOR\fR or \fBVIS_DISPLAY_CURSOR\fR.
340 .sp
341 .ne 2
342 .na
343 \fB\fBVIS_CONSDISPLAY\fR\fR
344 .ad
345 .RS 19n
346 Display data on the graphics device. The graphics driver is expected to display
347 the data contained in the \fBvis_display\fR structure at the specified
348 position on the console.
349 .RE
350
351 .sp
352 .LP
353 The \fBvis_display\fR structure contains the following fields:
354 .sp
355 .in +2
356 .nf
357 struct vis_display {
358 screen_pos_t row;
359 screen_pos_t col;
360 screen_size_t width;
361 screen_size_t height;
362 uchar_t *data;
363 color_t fg_color;
364 color_t bg_color;
365 };
366 .fi
367 .in -2
368
369 .sp
370 .LP
371 \fBrow\fR and \fBcol\fR specify at which starting row and column the date is to
372 be displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
373 \fBVIS_TEXT\fR, \fBrow\fR and \fBcol\fR are defined to be a character offset
374 from the starting position of the console device. If \fBmode\fR in the
375 \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBrow\fR and \fBcol\fR
376 are defined to be a pixel offset from the starting position of the console
377 device.
378 .sp
379 .LP
380 \fBwidth\fR and \fBheight\fR specify the size of the \fBdata\fR to be
381 displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
382 \fBVIS_TEXT\fR, \fBwidth\fR and \fBheight\fR define the size of \fBdata\fR as
383 a rectangle that is \fBwidth\fR characters wide and \fBheight\fR characters
384 high. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR,
385 \fBwidth\fR and \fBheight\fR define the size of \fBdata\fR as a rectangle that
386 is \fBwidth\fR pixels wide and \fBheight\fR pixels high.
387 .sp
388 .LP
389 \fB*data\fR is a pointer to the data to be displayed on the console device. If
390 \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, \fBdata\fR
391 is an array of \fBASCII\fR characters to be displayed on the console device.
392 The driver must break these characters up appropriately and display it in the
393 retangle defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR. If
394 \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR,
395 \fBdata\fR is an array of bitmap data to be displayed on the console device.
396 The driver must break this data up appropriately and display it in the retangle
397 defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR.
398 .sp
399 .LP
400 The \fBfg_color\fR and \fBbg_color\fR fields define the foreground and
401 background color map indexes to use when displaying the data. \fBfb_color\fR is
402 used for "on" pixels and \fBbg_color\fR is used for "off" pixels.
403 .sp
404 .ne 2
405 .na
406 \fB\fBVIS_CONSCOPY\fR\fR
407 .ad
408 .RS 16n
409 Copy data from one location on the device to another. The driver is expected
410 to copy the specified data. The source data should not be modified. Any
411 modifications to the source data should be as a side effect of the copy
412 destination overlapping the copy source.
413 .RE
414
415 .sp
416 .LP
417 The argument is a pointer to a \fBvis_copy\fR structure which contains the
418 following fields:
419 .sp
420 .in +2
421 .nf
422 struct vis_copy {
423 screen_pos_t s_row;
424 screen_pos_t s_col;
425 screen_pos_t e_row;
426 screen_pos_t e_col;
427 screen_pos_t t_row;
428 screen_pos_t t_col;
429 short direction;
430 };
431 .fi
432 .in -2
433
434 .sp
435 .LP
436 \fBs_row\fR, \fBs_col\fR, \fBe_row\fR, and \fBe_col\fR define the source
437 rectangle of the copy. \fBs_row\fR and \fBs_col\fR are the upper left corner of
438 the source rectangle. \fBe_row\fR and \fBe_col\fR are the lower right corner of
439 the source rectangle. If \fBmode\fR in the \fBVIS_DEVINIT\fR \fBioctl()\fR was
440 set to \fBVIS_TEXT\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR
441 are defined to be character offsets from the starting position of the console
442 device. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
443 \fBVIS_PIXEL\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR are
444 defined to be pixel offsets from the starting position of the console device.
445 .sp
446 .LP
447 \fBt_row\fR and \fBt_col\fR define the upper left corner of the destination
448 rectangle of the copy. The entire rectangle is copied to this location. If
449 \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR,
450 \fBt_row\fR, and \fBt_col\fR are defined to be character offsets from the
451 starting position of the console device. If \fBmode\fR in the
452 \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBt_row\fR, and
453 \fBt_col\fR are defined to be pixel offsets from the starting position of the
454 console device.
455 .sp
456 .LP
457 \fBdirection\fR specifies which way to do the copy. If direction is
458 \fBVIS_COPY_FORWARD\fR the graphics driver should copy data from position
459 (\fBs_row\fR, \fBs_col\fR) in the source rectangle to position (\fBt_row\fR,
460 \fBt_col\fR) in the destination rectangle. If direction is
461 \fBVIS_COPY_BACKWARDS\fR the graphics driver should copy data from position
462 (\fBe_row\fR, \fBe_col\fR) in the source rectangle to position
463 \fB(t_row+(e_row-s_row)\fR, \fBt_col+(e_col-s_col))\fR in the destination
464 rectangle.
465 .SS "Console Standalone Entry Points (Polled I/O Interfaces)"
466 .sp
467 .LP
468 Console standalone entry points are necessary only if the driver is
469 implementing console-compatible extensions. All console vectored standalone
470 entry points must be implemented along with all console-related ioctls if the
471 console extension is implemented.
472 .sp
473 .in +2
474 .nf
475 struct vis_polledio {
476 struct vis_polledio_arg *arg;
477 void (*display)(vis_polledio_arg *, struct vis_consdisplay *);
478 void (*copy)(vis_polledio_arg *, struct vis_conscopy *);
479 void (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
480 };
481 .fi
482 .in -2
483
484 .sp
485 .LP
486 The \fBvis_polledio\fR structure is passed from the driver to the Solaris
487 operating environment, conveying the entry point addresses of three functions
488 which perform the same operations of their similarly named ioctl counterparts.
489 The rendering parameters for each entry point are derived from the same
490 structure passed as the respective ioctl. See the Console Optional Ioctls
491 section of this manpage for an explanation of the specific function each of the
492 entry points, display(), copy() and cursor() are required to implement. In
493 addition to performing the prescribed function of their ioctl counterparts, the
494 standalone vectors operate in a special context and must adhere to a strict set
495 of rules. The polled I/O vectors are called directly whenever the system is
496 quisced (running in a limited context) and must send output to the display.
497 Standalone mode describes the state in which the system is running in
498 single-threaded mode and only one processor is active. Solaris operating
499 environment services are stopped, along with all other threads on the system,
500 prior to entering any of the polled I/O interfaces. The polled I/O vectors are
501 called when the system is running in a standalone debugger, when executing the
502 PROM monitor (OBP) or when panicking.
503 .sp
504 .LP
505 The following restrictions must be observed in the polled I/O functions:
506 .RS +4
507 .TP
508 1.
509 The driver must not allocate memory.
510 .RE
511 .RS +4
512 .TP
513 2.
514 The driver must not wait on mutexes.
515 .RE
516 .RS +4
517 .TP
518 3.
519 The driver must not wait for interrupts.
520 .RE
521 .RS +4
522 .TP
523 4.
524 The driver must not call any DDI or LDI services.
525 .RE
526 .RS +4
527 .TP
528 5.
529 The driver must not call any system services.
530 .RE
531 .sp
532 .LP
533 The system is single-threaded when calling these functions, meaning that all
534 other threads are effectively halted. Single-threading makes mutexes (which
535 cannot be held) easier to deal with, so long as the driver does not disturb any
536 shared state. See \fIWriting Device Drivers\fR for more information about
537 implementing polled I/O entry points.
538 .SH SEE ALSO
539 .sp
540 .LP
541 \fBioctl\fR(2)
542 .sp
543 .LP
544 \fIWriting Device Drivers\fR
545 .SH NOTES
546 .sp
547 .LP
548 On SPARC systems, compatible drivers supporting the kernel terminal emulator
549 should export the \fBtem-support\fR DDI property.\fBtem-support\fR indicates
550 that the driver supports the kernel terminal emulator. By exporting
551 \fBtem-support\fR it's possible to avoid premature handling of an incompatible
552 driver.
553 .sp
554 .ne 2
555 .na
556 \fBtem-support\fR
557 .ad
558 .RS 15n
559 This DDI property, set to 1, means driver is compatible with the console
560 kernel framebuffer interface.
561 .RE
562