TP3/shell/tests/exec/bootcom.s

# bootcom.s -- load a DOS .COM from the boot floppy and run it, with INT 21h
# wired to the serial port instead of a screen.
#
# This is the piece that lets a .COM produced by this compiler actually run.
# It is deliberately not DOS: it is a 512-byte boot sector that does the four
# things a DOS .COM loader does, and sends everything the program prints out
# the serial port so a test harness can read it.
#
#   1. install an INT 21h vector pointing at a handler below
#   2. INT 13h AH=02h: read the .COM off drive A: to 0000:0100
#   3. SS:SP = 0000:FFFE, the segment top -- where DOS puts a .COM's stack
#   4. JMP 0000:0100
#
# The INT 21h handler implements the four functions this runtime actually
# calls, and nothing else:
#
#   AH=02h  display character in AL
#   AH=09h  display the $-terminated string at DS:DX
#   AH=08h  read a character without echo; 1Ah at end of input
#   AH=4Ch  terminate
#
# Those four are the complete set.  See Runtime.mod: every Int21 in it is one
# of them (the "MovAh (0)" in EmitRdInt is not an INT 21h call, it is the
# MOV AH,0 that loads a digit into AL before an ADD -- an easy thing to
# misread as a fourth function).
#
# Two properties are load-bearing:
#
#   * The handler NEVER writes to the serial port as a marker.  The program's
#     output is arbitrary bytes, so any sentinel could collide with real
#     output.  Termination travels out of band instead, through the
#     isa-debug-exit device at port 0501h: the program exits with code 0 and
#     qemu exits (value<<1)|1 = 1.  A boot failure exits with value 7Fh, i.e.
#     qemu exit code 255, which is unambiguous.  Every byte on the serial port
#     is therefore program output, with nothing to strip.
#
#   * The program is loaded at 0000:0100, so segment 0 holds the IVT at
#     0000:0000-00FF and the program from 0100 up.  The input descriptor at
#     2000h sits past the end of any fixture and is simply part of the disk
#     image the harness writes, so the addresses here are assembly constants.
#
#     The one piece of scratch the handler keeps INSIDE the loaded region is
#     0702h, the output string cursor.  Since 0100h is image offset 0, that is
#     image offset 602h -- which is inside every fixture's image, because a
#     .COM is padded out to the data base at rtSz+1000h = 11B4h.  It is in the
#     ZERO GAP between the end of the code and that data base, so it is
#     harmless today, and nothing reads it before writing it.  But it is a
#     real limit and belongs in writing rather than in a discovery later: an
#     AH=09h against a program whose code reaches 602h scribbles over that
#     program's own code.  The code starts at 1C7h and the longest fixture's
#     ends at 468h, so the margin is 19Ah = 410 bytes of code -- and it is the
#     same unenforced 4 KiB code window the linker documents, seen from the
#     other end.  Moving the cursor above everything the read covers would
#     remove the limit; it stays at 0702h because nothing needs it yet, and
#     because every address in this file is restated in run_com_exec.py, which
#     is the thing that would have to change with it.  See the layout block at
#     the end of this file.
#
# Built and driven by tests/run_com_exec.py.  tests/exec/rtdrv.s assembles the
# other half of this machinery -- the driver that calls runtime entries directly
# -- and reuses this file rather than growing a second boot path.

	.code16
	.text
	.globl	_start

