AUTORUN.SYS and Auto-Booting Programs

Black Atari screen with the text THIS BASIC PROGRAM WAS STARTED BY AUTORUN.SYS, NOBODY TYPED RUN, and MEMLO=7276

Put a file called AUTORUN.SYS on an Atari DOS 2 disk and it runs every time the disk boots. That simple convention gave thousands of disks their "insert and switch on" convenience: games that started by themselves, handlers loaded before BASIC, and magazine disks that opened straight into a menu. This guide covers what DOS actually does with the file, how to make a BASIC program start by itself (BASIC programs can't simply be renamed), and how the other popular DOSes do the same job.

What you'll learn: when and how AUTORUN.SYS is loaded, what happens before and after it, the classic E: hook trick for starting a BASIC program (with a tested assembly version), combining and skipping autoruns, and the MyDOS, SpartaDOS, BW-DOS and Turbo-BASIC conventions.

What you need: a DOS 2.0S or 2.5 disk, the MADS assembler for the example, and a way to copy files to the disk. The binary file format itself (segments, RUNAD and INITAD) is covered in Inside the XEX, and boot sectors in Writing a Bootable Disk Program.

1. What DOS 2 does at boot

  1. The OS reads the boot sectors, which load DOS.SYS (the file manager) and link D: into the handler table.
  2. As part of its initialisation, DOS looks on drive 1 for AUTORUN.SYS. If the file exists, DOS binary-loads it exactly as the menu's L command would. Any INIT address (INITAD, $02E2) is called as soon as its segment loads, and the RUN address (RUNAD, $02E0) is called once the whole file is in memory.
  3. When the autorun code returns with RTS, DOS finishes its setup and the OS continues the cold start. If a cartridge (or XL/XE built-in BASIC) wants to run, it starts now. Otherwise the OS jumps through DOSVEC, which brings up the DUP menu if DUP.SYS is on the disk.

Three consequences follow:

  • AUTORUN.SYS runs before BASIC starts. Anything it changes, such as colours, margins, MEMLO or the handler table, is already in place when BASIC initialises. BASIC takes the start of its program memory from MEMLO at that point, so an AUTORUN handler that raises MEMLO is automatically protected.
  • It runs only at power-up. A one-line AUTORUN.SYS that increments a byte in page 6 shows this: after a RESET, the counter still reads 1 under DOS 2.5. Code that must survive RESET has to hook DOSINI itself (see Writing Your Own CIO Device Handler).
  • It's an ordinary binary file. Any XEX-style program renamed to AUTORUN.SYS will load. A program that never returns simply takes over the machine, which is how most games did it.

Typical AUTORUN.SYS files come in three kinds: small setup files that just change system settings, handlers (RS-232, printer and screen drivers) that install themselves and return, and BASIC program loaders. The last kind is the interesting one.

2. Why BASIC programs need a helper

A SAVEd BASIC program is tokenized data for the BASIC interpreter, not machine code, so DOS can't binary-load it. Something has to get BASIC to execute RUN "D:MENU.BAS" after BASIC has started, which is after AUTORUN.SYS has already finished. Some options:

  • Stuff the keyboard. The OS keeps only one pending keystroke (CH, location 764), so you can't type a whole command that way.
  • Print the command and force-read it. The screen editor's forced-read mode (AUX1 = 13 on IOCB 0) works inside BASIC, but BASIC's cold start clears the screen first.
  • Hook the E: handler. This is the classic answer, used for example by Carl Evans's AUTOGO in Atari BASIC Faster and Better (1983), a BASIC program that writes such an AUTORUN.SYS for any file name.

The hook works like this. The AUTORUN code finds the E entry in HATABS ($031A), copies the editor's 16-byte vector table into RAM, replaces the GET BYTE vector with its own routine, and points the E entry at the copy. When BASIC starts and asks the editor for its first input line, CIO calls the fake GET routine, which returns the command one character at a time. When it hands over the final RETURN (EOL), the routine puts the original HATABS entry back, so the keyboard works normally from then on. As far as BASIC can tell, someone typed the command very quickly.

3. A tested AUTORUN.SYS for BASIC programs

; AUTORUN.SYS that makes BASIC run a program - mads autorun.asm -o:autorun.sys
HATABS = $031A
PTR    = $CB            ; temporary page-zero pointer
EOL    = $9B

        org $0600       ; dead once the command has been read
install ldx #0
find    lda HATABS,x    ; find the E: entry
        cmp #'E'
        beq found
        inx
        inx
        inx
        cpx #36
        bcc find
        rts             ; no E: (can't happen)
found   stx eslot
        lda HATABS+1,x  ; remember the ROM vector table address
        sta PTR
        sta oldtab
        lda HATABS+2,x
        sta PTR+1
        sta oldtab+1
        ldy #15         ; copy the 16-byte table into RAM
cp      lda (PTR),y
        sta etab,y
        dey
        bpl cp
        lda #<(myget-1) ; replace GET BYTE (offset 4)
        sta etab+4
        lda #>(myget-1)
        sta etab+5
        lda #<etab      ; point E: at the patched copy
        sta HATABS+1,x
        lda #>etab
        sta HATABS+2,x
        lda #0
        sta pos
        rts             ; back to DOS, which carries on booting

myget   ldy pos         ; hand BASIC the next character
        lda cmd,y
        inc pos
        cmp #EOL
        bne ok
        ldx eslot       ; line complete: put the real E: back
        lda oldtab
        sta HATABS+1,x
        lda oldtab+1
        sta HATABS+2,x
        lda #EOL
ok      ldy #1          ; success
        rts

cmd     dta c'RUN "D:MENU.BAS"',EOL
eslot   dta 0
oldtab  dta a(0)
pos     dta 0
etab    .ds 16

        ini install

Assemble it, copy autorun.sys to the disk as AUTORUN.SYS along with DOS.SYS and your MENU.BAS, and boot with BASIC enabled. The screenshot shows the result on a DOS 2.5 disk: the program ran without anyone typing anything, and MEMLO reads 7276 ($1C6C), DOS 2.5's value. Notes:

  • The stub lives in page 6. It is only needed until BASIC has read the command line, after which your BASIC program may use page 6 freely. AUTOGO used the same arrangement.
  • Change cmd to run a different file, or to execute something else entirely. ENTER "D:SETUP.LST" would merge a listed file. A short string of statements such as POKE 82,0:RUN "D:MENU.BAS" also works, since BASIC accepts anything you could type at the READY prompt.
  • The GET routine doesn't need to preserve X, because CIO reloads the IOCB index itself before every handler call. Handler conventions are covered in Writing Your Own CIO Device Handler.
  • Without BASIC (an 800 with no cartridge, or an XL/XE booted with OPTION held), the DUP menu would receive the command instead. A careful loader checks first that a cartridge is present.

If you'd rather not assemble anything, DOS 2.5's SETUP.COM (option 3) builds an equivalent file from a menu, and can load the 850's R: handler at the same time. See Atari DOS 2.5: A Practical Guide.

4. More than one autorun, and skipping them

Because AUTORUN.SYS is a binary file, two programs can often be combined into one by appending binary files. DOS 2's copy command does this with the /A option. Antic's "AUTORUN Selector" (June 1989) used it to put a small prefix in front of an existing AUTORUN.SYS:

C
AUTORUN.SYS,SELECT.EXE/A

followed by deleting the old AUTORUN.SYS and renaming SELECT.EXE to take its place. Combining files works only if the parts don't load into the same memory, and if each part's INIT returns rather than taking over. A RUN address in the first part is replaced by any later one, since only the last RUNAD written counts.

The Selector prefix itself solved a common annoyance: DOS 2 has no way to bypass AUTORUN.SYS. The prefix reads CONSOL ($D01F). If SELECT is held during boot (bit 1 clear), it jumps through DOSVEC to the DOS menu instead of letting the rest of the file load. Antic's "Multi-AUTORUN" (March 1987) went the other way. It patched DOS.SYS to load AUTORUN.SYS, then AUTORUN1.SYS, AUTORUN2.SYS and so on, until one was missing.

On an XL/XE, holding OPTION during power-up disables the built-in BASIC. That matters both for autoruns that need the RAM at $A000–$BFFF and for BASIC loaders, which then have no BASIC to talk to.

5. Other DOSes

DOS Startup convention
Atari DOS 2.0S, 2.5 AUTORUN.SYS (binary) on D1:
MyDOS 4.50 AUTORUN.SYS, like DOS 2. Its utilities are shipped as .AUT files (e.g. ATARI850.AUT) for renaming
MyDOS 4.53 *.AR0 to *.AR9, several at boot. Plain AUTORUN.SYS support was removed
SpartaDOS 3.2 Both a STARTUP.BAT batch file and an AUTORUN.SYS
SpartaDOS X, DOS XE AUTOEXEC.BAT (a text batch file of commands)
BW-DOS STARTUP.BAT
Turbo-BASIC XL Runs AUTORUN.BAS from the boot disk when it starts

Under SpartaDOS X, starting a BASIC program needs no machine code. A text file holding the BASIC command is fed to BASIC with input redirection. Put RUN "D:START.BAS" in a text file called AUTOGO, then add this line to AUTOEXEC.BAT:

BASIC <<AUTOGO

The SDX manual also suggests renaming an old DOS 2-style BASIC loader to something like MENU.COM and running it with BASIC IN MENU. For AUTOEXEC.BAT basics and CONFIG.SYS's SET BATCH= alternative, see SpartaDOS X: Getting Started. Handler-type AUTORUN.SYS files can usually just be renamed to .COM and run from the SDX command line.

Troubleshooting

  • Nothing happens at boot: the file isn't named exactly AUTORUN.SYS, it isn't on the disk in drive 1, or the disk doesn't contain DOS.SYS (for example, the DOS files were never written to it).
  • Boots to the DOS menu instead of BASIC: BASIC is disabled (OPTION held, or no cartridge on an 800), or your AUTORUN code jumped through DOSVEC.
  • ERROR 170 (file not found) right after boot: the BASIC loader worked, but the file name in its command doesn't match the disk.
  • Machine locks up after loading: the AUTORUN code loads over DOS, its buffers or page zero still in use by DOS. Load above MEMLO (around $1C6C under DOS 2.5, more with extra buffers).
  • Works until RESET: expected. AUTORUN.SYS isn't reloaded on RESET, so hook DOSINI.

Further reading

  • De Re Atari (Atari, 1982), chapter 9: "The AUTORUN.SYS File". Note that it swaps the RUN and INIT addresses ($02E0 is RUN).
  • Carl M. Evans, Atari BASIC Faster and Better (IJG, 1983), chapter 15: AUTOGO, a BASIC program that writes an E:-hooking AUTORUN.SYS.
  • "AUTORUN Selector", Jason Strautman, Antic, June 1989. "Multi-AUTORUN", Bill Bodenstein, Antic, March 1987.
  • SpartaDOS X Reference Manual (ICD): chapter 5, batch files and I/O redirection, and the appendix on running DOS 2 AUTORUN files.
  • On this site: Inside the XEX, Atari DOS 2.5: A Practical Guide, MyDOS 4.5, Choosing a DOS and Saving and Loading BASIC Programs.

Credits