Introduction to Port Class

Most hardware drivers for PCI and DMA-based audio devices are based on the Port Class library, which is accessible through the PortCls system driver (Portcls.sys). PortCls is an audio port-class driver that Microsoft includes as part of the operating system. PortCls supplies a set of port drivers that implement most of the generic kernel streaming (KS) filter functionality. Therefore, PortCls simplifies the task of the audio driver developer. The hardware vendor only has to supply a set of miniport drivers to handle the hardware-specific functions of an audio adapter.

Although hardware vendors have the option to implement their own KS filters for their audio devices, this option is both difficult and unnecessary for typical audio devices. You can develop a KS filter to conform to either Stream.sys, the Stream class driver, or Avstream.sys, the AVStream class driver. But a KS filter that is based on Stream.sys cannot take advantage of the improvements that are only available in AVStream. For more information about KS filters and PortCls, see Getting Started with WDM Audio Drivers.

The internal implementation of PortCls can evolve to take advantage of kernel streaming improvements in successive Windows releases while it maintains compatibility with existing drivers.

PortCls is implemented in the Portcls.sys system file as an export driver (a kernel-mode DLL) and contains the following items:

A set of helper functions that can be called by the adapter driver

A collection of audio port drivers

It is the responsibility of the hardware vendor of an audio device, to provide an adapter driver. The adapter driver includes initialization and miniport driver-management code (including the DriverEntry function) and a collection of audio miniport drivers.

When the operating system loads the adapter driver, the adapter driver creates a set of miniport driver objects and prompts the PortCls system driver to create a corresponding set of port driver objects. (The code example in Subdevice Creation illustrates this process.) These port drivers are typically a subset of those that are available in the Portcls.sys file. Each miniport driver binds itself to a matching port driver from Portcls.sys to form a complete subdevice driver. The combination port-and-miniport subdevice driver is a KS filter (see Audio Filters). For example, a typical adapter driver might contain three miniport drivers: WaveRT, DMusUART, and Topology (with IMiniportWaveRT, IMiniportDMus, and IMiniportTopology interfaces). During initialization, these miniport drivers are bound to the WaveRT, DMus, and Topology port drivers (with IPortWaveRT, IPortDMus, and IPortTopology interfaces) that are contained in the Portcls.sys file. Each of these three subdevice drivers takes the form of a KS filter. The three filters together expose the complete functionality of the audio adapter.

Typically, the port drivers provide the majority of the functionality for each class of audio subdevice. For example, the WaveRT port driver does most of the work that is required to stream audio data to a DMA-based audio device, whereas the miniport driver provides device-specific details such as the DMA address and device name.

Audio adapter drivers and miniport drivers are typically written in Microsoft C++ and make extensive use of COM interfaces. The port-miniport driver architecture promotes modular design. Miniport driver writers should implement their driver as a C++ class derived from the IMiniport interface, which is defined in the header file Portcls.h. Hardware initialization takes place at driver load time—typically in the Init method of the IMiniport-derived class (for example, IMiniportWaveRT::Init). For more information about COM implementations of audio miniport drivers, see COM in the Kernel.

The following diagram illustrates the relationship between port and miniport drivers and their position in the audio stack.

In the preceding diagram, the KSEndpoint component is a system-supplied file that is provided with Windows Vista and later versions of Windows. This component is provided in the form of a DLL (Audiokse.dll). KSEndpoint abstracts the kernel-mode device endpoint, and provides the audio engine with access to the abstracted endpoint. For more information about the audio engine, see Exploring the Windows Vista Audio Engine.

The legend in the preceding diagram shows the boxes that represent driver components that the vendor provides. Note that the upper edge of each miniport driver interfaces to the lower edge of each port driver. For example, the WaveRT port driver exposes an IPortWaveRT interface to the WaveRT miniport driver, which exposes an IMiniportWaveRT interface to the port driver. These interfaces are sometimes referred to as upper-edge and lower-edge interfaces.

The port class and AVStream class drivers are similar in that they are both WDM drivers and they both support the WDM kernel streaming architecture. However, port class drivers differ from AVStream class drivers in the areas of multiprocessor handling and reentrancy. Port class drivers do the following:

Use a three-tiered approach that combines the class driver, port drivers, and vendor-supplied miniport drivers.

Have a restricted number of audio functions, allowing miniport drivers to operate closer to the audio hardware.

Allow several port or miniport drivers to be linked for a specific device. This feature allows for better support for multifunction cards.

Do not support external buses (for example, USB). All port drivers support devices that reside on the system buses (PCMCIA, and PCI).

The terminology for describing WDM audio ports and miniport drivers differs in some respects from the terms that are used for other classes of Windows drivers. These differences are explained in WDM Audio Terminology.

This section discusses the following topics:

Introduction to Storage Port Drivers

Microsoft Windows contains three system-supplied storage port drivers:

Storport Driver (Storport.sys), available in Windows Server 2003 and later versions of the operating system (recommended)

ATA Port Driver (Ataport.sys), available in Windows Vista and later versions of the operating system

The Storport driver is a more efficient, higher performance driver than SCSI Port. Therefore you should develop miniport drivers that work with the Storport driver whenever possible. It is particularly important to use Storport with high performance devices, such as host-based RAID and fibre channel adapters. Storport cannot be used with adapters or devices that do not support Plug and Play (PnP) or that must use system DMA. For a detailed list of restrictions on the use of the Storport driver, see Requirements for Using Storport with an Adapter.

