Comment this bad boy. Hopefully the next person that comes along won't

have to spend a few hours reading the code to figure all this out.

2 files changed, 196 insertions, 58 deletions

diff --git a/sys/boot/i386/boot2/boot1.S b/sys/boot/i386/boot2/boot1.S
index 2c557ec..da238b1 100644
--- a/sys/boot/i386/boot2/boot1.S
+++ b/sys/boot/i386/boot2/boot1.S
@@ -15,6 +15,7 @@
 
 # $FreeBSD$
 
+# Memory Locations
 		.set MEM_REL,0x700		# Relocation address
 		.set MEM_ARG,0x900		# Arguments
 		.set MEM_ORG,0x7c00		# Origin
@@ -22,11 +23,16 @@
 		.set MEM_BTX,0x9000		# BTX start
 		.set MEM_JMP,0x9010		# BTX entry point
 		.set MEM_USR,0xa000		# Client start
-
+	
+# Partition Constants 
 		.set PRT_OFF,0x1be		# Partition offset
 		.set PRT_NUM,0x4		# Partitions
 		.set PRT_BSD,0xa5		# Partition type
 
+# Flag Bits
+		.set FL_PACKET,0x80		# Packet mode
+
+# Misc. Constants
 		.set SIZ_PAG,0x1000		# Page size
 		.set SIZ_SEC,0x200		# Sector size
 
@@ -37,11 +43,21 @@
 start:		jmp main			# Start recognizably
 
 		.org 0x4,0x90
-
-# External read from disk
+# 
+# Trampoline used by boot2 to call read to read data from the disk via
+# the BIOS.  Call with:
+#
+# %cx:%ax	- long    - LBA to read in
+# %es:(%bx)	- caddr_t - buffer to read data into
+# %dl		- byte    - drive to read from
+# %dh		- byte    - num sectors to read
+# 
 
 xread:		push %ss			# Address
 		pop %ds				#  data
+#
+# Setup an EDD disk packet and pass it to read
+# 
 xread.1:					# Starting
 		pushl $0x0			#  absolute
 		push %cx			#  block
@@ -56,20 +72,37 @@ xread.1:					# Starting
 		callw read			# Read from disk
 		lea 0x10(%bp),%sp		# Clear stack
 		lret				# To far caller
+# 
+# Load the rest of boot2 and BTX up, copy the parts to the right locations,
+# and start it all up.
+#
 
-# Bootstrap
-
+#
+# Setup the segment registers to flat addressing (segment 0) and setup the
+# stack to end just below the start of our code.
+# 
 main:		cld				# String ops inc
 		xor %cx,%cx			# Zero
 		mov %cx,%es			# Address
 		mov %cx,%ds			#  data
 		mov %cx,%ss			# Set up
 		mov $start,%sp			#  stack
+#
+# Relocate ourself to MEM_REL.  Since %cx == 0, the inc %ch sets
+# %cx == 0x100.
+# 
 		mov %sp,%si			# Source
 		mov $MEM_REL,%di		# Destination
 		incb %ch			# Word count
 		rep				# Copy
 		movsw				#  code
+#
+# If we are on a hard drive, then load the MBR and look for the first
+# FreeBSD slice.  We use the fake partition entry below that points to
+# the MBR when we call nread.  The first pass looks for the first active
+# FreeBSD slice.  The second pass looks for the first non-active FreeBSD
+# slice if the first one fails.
+# 
 		mov $part4,%si			# Partition
 		cmpb $0x80,%dl			# Hard drive?
 		jb main.4			# No
@@ -89,29 +122,50 @@ main.3: 	add $0x10,%si	 		# Next entry
 		jb main.2			# Yes
 		dec %cx				# Do two
 		jcxz main.1			#  passes
+#
+# If we get here, we didn't find any FreeBSD slices at all, so print an
+# error message and die.
+# 
 		mov $msg_part,%si		# Message
 		jmp error			# Error
+#
+# Floppies use partition 0 of drive 0.
+# 
 main.4: 	xor %dx,%dx			# Partition:drive
+#
+# Ok, we have a slice and drive in %dx now, so use that to locate and load
+# boot2.  %si references the start of the slice we are looking for, so go
+# ahead and load up the first 16 sectors (boot1 + boot2) from that.  When
+# we read it in, we conveniently use 0x8c00 as our transfer buffer.  Thus,
+# boot1 ends up at 0x8c00, and boot2 starts at 0x8c00 + 0x200 = 0x8e00.
+# The first part of boot2 is boot2.ldr, which is 0x200 bytes of zeros.
+# The second part is BTX, which is thus loaded into 0x9000, which is where
+# it also runs from.  The boot2.bin binary starts right after the end of
+# BTX, so we have to figure out where the start of it is and then move the
+# binary to 0xb000.  Normally, BTX clients start at MEM_USR, or 0xa000, but
+# when we use btxld create boot2, we use an entry point of 0x1000.  That
+# entry point is relative, to MEM_USR, thus boot2.bin starts at 0xb000.
+# 
 main.5: 	mov %dx,MEM_ARG			# Save args
 		movb $0x10,%dh			# Sector count
 		callw nread			# Read disk
 		mov $MEM_BTX,%bx		# BTX
