bmd(7)
_________________________________________________________________
bmd Special File
(bit mapped display) DS/7000 series graphics display interface
_________________________________________________________________
DESCRIPTION
The bmd driver is the interface that provides kernel support for
the GIS II graphics instruction set provided on DS/7000 series
workstations. Concepts of graphics management under GIS II are
described fully in Chapter 7 of the ECLIPSE MV/Family 32-Bit
Systems Principles of Operation; the GIS II instructions are
described in the Instruction Dictionary contained within the same
manual. This manual page will give an overview of graphics
management under GIS II, and detail the support provided by the
bmd driver. All command codes and structures mentioned are
defined in the include file <sys/bmd.h>. See ioctl(2) for
information on how to use the system call.
The bmd is an exclusive-open device, meaning that if the bmd is
open, further attempts to open will fail until the bmd is closed.
This does not preclude multiple processes having open file
descriptors to the bmd, however; when a process forks a child,
the child inherits the file descriptors of the parent.
When the bmd is closed (via close(2)), all resources allocated to
the bmd (see below) are freed, and the bmd may be opened again by
another process.
Input events in the form described below are received by a
program via the read(2) system call. Write(2) simply returns
ENODEV in the external variable errno; screen graphics are
performed via the GIS II graphics instruction set.
A program interacts with the bmd using the ioctl commands
described below. Select(2) requests for reading are satisfied
when input events become available.
Bmd Characteristics
The bmd driver serves a range of graphics displays and pointer
devices. The BMD_GET_INFO ioctl returns current information
about a bmd.
The third argument to ioctl is a pointer to the following
structure type:
struct bmdgetinfo {
unsigned short sizex;
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
bmd(7)
unsigned short sizey;
unsigned short pixdepth;
unsigned short colordepth;
unsigned short displaytype;
unsigned short inputcontrol;
unsigned short akuplang;
unsigned short akupstat;
unsigned short ptdtype;
unsigned short ptddimensions;
unsigned short ptdnumbuttons;
};
The fields are all filled in with the current values. The size_x
and size_y fields are the size of the screen in pixels, and
pix_depth is the number of bits per pixel in the screen buffer.
Color_depth is the number of bits per color in the colormap that
can be used by the display (see the Palette Management section
below). The display_type is one of BMD_COLOR_DISPLAY, which
indicates that the palette red, green, and blue entries will be
used; BMD_MONOCHROME_DISPLAY, which indicates only on or off are
available (no palette); or BMD_GRAY_SCALE_DISPLAY, indicating
that the gray values in the palette entries will be used.
Input_control is a set of flags by which an application may
control the nature of input events. Currently defined flags are
BMD_INPUT_COMPRESS, which requests that consecutive mouse motion
events be combined into a single event, and
BMD_SUPPRESS_BUTTON_UP, which requests that button-up events be
suppressed. These flags are modified using the BMD_INPUT_CONTROL
ioctl, as described in "Device Control," below.
Akup_lang is the hardware-encoded language code of the keyboard;
consult documentation on the akup keyboard hardware for a
definition of the language codes.
Akup_stat is the current status of the keyboard LED and bell
attributes. The status word consists of a set of bit positions,
one for each LED on the keyboard, and one for the bell. The
flags are BMD_AKUP_ALP_LED (alpha lock LED), BMD_AKUP_ONLINE_LED,
BMD_AKUP_BELL, BMD_AKUP_F19_LED (function key 19 LED), and
BMD_AKUP_F20_LED. The LED's and bell are modified using the
BMD_SET_AKUP_STAT ioctl, as described in "Device Control," below.
Ptd_type is one of BMD_PTD_RELATIVE (relative motions are
reported) or BMD_PTD_ABSOLUTE (absolute cursor positions are
reported). Ptd_dimensions gives the number of dimensions
reported in mouse events (see "Input," below). Ptd_num_buttons
gives the number of buttons present on the mouse.
Ioctl will return -1 and the external variable errno will be set
to EFAULT (as defined in <sys/errno.h>) if the structure address
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
bmd(7)
passed in is invalid.
Forms
A "form" is the basic graphics entity with which the GIS II
microcode deals. Each pixelmap is a form which may or may not be
represented on any physical screen. All the GIS II instructions
use the contents of AC1 as a form id to identify the target form.
The "form descriptor" is a database by which the GIS II microcode
can access all necessary information about a given form. Some of
the information is contained in the descriptor itself, and some
information is kept in separate structures whose addresses are
kept in the form descriptor.
The form abstraction allows a pixelmap to reside either entirely
in screen memory, entirely in host memory, or partly in each.
The bmd driver supports only the first two types of forms. The
pixelmaps of screen-resident forms reside fully on the screen,
and are the size of the entire screen. The pixelmaps of memory-
resident forms reside fully in the application's address space.
Graphics instructions using a screen-resident form id will affect
the actual screen. Executing a GIS II instruction using a
memory-resident form affects "pixels" in a memory array in the
application's address space.
Form Management
Forms are created and deleted via the ioctl system call, using
special command codes specific to the bmd device. When the
process opens the bmd, no forms are available for use in graphics
instructions. The application may create screen-resident (or
physical) forms, which are the size and pixel depth of the
physical display. The application may create memory-resident
forms, specifying any size and pixel depth, subject to GIS II
restrictions. In the case of memory-resident forms, the
application is responsible for allocating memory for the memory-
resident pixelmaps.
As described above, multiple processes may have the bmd open at
once. However, forms are per-process resources, so each process
must maintain its own set of screen and memory forms; attempts by
a child process to use form descriptors created by its parent are
invalid, and will result in termination of the child process.
When the bmd is closed for the last time, all physical and memory
forms associated with that particular bmd are deleted, and the
bmd may be opened again.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
bmd(7)
The following ioctl command codes are available for form
management.
BMDCREATEPHYSFORM
This ioctl is used by a process to create a physical (screen-
resident) form for use in graphics instructions. The screen form
must be created in order to perform graphics to the physical
display.
The created form will have the width, height, and pixel depth of
the physical display.
The third argument to ioctl is the address of a short, in which
the form id will be returned.
In the event of failure, ioctl will return -1 and the following
error code may be returned in errno:
EFAULT The address to hold the form id was invalid.
BMDCREATEMEMFORM
The BMD_CREATE_MEM_FORM ioctl creates a memory-resident form for
the application, and returns the form id for use in GIS II
instructions. The third argument to ioctl is a pointer to the
structure of the following type:
struct bmdcreatememform {
unsigned short sizex;
unsigned short sizey;
unsigned short pixdepth;
short *pmapaddr;
short formid;
};
The application fills in the size_x, size_y, pix_depth, and
pmap_addr fields with the desired values. The size_x field must
be a power of two, and the pix_depth field must be a power of two
less than 32; these are restrictions imposed by GIS II
instruction set.
Pmap_addr is the word address of the memory pixelmap to which the
form will refer. Allocation of memory (via sbrk(2), the library
routine malloc(3), or some other means) for the pixelmap is the
responsibility of the caller. No attempt is made to validate the
address passed in; execution of GIS II instructions on a form
with an invalid pmap_addr will result in a validity violation,
and the process will abort. The pmap_addr may be set later or
changed using the BMD_SET_PMAP_ADDR ioctl.
If the creation of the memory-resident form fails, ioctl will
return -1 and the following error codes may be returned in errno:
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
bmd(7)
EFAULT The structure address was invalid.
EINVAL The size_x or pix_depth values did not satisfy the
requirements of the GIS II instruction set (see above).
BMDSETPMAPADDR
This ioctl sets the virtual pixelmap address of the memory-
resident form indicated by form_id. The third argument to ioctl
is a pointer to the following structure type:
struct setpmapaddr {
short formid;
short *pmapaddr;
};
ioctl verifies that the form is associated with the calling
process. Pmap_addr is the word address of the memory pixelmap to
which the form will refer. Allocation of memory (via sbrk(2),
the library routine malloc(3), or some other means) for the
pixelmap is the responsibility of the caller. No attempt is made
to validate the address passed in; execution of GIS instructions
on a form with an invalid pmap_addr may result in a validity
violation, and the process will abort.
In the event of failure, ioctl will return -1 and the following
error codes may be returned in errno.
EFAULT the structure address was invalid.
ENXIO the specified form id was not associated with the given
bmd or not owned by the calling process.
ENXIO the specified form was not a memory-resident form.
BMDSETCLIPRECT
The BMD_SET_CLIP_RECT ioctl sets the bounding rectangle of the
specified form. Any attempts to read or modify pixels outside
this region using the GIS II instruction set are ignored.
The third argument to ioctl is a pointer to the following
structure type:
struct setcliprect {
short formid;
unsigned short ulcx;
unsigned short ulcy;
unsigned short exty;
unsigned short exty;
};
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)
bmd(7)
In the event of failure, ioctl will return -1 and the following
error codes may be returned in errno:
EFAULT The structure address was invalid.
ENXIO The specified form id was not associated with the given
bmd or not owned by the calling process.
BMDDELETEFORM
This ioctl may be used by a process to delete forms created by
either BMD_CREATE_PHYS_FORM or BMD_CREATE_MEM_FORM. Future
attempts to use the form id will cause the process to terminate.
The third argument to ioctl is simply the form_id to delete.
In the event of failure, ioctl will return -1 and the following
error code may be returned in errno:
ENXIO The specified form id was not associated with the given
bmd or not owned by the calling process.
Input
Input from the keyboard and pointer device of a bmd is received
by a process through the read system call. All input is
transformed into a common event format, and it is up to the
reading process to parse the input events to determine their
meaning. Furthermore, keyboard events contain not ASCII
character codes, but AKUP-device key codes, which are independent
of keyboard language, and allow for arbitrary mapping of keys.
It is up to the reading process to perform any desired key
mapping.
Input events have the following format.
struct bmdevent {
struct {
unsigned bmdevclass:2;
unsigned bmdevtime:14;
} common;
unsigned short data[3];
};
#define bmdeventclass common.bmdevclass;
#define bmdeventtime common.bmdevtime;
The bmd_event_class defines the event as either a BMD_BUTTON
event or a BMD_MMOTION event. The bmd_event_time field gives the
relative time of the event in 1/10 second units. Note that this
value will wrap around to 0 after about 27 minutes, so only the
DG/UX 4.00 Page 6
Licensed material--property of copyright holder(s)
bmd(7)
relative time of proximate events is interesting. The "data"
field is event_class dependent. Structure types are available
for use once the event_class is determined.
Button Events
Button events have the following format:
struct bmdbuttonevent {
struct {
unsigned bmdevclass:2;
unsigned bmdevtime:14;
} common;
unsigned short unittype;
unsigned char direction;
unsigned char key;
unsigned short reserved;
};
Possible values for the unit_type are BMD_MOUSE and BMD_KEYBOARD.
The direction field can be either BMD_BTN_UP or BMD_BTN_DOWN.
The key is either the AKUP keycode, if the unit_type is
BMD_KEYBOARD, or the mouse button number, where 1 represents the
left-most button.
Mouse Motion Events
Mouse motion events have the following format:
struct bmdtrackevent {
struct {
unsigned bmdevclass:2;
unsigned bmdevtime:14;
} common;
short x;
short y;
short z;
};
For relative pointer devices (see BMD_GET_INFO above), x, y, and
z give the motion since the last event; for absolute devices, the
x, y, and z fields give the current pixel location of the pointer
device, with 0,0 being the upper-left-hand corner of the display.
No cursor drawing is performed by the driver; this operation is
the responsibility of the application.
Device Control
DG/UX 4.00 Page 7
Licensed material--property of copyright holder(s)
bmd(7)
ioctls are provided to allow applications to control the nature
of the input, the status of the AKUP keyboard, and the behavior
of the mouse.
BMDINPUTCONTROL
This ioctl allows the reading process to modify the nature of the
input events it receives. The third argument is a set of flags
indicating whether certain behaviors are requested. Currently
defined flags are BMD_INPUT_COMPRESS, which requests that
consecutive mouse motion events be combined into a single event,
and BMD_SUPPRESS_BUTTON_UP, which requests that button-up events
be suppressed. The default value is BMD_INPUT_COMPRESS on,
BMD_SUPPRESS_BUTTON_UP off.
For example, to turn off input compression and to turn on
suppression of button-up events, the following ioctl call may be
used:
ioctl(bmdfd, BMDINPUTCONTROL,
BMDSUPPRESSBUTTONUP);
No errors are returned.
BMDSETAKUPSTAT
This ioctl sets the status of the AKUP keyboard LED and bell
attributes. The third argument to ioctl consists of a set of
flags, one for each LED on the keyboard, and one for the bell.
If a flag is on in the flag word, the LED/bell will come on;
otherwise it will be turned off.
The available flags are BMD_AKUP_ALP_LED (alpha lock LED),
BMD_AKUP_ONLINE_LED, BMD_AKUP_BELL, BMD_AKUP_F19_LED (function
key 19 LED), and BMD_AKUP_F20_LED.
For example, to turn on the alpha lock key and the bell, the
following ioctl call may be used:
ioctl(bmdfd, BMDSETAKUPSTAT,
BMDAKUPALPLED|BMDAKUPBELL);
No errors are returned.
Palette Management
bmd devices map pixel values into color values by using a
colormap, or palette. The palette consists (logically) of an
array of color values, one per possible pixel value. For
example, if a display has a pixel-depth of 8 (meaning 8 bits of
DG/UX 4.00 Page 8
Licensed material--property of copyright holder(s)
bmd(7)
information per pixel), the palette is an array of 2^^8, or 256,
colors. When the device is refreshing the screen, pixel values
are translated into color values before being displayed.
Functions to get current palette entry values and to set the
palette are provided as ioctl command codes. Both palette ioctl
commands use the following structure:
struct bmdpaletteentry {
unsigned paletteindex;
unsigned redp0;
unsigned greenp0;
unsigned bluep0;
unsigned grayp0;
unsigned redp1;
unsigned greenp1;
unsigned bluep1;
unsigned grayp1;
};
The red, green, and blue values apply only to color displays, and
the gray values apply only to gray-scale displays. The p0 values
are for phase 0 display, and the p1 values are for phase 1
display. Using different color values for phase 0 and phase 1
causes the pixel to blink alternately the phase 0 color and the
phase 1 color.
Color values range from 0, which represents color off, to
((2^^32) - 1), which represents full intensity for the associated
color. However, many bmds will be unable to differentiate
between certain ranges of colors; this means only a certain
number of the upper-most bits in the color values will be
significant. This number, called the color-depth, is returned to
the caller by the BMD_GET_INFO ioctl, described in the "Bmd
Characteristics" section above.
For example, for a display with an 8 bit color-depth, only the
upper 8 bits of each color field are used by the device in
determining the intensity of a given color. This means that, for
a given color value (such as red_p1), values 030200000000 and
03027777777 will produce an identical color for a pixel.
The two ioctls provided are BMDGETPALETTEENTRY and
BMDSETPALETTEENTRY. With BMD_GET_PALETTE_ENTRY, the
application fills in the palette_index field with the desired
pixel value. ioctl will fill in the current color values.
BMD_SET_PALETTE_ENTRY allows the application to set the palette
entry color to new values. The application fills in the
palette_index and the desired color values, and calls ioctl.
ioctl executes the appropriate GIS microcode instructions. Upon
DG/UX 4.00 Page 9
Licensed material--property of copyright holder(s)
bmd(7)
return, pixels on the screen with the specified value will
display the specified color.
For both of these commands, ioctl will return -1 and the external
variable errno will be set to EFAULT if the structure address
passed in is invalid.
Bmd Console Behavior
In configuring DS/7000-series workstations, the system
administrator chooses the device that will serve as the Eclipse
MV architectural system console (see the manual Setting Up and
Starting Your MV2000DC or DS/7000 Series System). The DG/UX
operating system console interface (see syscon(7)) will be the
same as the physical system console chosen by the system
adminstrator. The behavior of the bmd device differs depending
on the administrator's choice of physical console.
If a bmd is serving as the console, applications that open the
bmd for reading (O_RDONLY or O_RDWR flags to open(2)) will
receive keyboard input through the odrt interface. If the bmd is
opened for writing only (O_WRONLY), or not opened, any keyboard
input is delivered as ASCII to the syscon interface. In this
way, an application may open the display for graphics output, but
still receive input through the syscon interface.
The bmd console unit is placed into SCP mode by pressing the
BREAK key 3 times in succession. The prompt SCP-CLI> indicates
that the processor is awaiting SCP commands. To return to normal
operation from SCP mode, type CONT and press New Line.
If an odrt is serving as the console, no bmd input is directed to
the console interface. Instead, keyboard and mouse events are
discarded when the bmd is opened for writing only, or not at all.
FILES
/dev/bmd? bmd device files
/usr/include/sys/bmd.h
include file with structure and constant definitions
SEE ALSO
syscon(7), odrt(7), con(7)
ECLIPSE MV/Family 32-Bit Systems Principles of Operation (014-
000704)
DG/UX 4.00 Page 10
Licensed material--property of copyright holder(s)
bmd(7)
Setting Up and Starting Your MV2000DC or DS/7000 Series System
(014-001213)
DG/UX 4.00 Page 11
Licensed material--property of copyright holder(s)