_start:
	cli
	xorw	%ax, %ax
	movw	%ax, %ds
	movw	%ax, %es
	movw	%ax, %ss
	movw	$0xfffe, %sp
	sti

	# IVT entry 21h lives at 0000:0084 (21h * 4): offset word then segment.
	# `handler' is a section-relative offset because the section starts at 0;
	# the segment this sector was loaded at is 7C00h.
	movw	$handler, %ax
	addw	$0x7c00, %ax
	movw	%ax, 0x84
	movw	$0, %ax
	movw	%ax, 0x86

	# INT 13h AH=00h: reset the drive controller.  A floppy that has just
	# been attached needs this before a read will succeed.
	movb	$0x00, %ah
	int	$0x13

	# Retry the read: qemu's floppy is a file image and a read can fail while
	# it settles.  Three attempts, then give up loudly.
	#
	# The read lands at SCRATCH, not at 0100h, and is copied down afterwards.
	# That is not ceremony.  0400h-04FFh is the BIOS data area, and SeaBIOS
	# keeps live state in it; a transfer whose destination covers that window
	# destroys it, and SeaBIOS writes part of it back *after* the DMA, so ten
	# bytes of BIOS data end up on top of the image once the transfer is over.
	#
	# The damage is the worst kind.  It is the right length, in the right
	# place, and nothing reports an error -- the read sets CF=0, exactly as
	# the jnc below expects.  It was found by a 19-byte probe that read 0440h
	# as its first instruction after the jump and got the BIOS's own bytes
	# back, and then confirmed by dumping the whole loaded image: one 10-byte
	# run wrong inside an otherwise byte-perfect 512-byte sector, which no
	# partial-read or sector-count bug can produce.
	#
	# 8000h is clear of the IVT (0-3FFh), the BDA (400-4FFh), SeaBIOS's stack
	# at 700h and the option-ROM window at C000h.  REP MOVSW is executed code,
	# so the copy is the LAST thing that touches 0100h-20FFh and no BIOS call
	# follows it.  The copy is what the program then runs out of, unchanged.
	movw	$3, %cx
.Lretry:
	movw	$SCRATCH, %bx		# ES:BX = 0000:8000
	movb	$0x02, %ah		# read sectors
	movb	$16, %al		# 16 * 512 = 8192 bytes, far more than any fixture
	movb	$0x00, %ch		# cylinder 0
	movb	$0x02, %cl		# sector 2 -- the .COM, 1-based
	movb	$0x00, %dh		# head 0
	movb	$0x00, %dl		# drive A
	int	$0x13
	jnc	.Lcopy
	decw	%cx
	jnz	.Lretry
.Lbootfail:
	movb	$0x7f, %al
	movw	$0x0501, %dx		# isa-debug-exit
	outb	%al, %dx
	cli
	hlt
.Lcopy:
	movw	$0x0100, %di
	movw	$SCRATCH, %si
	movw	$4096, %cx		# 8192 bytes = 16 sectors
	cld
	rep	movsw
	.byte	0xEA, 0x00, 0x01, 0x00, 0x00	# jmp 0000:0100

# ---------------------------------------------------------------- INT 21h
# Called with the program's registers.  DS is the caller's data segment
# (0000h here) and is preserved, so AH=09h can reach DS:DX the way DOS does.
# Every path ends at .Ldone, which restores everything and IRETs -- except
# AH=4Ch, which does not return at all.
handler:
	pushw	%ax
	pushw	%bx
	pushw	%cx
	pushw	%dx
	pushw	%si
	pushw	%di
	pushw	%ds
	pushw	%es

	# Direction flag, before anything reads it.  Both lodsb's below walk
	# FORWARD, and DF belongs to the interrupted program, not to the
	# handler: a handler that assumes the caller's DF is clear is correct
	# only for as long as no caller ever sets it.  It has never fired -
	# nothing in Runtime.mod uses a string instruction, so DF is whatever
	# the BIOS left, and that is 0 - which is exactly why it is worth
	# writing down.  DF is not restored, because nothing downstream reads
	# it and restoring it would mean saving EFLAGS around the whole handler.
	cld

	cmpb	$0x02, %ah
	je	.Lh02
	cmpb	$0x09, %ah
	je	.Lh09
	cmpb	$0x08, %ah
	je	.Lh08
	cmpb	$0x4c, %ah
	je	.Lh4c
	stc				# unknown function
	jmp	.Ldone

.Lh02:					# display character in AL
	call	ser_put
	clc
	jmp	.Ldone

.Lh09:					# display the $-terminated string at DS:DX
	movw	%dx, 0x0702		# ser_put clobbers DX, so keep the pointer
.Lh09next:
	movw	0x0702, %si		# lodsb: AL = [DS:SI].  Register-indirect
	lodsb				# addressing with no displacement is not
	cmpb	$0x24, %al		# expressible in gas .code16 syntax, and
	je	.Lh09done		# keeping the cursor in memory means the
	call	ser_put		# pointer survives ser_put's use of DX.
	incw	0x0702
	jmp	.Lh09next
.Lh09done:
	clc
	jmp	.Ldone

