* This bootloader enumerates to the host as a CDC Class device (virtual serial port), allowing for AVR109
* protocol compatible programming software to load firmware onto the AVR.
*
- * Out of the box this bootloader builds for the USB1287, and will fit into 4KB of bootloader space. If
- * you wish to enlarge this space and/or change the AVR model, you will need to edit the BOOT_START and MCU
- * values in the accompanying makefile.
+ * Out of the box this bootloader builds for the AT90USB1287 with an 8KB bootloader section size, and will fit
+ * into 4KB of bootloader space. If you wish to alter this size and/or change the AVR model, you will need to
+ * edit the MCU, FLASH_SIZE_KB and BOOT_SECTION_SIZE_KB values in the accompanying makefile.
*
- * This bootloader is compatible with the open source application AVRDUDE, or Atmel's AVRPROG.
+ * When the bootloader is running, the board's LED(s) will flash at regular intervals to distinguish the
+ * bootloader from the normal user application.
+ *
+ * \section Sec_Installation Driver Installation
*
* After running this bootloader for the first time on a new computer, you will need to supply the .INF
* file located in this bootloader project's directory as the device's driver when running under Windows.
* This will enable Windows to use its inbuilt CDC drivers, negating the need for custom drivers for the
* device. Other Operating Systems should automatically use their own inbuilt CDC-ACM drivers.
*
+ * \section Sec_HostApp Host Controller Application
+ *
+ * This bootloader is compatible with the open source application AVRDUDE, Atmel's AVRPROG, or other
+ * applications implementing the AVR109 protocol, which is documented on the Atmel website as an application
+ * note.
+ *
+ * \subsection SSec_AVRDude AVRDUDE (Windows, Mac, Linux)
+ *
+ * AVRDude is a free, cross-platform and open source command line programmer for Atmel and third party AVR
+ * programmers. It is available on the the Windows platform as part of the "WinAVR" package, or on other systems
+ * either from a build from the official source code, or in many distributions as a precompiled binary package.
+ *
+ * To load a new HEX file with AVRDude, specify "AVR109" as the programmer, with the allocated COM port. On Windows
+ * platforms this will be a COMx port name:
+ * \code
+ * avrdude -c AVR109 -p at90usb1287 -P COM0 -U flash:w:Mouse.hex
+ * \endcode
+ *
+ * On Linux systems, this will typically be a /dev/ttyACMx port name:
+ * \code
+ * avrdude -c AVR109 -p at90usb1287 -P /dev/ttyACM0 -U flash:w:Mouse.hex
+ * \endcode
+ *
+ * Refer to the AVRDude project documentation for additional usage instructions.
+ *
+ * \section Sec_API User Application API
+ *
+ * Several user application functions for FLASH and other special memory area manipulations are exposed by the bootloader,
+ * allowing the user application to call into the bootloader at runtime to read and write FLASH data.
+ *
+ * By default, the bootloader API jump table is located 32 bytes from the end of the device's FLASH memory, and follows the
+ * following layout:
+ *
+ * \code
+ * #define BOOTLOADER_API_CALL(Index) (void*)(((FLASHEND - 32) + (2 * Index)) / 2)
+ *
+ * void (*BootloaderAPI_ErasePage)(uint32_t Address) = BOOTLOADER_API_CALL(0);
+ * void (*BootloaderAPI_WritePage)(uint32_t Address) = BOOTLOADER_API_CALL(1);
+ * void (*BootloaderAPI_FillWord)(uint32_t Address, uint16_t Word) = BOOTLOADER_API_CALL(2);
+ * uint8_t (*BootloaderAPI_ReadSignature)(uint16_t Address) = BOOTLOADER_API_CALL(3);
+ * uint8_t (*BootloaderAPI_ReadFuse)(uint16_t Address) = BOOTLOADER_API_CALL(4);
+ * uint8_t (*BootloaderAPI_ReadLock)(void) = BOOTLOADER_API_CALL(5);
+ * void (*BootloaderAPI_WriteLock)(uint8_t LockBits) = BOOTLOADER_API_CALL(6);
+ *
+ * #define BOOTLOADER_MAGIC_SIGNATURE_START (FLASHEND - 2)
+ * #define BOOTLOADER_MAGIC_SIGNATURE 0xDCFB
+ *
+ * #define BOOTLOADER_CLASS_SIGNATURE_START (FLASHEND - 4)
+ * #define BOOTLOADER_CDC_SIGNATURE 0xCDC1
+ *
+ * #define BOOTLOADER_ADDRESS_START (FLASHEND - 8)
+ * #define BOOTLOADER_ADDRESS_LENGTH 4
+ * \endcode
+ *
+ * Bootloaders reporting a device release revision number of 1.00 or greater are bootloader API enabled. From the application
+ * the API support of the bootloader can be detected by reading the FLASH memory bytes located at address \c BOOTLOADER_MAGIC_SIGNATURE_START
+ * and comparing them to the value \c BOOTLOADER_MAGIC_SIGNATURE. The class of bootloader can be determined by reading the
+ * FLASH memory bytes located at address \c BOOTLOADER_CLASS_SIGNATURE_START and comparing them to the value \c BOOTLOADER_CDC_SIGNATURE.
+ * The start address of the bootloader can be retrieved by reading the bytes of FLASH memory starting from address \c BOOTLOADER_ADDRESS_START.
+ *
* \section Sec_Options Project Options
*
* The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value.
*
* <table>
* <tr>
+ * <td><b>Define Name:</b></td>
+ * <td><b>Location:</b></td>
+ * <td><b>Description:</b></td>
+ * </tr>
+ * <tr>
* <td>NO_BLOCK_SUPPORT</td>
* <td>Makefile LUFA_OPTS</td>
* <td>Define to disable memory block read/write support in the bootloader, requiring all reads and writes to be made
- * using the byte-level commands.
+ * using the byte-level commands.</td>
* </tr>
* <tr>
* <td>NO_EEPROM_BYTE_SUPPORT</td>
* <td>Makefile LUFA_OPTS</td>
* <td>Define to disable EEPROM memory byte read/write support in the bootloader, requiring all EEPROM reads and writes
- * to be made using the block-level commands.
+ * to be made using the block-level commands.</td>
* </tr>
* <tr>
* <td>NO_FLASH_BYTE_SUPPORT</td>
* <td>Makefile LUFA_OPTS</td>
* <td>Define to disable FLASH memory byte read/write support in the bootloader, requiring all FLASH reads and writes
- * to be made using the block-level commands.
+ * to be made using the block-level commands.</td>
* </tr>
* <tr>
* <td>NO_LOCK_BYTE_WRITE_SUPPORT</td>
* <td>Makefile LUFA_OPTS</td>
- * <td>Define to disable lock byte write support in the bootloader, preventing the lock bits from being set progmatically.
+ * <td>Define to disable lock byte write support in the bootloader, preventing the lock bits from being set programmatically.</td>
* </tr>
* </table>
*/
projects / pub / USBasp.git / blobdiff