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:

• Low-resolution graphics device at physical address 0x520000 (if present). 

• 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 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. 

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 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 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  —  HP-UX Release 9.0: August 1992