Subject: Sanity-check: wsdisplay(4) ioctl docs
To: None <tech-kern@netbsd.org>
From: Ben Harris <bjh21@netbsd.org>
List: tech-kern
Date: 06/22/2002 20:16:55
I've just committed some documentation of some of the ioctls supported by
wsdisplay(4) drivers. I'm not sure that it's all correct, though, since I
had to base it on the existing implementations. Could people who've used
these interfaces please take a look and tell me what I've got wrong?
Come to that, input from other people would be useful too. Here's what
I've added to wsdisplay(4):
IOCTLS
The following ioctl(2) calls are provided by the wsdisplay driver or by
devices which use it. Their definitions are found in
<dev/wscons/wsconsio.h>.
WSDISPLAYIO_GTYPE (int)
Retrieve the type of the display. The list of types is in
<dev/wscons/wsconsio.h>.
WSDISPLAYIO_GINFO (struct wsdisplay_fbinfo)
Retrieve basic information about a framebuffer display.
The returned structure is as follows:
struct wsdisplay_fbinfo {
u_int height;
u_int width;
u_int depth;
u_int cmsize;
};
The height and width members are counted in pixels. The
depth member indicates the number of bits per pixel, and
cmsize indicates the number of color map entries accessible
through WSDISPLAYIO_GETCMAP and WSDISPLAYIO_PUTCMAP. This
call is likely to be unavailable on text-only displays.
WSDISPLAYIO_GETCMAP (struct wsdisplay_cmap)
Retrieve the current color map from the display. This call
needs the following structure set up beforehand:
struct wsdisplay_cmap {
u_int index;
u_int count;
u_char *red;
u_char *green;
u_char *blue;
};
The index and count members specify the range of color map
entries to retrieve. The red, green and blue members
should each point to an array of count u_chars. On return,
these will be filled in with the appropriate entries from
the color map. On all displays that support this call,
values range from 0 for minimum intensity to 255 for maxi-
mum intensity, even if the display does not use eight bits
internally to represent intensity.
WSDISPLAYIO_PUTCMAP (struct wsdisplay_cmap)
Change the display's color map. The argument structure is
the same as for WSDISPLAYIO_GETCMAP, but red, green and
blue are taken as pointers to the values to use to set the
color map. This call is not available on displays with
fixed color maps.
WSDISPLAYIO_GVIDEO (int)
Get the current state of the display's video output. Pos-
sible values are:
WSDISPLAYIO_VIDEO_OFF
The display is blanked.
WSDISPLAYIO_VIDEO_ON
The display is enabled.
WSDISPLAYIO_SVIDEO (int)
Set the state of the display's video output. See
WSDISPLAYIO_GVIDEO above for possible values.
WSDISPLAYIO_GCURPOS (struct wsdisplay_curpos)
Retrieve the current position of the hardware cursor. The
returned structure is as follows:
struct wsdisplay_curpos {
u_int x, y;
};
The x and y members count the number of pixels right and
down, respectively, from the top-left corner of the display
to the hot spot of the cursor. This call is not available
on displays without a hardware cursor.
WSDISPLAYOP_SCURPOS (struct wsdisplay_curpos)
Set the current cursor position. The argument structure,
and its semantics, are the same as for WSDISPLAYIO_GCURPOS.
This call is not avilable on displays without a hardware
cursor.
WSDISPLAYIO_GCURMAX (struct wsdisplay_curpos)
Retrieve the maximum size of cursor supported by the dis-
play. The x and y members of the returned structure indi-
cate the maximum number of pixel rows and columns, respec-
tively, in a hardware cursor on this display. This call is
not available on displays without a hardware cursor.
WSDISPLAYIO_GCURSOR (struct wsdisplay_cursor)
Retrieve some or all of the hardware cursor's attributes.
The argument structure is as follows:
struct wsdisplay_cursor {
u_int which;
u_int enable;
struct wsdisplay_curpos pos;
struct wsdisplay_curpos hot;
struct wsdisplay_cmap cmap;
struct wsdisplay_curpos size;
u_char *image;
u_char *mask;
};
The which member indicates which of the values the applica-
tion requires to be returned. It should contain the logi-
cal OR of the following flags:
WSDISPLAYIO_CURSOR_DOCUR
Get enable, which indicates whether the cur-
sor is currently displayed (non-zero) or not
(zero).
WSDISPLAYIO_CURSOR_DOPOS
Get pos, which indicates the current position
of the cursor on the display, as would be re-
turned by WSDISPLAYIO_GCURPOS.
WSDISPLAYIO_CURSOR_DOHOT
Get hot, which indicates the location of the
``hot spot'' within the cursor. This is the
point on the cursor whose position on the
display is treated as being the position of
the cursor by other calls. Its location is
counted in pixels from the top-right corner
of the cursor.
WSDISPLAYIO_CURSOR_DOCMAP
Get cmap, which indicates the current cursor
color map. Unlike in a call to
WSDISPLAYIO_GETCMAP, cmap here need not have
its index and count members initialised.
They will be set to 0 and 2 respectively by
the call. This means that cmap.red,
cmap.green, and cmap.blue must each point to
at least enough space to hold two u_chars.
WSDISPLAYIO_CURSOR_DOSHAPE
Get size, image, and mask. These are, re-
spectively, the dimensions of the cursor in
pixels, the bitmap of set pixels in the cur-
sor and the bitmap of opaque pixels in the
cursor. The format in which these bitmaps
are returned, and hence the amount of space
that must be provided by the application, are
device-dependent.
WSDISPLAYIO_CURSOR_DOALL
Get all of the above.
The device my elect to return information that was not re-
quested by the user, so those elements of struct
wsdisplay_cursor which are pointers should be initialised
to NULL if not otherwise used. This call is not available
on displays without a hardware cursor.
WSDISPLAYIO_SCURSOR (struct wsdisplay_cursor)
Set some or all of the hardware cursor's attributes. The
argument structure is the same as for WSDISPLAYIO_GCURSOR.
The which member specifies which attributes of the cursor
are to be changed. It should contain the logical OR of the
following flags:
WSDISPLAYIO_CURSOR_DOCUR
If enable is zero, hide the cursor. Other-
wise, display it.
WSDISPLAYIO_CURSOR_DOPOS
Set the cursor's position on the display to
pos, the same as WSDISPLAYIO_SCURPOS.
WSDISPLAYIO_CURSOR_DOHOT
Set the ``hot spot'' of the cursor, as de-
fined above, to hot.
WSDISPLAYIO_CURSOR_DOCMAP
Set some or all of the cursor color map based
on cmap. The index and count elements of
cmap indicate which color map entries to set,
and the entries themselves come from
cmap.red, cmap.green, and cmap.blue.
WSDISPLAYIO_CURSOR_DOSHAPE
Set the cursor shape from size, image, and
mask. See above for their meanings.
WSDISPLAYIO_CURSOR_DOALL
Do all of the above.
This call is not available on displays without a hardware
cursor.
WSDISPLAYIO_GMODE (u_int)
Get the current mode of the display. Possible results in-
clude:
WSDISPLAYIO_MODE_EMUL
The display is in emulating (text) mode.
WSDISPLAYIO_MODE_MAPPED
The display is in mapped (graphics) mode.
WSDISPLAYIO_SMODE (u_int)
Set the current mode of the display. For possible argu-
ments, see WSDISPLAYIO_GMODE.
--
Ben Harris <bjh21@netbsd.org>
Portmaster, NetBSD/acorn26 <URL:http://www.netbsd.org/Ports/acorn26/>