ASPI on DOS: From the SCSI Manager Entry Point to a Completed Request

ASPI, the Advanced SCSI Programming Interface, separates a DOS application or device module from a particular SCSI host adapter. Instead of programming adapter registers directly, software submits a SCSI Request Block (SRB) to an ASPI manager. The manager handles host-adapter transport, while the caller still needs to understand the target’s SCSI command set, data direction, completion status, and sense data.

Adaptec’s archived ASPI for DOS specification describes the DOS contract. A crucial architectural detail is that classic DOS ASPI is not just a modern function imported from a DLL. The manager is exposed through a character device named SCSIMGR$; software opens it, uses DOS IOCTL read to obtain a far entry-point address, closes the handle, and then makes far calls to submit SRBs. The exact manager and host-adapter driver must be installed for the actual hardware.

Find the manager before building a request

The initialization sequence is a capability check. Open SCSIMGR$ with DOS INT 21h, function 3Dh, using read access. If open fails, report that no compatible manager is present. Then use IOCTL input (AX=4402h) to read the four-byte entry point into a buffer. Validate that the operation succeeded before calling it, and close the device handle on both success and error paths.

open character device "SCSIMGR$"
if open fails: ASPI manager is unavailable
IOCTL-read four-byte far entry point from the handle
if IOCTL fails or entry point is invalid: close and report failure
close handle
retain the far entry point for ASPI calls

This is pseudocode, not a copy-paste assembly routine. DOS memory model, pointer layout, stack cleanup, and the ASPI specification revision all matter. Under a DOS extender, the manager’s real-mode entry point and buffer addressing may require extender-specific support; a protected-mode pointer cannot simply be treated as a real-mode segment:offset.

The SRB is the request envelope

ASPI operations use an SRB with a common header: command code, status, host-adapter number, request flags, and reserved expansion bytes. Each command has a command-specific tail. The execute-SCSI-I/O command carries a target ID and logical unit number, transfer length and buffer pointer, sense-buffer length, CDB length, host-adapter and target status fields, and the command descriptor bytes.

Initialize every field required by the chosen SRB and zero reserved bytes. Set the host-adapter index returned by the manager’s inquiry operation; do not assume adapter zero on a machine with multiple controllers. Keep SCSI target ID and LUN distinct from the DOS drive letter. A target can contain multiple logical units, and ASPI does not make a LUN into a DOS block device automatically.

The CDB is the command sent to the SCSI target. Its opcode, field lengths, allocation lengths, and data direction come from the applicable SCSI command specification and the peripheral’s behavior. ASPI transports the CDB; it does not make an invalid command valid or turn a SCSI inquiry into a filesystem operation. In particular, a CD-ROM target discovered through ASPI still needs a CD-ROM driver and, for DOS drive-letter access in common setups, a separate MSCDEX-compatible redirector.

Completion is a state transition

After submitting an execute request, the SRB status may indicate that the request is pending rather than complete. Do not read transfer data or reuse the SRB and buffer until the manager reports completion. The manager can support polling or a post routine according to its interface. In DOS, polling is straightforward but should be bounded or integrated with a wait strategy that keeps the system responsive. A post routine may run in interrupt context in some implementations, so it must be short and must not call non-reentrant DOS services.

The ASPI command status, host-adapter status, and target SCSI status answer different questions. A completed SRB says the manager finished processing the request; it does not automatically mean the target returned successful SCSI status. A target CHECK CONDITION requires examining sense data to learn why the device rejected or could not complete the command. Selection timeout, bus reset, parity error, or phase error implicates a different layer. Preserve all status bytes and the request parameters in a diagnostic record before retrying.

On CHECK CONDITION, preserve and decode the sense bytes in the SRB’s sense area. The Adaptec DOS specification says the manager automatically issues REQUEST SENSE when a SCSI command ends in check condition, provided the caller allocated sense space. Issue a separate REQUEST SENSE only if the particular manager or target contract requires it; do not assume it is always necessary or safe to repeat. Do not retry every failed command identically. A unit-attention condition may call for retry after reporting media or reset state; an illegal-request sense key means the CDB may be unsupported; a not-ready condition can be normal during spin-up or media change. Interpret sense data according to the SCSI standard and the target’s documentation.

Buffer direction, lifetime, and DMA constraints

The SRB’s data buffer must remain valid until completion. Under real-mode DOS this generally means storage accessible to the ASPI manager and host-adapter driver, not a pointer into a transient stack frame that disappears or gets reused. Extended-memory or protected-mode clients must obey their ASPI manager or extender’s address translation rules. A buffer may also face DMA limitations or 64 KiB boundaries; the manager/adapter driver may use VDS, bounce buffers, or other mechanisms, but the application must follow the manager’s documented requirements rather than guessing that every pointer is directly DMA-able.

Set the request flags to match the direction from the host’s perspective. A data-in command transfers from target to host; data-out transfers from host to target. A mismatch can overwrite memory or send unintended bytes to a device. For commands with no data phase, use the documented no-data form and zero or omit transfer fields as required. Validate the allocation length against the actual destination buffer size before submitting the command.

Keep the SRB, data buffer, CDB, and sense area alive until completion and any callback has finished. Do not issue a second operation using the same SRB while the first is pending. If the program supports asynchronous submission, track the request state explicitly and coordinate cancellation and shutdown. An abort request is itself not proof that the target stopped accessing the buffer; wait for the manager’s completion/abort status before freeing memory.

Do not confuse discovery with a DOS drive

ASPI can enumerate host adapters and query device types, but it is a transport layer. A SCSI disk attached to an ASPI manager may be handled through BIOS INT 13h, a DOS block driver, an ASPI disk module, or a specialized application. A CD-ROM setup commonly combines a host-adapter ASPI manager, a SCSI CD-ROM driver, and MSCDEX or a compatible redirector. These pieces have separate responsibilities and load-order requirements.

This layering explains a frequent false diagnosis: “The ASPI manager sees my CD-ROM, therefore DOS should show a drive letter.” The manager only establishes that the transport can discover or communicate with the target. The CD-ROM driver creates a DOS-facing device, and the redirector assigns a logical drive interface. Verify each boot-stage message separately and use the corresponding driver’s documentation when a layer fails.

Robust request procedure

For each operation, initialize a fresh SRB, populate the exact CDB and transfer description, submit it through the far entry point, then wait for a terminal state. On completion, inspect ASPI status first, followed by adapter and target status where applicable. Preserve sense data before reusing the request block. Release buffers only after the manager guarantees the request is no longer active.

Test the manager-absent case, invalid adapter number, target absent, target busy, check condition with valid sense, unexpected host error, timeout, and repeated requests. Begin with a read-only inquiry command on a disposable target. Do not test write or format CDBs against live media. Validate the byte count, buffer canaries, CDB length, and direction flag under an emulator or a known test device.

Operational rule

ASPI standardizes the path to SCSI, not the meaning or safety of every SCSI command. Discover the manager through its DOS device interface, respect the SRB and asynchronous lifecycle, keep buffers valid and correctly directed, and interpret transport and target statuses separately. For user-facing filesystems, verify the DOS block/CD-ROM driver and redirector layers as well; ASPI discovery alone does not create a drive letter.

Related:

Sources: