AIX 5L for Itanium-based Systems Operating System

Device Driver Kit Beta ReleaseNotes

January 3, 2001- Beta3 - Update 3

Version History:

Update 3: Added Compliance Checklist.

Update 2: updated UDI component: New GIO mapper - Tools to support GIO - Improved sprops validation - Boot device support - Configuration methods to support GIO and network devices - Updated network mapper - Replaced udi.ddk package.

Update 1: updated UDI component: Updated tools and environment - Replaced udi.ddk package.

A. Introduction

Welcome to AIX 5L for Itanium-based Systems Device Driver Kit (DDK). This package contains documentation and sample code to assist in the development of AIX 5L for Itanium-based Systems device drivers. AIX 5L supports two driver models: the UDI driver interface, and the native AIX 5L driver interface. This version of the DDK supports both driver models. There are certain limitations on the UDI model which are noted below.

The AIX 5L native driver interface is based on IBM's AIX operating system device driver interface, complemented with technology from SCO's UnixWare operating system. This DDK is the build level of code that contains core level of function and stability such that third party developers can reasonably undertake device driver development using this level of documentation and sample code. This does not imply that the DDK is complete and fully functional, nor that the components in the Beta version will be present in the final product.

The Device Driver Kit is installed and executes on an AIX 5L for Itanium-based Systems Operating System, providing a native development environment. When used with the AIX 5L Software Development Environment (SDE), also installed and running on AIX 5L for Itanium-based Systems, allows developers to install and test device support on AIX 5L for IA65 systems.

Enhancements and changes will occur in various areas and at various stages of product development. Please note that although there is no defect** or update support available for AIX 5L for Itanium-based Systems in the Beta time frame, we welcome your feedback and suggestions. The DDK will be refreshed periodically in the coming months.

B. Purpose of this release

This Beta DDK release is intended specifically for developers creating device drivers for the AIX 5L for Itanium-based Systems Operating System.
A Compliance Checklist (checklist.zip) is provided for guidance and direction when developing device drivers. Once you download and uncompress the zip file, point your browser to the file named "AIX 5L Compliance Checklist1.0.htm" to review the checklist.

C. Supported Platforms and Adapters

The Beta DDK installs on AIX 5L for Itanium-based Systems to provide a native development environment. The DDK can be installed stand-alone on a AIX 5L for Itanium-based Systems system. However, in order to utilize the DDK to build AIX 5L for Itanium-based Systems device drivers, the companion Software Development Environment (SDE) is required.

The separate SDE package provides the headers, tools and documentation in order to compile and link native AIX 5L for Itanium-based Systems device drivers.

The supported platforms for device drivers built with this DDK include the Intel SDV workstation and the Intel SDV servers.

D. Installation Instructions

The target DDK installation is a AIX 5L for Itanium-based Systems

You need to download the AIX 5L for Itanium-based Systems Device Driver Kit, and complete the steps listed below. This installation or reinstallation of the DDK will overlay a prior installation. Any user created files are not affected by this installation. However, if you have modified existing DDK files, you must backup your changes prior to installing this version.

It is suggested that you first install the SDE, although it is not mandatory if your reason for installing the DDK is for educational purposes, and not to develop device drivers.

DDK documentation is included in a package. Certain programming information, API's and other relevant material is provided through links to other online documentation. Thus, it is strongly suggested that you have internet access to the online documentation. A web browser is required, and is included with the Operating System.

The documentation and references by the DDK are in HTML format.

Please follow the following steps in order to install the DDK on AIX 5L for Itanium-based Systems:

- Verify that enough space is available to install the DDK. (a minimum of 20MB of free space is required if you install all the components)
- Point your web browser to http://www.projectmonterey.com/libs/download/ddk.html
- Read and accept the license agreement prior to download of any packages. Your acceptance of the license agreement is required to download and install the DDK
- Once you accept the license agreement, you may download any of the installation files for the sample device drivers, documentation, and tools. These packages are in installp format, and contain source code, build instructions, installation scripts, and development tools. You do not need to download all the packages, but only the ones you are interested in:
- - The pseudo device driver (devices.ddk.pseudo)
  - The SCSI CD-ROM and adpater device driver (devices.ddk.scsi)
  - The Network device driver (devices.ddk.netentdd)
  - The Fibre Channel drivers (devices.ddk.fcdd) and (devices.ddk.fscsidd)
  - The TTY device driver (devices.ddk.tty)
  - The sample Installp package (sample.ddk.pseudo.package)
  - The DDK documentation package (devices.ddk.docs)
