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