NAME

tigr − 1500/3000 graphics interface

DESCRIPTION

The character special device files /dev/tigr∗ form the interface between the operating system and graphics programs.  The operating system uses the device files to control the Stardent 1500/3000 graphics hardware.  Operations on the files result in the transfer of commands and data between system memory and the graphics hardware.  Other file operations result in synchronization among processes, hardware, and the driver. 

The file /dev/tigr0 is used internally by the operating system as its interface for console output when not running the X11 window system.  Other minor device files /dev/tigr[1-9] may be used by any process.  In the most common case, the X11 window server will use /dev/tigr1, and the other minor devices /dev/tigr[2-9] will be available for applications (such as applications using Dore
´). Most standard clients of the X11 window server (including xterm, xclock, xload, etc.) deal only with the window server through a communications channel [such as DISPLAY=‘hostname‘:0, or DISPLAY=unix:0] and have no direct interaction with the graphics hardware. While wanting to coexist within a window system, Dore
´ applications usually want higher speed or more functionality (such as depth buffering) than provided by typical window servers, and find it necessary to use the tigr direct graphics interface. 

Each minor device is an exclusive-open device: a close() must be performed between any two open()s.  There are no read(), write(), or lseek() calls; ioctl() calls do all the work.  The Stardent 1500/3000 graphics board has a one-megabyte address space for drawing commands and data, along with an address translation table which allows mapping to any 256 4Kbyte pages of system memory.  (See the Hardware Reference Manual, part number 340-0011.) Although certain functions can be performed without using the graphics address space, all drawing commands must pass through the graphics address space. The /dev/tigr driver creates and manages a shared-memory interface among the application, the driver, and the graphics hardware.  Since the pages of the shared memory region are “locked down,” they provide high bandwidth, low latency, and low overhead for graphics operations. 

As defined in <machine/tigr.h>, the shared memory contains one header control structure cbmem, two circular buffers ( cmd and rpl for command and reply), and arbitrary data regions.  The cbmem structure lies at the low-address end of the region.  It contains an identifying tag, the length of the region, graphics synchronization locks/keys, and the pointers for the circular buffers.  One circular buffer, the command buffer, handles communication from the user to the kernel.  The other (reply) buffer takes care of communication from the kernel to the user.  All “pointers” within the tigr shared memory region are actually byte displacements from the lowest address in the region, making them region-relative.  The cbmem structure must be aligned on an 8-byte address boundary. 

Four pointers contained in a cbhdr structure control each circular buffer.  The fwa and lwa pointers describe the lowest address, and one beyond the highest address, used for the buffer.  The fwa and lwa must be constant for the life of the buffer.  Two other pointers, in and out, vary as the buffer is used.  in points to the location which will receive the next byte inserted into the buffer.  out points to the location containing the next byte to be removed from the buffer.  Whenever in==out, the buffer is empty. If in>out, then the buffer contains in−out bytes beginning at out. If in<out, then the buffer contains in−out+lwa−fwa total bytes; lwa−out bytes from out to lwa,followedby in−fwa bytes from fwa to in.

Communication within the circular buffers going between user code and the driver is in terms of cbpkt packets.  These packets contain a command number and room for a pointer and a length.  The command number is the same as the ioctl number; some commands can be issued either as a direct ioctl or from within a circular buffer command packet. 

Once the cbmem communication region has been established (via TGIOCBMEM ioctl), there is implicit exchange of information among the user code, tigr driver, and graphics hardware.  The tigr driver scans the set of open TGIOCBMEM regions in round-robin fashion, looking for a non-empty command buffer.  After executing the first command it finds, the driver enters a packet into the reply buffer and resumes scanning for commands with the next minor device.  Usually the reply packet is just a copy of the command packet, but an error is signalled by changing the cmd to TGIOERROR.  If the reply buffer is full, then the reply is discarded.  The driver scans for commands whenever the graphics hardware completes a drawing command, and at every vertical retrace whever the graphics hardware is idle.  To force earlier examination of the command buffers, use TGIOLOOK ioctl. 

Notice that the conventions of the tigr driver specify only the command and reply buffers.  The driver places no restrictions on graphics drawing command blocks other than requiring that they lie within the shared memory region and at an address divisible by 8 (which is a hardware restriction).  User code is free to use the “data” area as a single large buffer, alternating double buffer, multiple buffer pool, or any other way. 

Also note that the round-robin scanning does not necessarily preserve state of the underlying drawing hardware between successive commands from the same minor device.  Each drawing packet must be self-contained; any state which is necessary (rasterizer select, foreground color, Z function, plane mask, memory bank, etc.) must be explicitly set at the beginning of each DMA drawing command list. 

