Added User Application APIs to the CDC and DFU class bootloaders.

Bootloaders/CDC/BootloaderAPI.c

+/*
+             LUFA Library
+     Copyright (C) Dean Camera, 2011.
+
+  dean [at] fourwalledcubicle [dot] com
+           www.lufa-lib.org
+*/
+
+/*
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+
+  Permission to use, copy, modify, distribute, and sell this
+  software and its documentation for any purpose is hereby granted
+  without fee, provided that the above copyright notice appear in
+  all copies and that both that the copyright notice and this
+  permission notice and warranty disclaimer appear in supporting
+  documentation, and that the name of the author not be used in
+  advertising or publicity pertaining to distribution of the
+  software without specific, written prior permission.
+
+  The author disclaim all warranties with regard to this
+  software, including all implied warranties of merchantability
+  and fitness.  In no event shall the author be liable for any
+  special, indirect or consequential damages or any damages
+  whatsoever resulting from loss of use, data or profits, whether
+  in an action of contract, negligence or other tortious action,
+  arising out of or in connection with the use or performance of
+  this software.
+*/
+
+/** \file
+ *
+ *  Bootloader user application API functions.
+ */
+
+#include "BootloaderAPI.h"
+
+void BootloaderAPI_ErasePage(uint32_t Address)
+{
+	boot_page_erase_safe(Address);
+	boot_rww_enable();
+}
+
+void BootloaderAPI_WritePage(uint32_t Address)
+{
+	boot_page_write_safe(Address);
+	boot_rww_enable();
+}
+
+void BootloaderAPI_FillWord(uint32_t Address, uint16_t Word)
+{
+	boot_page_fill_safe(Address, Word);
+}
+
+uint8_t BootloaderAPI_ReadSignature(uint16_t Address)
+{
+	return boot_signature_byte_get(Address);
+}
+
+uint8_t BootloaderAPI_ReadFuse(uint16_t Address)
+{
+	return boot_lock_fuse_bits_get(Address);
+}
+
+uint8_t BootloaderAPI_ReadLock(void)
+{
+	return boot_lock_fuse_bits_get(GET_LOCK_BITS);
+}
+
+void BootloaderAPI_WriteLock(uint8_t LockBits)
+{
+	boot_lock_bits_set_safe(LockBits);
+}
+

Bootloaders/CDC/BootloaderAPI.h

+/*
+             LUFA Library
+     Copyright (C) Dean Camera, 2011.
+
+  dean [at] fourwalledcubicle [dot] com
+           www.lufa-lib.org
+*/
+
+/*
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+
+  Permission to use, copy, modify, distribute, and sell this
+  software and its documentation for any purpose is hereby granted
+  without fee, provided that the above copyright notice appear in
+  all copies and that both that the copyright notice and this
+  permission notice and warranty disclaimer appear in supporting
+  documentation, and that the name of the author not be used in
+  advertising or publicity pertaining to distribution of the
+  software without specific, written prior permission.
+
+  The author disclaim all warranties with regard to this
+  software, including all implied warranties of merchantability
+  and fitness.  In no event shall the author be liable for any
+  special, indirect or consequential damages or any damages
+  whatsoever resulting from loss of use, data or profits, whether
+  in an action of contract, negligence or other tortious action,
+  arising out of or in connection with the use or performance of
+  this software.
+*/
+
+/** \file
+ *
+ *  Header file for BootloaderAPI.c.
+ */
+
+#ifndef _BOOTLOADER_API_H_
+#define _BOOTLOADER_API_H_
+
+	/* Includes: */
+		#include <avr/io.h>
+		#include <avr/boot.h>
+		#include <stdbool.h>
+		
+		#include <LUFA/Common/Common.h>
+	
+	/* External Variables: */
+		extern uint8_t* BootloaderAPI_JumpTable;
+	
+	/* Function Prototypes: */
+		void    BootloaderAPI_ErasePage(uint32_t Address);
+		void    BootloaderAPI_WritePage(uint32_t Address);
+		void    BootloaderAPI_FillWord(uint32_t Address, uint16_t Word);
+		uint8_t BootloaderAPI_ReadSignature(uint16_t Address);
+		uint8_t BootloaderAPI_ReadFuse(uint16_t Address);
+		uint8_t BootloaderAPI_ReadLock(void);
+		void    BootloaderAPI_WriteLock(uint8_t LockBits);
+
+#endif
+

Bootloaders/CDC/BootloaderAPITable.S

