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