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