BASIC-DOS

Device Drivers

BASIC-DOS device drivers use PC DOS-style driver headers and request packets, with some simplifications and extensions. All built-in drivers are in BASDEV.COM; installable drivers (DEVICE=) aren’t supported yet.

Driver Headers

Each driver begins with a Device Driver Header (DDH):

Unlike PC DOS drivers, which have separate STRATEGY and INTERRUPT entry points, a BASIC-DOS driver has a single REQUEST entry point that performs the request immediately. (PC DOS always called a driver’s INTERRUPT routine right after its STRATEGY routine anyway.)

Device attributes:

In BASDEV.COM, each driver’s DDH_NEXT_OFF initially contains the driver’s length, and DDH_REQUEST initially points to its initialization code. Devinit uses the lengths to find each driver, sends it a DDC_INIT request, and chains the headers together. The driver’s INIT handler sets DDH_REQUEST to its real request handler and returns the end of its resident code in DDPI_END, so that its initialization code is discarded. For example, the entire NUL driver is:

NUL	DDH	<offset DEV:ddnul_end+16,,DDATTR_CHAR,offset ddnul_init,-1,20202020204C554Eh>

DEFPROC	ddnul_req,far
	ret
ENDPROC	ddnul_req

DEFPROC	ddnul_init,far
	mov	es:[bx].DDPI_END.OFF,offset ddnul_init
	mov	cs:[0].DDH_REQUEST,offset DEV:ddnul_req
	ret
ENDPROC	ddnul_init

The head of the driver chain is stored at 0:50Ah (DD_LIST), and DOS_UTL_GETDEV returns the header for a device name.

Request Packets

DOS calls the REQUEST entry point with a far call, with ES:BX -> request packet. Drivers don’t need to preserve any registers. Every packet begins with a 13-byte header (DDP):

PC DOS defined only the first 5 bytes of the header; BASIC-DOS uses the rest to pass context information. For example, DDC_OPEN returns a new context in DDP_CONTEXT, which DOS stores in the open file’s SFB and passes back with every later request for that handle.

INIT requests use a DDPI packet:

All other requests use a DDPRW packet:

Unlike PC DOS, DOS (not the driver) owns the BPBs for block devices: DOS passes the unit’s BPB in DDPRW_BPB, and DDC_MEDIACHK and DDC_BUILDBPB requests ask the driver to validate and rebuild it.

Commands:

On return, DDP_STATUS contains DDSTAT_DONE (0100h), plus DDSTAT_ERROR (8000h) and an error code in the low byte if the request failed. Disk error codes are the BIOS (INT 13h) error codes (eg, 03h for write-protect, 80h for drive not ready), and the other codes use values the BIOS doesn’t (eg, DDERR_UNKCMD, 06h, for an unknown command); see dev.inc for the complete list.

A request that must wait (eg, a keyboard read with no key available) calls DOS_UTL_WAIT with the packet address as the wait ID, which lets other sessions run; the driver’s interrupt handler later calls DOS_UTL_ENDWAIT with the same ID. Interrupt handlers should begin with a far call to DDINT_ENTER (0:530h) and end with a far jump to DDINT_LEAVE (0:535h), which lets DOS switch sessions when the interrupt ends.

IOCTL Functions

DOS_HDL_IOCTL (INT 21h, AH = 44h) sends IOCTL requests to drivers: AL is passed in DDP_CODE, CX in DDPRW_LENGTH, DX in DDPRW_LBA, and DS:SI in DDPRW_ADDR, and the result returned in DDP_CONTEXT is returned in DX. In addition to the standard codes (00h-07h), BASIC-DOS defines these:

CLOCK$

CON

Changing the video mode (with IOCTL_SETMODE, or with INT 10h directly) turns the context into a full-screen, borderless context that uses INT 10h for output, so text output and scrolling work in graphics modes. When the context returns to its original mode, its original geometry is restored.

FPU$

Built-in Drivers

Drivers that aren’t needed (eg, CON in a configuration that uses only serial consoles) can be omitted with SKIP=.

« Utility FunctionsFloating-Point Interface »