Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > F

framebuf(7)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

framebuf — information for raster frame-buffer devices

SYNOPSIS

#include <sys/framebuf.h>

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 open() system call. Multiple processes can have the frame-buffer device open concurrently.

close() invalidates the file descriptor associated with the frame-buffer device. After a close() 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 GCUNMAP ioctl() call (see below).

Once a process acquires a lock for the frame-buffer device, it must unlock it explicitly before calling close(); see GCUNLOCK below.

read() and write() system calls are undefined and always return an error. In this case errno is set to ENODEV.

The ioctl() system call is used to control a frame-buffer device. The select() 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() call. A call to select() 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 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() 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 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() 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. Irrelevant 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 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.

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() 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 */ 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 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

When requesting GCMAP, the parameter arg is ignored and should be set to 0.

All supported ITEs ignore the frame buffer lock for output.

ERRORS

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() was interrupted by a signal.

EINVAL

An invalid ioctl() command was made.

ENODEV

Attempted to use read() or write() system calls on the device.

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() command, but the device was locked by a different process.

AUTHOR

framebuf was developed by HP.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.