framebuf(7)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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.

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:

The kernel ensures that the flush_len bytes starting at flush_addr 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 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>.

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.

The operation would result in suspension of the calling process, but the request was either GCLOCK_NOWAIT or GCLOCK_BLOCKSIG_NOWAIT.

Attempted to lock the device, which is already locked by the same process.

A call to ioctl() was interrupted by a signal.

An invalid ioctl() command was made.

Attempted to use read() or write() 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 GCUNLOCK ioctl() command, but the device was locked by a different process.