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
|
1 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
2 .\" Copyright 2018, Joyent, Inc.
3 .\" The contents of this file are subject to the terms of the
4 .\" Common Development and Distribution License (the "License").
5 .\" You may not use this file except in compliance with the License.
6 .\"
7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 .\" or http://www.opensolaris.org/os/licensing.
9 .\" See the License for the specific language governing permissions
10 .\" and limitations under the License.
11 .\"
12 .\" When distributing Covered Code, include this CDDL HEADER in each
13 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 .\" If applicable, add the following below this CDDL HEADER, with the
15 .\" fields enclosed by brackets "[]" replaced with your own identifying
16 .\" information: Portions Copyright [yyyy] [name of copyright owner]
17 .Dd August 31, 2018
18 .Dt VISUAL_IO 7I
19 .Os
20 .Sh NAME
21 .Nm visual_io
22 .Nd illumos VISUAL I/O control operations
23 .Sh SYNOPSIS
24 .In sys/visual_io.h
25 .Sh DESCRIPTION
26 The illumos VISUAL environment defines a small set of ioctls for controlling
27 graphics and imaging devices.
28 .Pp
29 The
30 .Dv VIS_GETIDENTIFIER
31 ioctl is mandatory and must be implemented in
32 device drivers for graphics devices using the illumos VISUAL environment.
33 The
34 .Dv VIS_GETIDENTIFIER
35 ioctl is defined to return a device identifier from the device driver.
36 This identifier must be a uniquely-defined string.
37 .Pp
38 There are two additional sets of ioctls.
39 One supports mouse tracking via hardware cursor operations.
40 Use of this set is optional, however, if a graphics
41 device has hardware cursor support and implements these ioctls, the mouse
42 tracking performance is improved.
43 The remaining set supports the device acting
44 as the system console device.
45 Use of this set is optional, but if a graphics device is to be used as the
46 system console device, it must implement these ioctls.
47 .Pp
48 The VISUAL environment also defines interfaces for non-ioctl entry points into
49 the driver that the illumos operating environment calls when it is running in
50 standalone mode (for example, when using a stand-alone debugger, entering
51 the PROM monitor, or when the system panicking).
52 These are also known as
53 .Dq Polled I/O
54 entry points, which operate under an an explicit set of restrictions, described below.
55 .Sh IOCTLS
56 .Bl -tag -width VIS_GETIDENTIFIER -compact
57 .It Dv VIS_GETIDENTIFIER
58 This
59 .Xr ioctl 2
60 returns an identifier string to uniquely identify a device
61 used in the illumos VISUAL environment.
62 This is a mandatory ioctl and must return a unique string.
63 We suggest that the name be formed as
64 .Ao companysymbol Ac Ns Ao devicetype Ac .
65 For example, the
66 .Xr cgsix 7D
67 driver
68 returns
69 .Sy SUNWcg6 .
70 .Pp
71 .Dv VIS_GETIDENTIFIER
72 takes a
73 .Vt vis_identifier
74 structure as its parameter.
75 This structure has the form:
76 .Bd -literal -offset 2n
77 #define VIS_MAXNAMELEN 128
78 struct vis_identifier {
79 char name[VIS_MAXNAMELEN];
80 };
81 .Ed
82 .Pp
83 .It Dv VIS_GETCURSOR
84 .It Dv VIS_SETCURSOR
85 These ioctls fetch and set various cursor attributes, using the
86 .Vt vis_cursor
87 structure.
88 .Bd -literal -offset 2n
89 struct vis_cursorpos {
90 short x; /* cursor x coordinate */
91 short y; /* cursor y coordinate */
92 };
93
94 struct vis_cursorcmap {
95 int version; /* version */
96 int reserved;
97 /* red color map elements */
98 unsigned char *red;
99 /* green color map elements */
100 unsigned char *green;
101 /* blue color map elements */
102 unsigned char *blue;
103 };
104
105 #define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */
106 /* set cursor position */
107 #define VIS_CURSOR_SETPOSITION 0x02
108 /* set cursur hot spot */
109 #define VIS_CURSOR_SETHOTSPOT 0x04
110 /* set cursor colormap */
111 #define VIS_CURSOR_SETCOLORMAP 0x08
112 /* set cursor shape */
113 #define VIS_CURSOR_SETSHAPE 0x10
114 #define VIS_CURSOR_SETALL \e
115 (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \e
116 VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \e
117 VIS_CURSOR_SETSHAPE)
118
119 struct vis_cursor {
120 short set; /* what to set */
121 short enable; /* cursor on/off */
122 struct vis_cursorpos pos; /* cursor position */
123 struct vis_cursorpos hot; /* cursor hot spot */
124 struct vis_cursorcmap cmap; /* color map info */
125 /* cursor bitmap size */
126 struct vis_cursorpos size;
127 char *image; /* cursor image bits */
128 char *mask; /* cursor mask bits */
129 };
130 .Ed
131 .Pp
132 The
133 .Vt vis_cursorcmap
134 structure should contain pointers to two elements,
135 specifying the red, green, and blue values for foreground and background.
136 .Pp
137 .It Dv VIS_SETCURSORPOS
138 .It Dv VIS_MOVECURSOR
139 These ioctls fetch and move the current cursor position, using the
140 .Vt vis_cursorpos
141 structure.
142 .El
143 .Ss "Console Optional Ioctls"
144 The following ioctl sets are used by graphics drivers that are part of the
145 system console device.
146 All of the ioctls must be implemented to be a console device.
147 In addition, if the system does not have a prom or the prom goes away
148 during boot, the special standalone ioctls (listed below) must also be
149 implemented.
150 .Pp
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 .Pp
155 .Bl -tag -width VIS_CONSDISPLAY -compact -offset 2n
156 .It Dv VIS_PUTCMAP
157 .It Dv VIS_GETCMAP
158 Set or get color map entries.
159 .Pp
160 The argument is a pointer to a
161 .Vt vis_cmap
162 structure, which contains the
163 following fields:
164 .Bd -literal -offset 2n
165 struct vis_cmap {
166 int index;
167 int count;
168 uchar_t *red;
169 uchar_t *green;
170 uchar_t *blue;
171 }
172 .Ed
173 .Pp
174 .Fa index
175 is the starting index in the color map where you want to start
176 setting or getting color map entries.
177 .Pp
178 .Fa count
179 is the number of color map entries to set or get.
180 It also is the
181 size of the
182 .Fa red ,
183 .Fa green ,
184 and
185 .Fa blue
186 color arrays.
187 .Pp
188 .Fa *red ,
189 .Fa *green ,
190 and
191 .Fa *blue
192 are pointers to unsigned character arrays which contain the color map info to
193 set or where the color map info is placed on a get.
194 .Pp
195 .It Dv VIS_DEVINIT
196 Initializes the graphics driver as a console device.
197 .Pp
198 The argument is a pointer to a
199 .Vt vis_devinit
200 structure.
201 The graphics driver
202 is expected to allocate any local state information needed to be a console
203 device and fill in this structure.
204 .Bd -literal -offset 2n
205 struct vis_devinit {
206 int version;
207 screen_size_t width;
208 screen_size_t height;
209 screen_size_t linebytes;
210 unit_t size;
211 int depth;
212 short mode;
213 struct vis_polledio *polledio;
214 vis_modechg_cb_t modechg_cb;
215 struct vis_modechg_arg *modechg_arg;
216 };
217 .Ed
218 .Pp
219 .Fa version
220 is the version of this structure and should be set to
221 .Dv VIS_CONS_REV .
222 .Pp
223 .Fa width
224 and
225 .Fa height
226 are the width and height of the device.
227 If
228 .Fa mode
229 (see below) is
230 .Dv VIS_TEXT
231 then
232 .Fa width
233 and
234 .Fa height
235 are the number of characters wide and high of the device.
236 If
237 .Fa mode
238 is
239 .Dv VIS_PIXEL
240 then
241 .Fa width
242 and
243 .Fa height
244 are the number of pixels wide and high of the device.
245 .Pp
246 .Fa linebytes
247 is the number of bytes per line of the device.
248 .Pp
249 .Fa size
250 is the total size of the device in pixels.
251 .Pp
252 .Fa depth
253 is the pixel depth in device bits.
254 Currently supported depths are:
255 .Sy 1 ,
256 .Sy 4 ,
257 .Sy 8
258 and
259 .Sy 24 .
260 .Pp
261 .Fa mode
262 is the mode of the device.
263 Either
264 .Dv VIS_PIXEL
265 (data to be displayed is in bitmap format) or
266 .Dv VIS_TEXT
267 (data to be displayed is in ascii format).
268 .Pp
269 .Fa polledio
270 is used to pass the address of the structure containing the
271 standalone mode polled I/O entry points to the device driver back to the
272 terminal emulator.
273 The
274 .Vt vis_polledio
275 interfaces are described in the
276 Console Standalone Entry Points section of this manpage.
277 These entry points are where the operating system enters the driver when the
278 system is running in standalone mode.
279 These functions perform identically to the
280 .Dv VIS_CONSDISPLAY ,
281 .Dv VIS_CONSCURSOR ,
282 and
283 .Dv VIS_CONSCOPY
284 ioctls, but are called directly by the illumos
285 operating environment and must operate under a very strict set of assumptions.
286 .Pp
287 .Fa modechg_cb
288 is a callback function passed from the terminal emulator to
289 the framebuffer driver which the frame-buffer driver must call whenever a video
290 mode change event occurs that changes the screen height, width or depth.
291 The callback takes two arguments, an opaque handle,
292 .Fa modechg_arg ,
293 and the address of a
294 .Vt vis_devinit
295 struct containing the new video mode information.
296 .Pp
297 .Fa modechg_arg
298 is an opaque handle passed from the terminal emulator to the
299 driver, which the driver must pass back to the terminal emulator as an argument
300 to the
301 .Fa modechg_cb
302 function when the driver notifies the terminal emulator of a video mode change.
303 .Pp
304 .It Dv VIS_DEVFINI
305 Tells the graphics driver that it is no longer the system console device.
306 There is no argument to this ioctl.
307 The driver is expected to free any locally kept
308 state information related to the console.
309 .Pp
310 .It Dv VIS_CONSCURSOR
311 Describes the size and placement of the cursor on the screen.
312 The graphics
313 driver is expected to display or hide the cursor at the indicated position.
314 .Pp
315 The argument is a pointer to a
316 .Vt vis_conscursor
317 structure which contains
318 the following fields:
319 .Bd -literal -offset 2n
320 struct vis_conscursor {
321 screen_pos_t row;
322 screen_pos_t col;
323 screen_size_t width;
324 screen_size_t height
325 color_t fg_color;
326 color_t bg_color;
327 short action;
328 };
329 .Ed
330 .Pp
331 .Fa row
332 and
333 .Fa col
334 are the first row and column (upper left corner of the cursor).
335 .Pp
336 .Fa width
337 and
338 .Fa height
339 are the width and height of the cursor.
340 .Pp
341 If
342 .Fa mode
343 in the
344 .Dv VIS_DEVINIT
345 ioctl is set to
346 .Dv VIS_PIXEL ,
347 then
348 .Fa col ,
349 .Fa row ,
350 .Fa width
351 and
352 .Fa height
353 are in pixels.
354 If
355 .Fa mode
356 in the
357 .Dv VIS_DEVINIT
358 ioctl was set to
359 .Dv VIS_TEXT ,
360 then
361 .Fa col ,
362 .Fa row ,
363 .Fa width
364 and
365 .Fa height
366 are in characters.
367 .Pp
368 .Fa fg_color
369 and
370 .Fa bg_color
371 are the foreground and background color map
372 indexes to use when the
373 .Fa action
374 (see below) is set to
375 .Dv VIS_DISPLAY_CURSOR .
376 .Pp
377 .Fa action
378 indicates whether to display or hide the cursor.
379 It is set to either
380 .Dv VIS_HIDE_CURSOR
381 or
382 .Dv VIS_DISPLAY_CURSOR .
383 .Pp
384 .It Dv VIS_CONSDISPLAY
385 Display data on the graphics device.
386 The graphics driver is expected to display the data contained in the
387 .Vt vis_display
388 structure at the specified position on the console.
389 .Pp
390 The
391 .Vt vis_display
392 structure contains the following fields:
393 .Bd -literal -offset 2n
394 struct vis_display {
395 screen_pos_t row;
396 screen_pos_t col;
397 screen_size_t width;
398 screen_size_t height;
399 uchar_t *data;
400 color_t fg_color;
401 color_t bg_color;
402 };
403 .Ed
404 .Pp
405 .Fa row
406 and
407 .Fa col
408 specify at which starting row and column the date is to be displayed.
409 If
410 .Fa mode
411 in the
412 .Dv VIS_DEVINIT
413 ioctl was set to
414 .Dv VIS_TEXT ,
415 .Fa row
416 and
417 .Fa col
418 are defined to be a character offset
419 from the starting position of the console device.
420 If
421 .Fa mode
422 in the
423 .Dv VIS_DEVINIT
424 ioctl was set to
425 .Dv VIS_PIXEL ,
426 .Fa row
427 and
428 .Fa col
429 are defined to be a pixel offset from the starting position of the console
430 device.
431 .Pp
432 .Fa width
433 and
434 .Fa height
435 specify the size of the
436 .Fa data
437 to be displayed.
438 If
439 .Fa mode
440 in the
441 .Dv VIS_DEVINIT
442 ioctl was set to
443 .Dv VIS_TEXT ,
444 .Fa width
445 and
446 .Fa height
447 define the size of
448 .Fa data
449 as rectangle that is
450 .Fa width
451 characters wide and
452 .Fa height
453 characters high.
454 If
455 .Fa mode
456 in the
457 .Dv VIS_DEVINIT
458 ioctl was set to
459 .Dv VIS_PIXEL ,
460 .Fa width
461 and
462 .Fa height
463 define the size of
464 .Fa data
465 as a rectangle that is
466 .Fa width
467 pixels wide and
468 .Fa height
469 pixels high.
470 .Pp
471 .Fa *data
472 is a pointer to the data to be displayed on the console device.
473 If
474 .Fa mode
475 in the
476 .Dv VIS_DEVINIT
477 ioctl was set to
478 .Dv VIS_TEXT ,
479 .Fa data
480 is an array of
481 .Sy ASCII
482 characters to be displayed on the console device.
483 The driver must break these characters up appropriately and display it in the
484 rectangle defined by
485 .Fa row ,
486 .Fa col ,
487 .Fa width ,
488 and
489 .Fa height .
490 If
491 .Fa mode
492 in the
493 .Dv VIS_DEVINIT
494 ioctl was set to
495 .Dv VIS_PIXEL ,
496 .Fa data
497 is an array of bitmap data to be displayed on the console device.
498 The driver must break this data up appropriately and display it in the retangle
499 defined by
500 .Fa row ,
501 .Fa col ,
502 .Fa width ,
503 and
504 .Fa height .
505 .Pp
506 The
507 .Fa fg_color
508 and
509 .Fa bg_color
510 fields define the foreground and
511 background color map indexes to use when displaying the data.
512 .Fa fb_color
513 is used for
514 .Dq on
515 pixels and
516 .Fa bg_color
517 is used for
518 .Dq off
519 pixels.
520 .Pp
521 .It Dv VIS_CONSCOPY
522 Copy data from one location on the device to another.
523 The driver is expected to copy the specified data.
524 The source data should not be modified.
525 Any modifications to the source data should be as a side effect of the copy
526 destination overlapping the copy source.
527 .Pp
528 The argument is a pointer to a
529 .Vt vis_copy
530 structure which contains the following fields:
531 .Bd -literal -offset 2n
532 struct vis_copy {
533 screen_pos_t s_row;
534 screen_pos_t s_col;
535 screen_pos_t e_row;
536 screen_pos_t e_col;
537 screen_pos_t t_row;
538 screen_pos_t t_col;
539 short direction;
540 };
541 .Ed
542 .Pp
543 .Fa s_row ,
544 .Fa s_col ,
545 .Fa e_row ,
546 and
547 .Fa e_col
548 define the source rectangle of the copy.
549 .Fa s_row
550 and
551 .Fa s_col
552 are the upper left corner of the source rectangle.
553 .Fa e_row
554 and
555 .Fa e_col
556 are the lower right corner of the source rectangle.
557 If
558 .Fa mode
559 in the
560 .Dv VIS_DEVINIT
561 .Fn ioctl
562 was set to
563 .Dv VIS_TEXT ,
564 .Fa s_row ,
565 .Fa s_col ,
566 .Fa e_row ,
567 and
568 .Fa e_col
569 are defined to be character offsets from the starting position of the console
570 device.
571 If
572 .Fa mode
573 in the
574 .Dv VIS_DEVINIT
575 .Fn ioctl
576 was set to
577 .Dv VIS_PIXEL ,
578 .Fa s_row ,
579 .Fa s_col ,
580 .Fa e_row ,
581 and
582 .Fa e_col
583 are
584 defined to be pixel offsets from the starting position of the console device.
585 .Pp
586 .Fa t_row
587 and
588 .Fa t_col
589 define the upper left corner of the destination rectangle of the copy.
590 The entire rectangle is copied to this location.
591 If
592 .Fa mode
593 in the
594 .Dv VIS_DEVINIT
595 ioctl was set to
596 .Dv VIS_TEXT ,
597 .Fa t_row ,
598 and
599 .Fa t_col
600 are defined to be character offsets from the
601 starting position of the console device.
602 If
603 .Fa mode
604 in the
605 .Dv VIS_DEVINIT
606 ioctl was set to
607 .Dv VIS_PIXEL ,
608 .Fa t_row ,
609 and
610 .Fa t_col
611 are defined to be pixel offsets from the starting position of the
612 onssole device.
613 .Pp
614 .Fa direction
615 specifies which way to do the copy.
616 If direction is
617 .Dv VIS_COPY_FORWARD
618 the graphics driver should copy data from position
619 .Po
620 .Fa s_row ,
621 .Fa s_col
622 .Pc
623 in the source rectangle to position
624 .Po
625 .Fa t_row ,
626 .Fa t_col
627 .Pc
628 in the destination rectangle.
629 If direction is
630 .Dv VIS_COPY_BACKWARDS
631 the graphics driver should copy data from position
632 .Po
633 .Fa e_row ,
634 .Fa e_col
635 .Pc
636 in the source rectangle to position
637 .Po
638 .Fa t_row Ns + Ns
639 .Po
640 .Fa e_row Ns \- Ns
641 .Fa s_row
642 .Pc ,
643 .Fa t_col Ns + Ns
644 .Po
645 .Fa e_col Ns \- Ns
646 .Fa s_col
647 .Pc
648 .Pc
649 in the destination rectangle.
650 .El
651 .Ss "Console Standalone Entry Points (Polled I/O Interfaces)"
652 Console standalone entry points are necessary only if the driver is
653 implementing console-compatible extensions.
654 All console vectored standalone
655 entry points must be implemented along with all console-related ioctls if the
656 console extension is implemented.
657 .Bd -literal -offset 2n
658 struct vis_polledio {
659 struct vis_polledio_arg *arg;
660 void (*display)(vis_polledio_arg *, struct vis_consdisplay *);
661 void (*copy)(vis_polledio_arg *, struct vis_conscopy *);
662 void (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
663 };
664 .Ed
665 .Pp
666 The
667 .Vt vis_polledio
668 structure is passed from the driver to the illumos
669 operating environment, conveying the entry point addresses of three functions
670 which perform the same operations of their similarly named ioctl counterparts.
671 The rendering parameters for each entry point are derived from the same
672 structure passed as the respective ioctl.
673 See the
674 .Sx "Console Optional Ioctls"
675 section of this manpage for an explanation of the specific function each of the
676 entry points,
677 .Fn display ,
678 .Fn copy ,
679 and
680 .Fn cursor
681 are required to implement.
682 In
683 addition to performing the prescribed function of their ioctl counterparts, the
684 standalone vectors operate in a special context and must adhere to a strict set
685 of rules.
686 The polled I/O vectors are called directly whenever the system is
687 quisced (running in a limited context) and must send output to the display.
688 Standalone mode describes the state in which the system is running in
689 single-threaded mode and only one processor is active.
690 illumos operating
691 environment services are stopped, along with all other threads on the system,
692 prior to entering any of the polled I/O interfaces.
693 The polled I/O vectors are
694 called when the system is running in a standalone debugger, when executing the
695 PROM monitor (OBP) or when panicking.
696 .Pp
697 The following restrictions must be observed in the polled I/O functions:
698 .Bl -enum -offset indent
699 .It
700 The driver must not allocate memory.
701 .It
702 The driver must not wait on mutexes.
703 .It
704 The driver must not wait for interrupts.
705 .It
706 The driver must not call any DDI or LDI services.
707 .It
708 The driver must not call any system services.
709 .El
710 .Pp
711 The system is single-threaded when calling these functions, meaning that all
712 other threads are effectively halted.
713 Single-threading makes mutexes (which
714 cannot be held) easier to deal with, so long as the driver does not disturb any
715 shared state.
716 See
717 .%T Writing Device Drivers
718 for more information about implementing polled I/O entry points.
719 .Sh SEE ALSO
720 .Xr ioctl 2
721 .Rs
722 .%T Writing Device Drivers
723 .Re
724 .Sh NOTES
725 On SPARC systems, compatible drivers supporting the kernel terminal emulator
726 should export the
727 .Sy tem-support
728 DDI property.
729 .Sy tem-support
730 indicates that the driver supports the kernel terminal emulator.
731 By exporting
732 .Sy tem-support
733 it's possible to avoid premature handling of an incompatible driver.
734 .Bl -tag -width tem-support
735 .It Sy tem-support
736 This DDI property, set to 1, means driver is compatible with the console
737 kernel framebuffer interface.
738 .El
|