- In addition you should download the UDI tools necessary to build UDI drivers. This package is in installp format (udi.ddk). The UDI environment (shipped in the operating system) is a prerequisite when installing this package.
- In addition you should download the required tools necessary to package device drivers in installp format. This file is in tar format (tools.tar).
In the alternative, you can download a single compressed tar file that contains all the files listed above. After downloading that tar file (ddk_beta3.036E.tar.Z), extract the contents and install each individual package as needed.

E. Installing DDK Packages

Use "smitty installp" to install all the packages as follows:

Select the menu option to "Install and Update from ALL Available Software"
Enter the directory name where you downloaded or extracted each package,
Ensure that installation is successful for each package you install

F. Using the DDK

Each DDK package contains sample source code, make files to build the driver.
In order to compile the sample code, you need to install the AIX 5L for Itanium-based Systems native compiler and related tools. Ensure you set and export the environment variable using "export PATH=/usr/vac/bin:$PATH"

A manual update is required in files: "/usr/lib/drivers/kernex.imp" and "/usr/lib/drivers/pse.imp". The string "syscall3264" needs to be deleted in both files before bulding any driver.

For each driver package, simply run "make" to build the driver.

The documentation package describes the key points of each sample driver source and provides guide material for building device drivers.

Once you installed the documentation package, point your web browser to the DDK table of contents at /usr/ddk/docs/native/toc.htm.

Additional UDI documentation is included in /usr/ddk/docs/udi/udi.readme.html and /usr/ddk/docs/udi/udiguide.html.

G. DDK Contents

The DDK contains the following:

Documentation for developing device drivers – This documentation is in the form of programming guides, as well as links to programming interfaces and technical references.
UDI Tools needed for creating UDI packages.
UDI headers for compiling UDI device drivers.
Sample source code – This sample code is provided for illustrative purposes, and is intended to assist you in developing new device drivers. The sample code includes source code, Makefiles, and documentation for the following:
An elementary pseudo device driver, that illustrates the concepts of developing, configuring and loading native AIX 5L for Itanium-based Systems device drivers.
A more complex example, illustrating the interface of a SCSI device driver with a SCSI adapter device driver. The sample includes a typical SCSI CDROM device driver and the top half of a SCSI adapter device driver. The sample also includes the source code to load and configure the device driver. The sample also illustrates the use of import and export files, and how these are used by kernel extensions such as this driver.
A comprehensive sample driver that illustrates programming an ethernet network adapter.
A comprehensive sample driver that illustrates programming an fibre channel adapter.
A comprehensive sample driver that illustrates programming a tty adapter.
A sample installp package that can be used to package device drivers in insallp format
The accompanying documentation describes the key details of each of these samples. Once you have installed the DDK, you can navigate the documentation by starting at the table of contents page, which can be found in /usr/ddk/docs/native/toc.htm. A remote web browser is needed to view the documentation.

H. Where to go for Assistance

Please contact your AIX 5L for Itanium-based Systems Support Representative for further assistance. Please note that there is no defect support or updates in the Beta time period. We still welcome your feedback by contacting us at aix@us.ibm.com. Please include "DDK" in the subject line.

I. Limitations

The DDK sample code is intended to be illustrative in nature, and it is provided "as-is". Please refer to the license agreement for details on your use of the code.
Some of the online documentation refers to IBM's AIX Operating System documentation, and not specifically to the AIX 5L for Itanium-based Systems. It is anticipated that during the development phase of the system, AIX 5L for Itanium-based Systems specific documentation will become available. It is suggested that you visit the AIX 5L for Itanium-based Systems home page for updates.

J. This software and documentation is provided on an "AS IS" basis. It is subject to change without notice. Your reliance upon its content is at your own risk. IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION, WARRANTIES OF FITNESS AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.
(c) Copyright IBM Corporation, 2000. All rights reserved. U.S. Government Users Restricted Rights - Use, duplication, or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Intel is a trademark of Intel Corporation.

All other trademarks and registered trademarks are the property of their respective holders.