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