Sample Drivers and Driver Development Tools

The Sample Drivers and Driver Development Tools component of the DDK provides materials to assist you in developing device drivers for the Solaris release. These materials include:

• Sample device drivers
• Driver development tools
• Documentation

These materials cover:

• How to use Solaris DDI/DKI interfaces to ensure forward compatibility with future Solaris releases.
• How to implement drivers for different types of devices.

New Features

The following new features are in this release of the DDK Sample Drivers and Driver Development Tools component:

• Updated and merged Writing Device Drivers manual--This manual describes writing device drivers for both x86 and SPARC architectures.
• DDI compliance tool (DDICT)--This tool checks source code for noncompliance with the DDI/DKI.
• Frequently asked questions (FAQ) file--This file is a list of frequently asked questions about device drivers and DDI/DKI topics and answers to those questions.

Sample Device Drivers

The DDK includes a variety of sample device drivers. In some cases, the device drivers provided with the DDK are complete functioning modules; in other cases, hardware details are omitted or generalized to provide a template from which you can generate a functioning driver.

You can use these sample device drivers, together with hardware-specific documentation and the Writing Device Drivers manual, as a starting point for developing DDI/DKI-compliant drivers.

The DDK provides sample device drivers for the following:

• Simple SCSI target driver
• Block SCSI target driver
• Graphics (frame buffer) device driver
• Data link provider interface (DLPI) network device driver
• Simple programmed I/O driver
• Simple DMA character device driver
• Simple RAM disc driver

Driver Development Tools

The DDI compliance tool (DDICT) checks device driver C source code for non-DDI/DKI compliance. Non-DDI/DKI compliance is the use of features that are not part of the Solaris 2.x DDI/DKI. DDICT issues error and warning messages when it finds noncompliant code.

Documentation

The following driver development documentation is available in the DDK. See "A Complete List of DDK Documentation" on page 15 for the locations of these documents.

• man Pages(9): DDI and DKI Overview--Section 9 of the Solaris 2.4 Reference Manual AnswerBook. These manual pages document DDI/DKI source-level interfaces. Subsections cover:

  · 9E--required driver entry points

  · 9F--kernel functions drivers may call

  · 9S--kernel structures used by drivers

• Writing Device Drivers--This manual describes device driver development for character-oriented devices, block-oriented devices, and SCSI target devices. It also covers general device driver topics.
• FAQ--The FAQ is an ASCII file containing frequently asked questions and the answers to those questions for DDI/DKI and device driver development topics.
• ddict.1--This is the man page for DDICT.
• Data Link Provider Interface Specification--This document specifies a STREAMS kernel-level instantiation of the ISO Data Link Service Definition (DIS 8886) and Logical Link Control (DIS 8802/2).
• SCSI Host Bus Adapter Drivers--This PostScript document describes how to write a SCSI HBA nexus driver using the new DDI/DKI SCSI interfaces. This document is a work in progress and will become a chapter in the Writing Device Drivers manual, called "SCSI HBA Target Drivers." Although not yet complete, this chapter contains valuable information on creating a SCSI HBA driver and provides sample code illustrating the use of the HBA driver interfaces.

VISUAL for Solaris

The VISUAL for Solaris environment is the windows and graphics hardware developer environment. It includes support for the:

• XGL graphics library
• XIL imaging library
• X11R5-based window-system server (OpenWindows X server)

The VISUAL for Solaris environment includes application-programming interfaces (APIs) for a wide variety of graphics functionality, including:

• 2-D and 3-D geometric graphics (from the XGL graphics library).
• Imaging and digital video (from the XIL imaging library).
• Stencil-paint style graphics (from Display PostScript^(TM) library).
• Basic pixel graphics (from the X11 library).

You may build applications by using a set of application libraries, including libraries from SunSoft^(TM) and from third parties. These application libraries are built on a set of foundation libraries that are part of the Solaris development environment--one for each major area of graphics functionality. Some of these foundation libraries are also available directly to application developers in the Solaris 2.4 Software Developer Kit. Each foundation library defines a graphics porting interface that is the interface for porting the library to hardware devices.

You may port your device to the VISUAL for Solaris environment by porting one or more of the Solaris graphics porting interfaces (GPIs) to a device. The DDK provides information enabling you to do this. A device might be a:

• Frame buffer
• Graphics accelerator
• Input device
• Frame grabber
• Image compression device

A device might also be a software component, for example, an optimized version of a compression algorithm or rendering pipeline. You can use the Solaris GPIs to support such "software devices."

For further information on the VISUAL for Solaris environment see the following documents:

• Solaris VISUAL Overview for Driver Developers--This manual gives the overview and philosophy of the VISUAL for Solaris environment. It includes detailed discussions of:

  · XGL graphics library (geometry)

  · XIL imaging library (imaging and video)

  · Display PostScript (stencil-paint)

  · X Window System (pixel-based)

• Solaris VISUAL White Paper--This paper gives the overview and philosophy of the VISUAL for Solaris environment.

Solaris XGL 3.1 Graphics Library

The XGL graphics library is a foundation graphics library that provides geometry graphics support for Solaris-based applications. The XGL library includes a device-level interface that defines the mapping of XGL code to the underlying hardware. If you write XGL loadable device pipelines (device handlers), which provide this mapping, you can build graphics devices that support any binary XGL application.

Because the Solaris environment provides mechanisms to dynamically load kernel device drivers and user process shared libraries, you can incorporate a new graphics accelerator into the Solaris environment by providing a dynamically loadable kernel device driver and an XGL device pipeline.