+/*
+             LUFA Library
+     Copyright (C) Dean Camera, 2011.
+
+  dean [at] fourwalledcubicle [dot] com
+           www.lufa-lib.org
+*/
+
+/*
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+
+  Permission to use, copy, modify, distribute, and sell this
+  software and its documentation for any purpose is hereby granted
+  without fee, provided that the above copyright notice appear in
+  all copies and that both that the copyright notice and this
+  permission notice and warranty disclaimer appear in supporting
+  documentation, and that the name of the author not be used in
+  advertising or publicity pertaining to distribution of the
+  software without specific, written prior permission.
+
+  The author disclaim all warranties with regard to this
+  software, including all implied warranties of merchantability
+  and fitness.  In no event shall the author be liable for any
+  special, indirect or consequential damages or any damages
+  whatsoever resulting from loss of use, data or profits, whether
+  in an action of contract, negligence or other tortious action,
+  arising out of or in connection with the use or performance of
+  this software.
+*/
+
+; Bootloader API Jump Table
+.section .apitable, "ax"
+.org 0
+
+.global BootloaderAPI_JumpTable
+BootloaderAPI_JumpTable:
+	jmp BootloaderAPI_ErasePage
+	jmp BootloaderAPI_WritePage
+	jmp BootloaderAPI_FillWord
+	jmp BootloaderAPI_ReadSignature
+	jmp BootloaderAPI_ReadFuse
+	jmp BootloaderAPI_ReadLock
+	jmp BootloaderAPI_WriteLock

Bootloaders/CDC/BootloaderCDC.c