The ATA port driver shields an ATA miniport driver from the SCSI-based protocol that the port driver uses to communicate with higher-level drivers, such as storage class drivers. For instance, miniport drivers that are attached to either SCSI port or Storport must provide SCSI sense data to the port driver. This is not necessary for an ATA miniport driver. The ATA port driver collects the necessary data from the ATA miniport driver by using ATA commands, organizes the data so that it conforms to a SCSI sense data format, and passes the data on to higher-level drivers as though it were SCSI sense data. The ATA port driver also converts each SCSI_REQUEST_BLOCK that it receives from higher-level drivers into an ATA-based equivalent called an IDE_REQUEST_BLOCK.

Each port driver communicates with a set of vendor-supplied storage miniport drivers and supplies a set of support routines for the miniport drivers to call. Each port driver communicates with its miniport drivers by calling a standard set of routines that every storage miniport driver must implement. The miniport driver routines called by the SCSI port driver, the Storport driver, and the ATA port driver are very similar to one another. Lists of port driver support routines and miniport driver routines can be found in the following sections:

Port Driver	Support Routines	Miniport Driver Routines
Storport driver	Storport Driver Support Routines	Storport Driver Miniport Routines
SCSI Port driver	SCSI Port Driver Support Routines	SCSI Miniport Driver Routines
ATA port driver	ATA Port Driver Support Routines	ATA Miniport Driver Routines

If you want your storage device to be supported on client Windows products, or on server products earlier than Windows Server 2003, you must supply a SCSI Port miniport driver.

If you want your storage device to be supported on Windows Server 2003 and later versions of the server product family, you can provide either a Storport miniport driver or a SCSI miniport driver. If you wish to install an ATA storage device in Windows Vista and later versions of the operating system, you must provide an ATA port miniport driver.

The sections that follow describe the Storport, SCSI Port, and ATA port drivers and how they differ.

Portmon for Windows v3.03

By Mark Russinovich

Published: January 12, 2012

Download Portmon (226 KB)
Run now from Sysinternals Live.

Introduction

Portmon is a utility that monitors and displays all serial and parallel port activity on a system. It has advanced filtering and search capabilities that make it a powerful tool for exploring the way Windows works, seeing how applications use ports, or tracking down problems in system or application configurations.

Portmon 3.x

Version 3.x of Portmon marks the introduction of a number of powerful features.

• Remote monitoring: Capture kernel-mode and/or Win32 debug output from any computer accessible via TCP/IP — even across the Internet. You can monitor multiple remote computers simultaneously. Portmon will even install its client software itself if you are running it on a Windows NT/2K system and are capturing from another Windows NT/2K system in the same Network Neighborhood.
• Most-recent-filter lists:Portmon has been extended with powerful filtering capabilities and it remembers your most recent filter selections, with an interface that makes it easy to reselect them.
• Clipboard copy: Select multiple lines in the output window and copy their contents to the clipboard.
• Highlighting: Highlight debug output that matches your highlighting filter, and even customize the highlighting colors.
• Log-to-file: Write debug output to a file as its being captured.
• Printing: Print all or part of captured debug output to a printer.
• One-file payload:Portmon is now implemented as one file.

The on-line help-file describes all these features, and more, in detail.

Installation and Use

Simply execute the Portmon program file (portmon.exe) and Portmon will immediately start capturing debug output. To run Portmon on Windows 95 you must get the WinSock2 update from Microsoft. Note that if you run Portmon on Windows NT/2K portmon.exe must be located on a non-network drive and you must have administrative privilege. Menus, hot-keys, or toolbar buttons can be used to clear the window, save the monitored data to a file, search output, change the window font, and more. The on-line help describes all of Portmon’s features.

Portmon understands all serial and parallel port I/O control (IOCTLs) commands and will display them along with interesting information regarding their associated parameters. For read and write requests Portmon displays the first several dozen bytes of the buffer, using ‘.’ to represent non-printable characters. The Show Hex menu option lets you toggle between ASCII and raw hex output of buffer data.

How it Works: WinNT

The Portmon GUI is responsible for identifying serial and parallel ports. It does so by enumerating the serial ports that are configured under HKEY_LOCAL_MACHINE\Hardware\DeviceMap\SerialComm and the parallel ports defined under HKEY_LOCAL_MACHINE\Hardware\DeviceMap\Parallel Ports. These keys contain the mappings between serial and parallel port device names and the Win32-accessible names.

When you select a port to monitor, Portmon sends a request to its device driver that includes the NT name (e.g. \device\serial0) that you are interested in. The driver uses standard filtering APIs to attach its own filter device object to the target device object. First, it uses ZwCreateFile to open the target device. Then it translates the handle it receives back from ZwCreateFile to a device object pointer. After creating its own filter device object that matches the characteristics of the target, the driver calls IoAttachDeviceByPointer to establish the filter. From that point on the Portmon driver will see all requests aimed at the target device.

Portmon has built-in knowledge of all standard serial and parallel port IOCTLs, which are the primary way that applications and drivers configure and read status information from ports. The IOCTLs are defined in the DDK file \ddk\src\comm\inc\ntddser.h and \ddk\src\comm\inc\ntddpar.h, and some are documented in the DDK.

How it Works: Windows 95 and 98

On Windows 95 and 98, the Portmon GUI relies on a dynamically loaded VxD to capture serial and parallel activity. The Windows VCOMM (Virtual Communications) device driver serves as the interface to parallel and serial devices, so applications that access ports indirectly use its services. The Portmon VxD uses standard VxD service hooking to intercept all accesses to VCOMM’s functions. Like its NT device driver, Portmon‘s VxD interprets requests to display them in a friendly format. On Windows 95 and 98 Portmon monitors all ports so there is no port selection like on NT.

Download Portmon (226 KB)

Run now from Sysinternals Live.