.Lh08:					# read a character, no echo, 1Ah at EOF
	# NOTE: this is the one function whose RESULT is in AL, so it must return
	# through .Ldone8 and not .Ldone - see there.
	movw	INLEN, %ax		# inlen
	movw	INCUR, %bx		# input cursor
	# EOF is when the cursor has REACHED the length, i.e. INCUR >= INLEN.
	# `cmpw %bx, %ax / jbe' tests AX <= BX, that is INLEN <= INCUR, which is
	# true on the FIRST character: it returned 1Ah immediately, so readln saw
	# an empty input and then looped for the line terminator that never came.
	# t29_readln hung with no output at all.  (This was a bug in the harness,
	# not in the compiler - but a harness that feeds the program nothing can
	# never tell you whether the program handles input, so it is a bug that
	# hides bugs.)
	cmpw	%ax, %bx		# INCUR vs INLEN
	jae	.Lh08eof
	# INCUR is an index INTO the buffer, not an address: the bytes live at
	# INBUF, and SI = INCUR alone reads the interrupt vector table at 0000:0000
	# - so AH=08h returned IVT[0] (a low timer vector byte) as the first
	# character of input.  INCUR is 0 on the first call, which is the one
	# address in segment 0 that is guaranteed to be wrong.
	movw	%bx, %si
	addw	$INBUF, %si
	lodsb
	incw	INCUR
	clc
	jmp	.Ldone8		# NOT .Ldone: AL is the result here
.Lh08eof:
	movb	$0x1a, %al
	clc
	jmp	.Ldone8

.Lh4c:					# terminate: exit with AL as the code
	movw	$0x0501, %dx		# isa-debug-exit
	outb	%al, %dx
	cli
	hlt
	jmp	.Lh4c

.Ldone:
	popw	%es
	popw	%ds
	popw	%di
	popw	%si
	popw	%dx
	popw	%cx
	popw	%bx
	popw	%ax
	iret

# The same, but for the one function that RETURNS something in AL.  DOS
# AH=08h hands the character back in AL, so restoring AX on the way out
# throws the answer away and the caller reads whatever AX held on entry.
#
# This was silent in a way that is worth recording: the shim's read path was
# structurally correct - it found the buffer, advanced the cursor, cleared
# the carry - and the character was plainly in AL, one instruction before the
# return.  The discard happened in the epilogue, which every OTHER function
# needs.  So t29_readln did not see a wrong byte; it saw the *uninitialised*
# AX the runtime had at the call, which is the first byte of a pointer it was
# about to overwrite with the parsed value.  readln compared that against 0Dh,
# 0Ah and 1Ah, rejected it, and looped forever - a hang with no output, from
# a read that demonstrably worked.
#
# AX is therefore popped only on the paths where it is not a result, and
# AH=02h/09h (which also leave AL alone in DOS) keep using .Ldone.
.Ldone8:
	popw	%es
	popw	%ds
	popw	%di
	popw	%si
	popw	%dx
	popw	%cx
	popw	%bx
	addw	$2, %sp		# drop the saved AX, keep AL
	iret

# ser_put: send AL to the serial port, leaving AL and DX alone.
# No line-status polling: qemu's 16550 always accepts a byte, and a poll
# that never goes ready would hang the harness rather than fail it.
ser_put:
	pushw	%ax
	movw	$0x03f8, %dx
	outb	%al, %dx
	popw	%ax
	ret

# --------------------------------------------------------------- layout
# The input descriptor lives at 2000h, which the read + copy above covers
# (0100h + 2000h = 2100h) and which is well past the end of any fixture (the
# largest is 4493 bytes, so the image stops at 1285h).  So the descriptor is
# simply part of the disk image the harness writes, not something it has to
# patch into this boot sector afterwards -- which means the addresses here are
# assembly constants and the harness only has to know where they land in the
# file.  See run_com_exec.py, FLAT_OFF.
#
# SCRATCH is where the sector read parks the bytes before the copy moves them
# to 0100h.  Nothing may ever be placed there: the region is not reserved by
# this file, it is merely unused, and a future change that put a table at
# 8000h would be overwritten by the read and would not notice.
	.set	SCRATCH, 0x8000		# see the note above: not 0100h
	.set	INLEN, 0x2000		# word: number of input bytes
	.set	INCUR, 0x2002		# word: cursor, starts at INBUF
	.set	INBUF, 0x2004		# the bytes themselves
	.set	INMAX, 0x00fc		# 2100h - 2004h, the most that fits

	.org	510
	.byte	0x55, 0xAA