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