More documentation cleanup

Author: josh

bootloaders/readme.MD

@@ -1,13 +1,13 @@
-This folder contains the BlinkBIOS bootloader HEX file. This file is created by the BlinkBIOS repo...
+This folder contains the BlinkBIOS bootloader HEX file. The BlinkBIOS is a hardware abstraction layer that is loaded into the bootloader area of flash.
 
-https://github.com/bigjosh/Move38-BlinkBIOS
-
-..and then copied here after each compile by an Atmel Studio post-build event. Note that the this bootloader directory is hardcoded into the text of that event. 
+The blinkBIOS is an abstraction layer that provides access to the blinks hardware and is defined by the `blinkbios_*.h` files in the `cores/blinklib/shared` directory. 
 
+Ideally we would like to program the BIOS once into each blink when it is manufactured and then only update the application section of the flash thereafter, but unfortunately on this chip the entire flash is always erased on each hardware programming cycle, so we must reprogram the bootloader each time. That is why this HEX file must be included here.
+  
 This file is used by...
 
-1. The `upload` and `program` recipes to download a new sketch to a blink. Note that we could make upload only update the actual program and not the BIOS for faster turnaround during development, but I do not want to change this behavior now. The path to the bootloader is hardcoded into the recipes but is relative to the platform folder.
-2. The `Export Binary` function which creates a single HEX file with both the current sketch and the BIOS. In this case, the folder name must be `bootloader` as this is hardcoded into the IDE. 
+1. The `program` recipe in `platform.txt` that downloads a new sketch to a blink. 
+2. The `Export Binary` function which creates a single HEX file with both the current sketch and the BIOS. Note that this folder must be named `bootloader` as this is hardcoded into the Arduino IDE. 
 
 
 

cores/blinklib/shared/BlinkBIOS.hex

@@ -2,11 +2,9 @@ Do not manually change these files!
 
 They come from the `blinkbios` and must travel as a coherent set. 
 
-`BlinkBIOS.hex` contains the compiled image of the BlinkBIOS code. It is loaded in upper flash and takes care of lots of common hardware tasks so that individual games do not need duplicated code. 
-
-We program this file every time download a sketch. We also set the `BOOTRST` fuse so that the chip will jump to the bootload section rather than address 0x000 on RESET. Both of these happen in the `AVRDUDE` the recipes in `platform.txt`. 
+`bootloader/BlinkBIOS.hex` contains the compiled image of the BlinkBIOS code. It is loaded in upper flash and takes care of lots of common hardware tasks so that individual games do not need duplicated code. 
 
 To be able to successfully talk to the BIOS code, the blink user code must be compiled against the matching header files.
 
-All communications between user code the bios happens though the shared memory blocks defined in these headers. Fields marked as bios-volatile can be updated in background b the bios. 
+All communications between user code the bios happens though the shared memory blocks defined in these headers. Fields marked as bios-volatile can be updated in background by the bios. 
 

cores/blinklib/shared/readme.MD

@@ -134,7 +134,8 @@ tools.avrdude.program.verify=
 tools.avrdude.program.params.noverify=-V
 
 # Note that becuase `protocol` is not set in boards.txt, all uploads go here - even when the upload button is pressed. 
-# Note that we must proggram both the user code and the BIOS every time becuase all of flash memory is erased anytime you program any of it. 
+# Note that we must program both the user code and the BIOS every time becuase all of flash memory is erased anytime you program any of it. 
+# Note that we do not reproggram the fuses every time becuase the fuses are not erased on each cycle. You can use the "Program bootloader" function to program the fuses if they ever get messed up.
 # The -B 5 speeds up the clock to 200KHz which is the fastest we can go with the currently programmed 1MHz MCU clock at startup
 # Note that this used to be set to 250KHz but I found two different blinks that would not program at this speed