HPUX graphics[7]
graphics(7) Series 300/400 Only graphics(7)
NAME
CRT graphics - information for CRT graphics devices
Remarks:
This information is valid for Series 300/400 only.
DESCRIPTION
CRT graphics devices are frame-buffer based raster displays. These
devices use memory-mapped I/O to obtain much higher performance than
is possible with tty-based graphics terminals. CRT graphics devices
can be accessed directly using this interface, although access through
the STARBASE libraries is recommended (see starbase(3G)). Direct
access to frame-buffer devices entails precise knowledge of the
frame-buffer architecture being used. Input cannot be piped into or
redirected to frame-buffer devices because they are not serial
devices.
Special (device) files for CRT graphics devices are character special
files with major number 12.
The minor number for CRT graphics devices is of the form:
0xSSTTXX
where SS is a one-byte select code number, TT is a one-byte type
specifier, and XX is zero or contains device-specific information as
defined in the appropriate Starbase Device Drivers Library.
The type field in the minor number is defined as follows:
0 Auto-configures to one of the following:
o Low-resolution graphics device at physical address
0x520000 (if present).
o High-resolution graphics device at physical address
0x560000 if low resolution device at 0x520000 not
present.
1 High-resolution graphics device at physical address 0x560000
(unless there is no low resolution device at 0x520000, in
which case type 1 is invalid).
2 High- or low-resolution graphics device at the select code
specified by the select code field in the minor number.
Communication with a CRT graphics device is begun with an open system
call. Multiple processes may concurrently have the graphics device
open. A graphics device can be accessed by multiple processes at
once; however, each process overwrites the output of the others unless
one of the locking mechanisms described below, or some other
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
graphics(7) Series 300/400 Only graphics(7)
synchronization mechanism, is used. The locking mechanisms described
here are intended for cooperating processes only (see the description
of the GCLOCK ioctl call below).
The close system call shuts down the file descriptor associated with
the graphics device.
The read and write system calls are undefined and always return an
error.
For either case, errno is set to ENODEV.
The ioctl system call is used to control the graphics device. For all
frame buffers, the data bytes scan from left to right and from top to
bottom. A pixel, which is a visible dot on the screen, is associated
with a location in the frame buffer. Some devices map individual bits
to pixels; some map bytes or parts of bytes to pixels (see the
GCDESCRIBE ioctl request).
The following are valid ioctl requests:
GCDESCRIBE Describe the size, characteristics and mapped
regions of the frame-buffer. The information is
returned to the calling process in a
crt_frame_buffer_t data structure. The parameter
is defined as crt_frame_buffer_t *arg;. The
crt_frame_buffer_t data structure is described in
the file <sys/graphics.h>. Although some
structure fields contain addresses of one or more
frame-buffer device regions, the values of these
fields are not always defined. Only after a
successful GCMAP command is issued (see below) are
the correct addresses returned so the user can
access the frame-buffer regions directly using the
returned addresses.
GCID Provide a device identification number. The
parameter is defined as int *arg;. The
information returned from this request is a subset
of the information provided by GCDESCRIBE, and is
provided here for backward compatibility only.
The device identification numbers are listed in
the file <sys/graphics.h>
GCON, GCOFF Turn graphics on or off. These operations
are valid for devices whose CRT_GRAPHICS_ON_OFF
bit is set in the crt_attributes field of the
crt_frame_buffer_t data structure returned by the
GCDESCRIBE command. Otherwise, these commands
have no effect. The parameter arg should be set
to 0.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
graphics(7) Series 300/400 Only graphics(7)
GCAON, GCAOFF Turn alpha on or off. These operations are
valid for devices whose CRT_ALPHA_ON_OFF bit is
set in the crt_attributes field of the
crt_frame_buffer_t data structure returned by the
GCDESCRIBE command. Otherwise, these commands
have no effect. Parameter arg should be set to 0.
GCMAP Map the CRT graphics device into the user address
space at the address specified in the ioctl
argument. The parameter is char **arg;. The
value *arg is used as a requested address. The
actual mapping address is then returned in *arg.
If *arg is set to 0 before the call, the system
selects the first available address. Only
processes that make this request can directly
access the frame-buffer memory and control
registers. After a successful GCMAP call, the
fields crt_frame_base and crt_control_base in the
crt_frame_buffer_t data structure (returned by a
subsequent GCDESCRIBE ioctl call), hold the valid
addresses of these two regions of the frame-
buffer.
GCUNMAP Remove the mapping of the CRT graphics device from
the user address space. The parameter is char
**arg;. The value *arg is set to the actual
mapping address returned as *arg by the GCMAP call
that originally mapped the device into the user
address space.
GCLOCK Provide for exclusive use of the graphics device
by cooperating processes. The calling process
either locks the device and continues or is
blocked. Blocking in this case means that the
call returns only when the frame-buffer is
available or when the call is interrupted by a
signal. Waiting occurs if another process has
previously locked this frame-buffer using the
GCLOCK command and has not yet executed a GCUNLOCK
command. The GCLOCK command does not prevent
other non-cooperating processes from writing to
the frame-buffer; thus, GCLOCK is an advisory lock
only. The parameter arg should be set to 0. Any
attempt to lock the device more than once by the
same process fails, and causes errno to be set to
EBUSY.
Once the display is acquired for exclusive use
(and thus locked), all signals sent to the process
that otherwise would have been caught by the
process at the time of the GCLOCK call, are
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
graphics(7) Series 300/400 Only graphics(7)
withheld (blocked) until GCUNLOCK is requested.
Any attempt to modify the signal mask of the
process (see sigsetmask(2)) before a GCUNLOCK
request is made will not have any effect on these
blocked signals. The signals are not blocked
until the lock is actually acquired and might be
received while still awaiting the lock.
The signal SIGTSTP is blocked whether or not it is
currently being caught. The signals SIGTTIN and
SIGTTOU are also blocked on frame-buffer devices
where the ITE does not output to the device while
it is locked.
Except for the three signals mentioned above, this
call does not block signals that the process did
not expect to catch, nor does it block signals
that cannot be caught or ignored.
GCLOCK_MINIMUM Provide for exclusive use of the graphics device
by cooperating processes. This request has the
same effect on the graphics device as does the
GCLOCK request. However, this call does not block
any signals as does the GCLOCK request. The
GCLOCK_MINIMUM command does not prevent other
non-cooperating processes from writing to the
frame-buffer; thus, GCLOCK_MINIMUM is an advisory
lock only. The parameter arg should be set to 0.
Any attempt to lock the device more than once by
the same process fails, and causes errno to be set
to EBUSY.
GCUNLOCK Relinquish exclusive use of the CRT graphics
device. The parameter arg should be set to 0.
Any attempt to unlock a graphics device which is
locked by a different process will fail and cause
errno to be set to EPERM.
GCUNLOCK_MINIMUM Relinquish exclusive use of the CRT graphics
device. The parameter arg should be set to 0.
Any attempt to unlock a graphics device which is
locked by a different process will fail and cause
errno to be set to EPERM.
GCSLOT Provide pertinent information about the calling
process's participation in the system-wide
graphics locking mechanism (see the discussion
under GCLOCK above). The GCSLOT request does not
carry out any actual locking functionality. The
lock information is returned to the calling
process in a gcslot_info data structure. The
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
graphics(7) Series 300/400 Only graphics(7)
parameter is defined as gcslot_info *arg;. The
gcslot_info data structure is defined in the file
<sys/graphics.h>.
GCSTATIC_MAP Prevent the Internal Terminal Emulator (ITE) from
modifying the device's color map.
GCVARIABLE_MAP Allow the Internal Terminal Emulator (ITE) to
modify the device's color map.
One shared memory descriptor (see shmget(2)) is assigned to each
graphics device by the GCMAP request. The GCSLOT request attaches a
separate shared memory object that consumes a second shared memory
descriptor. Each shared memory descriptor is accessible only through
its graphics interface. Thus, any attempt to access them through
shmat(2)), shmctl(2)), shmdt(2)), etc. results in EACCES errors.
ERRORS
[ENODEV] Attempted to use read or write system calls on the
device.
[EINVAL] An invalid ioctl command was made.
[EBUSY] Attempt to lock a device which is already locked by the
same process.
[EPERM] Attempt to unlock a device which is locked by a
different process.
[ENXIO] No such device or too many opens.
[ENOSPC] Cannot allocate required resources for mapping.
[ENOMEM] Cannot allocate sufficient memory for mapping.
[EACCES] Illegal attempt to access shared memory descriptor.
[EMFILE] Cannot allocate required resources for locking
mechanism.
[ENOTTY] Bad ioctl command.
SEE ALSO
starbase(3G), mknod(1M), open(2), close(2), ioctl(2), sigsetmask(2).
mknod(1M).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992