Print this page
10562 Convert visual_io(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/visual_io.7i
+++ new/usr/src/man/man7i/visual_io.7i
1 -'\" te
2 1 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
3 -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH VISUAL_IO 7I "Oct 14, 2005"
7 -.SH NAME
8 -visual_io \- Solaris VISUAL I/O control operations
9 -.SH SYNOPSIS
10 -.LP
11 -.nf
12 -\fB#include <sys/visual_io.h>\fR
13 -.fi
14 -
15 -.SH DESCRIPTION
16 -.sp
17 -.LP
18 -The Solaris VISUAL environment defines a small set of ioctls for controlling
2 +.\" Copyright 2018, Joyent, Inc.
3 +.\" The contents of this file are subject to the terms of the
4 +.\" Common Development and Distribution License (the "License").
5 +.\" You may not use this file except in compliance with the License.
6 +.\"
7 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 +.\" or http://www.opensolaris.org/os/licensing.
9 +.\" See the License for the specific language governing permissions
10 +.\" and limitations under the License.
11 +.\"
12 +.\" When distributing Covered Code, include this CDDL HEADER in each
13 +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 +.\" If applicable, add the following below this CDDL HEADER, with the
15 +.\" fields enclosed by brackets "[]" replaced with your own identifying
16 +.\" information: Portions Copyright [yyyy] [name of copyright owner]
17 +.Dd August 31, 2018
18 +.Dt VISUAL_IO 7I
19 +.Os
20 +.Sh NAME
21 +.Nm visual_io
22 +.Nd illumos VISUAL I/O control operations
23 +.Sh SYNOPSIS
24 +.In sys/visual_io.h
25 +.Sh DESCRIPTION
26 +The illumos VISUAL environment defines a small set of ioctls for controlling
19 27 graphics and imaging devices.
20 -.sp
21 -.LP
22 -The \fBVIS_GETIDENTIFIER\fR ioctl is mandatory and must be implemented in
23 -device drivers for graphics devices using the Solaris VISUAL environment. The
24 -\fBVIS_GETIDENTIFIER\fR ioctl is defined to return a device identifier from the
25 -device driver. This identifier must be a uniquely-defined string.
26 -.sp
27 -.LP
28 -There are two additional sets of ioctls. One supports mouse tracking via
29 -hardware cursor operations. Use of this set is optional, however, if a graphics
28 +.Pp
29 +The
30 +.Dv VIS_GETIDENTIFIER
31 +ioctl is mandatory and must be implemented in
32 +device drivers for graphics devices using the illumos VISUAL environment.
33 +The
34 +.Dv VIS_GETIDENTIFIER
35 +ioctl is defined to return a device identifier from the device driver.
36 +This identifier must be a uniquely-defined string.
37 +.Pp
38 +There are two additional sets of ioctls.
39 +One supports mouse tracking via hardware cursor operations.
40 +Use of this set is optional, however, if a graphics
30 41 device has hardware cursor support and implements these ioctls, the mouse
31 -tracking performance is improved. The remaining set supports the device acting
32 -as the system console device. Use of this set is optional, but if a graphics
33 -device is to be used as the system console device, it must implement these
34 -ioctls.
35 -.sp
36 -.LP
42 +tracking performance is improved.
43 +The remaining set supports the device acting
44 +as the system console device.
45 +Use of this set is optional, but if a graphics device is to be used as the
46 +system console device, it must implement these ioctls.
47 +.Pp
37 48 The VISUAL environment also defines interfaces for non-ioctl entry points into
38 -the driver that the Solaris operating environment calls when it is running in
39 -standalone mode (for example, when using a stand-alone debugger, entering
40 -the PROM monitor, or when the system panicking). These are also known as
41 -"Polled I/O" entry points, which operate under an an explicit set of
42 -restrictions, described below.
43 -.SH IOCTLS
44 -.sp
45 -.ne 2
46 -.na
47 -\fB\fBVIS_GETIDENTIFIER\fR\fR
48 -.ad
49 -.RS 21n
50 -This \fBioctl()\fR returns an identifier string to uniquely identify a device
51 -used in the Solaris VISUAL environment. This is a mandatory ioctl and must
52 -return a unique string. We suggest that the name be formed as
53 -\fI<companysymbol><devicetype>\fR\&. For example, the \fBcgsix\fR driver
54 -returns \fBSUNWcg6\fR.
55 -.sp
56 -\fBVIS_GETIDENTIFIER\fR takes a \fBvis_identifier\fR structure as its
57 -parameter. This structure has the form:
58 -.sp
59 -.in +2
60 -.nf
49 +the driver that the illumos operating environment calls when it is running in
50 +standalone mode (for example, when using a stand-alone debugger, entering
51 +the PROM monitor, or when the system panicking).
52 +These are also known as
53 +.Dq Polled I/O
54 +entry points, which operate under an an explicit set of restrictions, described below.
55 +.Sh IOCTLS
56 +.Bl -tag -width VIS_GETIDENTIFIER -compact
57 +.It Dv VIS_GETIDENTIFIER
58 +This
59 +.Xr ioctl 2
60 +returns an identifier string to uniquely identify a device
61 +used in the illumos VISUAL environment.
62 +This is a mandatory ioctl and must return a unique string.
63 +We suggest that the name be formed as
64 +.Ao companysymbol Ac Ns Ao devicetype Ac .
65 +For example, the
66 +.Xr cgsix 7D
67 +driver
68 +returns
69 +.Sy SUNWcg6 .
70 +.Pp
71 +.Dv VIS_GETIDENTIFIER
72 +takes a
73 +.Vt vis_identifier
74 +structure as its parameter.
75 +This structure has the form:
76 +.Bd -literal -offset 2n
61 77 #define VIS_MAXNAMELEN 128
62 78 struct vis_identifier {
63 79 char name[VIS_MAXNAMELEN];
64 80 };
65 -.fi
66 -.in -2
67 -
68 -.RE
69 -
70 -.sp
71 -.ne 2
72 -.na
73 -\fB\fBVIS_GETCURSOR\fR\fR
74 -.ad
75 -.br
76 -.na
77 -\fB\fBVIS_SETCURSOR\fR\fR
78 -.ad
79 -.RS 21n
81 +.Ed
82 +.Pp
83 +.It Dv VIS_GETCURSOR
84 +.It Dv VIS_SETCURSOR
80 85 These ioctls fetch and set various cursor attributes, using the
81 -\fBvis_cursor\fR structure.
82 -.sp
83 -.in +2
84 -.nf
86 +.Vt vis_cursor
87 +structure.
88 +.Bd -literal -offset 2n
85 89 struct vis_cursorpos {
86 - short x; /* cursor x coordinate */
87 - short y; /* cursor y coordinate */
90 + short x; /* cursor x coordinate */
91 + short y; /* cursor y coordinate */
88 92 };
89 93
90 94 struct vis_cursorcmap {
91 - int version; /* version */
92 - int reserved;
93 - unsigned char *red; /* red color map elements */
94 - unsigned char *green;/* green color map elements */
95 - unsigned char *blue; /* blue color map elements */
95 + int version; /* version */
96 + int reserved;
97 + /* red color map elements */
98 + unsigned char *red;
99 + /* green color map elements */
100 + unsigned char *green;
101 + /* blue color map elements */
102 + unsigned char *blue;
96 103 };
97 104
98 105 #define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */
99 -#define VIS_CURSOR_SETPOSITION 0x02 /* set cursor position */
100 -#define VIS_CURSOR_SETHOTSPOT 0x04 /* set cursor hot spot */
101 -#define VIS_CURSOR_SETCOLORMAP 0x08 /* set cursor colormap */
102 -#define VIS_CURSOR_SETSHAPE 0x10 /* set cursor shape */
106 + /* set cursor position */
107 +#define VIS_CURSOR_SETPOSITION 0x02
108 + /* set cursur hot spot */
109 +#define VIS_CURSOR_SETHOTSPOT 0x04
110 + /* set cursor colormap */
111 +#define VIS_CURSOR_SETCOLORMAP 0x08
112 + /* set cursor shape */
113 +#define VIS_CURSOR_SETSHAPE 0x10
103 114 #define VIS_CURSOR_SETALL \e
104 115 (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \e
105 116 VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \e
106 117 VIS_CURSOR_SETSHAPE)
107 118
108 119 struct vis_cursor {
109 - short set; /* what to set */
110 - short enable; /* cursor on/off */
111 - struct vis_cursorpos pos; /* cursor position */
112 - struct vis_cursorpos hot; /* cursor hot spot */
113 - struct vis_cursorcmap cmap; /* color map info */
114 - struct vis_cursorpos size; /* cursor bitmap size */
115 - char *image; /* cursor image bits */
116 - char *mask; /* cursor mask bits */
120 + short set; /* what to set */
121 + short enable; /* cursor on/off */
122 + struct vis_cursorpos pos; /* cursor position */
123 + struct vis_cursorpos hot; /* cursor hot spot */
124 + struct vis_cursorcmap cmap; /* color map info */
125 + /* cursor bitmap size */
126 + struct vis_cursorpos size;
127 + char *image; /* cursor image bits */
128 + char *mask; /* cursor mask bits */
117 129 };
118 -.fi
119 -.in -2
120 -
121 -.RE
122 -
123 -.sp
124 -.LP
125 -The \fBvis_cursorcmap\fR structure should contain pointers to two elements,
130 +.Ed
131 +.Pp
132 +The
133 +.Vt vis_cursorcmap
134 +structure should contain pointers to two elements,
126 135 specifying the red, green, and blue values for foreground and background.
127 -.sp
128 -.ne 2
129 -.na
130 -\fB\fBVIS_SETCURSORPOS\fR\fR
131 -.ad
132 -.br
133 -.na
134 -\fB\fBVIS_MOVECURSOR\fR\fR
135 -.ad
136 -.RS 20n
136 +.Pp
137 +.It Dv VIS_SETCURSORPOS
138 +.It Dv VIS_MOVECURSOR
137 139 These ioctls fetch and move the current cursor position, using the
138 -\fBvis_cursorpos\fR structure.
139 -.RE
140 -
141 -.SS "Console Optional Ioctls"
142 -.sp
143 -.LP
140 +.Vt vis_cursorpos
141 +structure.
142 +.El
143 +.Ss "Console Optional Ioctls"
144 144 The following ioctl sets are used by graphics drivers that are part of the
145 -system console device. All of the ioctls must be implemented to be a console
146 -device. In addition, if the system does not have a prom or the prom goes away
145 +system console device.
146 +All of the ioctls must be implemented to be a console device.
147 +In addition, if the system does not have a prom or the prom goes away
147 148 during boot, the special standalone ioctls (listed below) must also be
148 149 implemented.
149 -.sp
150 -.LP
150 +.Pp
151 151 The coordinate system for the console device places 0,0 at the upper left
152 152 corner of the device, with rows increasing toward the bottom of the device and
153 153 columns increasing from left to right.
154 -.sp
155 -.ne 2
156 -.na
157 -\fBVIS_PUTCMAP\fR
158 -.ad
159 -.br
160 -.na
161 -\fB\fBVIS_GETCMAP\fR\fR
162 -.ad
163 -.RS 15n
154 +.Pp
155 +.Bl -tag -width VIS_CONSDISPLAY -compact -offset 2n
156 +.It Dv VIS_PUTCMAP
157 +.It Dv VIS_GETCMAP
164 158 Set or get color map entries.
165 -.RE
166 -
167 -.sp
168 -.LP
169 -The argument is a pointer to a \fBvis_cmap\fR structure, which contains the
159 +.Pp
160 +The argument is a pointer to a
161 +.Vt vis_cmap
162 +structure, which contains the
170 163 following fields:
171 -.sp
172 -.in +2
173 -.nf
164 +.Bd -literal -offset 2n
174 165 struct vis_cmap {
175 - int index;
176 - int count;
166 + int index;
167 + int count;
177 168 uchar_t *red;
178 169 uchar_t *green;
179 170 uchar_t *blue;
180 171 }
181 -.fi
182 -.in -2
183 -
184 -.sp
185 -.LP
186 -\fBindex\fR is the starting index in the color map where you want to start
172 +.Ed
173 +.Pp
174 +.Fa index
175 +is the starting index in the color map where you want to start
187 176 setting or getting color map entries.
188 -.sp
189 -.LP
190 -\fBcount\fR is the number of color map entries to set or get. It also is the
191 -size of the \fBred\fR, \fBgreen\fR, and \fBblue\fR color arrays.
192 -.sp
193 -.LP
194 -\fB*red\fR, \fB*green\fR, and \fB*blue\fR are pointers to unsigned character
195 -arrays which contain the color map info to set or where the color map info is
196 -placed on a get.
197 -.sp
198 -.ne 2
199 -.na
200 -\fB\fBVIS_DEVINIT\fR\fR
201 -.ad
202 -.RS 15n
177 +.Pp
178 +.Fa count
179 +is the number of color map entries to set or get.
180 +It also is the
181 +size of the
182 +.Fa red ,
183 +.Fa green ,
184 +and
185 +.Fa blue
186 +color arrays.
187 +.Pp
188 +.Fa *red ,
189 +.Fa *green ,
190 +and
191 +.Fa *blue
192 +are pointers to unsigned character arrays which contain the color map info to
193 +set or where the color map info is placed on a get.
194 +.Pp
195 +.It Dv VIS_DEVINIT
203 196 Initializes the graphics driver as a console device.
204 -.RE
205 -
206 -.sp
207 -.LP
208 -The argument is a pointer to a \fBvis_devinit\fR structure. The graphics driver
197 +.Pp
198 +The argument is a pointer to a
199 +.Vt vis_devinit
200 +structure.
201 +The graphics driver
209 202 is expected to allocate any local state information needed to be a console
210 203 device and fill in this structure.
211 -.sp
212 -.in +2
213 -.nf
204 +.Bd -literal -offset 2n
214 205 struct vis_devinit {
215 206 int version;
216 207 screen_size_t width;
217 208 screen_size_t height;
218 209 screen_size_t linebytes;
219 - unit_t size;
220 - int depth;
221 - short mode;
210 + unit_t size;
211 + int depth;
212 + short mode;
222 213 struct vis_polledio *polledio;
223 214 vis_modechg_cb_t modechg_cb;
224 215 struct vis_modechg_arg *modechg_arg;
225 216 };
226 -.fi
227 -.in -2
228 -
229 -.sp
230 -.LP
231 -\fBversion\fR is the version of this structure and should be set to
232 -\fBVIS_CONS_REV\fR.
233 -.sp
234 -.LP
235 -\fBwidth\fR and \fBheight\fR are the width and height of the device. If
236 -\fBmode\fR (see below) is \fBVIS_TEXT\fR then \fBwidth\fR and \fBheight\fR are
237 -the number of characters wide and high of the device. If \fBmode\fR is
238 -\fBVIS_PIXEL\fR then \fBwidth\fR and \fBheight\fR are the number of pixels wide
239 -and high of the device.
240 -.sp
241 -.LP
242 -\fBlinebytes\fR is the number of bytes per line of the device.
243 -.sp
244 -.LP
245 -\fBsize\fR is the total size of the device in pixels.
246 -.sp
247 -.LP
248 -\fBdepth\fR is the pixel depth in device bits. Currently supported depths are:
249 -\fB1\fR, \fB4\fR, \fB8\fR and \fB24\fR.
250 -.sp
251 -.LP
252 -\fBmode\fR is the mode of the device. Either \fBVIS_PIXEL\fR (data to be
253 -displayed is in bitmap format) or \fBVIS_TEXT\fR (data to be displayed is in
254 -ascii format).
255 -.sp
256 -.LP
257 -\fBpolledio\fR is used to pass the address of the structure containing the
217 +.Ed
218 +.Pp
219 +.Fa version
220 +is the version of this structure and should be set to
221 +.Dv VIS_CONS_REV .
222 +.Pp
223 +.Fa width
224 +and
225 +.Fa height
226 +are the width and height of the device.
227 +If
228 +.Fa mode
229 +(see below) is
230 +.Dv VIS_TEXT
231 +then
232 +.Fa width
233 +and
234 +.Fa height
235 +are the number of characters wide and high of the device.
236 +If
237 +.Fa mode
238 +is
239 +.Dv VIS_PIXEL
240 +then
241 +.Fa width
242 +and
243 +.Fa height
244 +are the number of pixels wide and high of the device.
245 +.Pp
246 +.Fa linebytes
247 +is the number of bytes per line of the device.
248 +.Pp
249 +.Fa size
250 +is the total size of the device in pixels.
251 +.Pp
252 +.Fa depth
253 +is the pixel depth in device bits.
254 +Currently supported depths are:
255 +.Sy 1 ,
256 +.Sy 4 ,
257 +.Sy 8
258 +and
259 +.Sy 24 .
260 +.Pp
261 +.Fa mode
262 +is the mode of the device.
263 +Either
264 +.Dv VIS_PIXEL
265 +(data to be displayed is in bitmap format) or
266 +.Dv VIS_TEXT
267 +(data to be displayed is in ascii format).
268 +.Pp
269 +.Fa polledio
270 +is used to pass the address of the structure containing the
258 271 standalone mode polled I/O entry points to the device driver back to the
259 -terminal emulator. The \fBvis_polledio\fR interfaces are described in the
260 -Console Standalone Entry Points section of this manpage. These entry points are
261 -where the operating system enters the driver when the system is running in
262 -standalone mode. These functions perform identically to the VIS_CONSDISPLAY,
263 -VIS_CONSCURSOR and VIS_CONSCOPY ioctls, but are called directly by the Solaris
272 +terminal emulator.
273 +The
274 +.Vt vis_polledio
275 +interfaces are described in the
276 +Console Standalone Entry Points section of this manpage.
277 +These entry points are where the operating system enters the driver when the
278 +system is running in standalone mode.
279 +These functions perform identically to the
280 +.Dv VIS_CONSDISPLAY ,
281 +.Dv VIS_CONSCURSOR ,
282 +and
283 +.Dv VIS_CONSCOPY
284 +ioctls, but are called directly by the illumos
264 285 operating environment and must operate under a very strict set of assumptions.
265 -.sp
266 -.LP
267 -\fBmodechg_cb\fR is a callback function passed from the terminal emulator to
286 +.Pp
287 +.Fa modechg_cb
288 +is a callback function passed from the terminal emulator to
268 289 the framebuffer driver which the frame-buffer driver must call whenever a video
269 -mode change event occurs that changes the screen height, width or depth. The
270 -callback takes two arguments, an opaque handle, \fBmodechg_arg\fR, and the
271 -address of a vis_devinit struct containing the new video mode information.
272 -.sp
273 -.LP
274 -\fBmodechg_arg\fR is an opaque handle passed from the terminal emulator to the
290 +mode change event occurs that changes the screen height, width or depth.
291 +The callback takes two arguments, an opaque handle,
292 +.Fa modechg_arg ,
293 +and the address of a
294 +.Vt vis_devinit
295 +struct containing the new video mode information.
296 +.Pp
297 +.Fa modechg_arg
298 +is an opaque handle passed from the terminal emulator to the
275 299 driver, which the driver must pass back to the terminal emulator as an argument
276 -to the \fBmodechg_cb\fR function when the driver notifies the terminal emulator
277 -of a video mode change.
278 -.sp
279 -.ne 2
280 -.na
281 -\fB\fBVIS_DEVFINI\fR\fR
282 -.ad
283 -.RS 18n
284 -Tells the graphics driver that it is no longer the system console device. There
285 -is no argument to this ioctl. The driver is expected to free any locally kept
300 +to the
301 +.Fa modechg_cb
302 +function when the driver notifies the terminal emulator of a video mode change.
303 +.Pp
304 +.It Dv VIS_DEVFINI
305 +Tells the graphics driver that it is no longer the system console device.
306 +There is no argument to this ioctl.
307 +The driver is expected to free any locally kept
286 308 state information related to the console.
287 -.RE
288 -
289 -.sp
290 -.ne 2
291 -.na
292 -\fB\fBVIS_CONSCURSOR\fR\fR
293 -.ad
294 -.RS 18n
295 -Describes the size and placement of the cursor on the screen. The graphics
309 +.Pp
310 +.It Dv VIS_CONSCURSOR
311 +Describes the size and placement of the cursor on the screen.
312 +The graphics
296 313 driver is expected to display or hide the cursor at the indicated position.
297 -.RE
298 -
299 -.sp
300 -.LP
301 -The argument is a pointer to a \fBvis_conscursor\fR structure which contains
314 +.Pp
315 +The argument is a pointer to a
316 +.Vt vis_conscursor
317 +structure which contains
302 318 the following fields:
303 -.sp
304 -.in +2
305 -.nf
319 +.Bd -literal -offset 2n
306 320 struct vis_conscursor {
307 321 screen_pos_t row;
308 322 screen_pos_t col;
309 323 screen_size_t width;
310 324 screen_size_t height
311 325 color_t fg_color;
312 326 color_t bg_color;
313 327 short action;
314 328 };
315 -.fi
316 -.in -2
317 -
318 -.sp
319 -.LP
320 -\fBrow\fR and \fBcol\fR are the first row and column (upper left corner of the
321 -cursor).
322 -.sp
323 -.LP
324 -\fBwidth\fR and \fBheight\fR are the width and height of the cursor.
325 -.sp
326 -.LP
327 -If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl is set to \fBVIS_PIXEL\fR, then
328 -\fBcol\fR, \fBrow\fR, \fBwidth\fR and \fBheight\fR are in pixels. If \fBmode\fR
329 -in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, then \fBcol\fR,
330 -\fBrow\fR, \fBwidth\fR and \fBheight\fR are in characters.
331 -.sp
332 -.LP
333 -\fBfg_color\fR and \fBbg_color\fR are the foreground and background color map
334 -indexes to use when the \fBaction\fR (see below) is set to
335 -\fBVIS_DISPLAY_CURSOR\fR.
336 -.sp
337 -.LP
338 -\fBaction\fR indicates whether to display or hide the cursor. It is set to
339 -either \fBVIS_HIDE_CURSOR\fR or \fBVIS_DISPLAY_CURSOR\fR.
340 -.sp
341 -.ne 2
342 -.na
343 -\fB\fBVIS_CONSDISPLAY\fR\fR
344 -.ad
345 -.RS 19n
346 -Display data on the graphics device. The graphics driver is expected to display
347 -the data contained in the \fBvis_display\fR structure at the specified
348 -position on the console.
349 -.RE
350 -
351 -.sp
352 -.LP
353 -The \fBvis_display\fR structure contains the following fields:
354 -.sp
355 -.in +2
356 -.nf
329 +.Ed
330 +.Pp
331 +.Fa row
332 +and
333 +.Fa col
334 +are the first row and column (upper left corner of the cursor).
335 +.Pp
336 +.Fa width
337 +and
338 +.Fa height
339 +are the width and height of the cursor.
340 +.Pp
341 +If
342 +.Fa mode
343 +in the
344 +.Dv VIS_DEVINIT
345 +ioctl is set to
346 +.Dv VIS_PIXEL ,
347 +then
348 +.Fa col ,
349 +.Fa row ,
350 +.Fa width
351 +and
352 +.Fa height
353 +are in pixels.
354 +If
355 +.Fa mode
356 +in the
357 +.Dv VIS_DEVINIT
358 +ioctl was set to
359 +.Dv VIS_TEXT ,
360 +then
361 +.Fa col ,
362 +.Fa row ,
363 +.Fa width
364 +and
365 +.Fa height
366 +are in characters.
367 +.Pp
368 +.Fa fg_color
369 +and
370 +.Fa bg_color
371 +are the foreground and background color map
372 +indexes to use when the
373 +.Fa action
374 +(see below) is set to
375 +.Dv VIS_DISPLAY_CURSOR .
376 +.Pp
377 +.Fa action
378 +indicates whether to display or hide the cursor.
379 +It is set to either
380 +.Dv VIS_HIDE_CURSOR
381 +or
382 +.Dv VIS_DISPLAY_CURSOR .
383 +.Pp
384 +.It Dv VIS_CONSDISPLAY
385 +Display data on the graphics device.
386 +The graphics driver is expected to display the data contained in the
387 +.Vt vis_display
388 +structure at the specified position on the console.
389 +.Pp
390 +The
391 +.Vt vis_display
392 +structure contains the following fields:
393 +.Bd -literal -offset 2n
357 394 struct vis_display {
358 395 screen_pos_t row;
359 396 screen_pos_t col;
360 397 screen_size_t width;
361 398 screen_size_t height;
362 399 uchar_t *data;
363 400 color_t fg_color;
364 401 color_t bg_color;
365 402 };
366 -.fi
367 -.in -2
368 -
369 -.sp
370 -.LP
371 -\fBrow\fR and \fBcol\fR specify at which starting row and column the date is to
372 -be displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
373 -\fBVIS_TEXT\fR, \fBrow\fR and \fBcol\fR are defined to be a character offset
374 -from the starting position of the console device. If \fBmode\fR in the
375 -\fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBrow\fR and \fBcol\fR
376 -are defined to be a pixel offset from the starting position of the console
403 +.Ed
404 +.Pp
405 +.Fa row
406 +and
407 +.Fa col
408 +specify at which starting row and column the date is to be displayed.
409 +If
410 +.Fa mode
411 +in the
412 +.Dv VIS_DEVINIT
413 +ioctl was set to
414 +.Dv VIS_TEXT ,
415 +.Fa row
416 +and
417 +.Fa col
418 +are defined to be a character offset
419 +from the starting position of the console device.
420 +If
421 +.Fa mode
422 +in the
423 +.Dv VIS_DEVINIT
424 +ioctl was set to
425 +.Dv VIS_PIXEL ,
426 +.Fa row
427 +and
428 +.Fa col
429 +are defined to be a pixel offset from the starting position of the console
377 430 device.
378 -.sp
379 -.LP
380 -\fBwidth\fR and \fBheight\fR specify the size of the \fBdata\fR to be
381 -displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
382 -\fBVIS_TEXT\fR, \fBwidth\fR and \fBheight\fR define the size of \fBdata\fR as
383 -a rectangle that is \fBwidth\fR characters wide and \fBheight\fR characters
384 -high. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR,
385 -\fBwidth\fR and \fBheight\fR define the size of \fBdata\fR as a rectangle that
386 -is \fBwidth\fR pixels wide and \fBheight\fR pixels high.
387 -.sp
388 -.LP
389 -\fB*data\fR is a pointer to the data to be displayed on the console device. If
390 -\fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, \fBdata\fR
391 -is an array of \fBASCII\fR characters to be displayed on the console device.
392 -The driver must break these characters up appropriately and display it in the
393 -retangle defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR. If
394 -\fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR,
395 -\fBdata\fR is an array of bitmap data to be displayed on the console device.
431 +.Pp
432 +.Fa width
433 +and
434 +.Fa height
435 +specify the size of the
436 +.Fa data
437 +to be displayed.
438 +If
439 +.Fa mode
440 +in the
441 +.Dv VIS_DEVINIT
442 +ioctl was set to
443 +.Dv VIS_TEXT ,
444 +.Fa width
445 +and
446 +.Fa height
447 +define the size of
448 +.Fa data
449 +as rectangle that is
450 +.Fa width
451 +characters wide and
452 +.Fa height
453 +characters high.
454 +If
455 +.Fa mode
456 +in the
457 +.Dv VIS_DEVINIT
458 +ioctl was set to
459 +.Dv VIS_PIXEL ,
460 +.Fa width
461 +and
462 +.Fa height
463 +define the size of
464 +.Fa data
465 +as a rectangle that is
466 +.Fa width
467 +pixels wide and
468 +.Fa height
469 +pixels high.
470 +.Pp
471 +.Fa *data
472 +is a pointer to the data to be displayed on the console device.
473 +If
474 +.Fa mode
475 +in the
476 +.Dv VIS_DEVINIT
477 +ioctl was set to
478 +.Dv VIS_TEXT ,
479 +.Fa data
480 +is an array of
481 +.Sy ASCII
482 +characters to be displayed on the console device.
483 +The driver must break these characters up appropriately and display it in the
484 +rectangle defined by
485 +.Fa row ,
486 +.Fa col ,
487 +.Fa width ,
488 +and
489 +.Fa height .
490 +If
491 +.Fa mode
492 +in the
493 +.Dv VIS_DEVINIT
494 +ioctl was set to
495 +.Dv VIS_PIXEL ,
496 +.Fa data
497 +is an array of bitmap data to be displayed on the console device.
396 498 The driver must break this data up appropriately and display it in the retangle
397 -defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR.
398 -.sp
399 -.LP
400 -The \fBfg_color\fR and \fBbg_color\fR fields define the foreground and
401 -background color map indexes to use when displaying the data. \fBfb_color\fR is
402 -used for "on" pixels and \fBbg_color\fR is used for "off" pixels.
403 -.sp
404 -.ne 2
405 -.na
406 -\fB\fBVIS_CONSCOPY\fR\fR
407 -.ad
408 -.RS 16n
409 -Copy data from one location on the device to another. The driver is expected
410 -to copy the specified data. The source data should not be modified. Any
411 -modifications to the source data should be as a side effect of the copy
499 +defined by
500 +.Fa row ,
501 +.Fa col ,
502 +.Fa width ,
503 +and
504 +.Fa height .
505 +.Pp
506 +The
507 +.Fa fg_color
508 +and
509 +.Fa bg_color
510 +fields define the foreground and
511 +background color map indexes to use when displaying the data.
512 +.Fa fb_color
513 +is used for
514 +.Dq on
515 +pixels and
516 +.Fa bg_color
517 +is used for
518 +.Dq off
519 +pixels.
520 +.Pp
521 +.It Dv VIS_CONSCOPY
522 +Copy data from one location on the device to another.
523 +The driver is expected to copy the specified data.
524 +The source data should not be modified.
525 +Any modifications to the source data should be as a side effect of the copy
412 526 destination overlapping the copy source.
413 -.RE
414 -
415 -.sp
416 -.LP
417 -The argument is a pointer to a \fBvis_copy\fR structure which contains the
418 -following fields:
419 -.sp
420 -.in +2
421 -.nf
527 +.Pp
528 +The argument is a pointer to a
529 +.Vt vis_copy
530 +structure which contains the following fields:
531 +.Bd -literal -offset 2n
422 532 struct vis_copy {
423 533 screen_pos_t s_row;
424 534 screen_pos_t s_col;
425 535 screen_pos_t e_row;
426 536 screen_pos_t e_col;
427 537 screen_pos_t t_row;
428 538 screen_pos_t t_col;
429 539 short direction;
430 540 };
431 -.fi
432 -.in -2
433 -
434 -.sp
435 -.LP
436 -\fBs_row\fR, \fBs_col\fR, \fBe_row\fR, and \fBe_col\fR define the source
437 -rectangle of the copy. \fBs_row\fR and \fBs_col\fR are the upper left corner of
438 -the source rectangle. \fBe_row\fR and \fBe_col\fR are the lower right corner of
439 -the source rectangle. If \fBmode\fR in the \fBVIS_DEVINIT\fR \fBioctl()\fR was
440 -set to \fBVIS_TEXT\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR
441 -are defined to be character offsets from the starting position of the console
442 -device. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to
443 -\fBVIS_PIXEL\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR are
444 -defined to be pixel offsets from the starting position of the console device.
445 -.sp
446 -.LP
447 -\fBt_row\fR and \fBt_col\fR define the upper left corner of the destination
448 -rectangle of the copy. The entire rectangle is copied to this location. If
449 -\fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR,
450 -\fBt_row\fR, and \fBt_col\fR are defined to be character offsets from the
451 -starting position of the console device. If \fBmode\fR in the
452 -\fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBt_row\fR, and
453 -\fBt_col\fR are defined to be pixel offsets from the starting position of the
454 -console device.
455 -.sp
456 -.LP
457 -\fBdirection\fR specifies which way to do the copy. If direction is
458 -\fBVIS_COPY_FORWARD\fR the graphics driver should copy data from position
459 -(\fBs_row\fR, \fBs_col\fR) in the source rectangle to position (\fBt_row\fR,
460 -\fBt_col\fR) in the destination rectangle. If direction is
461 -\fBVIS_COPY_BACKWARDS\fR the graphics driver should copy data from position
462 -(\fBe_row\fR, \fBe_col\fR) in the source rectangle to position
463 -\fB(t_row+(e_row-s_row)\fR, \fBt_col+(e_col-s_col))\fR in the destination
464 -rectangle.
465 -.SS "Console Standalone Entry Points (Polled I/O Interfaces)"
466 -.sp
467 -.LP
541 +.Ed
542 +.Pp
543 +.Fa s_row ,
544 +.Fa s_col ,
545 +.Fa e_row ,
546 +and
547 +.Fa e_col
548 +define the source rectangle of the copy.
549 +.Fa s_row
550 +and
551 +.Fa s_col
552 +are the upper left corner of the source rectangle.
553 +.Fa e_row
554 +and
555 +.Fa e_col
556 +are the lower right corner of the source rectangle.
557 +If
558 +.Fa mode
559 +in the
560 +.Dv VIS_DEVINIT
561 +.Fn ioctl
562 +was set to
563 +.Dv VIS_TEXT ,
564 +.Fa s_row ,
565 +.Fa s_col ,
566 +.Fa e_row ,
567 +and
568 +.Fa e_col
569 +are defined to be character offsets from the starting position of the console
570 +device.
571 +If
572 +.Fa mode
573 +in the
574 +.Dv VIS_DEVINIT
575 +.Fn ioctl
576 +was set to
577 +.Dv VIS_PIXEL ,
578 +.Fa s_row ,
579 +.Fa s_col ,
580 +.Fa e_row ,
581 +and
582 +.Fa e_col
583 +are
584 +defined to be pixel offsets from the starting position of the console device.
585 +.Pp
586 +.Fa t_row
587 +and
588 +.Fa t_col
589 +define the upper left corner of the destination rectangle of the copy.
590 +The entire rectangle is copied to this location.
591 +If
592 +.Fa mode
593 +in the
594 +.Dv VIS_DEVINIT
595 +ioctl was set to
596 +.Dv VIS_TEXT ,
597 +.Fa t_row ,
598 +and
599 +.Fa t_col
600 +are defined to be character offsets from the
601 +starting position of the console device.
602 +If
603 +.Fa mode
604 +in the
605 +.Dv VIS_DEVINIT
606 +ioctl was set to
607 +.Dv VIS_PIXEL ,
608 +.Fa t_row ,
609 +and
610 +.Fa t_col
611 +are defined to be pixel offsets from the starting position of the
612 +onssole device.
613 +.Pp
614 +.Fa direction
615 +specifies which way to do the copy.
616 +If direction is
617 +.Dv VIS_COPY_FORWARD
618 +the graphics driver should copy data from position
619 +.Po
620 +.Fa s_row ,
621 +.Fa s_col
622 +.Pc
623 +in the source rectangle to position
624 +.Po
625 +.Fa t_row ,
626 +.Fa t_col
627 +.Pc
628 +in the destination rectangle.
629 +If direction is
630 +.Dv VIS_COPY_BACKWARDS
631 +the graphics driver should copy data from position
632 +.Po
633 +.Fa e_row ,
634 +.Fa e_col
635 +.Pc
636 +in the source rectangle to position
637 +.Po
638 +.Fa t_row Ns + Ns
639 +.Po
640 +.Fa e_row Ns \- Ns
641 +.Fa s_row
642 +.Pc ,
643 +.Fa t_col Ns + Ns
644 +.Po
645 +.Fa e_col Ns \- Ns
646 +.Fa s_col
647 +.Pc
648 +.Pc
649 +in the destination rectangle.
650 +.El
651 +.Ss "Console Standalone Entry Points (Polled I/O Interfaces)"
468 652 Console standalone entry points are necessary only if the driver is
469 -implementing console-compatible extensions. All console vectored standalone
653 +implementing console-compatible extensions.
654 +All console vectored standalone
470 655 entry points must be implemented along with all console-related ioctls if the
471 656 console extension is implemented.
472 -.sp
473 -.in +2
474 -.nf
657 +.Bd -literal -offset 2n
475 658 struct vis_polledio {
476 659 struct vis_polledio_arg *arg;
477 660 void (*display)(vis_polledio_arg *, struct vis_consdisplay *);
478 661 void (*copy)(vis_polledio_arg *, struct vis_conscopy *);
479 662 void (*cursor)(vis_polledio_arg *, struct vis_conscursor *);
480 663 };
481 -.fi
482 -.in -2
483 -
484 -.sp
485 -.LP
486 -The \fBvis_polledio\fR structure is passed from the driver to the Solaris
664 +.Ed
665 +.Pp
666 +The
667 +.Vt vis_polledio
668 +structure is passed from the driver to the illumos
487 669 operating environment, conveying the entry point addresses of three functions
488 670 which perform the same operations of their similarly named ioctl counterparts.
489 671 The rendering parameters for each entry point are derived from the same
490 -structure passed as the respective ioctl. See the Console Optional Ioctls
672 +structure passed as the respective ioctl.
673 +See the
674 +.Sx "Console Optional Ioctls"
491 675 section of this manpage for an explanation of the specific function each of the
492 -entry points, display(), copy() and cursor() are required to implement. In
676 +entry points,
677 +.Fn display ,
678 +.Fn copy ,
679 +and
680 +.Fn cursor
681 +are required to implement.
682 +In
493 683 addition to performing the prescribed function of their ioctl counterparts, the
494 684 standalone vectors operate in a special context and must adhere to a strict set
495 -of rules. The polled I/O vectors are called directly whenever the system is
685 +of rules.
686 +The polled I/O vectors are called directly whenever the system is
496 687 quisced (running in a limited context) and must send output to the display.
497 688 Standalone mode describes the state in which the system is running in
498 -single-threaded mode and only one processor is active. Solaris operating
689 +single-threaded mode and only one processor is active.
690 +illumos operating
499 691 environment services are stopped, along with all other threads on the system,
500 -prior to entering any of the polled I/O interfaces. The polled I/O vectors are
692 +prior to entering any of the polled I/O interfaces.
693 +The polled I/O vectors are
501 694 called when the system is running in a standalone debugger, when executing the
502 695 PROM monitor (OBP) or when panicking.
503 -.sp
504 -.LP
696 +.Pp
505 697 The following restrictions must be observed in the polled I/O functions:
506 -.RS +4
507 -.TP
508 -1.
698 +.Bl -enum -offset indent
699 +.It
509 700 The driver must not allocate memory.
510 -.RE
511 -.RS +4
512 -.TP
513 -2.
701 +.It
514 702 The driver must not wait on mutexes.
515 -.RE
516 -.RS +4
517 -.TP
518 -3.
703 +.It
519 704 The driver must not wait for interrupts.
520 -.RE
521 -.RS +4
522 -.TP
523 -4.
705 +.It
524 706 The driver must not call any DDI or LDI services.
525 -.RE
526 -.RS +4
527 -.TP
528 -5.
707 +.It
529 708 The driver must not call any system services.
530 -.RE
531 -.sp
532 -.LP
709 +.El
710 +.Pp
533 711 The system is single-threaded when calling these functions, meaning that all
534 -other threads are effectively halted. Single-threading makes mutexes (which
712 +other threads are effectively halted.
713 +Single-threading makes mutexes (which
535 714 cannot be held) easier to deal with, so long as the driver does not disturb any
536 -shared state. See \fIWriting Device Drivers\fR for more information about
537 -implementing polled I/O entry points.
538 -.SH SEE ALSO
539 -.sp
540 -.LP
541 -\fBioctl\fR(2)
542 -.sp
543 -.LP
544 -\fIWriting Device Drivers\fR
545 -.SH NOTES
546 -.sp
547 -.LP
715 +shared state.
716 +See
717 +.%T Writing Device Drivers
718 +for more information about implementing polled I/O entry points.
719 +.Sh SEE ALSO
720 +.Xr ioctl 2
721 +.Rs
722 +.%T Writing Device Drivers
723 +.Re
724 +.Sh NOTES
548 725 On SPARC systems, compatible drivers supporting the kernel terminal emulator
549 -should export the \fBtem-support\fR DDI property.\fBtem-support\fR indicates
550 -that the driver supports the kernel terminal emulator. By exporting
551 -\fBtem-support\fR it's possible to avoid premature handling of an incompatible
552 -driver.
553 -.sp
554 -.ne 2
555 -.na
556 -\fBtem-support\fR
557 -.ad
558 -.RS 15n
726 +should export the
727 +.Sy tem-support
728 +DDI property.
729 +.Sy tem-support
730 +indicates that the driver supports the kernel terminal emulator.
731 +By exporting
732 +.Sy tem-support
733 +it's possible to avoid premature handling of an incompatible driver.
734 +.Bl -tag -width tem-support
735 +.It Sy tem-support
559 736 This DDI property, set to 1, means driver is compatible with the console
560 737 kernel framebuffer interface.
561 -.RE
562 -
738 +.El
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX