From 141f24b4a13144a49fe21f7352b0e9d34962e2dd Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Fri, 22 Mar 2013 23:24:02 +0000 Subject: [PATCH] Add known-issues documentation section to the various LUFA bootloaders. --- Bootloaders/CDC/BootloaderCDC.txt | 20 ++++++++++++++++++ Bootloaders/DFU/BootloaderDFU.txt | 14 +++++++++++++ Bootloaders/HID/BootloaderHID.txt | 16 ++++++++++---- .../MassStorage/BootloaderMassStorage.txt | 21 +++++++++++++++++++ Bootloaders/Printer/BootloaderPrinter.txt | 15 +++++++++++++ 5 files changed, 82 insertions(+), 4 deletions(-) diff --git a/Bootloaders/CDC/BootloaderCDC.txt b/Bootloaders/CDC/BootloaderCDC.txt index b087bd5756..379988f9e9 100644 --- a/Bootloaders/CDC/BootloaderCDC.txt +++ b/Bootloaders/CDC/BootloaderCDC.txt @@ -161,6 +161,26 @@ * +----------------------------+ FLASHEND * \endverbatim * + * \section Sec_KnownIssues Known Issues: + * + * \par On Linux machines, the CDC bootloader is unstable or inaccessible. + * A change to the \c ModemManager module in many Linux distributions causes + * this module to try to take control over inserted CDC devices, corrupting the + * datastream. A UDEV rule is required to prevent this. + * See here for resolution steps. + * + * \par On Linux machines, the CDC bootloader is inaccessible. + * On many Linux systems, non-root users do not have automatic access to newly + * inserted CDC devices. Root privileges or a UDEV rule is required to gain + * access. + * See here for resolution steps. + * + * \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 * * The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value. diff --git a/Bootloaders/DFU/BootloaderDFU.txt b/Bootloaders/DFU/BootloaderDFU.txt index a8c4f0f515..8cba21a911 100644 --- a/Bootloaders/DFU/BootloaderDFU.txt +++ b/Bootloaders/DFU/BootloaderDFU.txt @@ -181,6 +181,20 @@ * To make the bootloader function on smaller devices (those with a physical * bootloader section of smaller than 6KB) * + * \section Sec_KnownIssues Known Issues: + * + * \par On Linux machines, the DFU bootloader is inaccessible. + * On many Linux systems, non-root users do not have automatic access to newly + * inserted DFU devices. Root privileges or a UDEV rule is required to gain + * access. + * See here for resolution steps. + * + * \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 * * The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value. diff --git a/Bootloaders/HID/BootloaderHID.txt b/Bootloaders/HID/BootloaderHID.txt index 72583fd960..dba2b6502f 100644 --- a/Bootloaders/HID/BootloaderHID.txt +++ b/Bootloaders/HID/BootloaderHID.txt @@ -3,7 +3,7 @@ * This file contains special DoxyGen information for the generation of the main page and other special * documentation pages. It is not a project source file. */ - + /** \mainpage HID Class USB AVR Bootloader * * \section SSec_Compat Demo Compatibility: @@ -28,7 +28,7 @@ * USB Class: * Human Interface Device Class (HID) * - * + * * USB Subclass: * N/A * @@ -44,13 +44,13 @@ * * * - * \section SSec_Description Project Description: + * \section SSec_Description Project Description: * * This bootloader enumerates to the host as a HID Class device, allowing for device FLASH programming through * the supplied command line software, which is a modified version of Paul's TeensyHID Command Line loader code * from PJRC (used with permission). This bootloader is deliberatley non-compatible with the properietary PJRC * HalfKay bootloader GUI; only the command line interface software accompanying this bootloader will work with it. - * + * * Out of the box this bootloader builds for the AT90USB1287 with an 8KB bootloader section size, and will fit * into 2KB of bootloader space for the Series 2 USB AVRs (ATMEGAxxU2, AT90USBxx2) or 4KB of bootloader space for * all other models. If you wish to alter this size and/or change the AVR model, you will need to edit the MCU, @@ -74,6 +74,14 @@ * hid_bootloader_cli -mmcu=at90usb1287 Mouse.hex * \endcode * + * \section Sec_KnownIssues Known Issues: + * + * \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 SSec_Options Project Options * * The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value. diff --git a/Bootloaders/MassStorage/BootloaderMassStorage.txt b/Bootloaders/MassStorage/BootloaderMassStorage.txt index 19751d3be6..e072d2d248 100644 --- a/Bootloaders/MassStorage/BootloaderMassStorage.txt +++ b/Bootloaders/MassStorage/BootloaderMassStorage.txt @@ -166,6 +166,27 @@ * +----------------------------+ FLASHEND * \endverbatim * + * \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 filesystem synced via an appropriate command + * (such as the OS's normal disk ejection command) before disconnecting the device. + * + * \par On Linux machines, written data may be corrupted. + * Linux systems appear to attempt a full filesystem re-write when the virtual + * firmware file of the bootloader is written to normally, causing corrupt + * device programming. On Linux systems, new firmware should be copied over + * in-place via the \c dd command on the virtual file to ensure the filesystem + * is left intact. + * + * \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 * * The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value. diff --git a/Bootloaders/Printer/BootloaderPrinter.txt b/Bootloaders/Printer/BootloaderPrinter.txt index 01237fd59e..71e9b2871a 100644 --- a/Bootloaders/Printer/BootloaderPrinter.txt +++ b/Bootloaders/Printer/BootloaderPrinter.txt @@ -154,6 +154,21 @@ * +----------------------------+ FLASHEND * \endverbatim * + * + * \section Sec_KnownIssues Known Issues: + * + * \par On Linux machines, new firmware fails to be sent to the device via CUPS. + * Only a limited subset of normal printer functionality is exposed via the + * bootloader, causing CUPS to reject print requests from applications that + * are unable to handle true plain-text printing. For best results, the low + * level \c lpr command should be used to print new firmware to the bootloader. + * + * \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 * * The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value.