-		mov 0xa(%bx),%si		# Point past
-		add %bx,%si			#  it
+		mov 0xa(%bx),%si		# Get BTX length and set
+		add %bx,%si			#  %si to start of boot2.bin
 		mov $MEM_USR+SIZ_PAG,%di	# Client page 1
 		mov $MEM_BTX+0xe*SIZ_SEC,%cx	# Byte
 		sub %si,%cx			#  count
 		rep				# Relocate
 		movsb				#  client
 		sub %di,%cx			# Byte count
-		xorb %al,%al			# Zero
-		rep				#  assumed
-		stosb				#  bss
+		xorb %al,%al			# Zero assumed bss from
+		rep				#  the end of boot2.bin
+		stosb				#  up to 0x10000
 		callw seta20			# Enable A20
 		jmp start+MEM_JMP-MEM_ORG	# Start BTX
-
-# Enable A20
-
+# 
+# Enable A20 so we can access memory above 1 meg.
+# 
 seta20: 	cli				# Disable interrupts
 seta20.1:	inb $0x64,%al			# Get status
 		testb $0x2,%al			# Busy?
@@ -125,28 +179,31 @@ seta20.2:	inb $0x64,%al			# Get status
 		outb %al,$0x60			#  A20
 		sti				# Enable interrupts
 		retw				# To caller
-
-# Local read from disk
-
+# 
+# Trampoline used to call read from within boot1.
+# 
 nread:		mov $MEM_BUF,%bx		# Transfer buffer
 		mov 0x8(%si),%ax		# Get
 		mov 0xa(%si),%cx		#  LBA
 		push %cs			# Read from
 		callw xread.1	 		#  disk
-		jnc return			# If success
-		mov $msg_read,%si		# Message
-
-# Error exit
-
+		jnc return			# If success, return
+		mov $msg_read,%si		# Otherwise, set the error
+						#  message and fall through to
+						#  the error routine
+# 
+# Print out the error message pointed to by %ds:(%si) followed
+# by a prompt, wait for a keypress, and then reboot the machine.
+# 
 error:		callw putstr			# Display message
 		mov $prompt,%si			# Display
 		callw putstr			#  prompt
 		xorb %ah,%ah			# BIOS: Get
 		int $0x16			#  keypress
 		int $0x19			# BIOS: Reboot
-
-# Display string
-
+# 
+# Display a null-terminated string using the BIOS output.
+# 
 putstr.0:	mov $0x7,%bx	 		# Page:attribute
 		movb $0xe,%ah			# BIOS: Display
 		int $0x10			#  character
@@ -154,13 +211,25 @@ putstr: 	lodsb				# Get char
 		testb %al,%al			# End of string?
 		jne putstr.0			# No
 
+#
+# Overused return code.  ereturn is used to return an error from the
+# read function.  Since we assume putstr succeeds, we (ab)use the
+# same code when we return from putstr. 
+# 
 ereturn:	movb $0x1,%ah			# Invalid
 		stc				#  argument
 return: 	retw				# To caller
-
-# Read from disk
-
-read:		testb $0x80,%cs:MEM_REL+flags-start # LBA support enabled?
+# 
+# Reads sectors from the disk.  If EDD is enabled, then check if it is
+# installed and use it if it is.  If it is not installed or not enabled, then
+# fall back to using CHS.  Since we use a LBA, if we are using CHS, we have to
+# fetch the drive parameters from the BIOS and divide it out ourselves.
+# Call with:
+#
+# %dl	- byte     - drive number
+# stack - 10 bytes - EDD Packet
+# 
+read:		testb $FL_PACKET,%cs:MEM_REL+flags-start # LBA support enabled?
 		jz read.1			# No
 		mov $0x55aa,%bx			# Magic
 		push %dx			# Save
@@ -252,6 +321,6 @@ flags:		.byte FLAGS			# Flags
 part4:		.byte 0x80, 0x00, 0x01, 0x00
 		.byte 0xa5, 0xff, 0xff, 0xff
 		.byte 0x00, 0x00, 0x00, 0x00
-		.byte 0x50, 0xc3, 0x00, 0x00
+		.byte 0x50, 0xc3, 0x00, 0x00	# 50000 sectors long, bleh
 
 		.word 0xaa55			# Magic number
