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