The XGL architecture provides open, well-defined interfaces that facilitate the task of implementing loadable device pipelines. The geometry-rendering interfaces are organized into a set of porting layers, which enable you to map underlying hardware capabilities to the XGL application-programming API. You can choose a layer for the device pipeline based on the functionality of the device and let XGL handle the rendering of functionality not accelerated by the device. For further information on the XGL graphics library, see the following documents:

• XGL Device Pipeline Porting Guide--This guide describes how to write an XGL graphics handler. It provides information on XGL internal interfaces and utilities, and on the mechanisms that enable the device code to work with the XGL device-independent code.
• XGL Architecture Guide--This guide provides information on the XGL architecture and presents details on the implementation of key aspects of that architecture. It also provides information on the design of the XGL loadable pipelines and describes XGL object-oriented internal design and coding conventions.
• XGL Test Suite User's Guide--This guide describes the installation and use of a set of graphics verification programs used to test the accuracy of a particular XGL implementation.
• The XGL White Paper--This white paper describes the purpose, structure, and features of functions in the XGL graphics library.

Solaris XIL 1.2 Imaging Library

The Solaris XIL imaging library is a foundation library for image processing and digital video applications. The XIL imaging library provides a single interface to the hardware with which it interacts. The XIL library has two public interfaces:

• ISV interface--documented in the Solaris 2.4 Software Developer Kit (SDK).
• Technology provider interface--provided with the Solaris 2.4 DDK. It enables you to:

  · Port new hardware devices to the XIL imaging library.

  · Accelerate existing XIL functions.

  · Add video compressors and decompressors to the XIL imaging library.

For further information on the XIL imaging library see the following documents:

• XIL Device Porting and Extensibility Guide--This guide describes the architecture and internal interfaces of the XIL library. It also describes the XIL library C++ classes and the mechanism for acceleration and porting of new hardware. If you are porting hardware to use the XIL imaging library or if you are writing device-independent acceleration code for XIL operations, you should read this guide.
• XIL Test Suite User's Guide--This guide describes how to run the Xilch test suite to verify the XIL imaging library. It also describes how to create new Xilch tests and benchmarking.
• The XIL White Paper--This white paper describes the purpose, structure, and features of functions in the XIL imaging library.

OpenWindows X Server 3.4

The OpenWindows X Server is based on the MIT X Consortium X11R5 server. The OpenWindows X Server provides basic window system and pixel graphics support. It also provides stencil-paint style graphics through the Display PostScript (DPS) extension.

The OpenWindows X Server provides a device-level GPI based on the standard Device Dependent X (DDX) interface and the XInput Extension for input devices. You can incorporate support for new graphics accelerators or input devices by providing dynamically loadable device handlers that implement the GPI for the OpenWindows X Server.

While the OpenWindows X Server defines a basic GPI based on DDX, it provides several utility porting layers that help you implement the GPI on various types of graphics accelerators and input devices. Some of these utility porting layers are common to the X11R5 server, such as:

• Color frame buffer (cfb)
• Monochrome frame buffer (mfb)
• Machine independent (mi)

Other layers, such as direct graphics access (DGA) and multiple plane group (MPG), enable you to use SunSoft features that provide enhanced graphics performance or support for advanced frame buffer architectures. The porting interface enables phased porting. This means that, in the beginning of porting, you can provide a basic port with limited acceleration, and later you can optimize the device port to use the full graphics accelerator functionality.

The OpenWindows X Server includes:

• Sample device handler source code for many devices.
• Sample source code for some of the utility layers to aid debugging.
• Server header files required to compile device handlers.
• Sample directory hierarchy, including Imakefiles, to help build device handlers.

New Features

The following features are new for this release of the DDK:

• Support for x86 and SPARC architectures
• Support transparent overlays
• Enhanced DGA drawable interface
• OWconfig access method
• Debug server to aid in debugging your DDX handlers
• Support for visual gamma corrections

For more information on the OpenWindows X Server, including detailed information on these new features, see the OpenWindows Server Device Developer's Guide. This guide provides detailed information for writing device handlers for the OpenWindows X server.

FCode Development Tools

FCode is a Forth-like language used to write to OpenBoot PROM code for SBus cards. When used with the other standard programming tools provided with the Solaris release, the FCode tokenizer, detokenizer, and fakeboot are important FCode development tools.

The FCode tokenizer converts FCode source into FCode binary that is suitable to reside on PROM. Use the FCode tokenizer if you want to design new SBus interface cards for Sun SPARC systems. The detokenizer converts the FCode executable file into a source file. For testing, fakeboot encloses an executable in a file suitable for loading into memory with the boot program.

For more information on FCode development of OpenBoot PROM and SBus cards, see the following documentation:

• Writing FCode Programs manual--describes how to write, debug, and test FCode programs for SPARC-based systems and interface card devices.

For additional information on FCode development of OpenBoot PROM and SBus cards, you may want to see the following documentation although it is not provided with the DDK:

• OpenBoot Command Reference Manual--This manual is available in the Solaris 2.4 System Administrator AnswerBook on-line documentation.
• OpenBoot Quick Reference Card--This card provides a quick reference for OpenBoot commands. It is available in the Solaris 2.4 System Administrator AnswerBook on-line documentation.
• IEEE Standard for a Chip and Module Interconnect Bus: SBus (IEEE Standard 1496-1993)--Please write IEEE to obtain a copy of this specification at:

  Institute of Electrical and Electronic Engineers, Inc. 345 East 47th Street

  New York, NY 10017, USA