@@ -63,6 +63,10 @@ static bool RunBootloader = true;
  */
 int main(void)
 {
+	/* Force a reference to the API jump table to prevent the linker from discarding it */
+	uint8_t* volatile Dummy = BootloaderAPI_JumpTable;
+	(void)Dummy;
+
 	/* Setup hardware required for the bootloader */
 	SetupHardware();
 

Bootloaders/CDC/BootloaderCDC.h

@@ -46,6 +46,7 @@
 		#include <stdbool.h>
 
 		#include "Descriptors.h"
+		#include "BootloaderAPI.h"		
 
 		#include <LUFA/Drivers/USB/USB.h>
 		#include <LUFA/Drivers/Board/LEDs.h>

Bootloaders/CDC/BootloaderCDC.txt

@@ -86,6 +86,25 @@
  *
  *  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_START(Index)        (void*)(((FLASHEND - 32) + (2 * Index)) / 2)
+ *  void    (*BootloaderAPI_ErasePage)(uint32_t Address)               = BOOTLOADER_API_START(0);
+ *  void    (*BootloaderAPI_WritePage)(uint32_t Address)               = BOOTLOADER_API_START(1);
+ *  void    (*BootloaderAPI_FillWord)(uint32_t Address, uint16_t Word) = BOOTLOADER_API_START(2);
+ *  uint8_t (*BootloaderAPI_ReadSignature)(uint16_t Address)           = BOOTLOADER_API_START(3);
+ *  uint8_t (*BootloaderAPI_ReadFuse)(uint16_t Address)                = BOOTLOADER_API_START(4);
+ *  uint8_t (*BootloaderAPI_ReadLock)(void)                            = BOOTLOADER_API_START(5);
+ *  void    (*BootloaderAPI_WriteLock)(uint8_t LockBits)               = BOOTLOADER_API_START(6);
+ *  \endcode
+ *
  *  \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.

Bootloaders/CDC/makefile

@@ -97,6 +97,7 @@ F_USB = $(F_CPU)
 FLASH_SIZE_KB        = 128
 BOOT_SECTION_SIZE_KB = 4
 BOOT_START           = 0x$(shell echo "obase=16; ($(FLASH_SIZE_KB) - $(BOOT_SECTION_SIZE_KB)) * 1024" | bc)
+BOOT_API_TABLESTART  = 0x$(shell echo "obase=16; (($(FLASH_SIZE_KB) * 1024) - 32)" | bc)
 
 
 # Output format. (can be srec, ihex, binary)
@@ -142,6 +143,7 @@ include $(LUFA_PATH)/LUFA/makefile
 
 # List C source files here. (C dependencies are automatically generated.)
 SRC = $(TARGET).c                                                 \
+	  BootloaderAPI.c                                             \
 	  Descriptors.c                                               \
 	  $(LUFA_SRC_USB)                                             \
 
@@ -157,7 +159,7 @@ CPPSRC =
 #     Even though the DOS/Win* filesystem matches both .s and .S the same,
 #     it will preserve the spelling of the filenames, and gcc itself does
 #     care about how the name is spelled on its command-line.
-ASRC =
+ASRC = BootloaderAPITable.S
 
 
 # Optimization level, can be [0, 1, 2, 3, s].
@@ -338,7 +340,7 @@ EXTMEMOPTS =
 #    -Map:      create map file
 #    --cref:    add cross reference to  map file
 LDFLAGS  = -Wl,-Map=$(TARGET).map,--cref
-LDFLAGS += -Wl,--section-start=.text=$(BOOT_START)
+LDFLAGS += -Wl,--section-start=.text=$(BOOT_START) -Wl,--section-start=.apitable=$(BOOT_API_TABLESTART)
 LDFLAGS += -Wl,--relax
 LDFLAGS += -Wl,--gc-sections
 LDFLAGS += $(EXTMEMOPTS)

Bootloaders/DFU/BootloaderAPI.c

+/*
+             LUFA Library
+     Copyright (C) Dean Camera, 2011.
+
+  dean [at] fourwalledcubicle [dot] com
+           www.lufa-lib.org
+*/
+
+/*
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+
+  Permission to use, copy, modify, distribute, and sell this
+  software and its documentation for any purpose is hereby granted
+  without fee, provided that the above copyright notice appear in
+  all copies and that both that the copyright notice and this
+  permission notice and warranty disclaimer appear in supporting
+  documentation, and that the name of the author not be used in
+  advertising or publicity pertaining to distribution of the
+  software without specific, written prior permission.
+
+  The author disclaim all warranties with regard to this
+  software, including all implied warranties of merchantability
+  and fitness.  In no event shall the author be liable for any
+  special, indirect or consequential damages or any damages
+  whatsoever resulting from loss of use, data or profits, whether
+  in an action of contract, negligence or other tortious action,
+  arising out of or in connection with the use or performance of
+  this software.
+*/
+
+/** \file
+ *
+ *  Bootloader user application API functions.
+ */
+
+#include "BootloaderAPI.h"
+
+void BootloaderAPI_ErasePage(uint32_t Address)
+{
+	boot_page_erase_safe(Address);
+	boot_rww_enable();
+}
+
+void BootloaderAPI_WritePage(uint32_t Address)
+{
+	boot_page_write_safe(Address);
+	boot_rww_enable();
+}
+
+void BootloaderAPI_FillWord(uint32_t Address, uint16_t Word)
+{
+	boot_page_fill_safe(Address, Word);
+}
+
+uint8_t BootloaderAPI_ReadSignature(uint16_t Address)
+{
+	return boot_signature_byte_get(Address);
+}
+
+uint8_t BootloaderAPI_ReadFuse(uint16_t Address)
+{
+	return boot_lock_fuse_bits_get(Address);
+}
+
+uint8_t BootloaderAPI_ReadLock(void)
+{
+	return boot_lock_fuse_bits_get(GET_LOCK_BITS);
+}
+
+void BootloaderAPI_WriteLock(uint8_t LockBits)
+{
+	boot_lock_bits_set_safe(LockBits);
+}
+

Bootloaders/DFU/BootloaderAPI.h

+/*
+             LUFA Library
+     Copyright (C) Dean Camera, 2011.
+
+  dean [at] fourwalledcubicle [dot] com
+           www.lufa-lib.org
+*/
+
+/*
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+
+  Permission to use, copy, modify, distribute, and sell this
+  software and its documentation for any purpose is hereby granted
+  without fee, provided that the above copyright notice appear in
+  all copies and that both that the copyright notice and this
+  permission notice and warranty disclaimer appear in supporting
+  documentation, and that the name of the author not be used in
+  advertising or publicity pertaining to distribution of the
+  software without specific, written prior permission.
+
+  The author disclaim all warranties with regard to this
+  software, including all implied warranties of merchantability
+  and fitness.  In no event shall the author be liable for any
+  special, indirect or consequential damages or any damages
+  whatsoever resulting from loss of use, data or profits, whether
+  in an action of contract, negligence or other tortious action,
+  arising out of or in connection with the use or performance of
+  this software.
+*/
+
+/** \file
+ *
+ *  Header file for BootloaderAPI.c.
+ */
+
+#ifndef _BOOTLOADER_API_H_
+#define _BOOTLOADER_API_H_
+
+	/* Includes: */
+		#include <avr/io.h>
+		#include <avr/boot.h>
+		#include <stdbool.h>
+		
+		#include <LUFA/Common/Common.h>
+	
+	/* External Variables: */
+		extern uint8_t* BootloaderAPI_JumpTable;
+	
+	/* Function Prototypes: */
+		void    BootloaderAPI_ErasePage(uint32_t Address);
+		void    BootloaderAPI_WritePage(uint32_t Address);
+		void    BootloaderAPI_FillWord(uint32_t Address, uint16_t Word);
+		uint8_t BootloaderAPI_ReadSignature(uint16_t Address);
+		uint8_t BootloaderAPI_ReadFuse(uint16_t Address);
+		uint8_t BootloaderAPI_ReadLock(void);
+		void    BootloaderAPI_WriteLock(uint8_t LockBits);
+
+#endif
+

Bootloaders/DFU/BootloaderAPITable.S

+/*
+             LUFA Library
+     Copyright (C) Dean Camera, 2011.
+
+  dean [at] fourwalledcubicle [dot] com
+           www.lufa-lib.org
+*/
+
+/*
+  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+
+  Permission to use, copy, modify, distribute, and sell this
+  software and its documentation for any purpose is hereby granted
+  without fee, provided that the above copyright notice appear in
+  all copies and that both that the copyright notice and this
+  permission notice and warranty disclaimer appear in supporting
+  documentation, and that the name of the author not be used in
+  advertising or publicity pertaining to distribution of the
+  software without specific, written prior permission.
+
+  The author disclaim all warranties with regard to this
+  software, including all implied warranties of merchantability
+  and fitness.  In no event shall the author be liable for any
+  special, indirect or consequential damages or any damages
+  whatsoever resulting from loss of use, data or profits, whether
+  in an action of contract, negligence or other tortious action,
+  arising out of or in connection with the use or performance of
+  this software.
+*/
+
+; Bootloader API Jump Table
+.section .apitable, "ax"
+.org 0
+
+.global BootloaderAPI_JumpTable
+BootloaderAPI_JumpTable:
+	jmp BootloaderAPI_ErasePage
+	jmp BootloaderAPI_WritePage
+	jmp BootloaderAPI_FillWord
+	jmp BootloaderAPI_ReadSignature
+	jmp BootloaderAPI_ReadFuse
+	jmp BootloaderAPI_ReadLock
+	jmp BootloaderAPI_WriteLock

Bootloaders/DFU/BootloaderDFU.c

@@ -99,6 +99,10 @@ static uint16_t EndAddr = 0x0000;
  */
 int main(void)
 {
+	/* Force a reference to the API jump table to prevent the linker from discarding it */
+	uint8_t* volatile Dummy = BootloaderAPI_JumpTable;
+	(void)Dummy;
+
 	/* Configure hardware required by the bootloader */
 	SetupHardware();
 
@@ -742,4 +746,3 @@ static void ProcessReadCommand(void)
 	else if (IS_ONEBYTE_COMMAND(SentCommand.Data, 0x01))                    // Read signature byte
 	  ResponseByte = SignatureInfo[DataIndexToRead - 0x30];
 }
-

Bootloaders/DFU/BootloaderDFU.h

@@ -48,6 +48,7 @@
 		#include <stdbool.h>
 
 		#include "Descriptors.h"
+		#include "BootloaderAPI.h"
 
 		#include <LUFA/Drivers/USB/USB.h>
 		#include <LUFA/Drivers/Board/LEDs.h>

Bootloaders/DFU/BootloaderDFU.txt

@@ -89,6 +89,27 @@
  *  dfu-programmer at90usb1287 erase flash Mouse.hex
  *  \endcode
  *
+ *  \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.
+ *
+ *  \note The APIs exposed by the DFU class bootloader are \b NOT compatible with the API exposed by the official Atmel DFU bootloader.
+ *
+ *  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_START(Index)        (void*)(((FLASHEND - 32) + (2 * Index)) / 2)
+ *  void    (*BootloaderAPI_ErasePage)(uint32_t Address)               = BOOTLOADER_API_START(0);
+ *  void    (*BootloaderAPI_WritePage)(uint32_t Address)               = BOOTLOADER_API_START(1);
+ *  void    (*BootloaderAPI_FillWord)(uint32_t Address, uint16_t Word) = BOOTLOADER_API_START(2);
+ *  uint8_t (*BootloaderAPI_ReadSignature)(uint16_t Address)           = BOOTLOADER_API_START(3);
+ *  uint8_t (*BootloaderAPI_ReadFuse)(uint16_t Address)                = BOOTLOADER_API_START(4);
+ *  uint8_t (*BootloaderAPI_ReadLock)(void)                            = BOOTLOADER_API_START(5);
+ *  void    (*BootloaderAPI_WriteLock)(uint8_t LockBits)               = BOOTLOADER_API_START(6);
+ *  \endcode
+ *
  *  \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.

Bootloaders/DFU/makefile

@@ -97,6 +97,7 @@ F_USB = $(F_CPU)
 FLASH_SIZE_KB        = 128
 BOOT_SECTION_SIZE_KB = 4
 BOOT_START           = 0x$(shell echo "obase=16; ($(FLASH_SIZE_KB) - $(BOOT_SECTION_SIZE_KB)) * 1024" | bc)
+BOOT_API_TABLESTART  = 0x$(shell echo "obase=16; (($(FLASH_SIZE_KB) * 1024) - 32)" | bc)
 
 
 # Output format. (can be srec, ihex, binary)
@@ -137,6 +138,7 @@ include $(LUFA_PATH)/LUFA/makefile
 
 # List C source files here. (C dependencies are automatically generated.)
 SRC = $(TARGET).c                                                 \
+	  BootloaderAPI.c                                             \
 	  Descriptors.c                                               \
 	  $(LUFA_SRC_USB)                                             \
 
@@ -152,7 +154,7 @@ CPPSRC =
 #     Even though the DOS/Win* filesystem matches both .s and .S the same,
 #     it will preserve the spelling of the filenames, and gcc itself does
 #     care about how the name is spelled on its command-line.
-ASRC =
+ASRC = BootloaderAPITable.S
 
 
 # Optimization level, can be [0, 1, 2, 3, s].
@@ -333,7 +335,7 @@ EXTMEMOPTS =
 #    -Map:      create map file
 #    --cref:    add cross reference to  map file
 LDFLAGS  = -Wl,-Map=$(TARGET).map,--cref
-LDFLAGS += -Wl,--section-start=.text=$(BOOT_START)
+LDFLAGS += -Wl,--section-start=.text=$(BOOT_START) -Wl,--section-start=.apitable=$(BOOT_API_TABLESTART)
 LDFLAGS += -Wl,--relax
 LDFLAGS += -Wl,--gc-sections
 LDFLAGS += $(EXTMEMOPTS)

LUFA/ManPages/ChangeLog.txt

@@ -5,6 +5,25 @@
  */
 
  /** \page Page_ChangeLog Project Changelog
+  *
+  *  \section Sec_ChangeLogXXXXXX Version XXXXXX
+  *  <b>New:</b>
+  *  - Core:
+  *   - None
+  *  - Library Applications:
+  *   - Added User Application APIs to the CDC and DFU class bootloaders
+  *
+  *  <b>Changed:</b>
+  *  - Core:
+  *   - None
+  *  - Library Applications:
+  *   - None
+  *
+  *  <b>Fixed:</b>
+  *  - Core:
+  *   - None
+  *  - Library Applications:
+  *   - None
   *
   *  \section Sec_ChangeLog111009 Version 111009
   *  <b>New:</b>

LUFA/ManPages/ConfiguringApps.txt

@@ -52,7 +52,7 @@
  *
  *  If you are not using any board-specific drivers in the LUFA library, or you are using a custom board layout, change this to read
  *  "USER" (no quotes) instead of a standard board name. If the USER board type is selected and the application makes use of one or more
- *  board-specific hardware drivers inside the LUFA library, then the appropriate stub drives files should be copied from the /BoardStubs/
+ *  board-specific hardware drivers inside the LUFA library, then the appropriate stub drives files should be copied from the \c /CodeTemplates/DriverStubs/
  *  directory into a /Board/ folder inside the application directory, and the stub driver completed with the appropriate code to drive the
  *  custom board's hardware.
  *

LUFA/ManPages/MigrationInformation.txt

@@ -10,6 +10,9 @@
  *  to the next version released. It does not indicate all new additions to the library in each version change, only
  *  areas relevant to making older projects compatible with the API changes of each new release.
  *
+ *  \section Sec_MigrationXXXXXX Migrating from 111009 to XXXXXX
+ *  None
+ *
  *  \section Sec_Migration111009 Migrating from 110528 to 111009
  *  <b>Non-USB Library Components</b>
  *    - The \c JTAG_DEBUG_ASSERT() macro has been renamed \ref JTAG_ASSERT() to be consistent with \ref STDOUT_ASSERT().

LUFA/Version.h

@@ -43,10 +43,10 @@
 	/* Public Interface - May be used in end-application: */
 		/* Macros: */
 			/** Indicates the version number of the library, as an integer. */
-			#define LUFA_VERSION_INTEGER     0x111009
+			#define LUFA_VERSION_INTEGER     0x000000
 
 			/** Indicates the version number of the library, as a string. */
-			#define LUFA_VERSION_STRING      "111009"
+			#define LUFA_VERSION_STRING      "000000"
 
 #endif