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 */
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
|
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 */
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
|