diff --git a/sys/boot/i386/boot2/boot1.s b/sys/boot/i386/boot2/boot1.s
index 2c557ec..da238b1 100644
--- a/sys/boot/i386/boot2/boot1.s
+++ b/sys/boot/i386/boot2/boot1.s
@@ -15,6 +15,7 @@
 
 # $FreeBSD$
 
+# Memory Locations
 		.set MEM_REL,0x700		# Relocation address
 		.set MEM_ARG,0x900		# Arguments
 		.set MEM_ORG,0x7c00		# Origin
@@ -22,11 +23,16 @@
 		.set MEM_BTX,0x9000		# BTX start
 		.set MEM_JMP,0x9010		# BTX entry point
 		.set MEM_USR,0xa000		# Client start
-
+	
+# Partition Constants 
 		.set PRT_OFF,0x1be		# Partition offset
 		.set PRT_NUM,0x4		# Partitions
 		.set PRT_BSD,0xa5		# Partition type
 
+# Flag Bits
+		.set FL_PACKET,0x80		# Packet mode
+
+# Misc. Constants
 		.set SIZ_PAG,0x1000		# Page size
 		.set SIZ_SEC,0x200		# Sector size
 
@@ -37,11 +43,21 @@
 start:		jmp main			# Start recognizably
 
 		.org 0x4,0x90
-
-# External read from disk
+# 
+# Trampoline used by boot2 to call read to read data from the disk via
+# the BIOS.  Call with:
+#
+# %cx:%ax	- long    - LBA to read in
+# %es:(%bx)	- caddr_t - buffer to read data into
+# %dl		- byte    - drive to read from
+# %dh		- byte    - num sectors to read
+# 
 
 xread:		push %ss			# Address
 		pop %ds				#  data
+#
+# Setup an EDD disk packet and pass it to read
+# 
 xread.1:					# Starting
 		pushl $0x0			#  absolute
 		push %cx			#  block
@@ -56,20 +72,37 @@ xread.1:					# Starting
 		callw read			# Read from disk
 		lea 0x10(%bp),%sp		# Clear stack
 		lret				# To far caller
+# 
+# Load the rest of boot2 and BTX up, copy the parts to the right locations,
+# and start it all up.
+#
 
-# Bootstrap
-
+#
+# Setup the segment registers to flat addressing (segment 0) and setup the
+# stack to end just below the start of our code.
+# 
 main:		cld				# String ops inc
 		xor %cx,%cx			# Zero
 		mov %cx,%es			# Address
 		mov %cx,%ds			#  data
 		mov %cx,%ss			# Set up
 		mov $start,%sp			#  stack
+#
+# Relocate ourself to MEM_REL.  Since %cx == 0, the inc %ch sets
+# %cx == 0x100.
+# 
 		mov %sp,%si			# Source
 		mov $MEM_REL,%di		# Destination
 		incb %ch			# Word count
 		rep				# Copy
 		movsw				#  code
+#
+# If we are on a hard drive, then load the MBR and look for the first
+# FreeBSD slice.  We use the fake partition entry below that points to
+# the MBR when we call nread.  The first pass looks for the first active
+# FreeBSD slice.  The second pass looks for the first non-active FreeBSD
+# slice if the first one fails.
+# 
 		mov $part4,%si			# Partition
 		cmpb $0x80,%dl			# Hard drive?
 		jb main.4			# No
@@ -89,29 +122,50 @@ main.3: 	add $0x10,%si	 		# Next entry
 		jb main.2			# Yes
 		dec %cx				# Do two
 		jcxz main.1			#  passes
+#
+# If we get here, we didn't find any FreeBSD slices at all, so print an
+# error message and die.
+# 
 		mov $msg_part,%si		# Message
 		jmp error			# Error
+#
+# Floppies use partition 0 of drive 0.
+# 
 main.4: 	xor %dx,%dx			# Partition:drive
+#
+# Ok, we have a slice and drive in %dx now, so use that to locate and load
+# boot2.  %si references the start of the slice we are looking for, so go
+# ahead and load up the first 16 sectors (boot1 + boot2) from that.  When
+# we read it in, we conveniently use 0x8c00 as our transfer buffer.  Thus,
+# boot1 ends up at 0x8c00, and boot2 starts at 0x8c00 + 0x200 = 0x8e00.
+# The first part of boot2 is boot2.ldr, which is 0x200 bytes of zeros.
+# The second part is BTX, which is thus loaded into 0x9000, which is where
+# it also runs from.  The boot2.bin binary starts right after the end of
+# BTX, so we have to figure out where the start of it is and then move the
+# binary to 0xb000.  Normally, BTX clients start at MEM_USR, or 0xa000, but
+# when we use btxld create boot2, we use an entry point of 0x1000.  That
+# entry point is relative, to MEM_USR, thus boot2.bin starts at 0xb000.
+# 
 main.5: 	mov %dx,MEM_ARG			# Save args
 		movb $0x10,%dh			# Sector count
 		callw nread			# Read disk
 		mov $MEM_BTX,%bx		# BTX
