Document the kernel startup code

kernel/start.68k

@@ -2,68 +2,61 @@
 .global _start
 | Receives pointer to program headers in a0 and number of program headers in d0
 _start:
-move.l d0, d2
-move.l a0, a1
-move.b #0x5, d0
+move.l d0, d2 | Move the number of program headers to d2
+move.l a0, a1 | Move the program headaer pointer to a1
+move.b #0x5, d0 | Get the pointer to the MMU card
 bsr.w find_first_card_early
-cmpa.l #0, a0
+cmpa.l #0, a0 | Abort if there is no MMU card
 beq.w no_mmu
-subq.w #0x1, d2
+subq.w #0x1, d2 | Adjust the number of program headers for dbra
 phead_loop:
 move.l (a1), d1 | If the type of the program header isn't 1 (LOAD), skip the header
 cmpi.l #0x1, d1
 bne.b next_phead
-| move.b (9, a1), d1 | If the program header is not in the upper quarter, skip it
-| cmpi.b #0xc0, d1
-| bgt.b next_phead
 move.l (20, a1), d4 | Put the memory size in d4
-move.l d4, d3
-lsr #8, d3
+move.l d4, d3 | Copy the size to d3
+lsr #8, d3 | Shift d3 right 12 bits to get the number of full pages the segment takes up
 lsr #4, d3
-andi.l #0xFFF, d4
+andi.l #0xFFF, d4 | If the segment takes up a partial page, add 1 to the number of required pages in d3
 cmp.l #0x0, d4
 beq.b even_page
 addq.l #1, d3
 even_page:
-subq.b #1, d3
-move.l (12, a1), d1
-ori.l #3, d1
-move.l (8, a1), d0
+subq.b #1, d3 | | Adjust the number of pages to map for dbra
+move.l (12, a1), d2 | Get the starting physical page in d3
+ori.l #3, d1 | Set the present and writable falgs on the entry
+move.l (8, a1), d0 | Get the starting virtual page number in the quarter in d0
 lsr.l #8, d0
 lsr.l #4, d0
 andi.l #0x3ff, d0
-lsl #2, d0
+lsl #2, d0 | Get the pointer to the entry for the page in a2
 move.l #kernel_map, a2
 adda d0, a2
-| d3 contains number of pages - 1
-| d1 initial map entry
-| a2 pointer to initial map entry location
 map_loop:
-move.l d1, (a2)+
-addi.l #0x1000, d1
-dbra d3, map_loop
+move.l d1, (a2)+ | Write the entry to the mapping page and advance the entry pointer
+addi.l #0x1000, d1 | Advance the entry to the next physical page
+dbra d3, map_loop | Loop back if there are more pages to map
 next_phead:
 lea (0x20, a1), a1 | Advance a1 to point to the next program header
 dbra d2, phead_loop | If there are more program headers, loop back
 io_map:
-move.l #15, d0
-move.l #(kernel_map + 0x3f0 * 4), a1
-move.l #0xffff0003, d1
+move.l #15, d0 | Put the number of IO pages in d0, minus one to adjust for dbra
+move.l #(kernel_map + 0x3f0 * 4), a1 | Put the poiner to the mapping for virtual page 0xFF0000 in a1
+move.l #0xffff0003, d1 | Put the inital map entry in d1
 io_map_loop:
-move.l d1, (a1)+
-addi.l #0x1000, d1
-dbra d0, io_map_loop
-map_done:
-move.l #kernel_map, d0
-ori.l #0x1, d0
-move.l d0, (0x0, a0)
+move.l d1, (a1)+ | Write the entry to the mapping page and advance the entry pointer
+addi.l #0x1000, d1 | Advance the entry to the next physical page
+dbra d0, io_map_loop | Loop back if there are more pages to map
+move.l #kernel_map, d0 | Load the pointer to the mapping page into d0
+ori.l #0x1, d0 | Set the map page present flag
+move.l d0, (0x0, a0) | Write the mapping page to both the lower and upper quarter map registers
 move.l d0, (0xC, a0)
-move.w #1, (0x14, a0)
-move.w #0, 0xff0000
-move.l #bootstrap_stack, a7
-jmp main
+move.w #1, (0x14, a0) | Enable the MMU
+move.w #0, 0xff0000 | Disable the IO space at the top of the lower 16MB of memory
+move.l #bootstrap_stack, a7 | Load the initial stack pointer
+jmp main | Jump to the kernel's main function
 no_mmu:
-stop #2700
+stop #2700 | If there was no MMU card, halt the CPU
 
 | Finds the first card with the type in d0.b, and returns it's IO base address in a0, or 0 if not found
 | Clobbers d1