hpux framebuf man page on unix.com

framebuf(7) Miscellaneous Information Manual framebuf(7)

NAME
framebuf - information for raster frame-buffer devices

SYNOPSIS
DESCRIPTION
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 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
appropriate systems administrator's manuals.

Communication with a frame-buffer device begins with an system call. Multiple processes can have the frame-buffer device open concur-
rently.

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
descriptor 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 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 asso-
ciated 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 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 provided 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 command. 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 memory 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 successive 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 implementa-
tion 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 successful 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 inter-
rupted, 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 parameter 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 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" call are withheld (blocked) until is requested. Any attempt to modify the signal mask
of the process (see sigsetmask(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 SIGTTOU 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 writing 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 signal 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 rectangle 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. Currently, there are no supported flags and this parameter should be set
to zero, otherwise the system 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 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 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 specifies 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 ALSO
mknod(1M), close(2), ioctl(2), lockf(2), open(2), select(2), signal(2), sigsetmask(2), termio(7).

framebuf(7)

Similar Topics in the Unix Linux Community
intel 845, framebuffer£¿
framebuffer question
framebuffer desktop

hpux man page for framebuf