framebuf(7) framebuf(7)
NAME [Toc] [Back]
framebuf - information for raster frame-buffer devices
SYNOPSIS [Toc] [Back]
#include <sys/framebuf.h>
DESCRIPTION [Toc] [Back]
Frame-buffer devices are raster-based displays. These devices use
memory-mapped I/O to obtain much higher performance than possible with
tty-based graphic terminals. Frame-buffer devices can be accessed
directly using this interface, although access through the STARBASE
libraries is recommended (see starbase(3G)). Direct access to framebuffer
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.
Each frame-buffer device is associated with a character special file.
Major and minor numbers for frame-buffer devices are implementationdependent.
The minor numbers for these devices denote different frame
buffers. Implementation-specific details are discussed in the
appropriate systems administrator's manuals.
Communication with a frame-buffer device begins with an open(2) system
call. Multiple processes can have the frame-buffer device open
concurrently.
close(2) invalidates the file descriptor associated with the framebuffer
device. After a close system call, any access to the framebuffer
device address range might result in a memory fault and the
signal SIGSEGV being sent to the process (see signal(2)). A process
cannot unmap the frame buffer from its address space after the framebuffer
special file is closed. To unmap a frame buffer, use the
GCUNMAP ioctl(2) call (see below).
Once a process acquires a lock for the frame-buffer device, it must
unlock it explicitly before calling close(2); see GCUNLOCK below.
read(2) and write(2) system calls are undefined and always return an
error. In this case errno is set to ENODEV.
The ioctl(2) system call is used to control a frame-buffer device.
The select(2) system call is used to test the frame-buffer device for
exceptional conditions. Interrupts from the graphic hardware are
considered exceptional conditions. An exceptional condition is
automatically cleared after any process that opens the frame-buffer
device is notified of the exception by a select(2) call. A call to
select(2) for read or write on the file descriptor associated with the
frame-buffer device returns a false condition in the read and write
bit masks (see select(2)).
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
A frame-buffer device can be accessed by multiple processes at once.
However, each process overwrites the output of the others unless one
of the lock mechanisms described here or some other synchronization
mechanism is used. The lock mechanisms described here are intended
for cooperating processes only.
For all frame buffers, 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. Each device maps one
or more bits in memory to a pixel on the screen, although the bits in
the frame buffer might not be continuous. Information describing the
frame-buffer structure and attributes is found in the
crt_frame_buffer_t data structure. The crt_frame_buffer_t data
structure includes the following fields:
int crt_id; /*display identifier*/
unsigned int crt_attributes; /*flags denoting attributes*/
char *crt_frame_base; /*first byte in frame-buffer memory*/
char *crt_control_base; /*first byte of the control*/
/*registers*/
char *crt_region [ CRT_MAX_REGIONS ];
/*other regions associated with the*/
/*frame-buffer device*/
The following are valid ioctl(2) 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, and the
parameter is defined as crt_frame_buffer_t *arg;.
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 when using this command is a
subset of the information provided by GCDESCRIBE,
and is provided here for backward compatibility
only.
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
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
crt_frame_buffer_t data structure returned by the
GCDESCRIBE command. Otherwise, these commands
have no effect.
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.
GCMAP Make the frame-buffer memory, graphics control,
and other device regions accessible to the user
process making the call. Only processes that
request this can directly access 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(2) call), hold the valid addresses of these
two regions of the frame buffer. If, for a
specific device, more than two regions are to be
mapped to the user's address space, the base
addresses of up to CRT_MAX_REGIONS extra device
regions will be placed in the array crt_region in
successive order. Only the regions pertinent to a
specific frame buffer are mapped. Irrelevent
region fields in the crt_frame_buffer_t data
structure are set to 0. Use of the arg parameter
is implementation dependent (see DEPENDENCIES
below). The base addresses for frame-buffer
regions are always page aligned.
GCUNMAP Cause access to the frame-buffer memory, graphics
control, and possibly other device regions to be
removed from the requesting process. The
parameter arg is ignored and should be set to 0.
Any attempt to access these memory regions after a
successful GCUNMAP call results in a memory fault
and sends the signal SIGSEGV to the process.
GCLOCK Provide for exclusive use of the frame-buffer
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. If the call is interrupted, it returns an
error and errno is set to EINTR. Waiting occurs
if another process has previously locked this
frame buffer using the GCLOCK command and has not
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
executed a GCUNLOCK command yet. 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 is ignored and should be set to 0.
This call prevents the Internal Terminal Emulator
(ITE) from corrupting the state of the graphics
hardware (see termio(7)). On some systems, as
long as the frame buffer is locked with a GCLOCK
command, the ITE does not output text to it (see
DEPENDENCIES below). Any attempt to lock the
device more than once by the same process fails,
and causes errno to be set to EBUSY.
GCLOCK_NOWAIT Provide for exclusive use of the frame-buffer
device by cooperating processes. This request has
the same effect on the frame-buffer device as does
the GCLOCK request. However, this call does not
wait for the frame buffer to be released by other
processes. If the frame-buffer device is locked,
the process is not blocked; instead, the system
call returns an error and causes errno to be set
to EAGAIN. The parameter arg is ignored and
should be set to 0.
GCLOCK_BLOCKSIG Provide for exclusive use of the frame-buffer
device by cooperating processes while blocking all
incoming signals for the calling process that
otherwise might have been caught. This call is a
superset of the GCLOCK call. The parameter arg is
ignored and should be set to 0. When 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 also blocked whether or not
it is 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. See DEPENDENCIES below.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
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. This command
does not prevent other non-cooperating processes
from writing to the frame buffer.
GCLOCK_BLOCKSIG_NOWAIT
Provide for exclusive use of the frame-buffer
device by cooperating processes, while blocking
all incoming signals for the calling process that
otherwise would have been caught. This request
has the same effect on the frame-buffer device as
does the GCLOCK_BLOCKSIG request. However, this
call does not wait for the frame buffer to be
released by other processes. If the frame-buffer
device is locked, the process is not blocked, but
the system call returns an error and causes errno
to be set to EAGAIN. The parameter arg is ignored
and should be set to 0.
GCUNLOCK Relinquish exclusive use of the frame-buffer
device. If the device is locked with a
GCLOCK_BLOCKSIG or GCLOCK_BLOCKSIG_NOWAIT ioctl(2)
request, the signal mask of the calling process is
restored to its state prior to the locking
request.
GCRESET Reset the graphic hardware associated with the
frame-buffer device to a defined initial state.
The call enables the frame-buffer device to
respond to the ioctl requests defined here.
GCDMA_OUTPUT Send DMA output to the frame-buffer device. This
system call is used to transfer data from a user's
array to a rectangular area of the graphics
frame-buffer, or optionally, to the device's
graphics control space.
The parameters for the DMA are passed in a
"crt_dma_ctrl_t" data structure, which includes
the following fields:
char *mem_addr; /* Starting address of data
being transferred */
char *fb_addr; /* Address of framebuffer
destination */
int length; /* Number of bytes to transfer,
including those "skipped" */
int linelength; /* Number of bytes written
on each framebuffer row */
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
int skipcount; /* Number of source bytes to
ignore after each "linelength" */
unsigned int flags; /* Specified options to the driver */
To write to the graphics frame-buffer, set
fb_addr to the address of the upper-left corner of
the rectangle to be drawn. The DMA will write
linelength bytes on each frame-buffer row, ignore
the next skipcount bytes of memory data, then
resume writing at the same starting position on
each succeeding frame-buffer row. This is
continued until length bytes are either written or
ignored.
To write to the graphics control space, set
fb_addr to the address of the first graphics
control register to write. In this case,
linelength and skipcount are ignored.
The flags parameter specifies options for the DMA.
Currently, there are no supported flags and this
parameter should be set to zero, otherwise the
system call will fail and errno is set to EINVAL.
The DMA has the same effect on the frame-buffer
device as using store instructions to write the
data. Thus, various graphics control registers
may affect the results of the DMA. It is the
responsibility of the user program to perform any
necessary set-up of the frame-buffer device so
that the DMA has the desired results.
The skipcount parameter allows the user to refresh
a portion of a window image that the user has
stored in memory for those cases where only a
portion of the image needs to be refreshed. The
window image is then a superset of the rectangle
being updated, and might thus have different
dimensions. The skipcount specifies the portion
of the row in the larger window image that is
excluded from the rectangle. Thus, linelength
plus skipcount would be the number of bytes in
each row of the larger window image array.
If a particular framebuffer device supports this
system call, the CRT_DMA_OUTPUT flag in the
crt_attributes field of the crt_frame_buffer_t
structure is set. Some framebuffer devices
supporting DMA might restrict alignment of the
various parameters, and are specified in the
DEPENDENCIES section below. The kernel ensures
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
that these restrictions are obeyed, and if they
are not the system call will fail and set errno to
EINVAL.
It is the responsibility of the application to
guarantee that the system's physical memory is
up-to-date by flushing the processor's data cache.
One should use the GCDMA_DATAFLUSH ioctl to ensure
that the data is consistent before initiating a
DMA transfer.
GCDMA_DATAFLUSH Flush the specified data from the processor's data
cache to the system's main memory. This system
call is intended to be used before DMA to ensure
that an up-to-date version of the data is
transferred to the framebuffer or to control
space.
The parameters for the flush are passed in a
crt_flush_t data structure, which includes the
following fields:
char *flush_addr; /* Starting address of data
to be flushed */
int flush_len; /* Number of bytes to flush */
The kernel ensures that the flush_len bytes
starting at flush_addr are consistent in main
memory with respect to the cache.
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 crt_gcslot_t data structure. The
parameter is defined as crt_gcslot_t *arg;. The
crt_gcslot_t data structure is defined in the file
<sys/framebuf.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.
DEPENDENCIES [Toc] [Back]
Series 700/800
When requesting GCMAP, the parameter arg is ignored and should be
set to 0.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
All supported ITEs ignore the frame buffer lock for output.
Series 700
Among the device identification constants that can be returned
both by the GCID call and in the crt_id field of the
crt_frame_buffer_t data structure by the GCDESCRIBE call are:
S9000_ID_98705 [Toc] [Back]
S9000_ID_98736
S9000_ID_A1659A
S9000_ID_A1439A
If a memory-mapped graphics co-processor is available, it is
mapped in with other graphics regions as the result of a GCMAP
call, and its address is recorded as the last entry in the crt
region array returned by the GCDESCRIBE call.
Series 800
The following device identification constants are returned both
by the GCID call and in the crt_id field of the
crt_frame_buffer_t data structure by the GCDESCRIBE call:
S9000_ID_98720 [Toc] [Back]
S9000_ID_98730
S9000_ID_98550
For the HPA1047A Interface Card, the fields of the crt_dma_info
structure have the following restrictions:
mem_addr 32-byte aligned
fb_addr 16-byte aligned
length non-zero multiple of 32
skipcount 0
ERRORS [Toc] [Back]
[EAGAIN] The operation would result in suspension of the calling
process, but the request was either GCLOCK_NOWAIT or
GCLOCK_BLOCKSIG_NOWAIT.
[EBUSY] Attempted to lock the device, which is already locked
by the same process.
[EINTR] A call to ioctl(2) was interrupted by a signal.
[EINVAL] An invalid ioctl(2) command was made.
[ENODEV] Attempted to use read(2) or write(2) system calls on
the device.
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
framebuf(7) framebuf(7)
[ENOMEM] Sufficient memory for mapping could not be allocated.
[ENOSPC] Required resources for mapping could not be allocated.
[ENXIO] The minor number on the device file refers to a
nonexistent device.
[EPERM] Requested GCUNLOCK ioctl(2) command, but the device was
locked by a different process.
AUTHOR [Toc] [Back]
framebuf was developed by HP.
SEE ALSO [Toc] [Back]
select(2), open(2), close(2), signal(2), sigsetmask(2), lockf(2),
ioctl(2), mknod(1M), starbase(3G), termio(7).
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003 [ Back ] |
