1visual_io(7I)                   Ioctl Requests                   visual_io(7I)
2
3
4

NAME

6       visual_io - Solaris VISUAL I/O control operations
7

SYNOPSIS

9       #include <sys/visual_io.h>
10
11

DESCRIPTION

13       The  Solaris  VISUAL environment defines a small set of ioctls for con‐
14       trolling 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 environ‐
19       ment. The VIS_GETIDENTIFIER ioctl is defined to return a device identi‐
20       fier from the device driver. This identifier must be a uniquely-defined
21       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

IOCTLS

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

SEE ALSO

425       ioctl(2)
426
427
428       Writing Device Drivers
429

NOTES

431       On SPARC systems, compatible drivers  supporting  the  kernel  terminal
432       emulator  should  export the tem-support DDI property.tem-support indi‐
433       cates that the driver supports the kernel terminal emulator. By export‐
434       ing  tem-support it's possible to avoid premature handling of an incom‐
435       patible driver.
436
437       tem-support    This DDI property, set to 1, means driver is  compatible
438                      with   the   console                              kernel
439                      framebuffer interface.
440
441
442
443
444SunOS 5.11                        14 Oct 2005                    visual_io(7I)
Impressum