framebuf(7)framebuf(7)NAMEframebuf - information for raster frame-buffer devices
SYNOPSISDESCRIPTION
Frame-buffer devices are raster-based displays. These devices use mem‐
ory-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 graphics
libraries is recommended. 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.
Each frame-buffer device is associated with a character special file.
Major and minor numbers for frame-buffer devices are implementation-
dependent. The minor numbers for these devices denote different frame
buffers. Implementation-specific details are discussed in the appro‐
priate systems administrator's manuals.
Communication with a frame-buffer device begins with an system call.
Multiple processes can have the frame-buffer device open concurrently.
invalidates the file descriptor associated with the frame-buffer
device. After a system call, any access to the frame-buffer 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 frame-buffer special file
is closed. To unmap a frame buffer, use the call (see below).
Once a process acquires a lock for the frame-buffer device, it must
unlock it explicitly before calling see below.
and system calls are undefined and always return an error. In this
case is set to
The system call is used to control a frame-buffer device. The system
call is used to test the frame-buffer device for exceptional condi‐
tions. 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 call. A call to for read or write on the file descrip‐
tor associated with the frame-buffer device returns a false condition
in the read and write bit masks (see select(2)).
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 mecha‐
nism 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 associ‐
ated 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-buf‐
fer structure and attributes is found in the data structure. The 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 requests:
Describe the size, characteristics, and mapped regions of the frame
buffer.
The information is returned to the calling process
in a data structure, and the parameter is defined
as 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 command is issued (see
below) are the correct addresses returned so the
user can access the frame-buffer regions directly
using the returned addresses.
Provide a device identification number. The parameter is defined as
The information returned when using this command is
a subset of the information provided by and is pro‐
vided here for backward compatibility only.
Turn graphics on or off. These operations are valid for
devices whose CRT_GRAPHICS_ON_OFF bit is set in the
field of the data structure returned by the com‐
mand. Otherwise, these commands have no effect.
Turn alpha on or off. These operations are valid for devices whose
CRT_ALPHA_ON_OFF bit is set in the field of the
data structure returned by the command. Otherwise,
these commands have no effect.
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 mem‐
ory and control registers. After a successful
call, the fields and in the data structure
(returned by a subsequent 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 in suc‐
cessive order. Only the regions pertinent to a
specific frame buffer are mapped. Irrelevant
region fields in the data structure are set to Use
of the arg parameter is implementation dependent
(see below). The base addresses for frame-buffer
regions are always page aligned.
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 Any
attempt to access these memory regions after a suc‐
cessful call results in a memory fault and sends
the signal SIGSEGV to the process.
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 is set to Waiting occurs if
another process has previously locked this frame
buffer using the command and has not executed a
command yet. The command does not prevent other
non-cooperating processes from writing to the frame
buffer; thus, is an advisory lock only. The param‐
eter arg is ignored and should be set to
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 command, the
ITE does not output text to it (see below). Any
attempt to lock the device more than once by the
same process fails, and causes to be set to
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
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 to be set to The parameter arg is
ignored and should be set to
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 call. The parameter arg is ignored and should
be set to When the display is acquired for exclu‐
sive use (and thus locked), all signals sent to the
process that otherwise would have been caught by
the process "at the time of the" call are withheld
(blocked) until is requested. Any attempt to mod‐
ify the signal mask of the process (see sigset‐
mask(2)) before a 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 SIGT‐
TOU are also blocked on frame-buffer devices where
the ITE does not output to the device while it is
locked. See below.
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 writ‐
ing to the frame buffer.
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
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 to be set to The parameter arg is
ignored and should be set to
Relinquish exclusive use of the frame-buffer device.
If the device is locked with a or request, the sig‐
nal mask of the calling process is restored to its
state prior to the locking request.
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 requests
defined here.
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 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 */
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 to
the address of the upper-left corner of the rectan‐
gle to be drawn. The DMA will write bytes on each
frame-buffer row, ignore the next bytes of memory
data, then resume writing at the same starting
position on each succeeding frame-buffer row. This
is continued until bytes are either written or
ignored.
To write to the graphics control space, set to
the address of the first graphics control register
to write. In this case, and are ignored.
The parameter specifies options for the DMA. Cur‐
rently, there are no supported flags and this
parameter should be set to zero, otherwise the sys‐
tem call will fail and is set to
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 responsi‐
bility of the user program to perform any necessary
set-up of the frame-buffer device so that the DMA
has the desired results.
The parameter allows the user to refresh a portion
of a window image that the user has stored in mem‐
ory 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 speci‐
fies the portion of the row in the larger window
image that is excluded from the rectangle. Thus,
plus 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 field
of the structure is set. Some framebuffer
devices supporting DMA might restrict alignment of
the various parameters, and are specified in the
section below. The kernel ensures that these
restrictions are obeyed, and if they are not the
system call will fail and set to
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 ioctl to ensure that the data is
consistent before initiating a DMA transfer.
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 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 bytes starting at are
consistent in main memory with respect to the
cache.
Provide pertinent information
about the calling process's participation in the
system-wide graphics locking mechanism (see the
discussion under above). The request does not
carry out any actual locking functionality. The
lock information is returned to the calling process
in a data structure. The parameter is defined as
The data structure is defined in the file
Prevent the Internal Terminal Emulator (ITE)
from modifying the device's color map.
Allow the Internal Terminal Emulator (ITE)
to modify the device's color map.
DEPENDENCIES
When requesting the parameter arg is ignored and should be set to
All supported ITEs ignore the frame buffer lock for output.
ERRORS
The operation would result in suspension of the calling process,
but the request was either or
Attempted to lock the device, which is already locked by the same
process.
A call to was interrupted by a signal.
An invalid command was made.
Attempted to use
or system calls on the device.
Sufficient memory for mapping could not be allocated.
Required resources for mapping could not be allocated.
The minor number on the device file refers to a nonexistent device.
Requested command, but the device was locked by a different
process.
AUTHOR
was developed by HP.
SEE ALSOmknod(1M), close(2), ioctl(2), lockf(2), open(2), select(2), signal(2),
sigsetmask(2), termio(7).
framebuf(7)