SYNCHRONIZATION

The tigr driver provides three forms of synchronization.  A TGIOWAIT ioctl will cause the process to sleep until the reply buffer is not empty.  This lets the user code insure that drawing has completed before going on to do something else.  Two other forms of synchronization provide for cooperation between a window server and good-citizen applications, and for rendezvous between multi-threaded applications, a server, and the hardware front/back video double buffer swapping. 

By using the TGIOGEOMSET and TGIOGEOMUSE commands, a window server and cooperating processes using direct graphics can maintain sanity with respect to window location, size, and exposure.  Any process (but usually the window server) can specify an arbitrary 32-bit global “window geometry lock” with the TGIOGEOMSET command.  Thereafter, the tigr driver will return an error on any conditional graphics read or write command (TGIORCOND or TGIOWCOND) unless the same 32-bit value has been specified in a previous TGIOGEOMUSE command.  The error stops command scanning on the affected minor device, but leaves the command buffer intact.  A cooperating direct graphics process can recover by inquiring the new screen geometry from the server, specifying the new 32-bit key in a TGIOGEOMUSE ioctl, possibly changing the data in the drawing command to reflect its new window location, and clearing the error condition with TGIOCLRERR ioctl.  The tigr driver will once again include the command buffer in its round-robin scan. 

With the TGIODBSET, TGIODBWAIT, and TGIODBSWAP commands, a window server and cooperating multi-threaded animation process can synchronize drawing with front/back video buffer swapping.  Each animation thread puts a TGIODBWAIT command into its circular buffer, and does a TGIOWAIT ioctl until the driver has seen it.  Then the thread notifies the window server that it is ready to swap.  The thread is free to continue putting commands into the buffer, but as long as the 32-bit value does not match, the tigr driver will not take commands out of the buffer.  When the window server determines that all threads are ready to swap, it draws the appropriate stripes in the control planes, performs a TGIODBSET for each corresponding minor device, and finally does a TGIODBSWAP specifying the new control plane.  The tigr driver requests that the hardware swap control planes at the next vertical retrace.  Upon receiving the vertical retrace interrupt, the driver releases each minor device whose DBSET and DBWAIT value match. 

IOCTLS

The ioctl calls supported by the tigr driver are:

CommandAddressDescription

TGIOWCLUT&tgclutwrite color lookup table
TGIORCLUT&tgclutread color lookup table
TGIODBUF0 or 1set which plane controls front/back video buffer
TGIORESETrecover from total disaster
TGIOWAITsleep until reply buffer is not empty
TGIOSTATUS&intreturn GR_MISC hardware register
TGIOERRS&intobsolete
TGIORDCNT&intobsolete
TGIOMODEintobsolete
TGIOVIDEOintload predefined video timing
TGIOWSRAM&int[2048]load custom video timing (superuser only)
TGIORSRAM&int[2048]read video timing (superuser only)
TGIOWVTCTL&intwrite GR_VTCTL register (superuser only)
TGIORVTCTL&intread GR_VTCTL register (superuser only)
TGIOCBMEM&cbmemestablish shared memory communication region
TGIOWRITE&dma_blocksend data to hardware
TGIOREAD&dma_blockreceive data from hardware
TGIOGETDB&intget next plane to control front/back video
TGIODBSWAP0 or 1change front/back video buffer at next retrace
TGIOWDACCTL&?write DAC registers
TGIORDACCTL&?read DAC registers
TGIOCBNOP&dma_blockdo nothing
TGIODBSETkeyset front/back key; len has minor device
TGIODBWAITkeywait until front/back lock matches
TGIOGEOMSETkeyset global window geometry lock
TGIOGEOMUSEkeyinhibit conditional read/write unless key fits lock
TGIOWCOND&dma_blockconditional TGIOWRITE
TGIORCOND&dma_blockconditional TGIOREAD
TGIOSBUS&intread GR_SBUS register
TGIOEXPENA0 or 1disable/enable graphics expansion board
TGIOBLANK0 or 1turn screen off (0) or on (1)
TGIOCLRERRclear error flag for this minor device
TGIOLOOKstart scan for commands now (don’t wait for retrace)
TGIOCHKDMA0 or 1software interpret DMA command lists for obvious errors
TGIORETRACEnwait until n more vertical retraces have occurred

FILES

/dev/tigrx − a minor device for display 0
/dev/tigr1x − a minor device for display 1

September 29, 2021