-		mov 0xa(%bx),%si		# Point past
-		add %bx,%si			#  it
+		mov 0xa(%bx),%si		# Get BTX length and set
+		add %bx,%si			#  %si to start of boot2.bin
 		mov $MEM_USR+SIZ_PAG,%di	# Client page 1
 		mov $MEM_BTX+0xe*SIZ_SEC,%cx	# Byte
 		sub %si,%cx			#  count
 		rep				# Relocate
 		movsb				#  client
 		sub %di,%cx			# Byte count
-		xorb %al,%al			# Zero
-		rep				#  assumed
-		stosb				#  bss
+		xorb %al,%al			# Zero assumed bss from
+		rep				#  the end of boot2.bin
+		stosb				#  up to 0x10000
 		callw seta20			# Enable A20
 		jmp start+MEM_JMP-MEM_ORG	# Start BTX
-
-# Enable A20
-
+# 
+# Enable A20 so we can access memory above 1 meg.
+# 
 seta20: 	cli				# Disable interrupts
 seta20.1:	inb $0x64,%al			# Get status
 		testb $0x2,%al			# Busy?
@@ -125,28 +179,31 @@ seta20.2:	inb $0x64,%al			# Get status
 		outb %al,$0x60			#  A20
 		sti				# Enable interrupts
 		retw				# To caller
-
-# Local read from disk
-
+# 
+# Trampoline used to call read from within boot1.
+# 
 nread:		mov $MEM_BUF,%bx		# Transfer buffer
 		mov 0x8(%si),%ax		# Get
 		mov 0xa(%si),%cx		#  LBA
 		push %cs			# Read from
 		callw xread.1	 		#  disk
-		jnc return			# If success
-		mov $msg_read,%si		# Message
-
-# Error exit
-
+		jnc return			# If success, return
+		mov $msg_read,%si		# Otherwise, set the error
+						#  message and fall through to
+						#  the error routine
+# 
+# Print out the error message pointed to by %ds:(%si) followed
+# by a prompt, wait for a keypress, and then reboot the machine.
+# 
 error:		callw putstr			# Display message
 		mov $prompt,%si			# Display
 		callw putstr			#  prompt
 		xorb %ah,%ah			# BIOS: Get
 		int $0x16			#  keypress
 		int $0x19			# BIOS: Reboot
-
-# Display string
-
+# 
+# Display a null-terminated string using the BIOS output.
+# 
 putstr.0:	mov $0x7,%bx	 		# Page:attribute
 		movb $0xe,%ah			# BIOS: Display
 		int $0x10			#  character
@@ -154,13 +211,25 @@ putstr: 	lodsb				# Get char
 		testb %al,%al			# End of string?
 		jne putstr.0			# No
 
+#
+# Overused return code.  ereturn is used to return an error from the
+# read function.  Since we assume putstr succeeds, we (ab)use the
+# same code when we return from putstr. 
+# 
 ereturn:	movb $0x1,%ah			# Invalid
 		stc				#  argument
 return: 	retw				# To caller
-
-# Read from disk
-
-read:		testb $0x80,%cs:MEM_REL+flags-start # LBA support enabled?
+# 
+# Reads sectors from the disk.  If EDD is enabled, then check if it is
+# installed and use it if it is.  If it is not installed or not enabled, then
+# fall back to using CHS.  Since we use a LBA, if we are using CHS, we have to
+# fetch the drive parameters from the BIOS and divide it out ourselves.
+# Call with:
+#
+# %dl	- byte     - drive number
+# stack - 10 bytes - EDD Packet
+# 
+read:		testb $FL_PACKET,%cs:MEM_REL+flags-start # LBA support enabled?
 		jz read.1			# No
 		mov $0x55aa,%bx			# Magic
 		push %dx			# Save
@@ -252,6 +321,6 @@ flags:		.byte FLAGS			# Flags
 part4:		.byte 0x80, 0x00, 0x01, 0x00
 		.byte 0xa5, 0xff, 0xff, 0xff
 		.byte 0x00, 0x00, 0x00, 0x00
-		.byte 0x50, 0xc3, 0x00, 0x00
+		.byte 0x50, 0xc3, 0x00, 0x00	# 50000 sectors long, bleh
 
 		.word 0xaa55			# Magic number