unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 framebuf(7)							 framebuf(7)




 NAME
      framebuf - information for raster frame-buffer devices

 SYNOPSIS
      #include <&lt&lt&lt;sys/framebuf.h>&gt&gt&gt;

 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 STARBASE
      libraries is recommended (see starbase(3G)).  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(2) system
      call.  Multiple processes can have the frame-buffer device open
      concurrently.

      close(2) 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(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 Release 11i: November 2000






 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 Release 11i: November 2000






 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 Release 11i: November 2000






 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 Release 11i: November 2000






 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 Release 11i: November 2000






 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 Release 11i: November 2000






 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
      Series 700/800
	   When requesting GCMAP, the parameter arg is ignored and should be
	   set to 0.



 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 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
		     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
		     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
      [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 Release 11i: November 2000






 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
      framebuf was developed by HP.

 SEE ALSO
      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 Release 11i: November 2000