Add Atmel Studio integration known issues.

[pub/USBasp.git] / Bootloaders / MassStorage / BootloaderMassStorage.txt

diff --git a/Bootloaders/MassStorage/BootloaderMassStorage.txt b/Bootloaders/MassStorage/BootloaderMassStorage.txt
index 7ca7c1f..0b30cbf 100644 (file)
--- a/Bootloaders/MassStorage/BootloaderMassStorage.txt
+++ b/Bootloaders/MassStorage/BootloaderMassStorage.txt
@@ -12,6 +12,8 @@
  *
  *  \li Series 7 USB AVRs (AT90USBxxx7)
  *  \li Series 6 USB AVRs (AT90USBxxx6)
  *
  *  \li Series 7 USB AVRs (AT90USBxxx7)
  *  \li Series 6 USB AVRs (AT90USBxxx6)

+ *  \li Series 4 USB AVRs (ATMEGAxxU4) - <i>See \ref SSec_Aux_Space</i>
+ *  \li ATMEGA32U2 - <i>See \ref SSec_Aux_Space</i>

  *
  *  \section Sec_Info USB Information:
  *
  *
  *  \section Sec_Info USB Information:
  *


@@ -49,7 +51,7 @@
  *  firmware image file, to load firmware onto the AVR.
  *
  *  Out of the box this bootloader builds for the AT90USB1287 with an 8KB bootloader section size, and will fit
  *  firmware image file, to load firmware onto the AVR.
  *
  *  Out of the box this bootloader builds for the AT90USB1287 with an 8KB bootloader section size, and will fit

- *  into 8KB of bootloader space. If you wish to alter this size and/or change the AVR model, you will need to
+ *  into 6KB 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.
  *
  *  When the bootloader is running, the board's LED(s) will flash at regular intervals to distinguish the
  *  edit the MCU, FLASH_SIZE_KB and BOOT_SECTION_SIZE_KB values in the accompanying makefile.
  *
  *  When the bootloader is running, the board's LED(s) will flash at regular intervals to distinguish the


@@ -69,6 +71,11 @@
  *
  *  The current device firmware can be read from the device by reading a file from the virtual FAT filesystem.
  *
  *
  *  The current device firmware can be read from the device by reading a file from the virtual FAT filesystem.
  *

+ *  \warning This bootloader is currently <b>incompatible with the Apple MacOS X OS Finder GUI</b>, due to the
+ *           large amount of meta files this OS attempts to write to the disk along with the new binaries. On
+ *           this platform, firmwares must be copied to the disk via the Terminal application only to prevent
+ *           firmware corruption.
+ *

  *  \section Sec_API User Application API
  *
  *  Several user application functions for FLASH and other special memory area manipulations are exposed by the bootloader,
  *  \section Sec_API User Application API
  *
  *  Several user application functions for FLASH and other special memory area manipulations are exposed by the bootloader,


@@ -100,6 +107,22 @@
  *  #define BOOTLOADER_ADDRESS_LENGTH          4
  *  \endcode
  *
  *  #define BOOTLOADER_ADDRESS_LENGTH          4
  *  \endcode
  *

+ *  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_MASS_STORAGE_SIGNATURE. The start address of the bootloader can be retrieved by reading the bytes
+ *  of FLASH memory starting from address \c BOOTLOADER_ADDRESS_START.
+ *
+ *  \subsection SSec_Aux_Space Auxiliary Bootloader Section
+ *  To make the bootloader function on smaller devices (those with a physical bootloader section of smaller than 6KB) a second
+ *  section of memory (called the <i>Auxiliary Bootloader Section</i>) is added before the start of the real bootloader section,
+ *  and is filled with a portion of the bootloader code. This allows smaller devices to run the bootloader, at the cost of an
+ *  additional portion of the device's FLASH (the bootloader section size in KB subtracted from the 6KB total size). A small
+ *  trampoline is inserted at the start of the auxiliary section so that the bootloader will run normally in the case of a blank
+ *  application section.
+ *
+ *  On devices supporting a 8KB bootloader section size, the AUX section is not created in the final binary.
+ *

  *  \subsection SSec_API_MemLayout Device Memory Map
  *  The following illustration indicates the final memory map of the device when loaded with the bootloader.
  *
  *  \subsection SSec_API_MemLayout Device Memory Map
  *  The following illustration indicates the final memory map of the device when loaded with the bootloader.
  *


@@ -121,6 +144,16 @@
  *  |                            |
  *  |                            |
  *  |                            |
  *  |                            |
  *  |                            |
  *  |                            |

+ *  |                            |
+ *  +----------------------------+ FLASHEND - BOOT_SECTION_SIZE - BOOT_AUX_SECTION_SIZE
+ *  | Booloader Start Trampoline |
+ *  | (Not User App. Accessible) |
+ *  +----------------------------+ FLASHEND - BOOT_SECTION_SIZE - BOOT_AUX_SECTION_SIZE + 4
+ *  |                            |
+ *  |     Auxiliary Bootloader   |
+ *  |  Space for Smaller Devices |
+ *  | (Not User App. Accessible) |
+ *  |                            |

  *  +----------------------------+ FLASHEND - BOOT_SECTION_SIZE
  *  |                            |
  *  |   Bootloader Application   |
  *  +----------------------------+ FLASHEND - BOOT_SECTION_SIZE
  *  |                            |
  *  |   Bootloader Application   |


@@ -138,11 +171,19 @@
  *  +----------------------------+ FLASHEND
  *  \endverbatim
  *
  *  +----------------------------+ FLASHEND
  *  \endverbatim
  *

- *  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_MASS_STORAGE_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_KnownIssues Known Issues:
+ *
+ *  \par In some cases, the application is not fully loaded into the device.
+ *  Write-caching on some operating systems may interfere with the normal
+ *  operation of the bootloader. Write caching should be disabled when using the
+ *  Mass Storage bootloader, or the file system synced via an appropriate command
+ *  (such as the OS's normal disk ejection command) before disconnecting the device.
+ *
+ *  \par After loading an application, it is not run automatically on startup.
+ *  Some USB AVR boards ship with the BOOTRST fuse set, causing the bootloader
+ *  to run automatically when the device is reset. In most cases, the BOOTRST
+ *  fuse should be disabled and the HWBE fuse used instead to run the bootloader
+ *  when needed.

  *
  *  \section Sec_Options Project Options
  *
  *
  *  \section Sec_Options Project Options
  *


@@ -150,9 +191,15 @@
  *
  *  <table>
  *   <tr>
  *
  *  <table>
  *   <tr>

- *    <td>
- *     None
- *    </td>
+ *    <th><b>Define Name:</b></th>
+ *    <th><b>Location:</b></th>
+ *    <th><b>Description:</b></th>
+ *   </tr>
+ *   <tr>
+ *    <td>NO_APP_START_ON_EJECT</td>
+ *    <td>AppConfig.h</td>
+ *    <td>Define to disable automatic start of the loaded application when the virtual
+ *        Mass Storage disk is ejected on the host.</td>

  *   </tr>
  *  </table>
  */
  *   </tr>
  *  </table>
  */