Add Doxygen documentation to the completed portions of the PDI programming protocol...

diff --git a/Projects/AVRISP/AVRISP.txt b/Projects/AVRISP/AVRISP.txt
index 6eeef38..2de8dd2 100644 (file)
--- a/Projects/AVRISP/AVRISP.txt
+++ b/Projects/AVRISP/AVRISP.txt
@@ -13,7 +13,7 @@
  *  - Series 7 USB AVRs\r
  *  - Series 6 USB AVRs\r
  *  - Series 4 USB AVRs\r
  *  - Series 7 USB AVRs\r
  *  - Series 6 USB AVRs\r
  *  - Series 4 USB AVRs\r

- *  - Series 2 USB AVRs\r
+ *  - Series 2 USB AVRs (8KB versions with reduced features only)\r

  *\r
  *  \section SSec_Info USB Information:\r
  *\r
  *\r
  *  \section SSec_Info USB Information:\r
  *\r


@@ -51,7 +51,7 @@
  *  level conversion can be made to allow for the programming of 3.3V AVR designs.\r
  *\r
  *  This device spoofs Atmel's official AVRISP-MKII device PID so that it remains compatible with Atmel's AVRISP-MKII\r
  *  level conversion can be made to allow for the programming of 3.3V AVR designs.\r
  *\r
  *  This device spoofs Atmel's official AVRISP-MKII device PID so that it remains compatible with Atmel's AVRISP-MKII\r

- *  drivers. When promted, direct your OS to install Atmel's AVRISP-MKII drivers provided with AVRStudio.\r
+ *  drivers. When prompted, direct your OS to install Atmel's AVRISP-MKII drivers provided with AVRStudio.\r

  *\r
  *  Note that this design currently has several limitations:\r
  *    - Minimum ISP target clock speed of 500KHz due to hardware SPI used\r
  *\r
  *  Note that this design currently has several limitations:\r
  *    - Minimum ISP target clock speed of 500KHz due to hardware SPI used\r


@@ -62,7 +62,10 @@
  *  without an ADC converter, VTARGET will report at a fixed 5V level.\r
  *\r
  *  When compiled for the XPLAIN board target, this will automatically configure itself for the correct connections to the\r
  *  without an ADC converter, VTARGET will report at a fixed 5V level.\r
  *\r
  *  When compiled for the XPLAIN board target, this will automatically configure itself for the correct connections to the\r

- *  XPLAIN's XMEGA AVR, and will enable only PDI programming support.\r
+ *  XPLAIN's XMEGA AVR, and will enable PDI only programming support (since ISP mode is not needed).\r
+ *\r
+ *  While this application can be compiled for USB AVRs with as little as 8KB of FLASH, for full functionality 16KB or more\r
+ *  of FLASH is required. On 8KB devices, either ISP or PDI programming support can be disabled to reduce program size.\r

  *\r
  *\r
  *  Connections to the device for SPI programming (when enabled):\r
  *\r
  *\r
  *  Connections to the device for SPI programming (when enabled):\r


@@ -203,8 +206,10 @@
  *   <tr>\r
  *    <td>PDI_VIA_HARDWARE_USART</td>\r
  *    <td>Makefile CDEFS</td>\r
  *   <tr>\r
  *    <td>PDI_VIA_HARDWARE_USART</td>\r
  *    <td>Makefile CDEFS</td>\r

- *    <td>Define to force the PDI protocol (when enabled) to use the hardware USART instead of bit-banging to match the official\r
- *        AVRISP pinout. <i>Automatically set when compiled for the XPLAIN board.</i></td>  \r
+ *    <td>Define to force the PDI protocol (when enabled) to use the much faster hardware USART instead of bit-banging to\r
+ *        match the official AVRISP pinout. This breaks pinout compatibility with the official AVRISP MKII (and requires \r
+ *        seperate ISP and PDI programming headers) but increases programming speed dramatically.\r
+ *        <i>Ignored when compiled for the XPLAIN board.</i></td>  \r

  *   </tr>\r
  *  </table>\r
  */\r
  *   </tr>\r
  *  </table>\r
  */\r

diff --git a/Projects/AVRISP/Lib/NVMTarget.c b/Projects/AVRISP/Lib/NVMTarget.c
index b57cf6d..85de130 100644 (file)
--- a/Projects/AVRISP/Lib/NVMTarget.c
+++ b/Projects/AVRISP/Lib/NVMTarget.c
@@ -38,6 +38,10 @@
 \r
 #if defined(ENABLE_PDI_PROTOCOL) || defined(__DOXYGEN__)\r
 \r
 \r
 #if defined(ENABLE_PDI_PROTOCOL) || defined(__DOXYGEN__)\r
 \r

+/** Sends the given NVM register address to the target.\r
+ *\r
+ *  \param[in] Register  NVM register whose absolute address is to be sent\r
+ */\r

 void NVMTarget_SendNVMRegAddress(uint8_t Register)\r
 {\r
        /* Determine the absolute register address from the NVM base memory address and the NVM register address */\r
 void NVMTarget_SendNVMRegAddress(uint8_t Register)\r
 {\r
        /* Determine the absolute register address from the NVM base memory address and the NVM register address */\r


@@ -50,6 +54,10 @@ void NVMTarget_SendNVMRegAddress(uint8_t Register)
        PDITarget_SendByte(Address >> 24);\r
 }\r
 \r
        PDITarget_SendByte(Address >> 24);\r
 }\r
 \r

+/** Sends the given 32-bit absolute address to the target.\r
+ *\r
+ *  \param[in] AbsoluteAddress  Absolute address to send to the target\r
+ */\r

 void NVMTarget_SendAddress(uint32_t AbsoluteAddress)\r
 {\r
        /* Send the given 32-bit address to the target, LSB first */\r
 void NVMTarget_SendAddress(uint32_t AbsoluteAddress)\r
 {\r
        /* Send the given 32-bit address to the target, LSB first */\r


@@ -59,6 +67,11 @@ void NVMTarget_SendAddress(uint32_t AbsoluteAddress)
        PDITarget_SendByte(AbsoluteAddress >> 24);\r
 }\r
 \r
        PDITarget_SendByte(AbsoluteAddress >> 24);\r
 }\r
 \r

+/** Waits while the target's NVM controller is busy performing an operation, exiting if the\r
+ *  timeout period expires.\r
+ *\r
+ *  \return Boolean true if the NVM controller became ready within the timeout period, false otherwise\r
+ */\r

 bool NVMTarget_WaitWhileNVMControllerBusy(void)\r
 {\r
        TCNT0 = 0;\r
 bool NVMTarget_WaitWhileNVMControllerBusy(void)\r
 {\r
        TCNT0 = 0;\r


@@ -78,7 +91,13 @@ bool NVMTarget_WaitWhileNVMControllerBusy(void)
        return false;\r
 }\r
 \r
        return false;\r
 }\r
 \r

-uint32_t NVMTarget_GetMemoryCRC(uint8_t MemoryCommand)\r
+/** Retrieves the CRC value of the given memory space.\r
+ *\r
+ *  \param[in] CRCCommand  NVM CRC command to issue to the target\r
+ *\r
+ *  \return 24-bit CRC value for the given address space\r
+ */\r
+uint32_t NVMTarget_GetMemoryCRC(uint8_t CRCCommand)\r

 {\r
        uint32_t MemoryCRC;\r
 \r
 {\r
        uint32_t MemoryCRC;\r
 \r


@@ -87,7 +106,7 @@ uint32_t NVMTarget_GetMemoryCRC(uint8_t MemoryCommand)
        /* Set the NVM command to the correct CRC read command */\r
        PDITarget_SendByte(PDI_CMD_STS | (PDI_DATSIZE_4BYTES << 2));\r
        NVMTarget_SendNVMRegAddress(NVM_REG_CMD);\r
        /* Set the NVM command to the correct CRC read command */\r
        PDITarget_SendByte(PDI_CMD_STS | (PDI_DATSIZE_4BYTES << 2));\r
        NVMTarget_SendNVMRegAddress(NVM_REG_CMD);\r

-       PDITarget_SendByte(MemoryCommand);\r
+       PDITarget_SendByte(CRCCommand);\r

 \r
        /* Set CMDEX bit in NVM CTRLA register to start the CRC generation */\r
        PDITarget_SendByte(PDI_CMD_STS | (PDI_DATSIZE_4BYTES << 2));\r
 \r
        /* Set CMDEX bit in NVM CTRLA register to start the CRC generation */\r
        PDITarget_SendByte(PDI_CMD_STS | (PDI_DATSIZE_4BYTES << 2));\r


@@ -116,6 +135,12 @@ uint32_t NVMTarget_GetMemoryCRC(uint8_t MemoryCommand)
        return MemoryCRC;\r
 }\r
 \r
        return MemoryCRC;\r
 }\r
 \r

+/** Reads memory from the target's memory spaces.\r
+ *\r
+ *  \param[in]  ReadAddress  Start address to read from within the target's address space\r
+ *  \param[out] ReadBuffer   Buffer to store read data into\r
+ *  \param[in]  ReadSize     Number of bytes to read\r
+ */\r

 void NVMTarget_ReadMemory(uint32_t ReadAddress, uint8_t* ReadBuffer, uint16_t ReadSize)\r
 {\r
        NVMTarget_WaitWhileNVMControllerBusy();\r
 void NVMTarget_ReadMemory(uint32_t ReadAddress, uint8_t* ReadBuffer, uint16_t ReadSize)\r
 {\r
        NVMTarget_WaitWhileNVMControllerBusy();\r


@@ -149,6 +174,11 @@ void NVMTarget_ReadMemory(uint32_t ReadAddress, uint8_t* ReadBuffer, uint16_t Re
        }\r
 }\r
 \r
        }\r
 }\r
 \r

+/** Erases a specific memory space of the target.\r
+ *\r
+ *  \param[in] EraseCommand  NVM erase command to send to the device\r
+ *  \param[in] Address  Address inside the memory space to erase\r
+ */\r

 void NVMTarget_EraseMemory(uint8_t EraseCommand, uint32_t Address)\r
 {\r
        NVMTarget_WaitWhileNVMControllerBusy();\r
 void NVMTarget_EraseMemory(uint8_t EraseCommand, uint32_t Address)\r
 {\r
        NVMTarget_WaitWhileNVMControllerBusy();\r

diff --git a/Projects/AVRISP/Lib/NVMTarget.h b/Projects/AVRISP/Lib/NVMTarget.h
index 7fde845..b43967f 100644 (file)
--- a/Projects/AVRISP/Lib/NVMTarget.h
+++ b/Projects/AVRISP/Lib/NVMTarget.h
@@ -109,7 +109,7 @@
                void     NVMTarget_SendNVMRegAddress(uint8_t Register);\r
                void     NVMTarget_SendAddress(uint32_t AbsoluteAddress);\r
                bool     NVMTarget_WaitWhileNVMControllerBusy(void);\r
                void     NVMTarget_SendNVMRegAddress(uint8_t Register);\r
                void     NVMTarget_SendAddress(uint32_t AbsoluteAddress);\r
                bool     NVMTarget_WaitWhileNVMControllerBusy(void);\r

-               uint32_t NVMTarget_GetMemoryCRC(uint8_t MemoryCommand);\r
+               uint32_t NVMTarget_GetMemoryCRC(uint8_t CRCCommand);\r

                void     NVMTarget_ReadMemory(uint32_t ReadAddress, uint8_t* ReadBuffer, uint16_t ReadSize);\r
                void     NVMTarget_EraseMemory(uint8_t EraseCommand, uint32_t Address);\r
 \r
                void     NVMTarget_ReadMemory(uint32_t ReadAddress, uint8_t* ReadBuffer, uint16_t ReadSize);\r
                void     NVMTarget_EraseMemory(uint8_t EraseCommand, uint32_t Address);\r
 \r

diff --git a/Projects/AVRISP/Lib/PDIProtocol.c b/Projects/AVRISP/Lib/PDIProtocol.c
index af6fbea..24ce26c 100644 (file)
--- a/Projects/AVRISP/Lib/PDIProtocol.c
+++ b/Projects/AVRISP/Lib/PDIProtocol.c
@@ -37,9 +37,12 @@
 #include "PDIProtocol.h"\r
 \r
 #if defined(ENABLE_PDI_PROTOCOL) || defined(__DOXYGEN__)\r
 #include "PDIProtocol.h"\r
 \r
 #if defined(ENABLE_PDI_PROTOCOL) || defined(__DOXYGEN__)\r

-#warning PDI Programming Protocol support is incomplete and not currently suitable for use.\r
+#warning PDI Programming Protocol support is incomplete and not currently suitable for general use.\r

 \r
 \r

+/** Base absolute address for the target's NVM controller */\r

 uint32_t XPROG_Param_NVMBase;\r
 uint32_t XPROG_Param_NVMBase;\r

+\r
+/** Size in bytes of the target's EEPROM page */\r

 uint32_t XPROG_Param_EEPageSize;\r
 \r
 /** Handler for the CMD_XPROG_SETMODE command, which sets the programmer-to-target protocol used for PDI\r
 uint32_t XPROG_Param_EEPageSize;\r
 \r
 /** Handler for the CMD_XPROG_SETMODE command, which sets the programmer-to-target protocol used for PDI\r

diff --git a/Projects/AVRISP/Lib/PDITarget.c b/Projects/AVRISP/Lib/PDITarget.c
index 9f2bea8..c774fda 100644 (file)
--- a/Projects/AVRISP/Lib/PDITarget.c
+++ b/Projects/AVRISP/Lib/PDITarget.c
@@ -38,12 +38,18 @@
 \r
 #if defined(ENABLE_PDI_PROTOCOL) || defined(__DOXYGEN__)\r
 \r
 \r
 #if defined(ENABLE_PDI_PROTOCOL) || defined(__DOXYGEN__)\r
 \r

+/** Flag to indicate if the USART is currently in Tx or Rx mode. */\r

 volatile bool     IsSending;\r
 \r
 #if !defined(PDI_VIA_HARDWARE_USART)\r
 volatile bool     IsSending;\r
 \r
 #if !defined(PDI_VIA_HARDWARE_USART)\r

+/** Software USART raw frame bits for transmission/reception. */\r

 volatile uint16_t SoftUSART_Data;\r
 volatile uint16_t SoftUSART_Data;\r

+\r
+/** Bits remaining to be sent or received via the software USART. */\r

 volatile uint8_t  SoftUSART_BitCount;\r
 \r
 volatile uint8_t  SoftUSART_BitCount;\r
 \r

+\r
+/** ISR to manage the software USART when bit-banged USART mode is selected. */\r

 ISR(TIMER1_COMPA_vect, ISR_BLOCK)\r
 {\r
        /* Toggle CLOCK pin in a single cycle (see AVR datasheet) */\r
 ISR(TIMER1_COMPA_vect, ISR_BLOCK)\r
 {\r
        /* Toggle CLOCK pin in a single cycle (see AVR datasheet) */\r


@@ -81,6 +87,7 @@ ISR(TIMER1_COMPA_vect, ISR_BLOCK)
 }\r
 #endif\r
 \r
 }\r
 #endif\r
 \r

+/** Enables the target's PDI interface, holding the target in reset until PDI mode is exited. */\r

 void PDITarget_EnableTargetPDI(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r
 void PDITarget_EnableTargetPDI(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r


@@ -122,6 +129,7 @@ void PDITarget_EnableTargetPDI(void)
 #endif\r
 }\r
 \r
 #endif\r
 }\r
 \r

+/** Disables the target's PDI interface, exits programming mode and starts the target's application. */\r

 void PDITarget_DisableTargetPDI(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r
 void PDITarget_DisableTargetPDI(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r


@@ -146,6 +154,10 @@ void PDITarget_DisableTargetPDI(void)
 #endif\r
 }\r
 \r
 #endif\r
 }\r
 \r

+/** Sends a byte via the USART.\r
+ *\r
+ *  \param[in] Byte  Byte to send through the USART\r
+ */\r

 void PDITarget_SendByte(uint8_t Byte)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r
 void PDITarget_SendByte(uint8_t Byte)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r


@@ -192,6 +204,10 @@ void PDITarget_SendByte(uint8_t Byte)
 #endif\r
 }\r
 \r
 #endif\r
 }\r
 \r

+/** Receives a byte via the software USART, blocking until data is received.\r
+ *\r
+ *  \return Received byte from the USART\r
+ */\r

 uint8_t PDITarget_ReceiveByte(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r
 uint8_t PDITarget_ReceiveByte(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r


@@ -234,6 +250,7 @@ uint8_t PDITarget_ReceiveByte(void)
 #endif\r
 }\r
 \r
 #endif\r
 }\r
 \r

+/** Sends a BREAK via the USART to the attached target, consisting of a full frame of idle bits. */\r

 void PDITarget_SendBreak(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r
 void PDITarget_SendBreak(void)\r
 {\r
 #if defined(PDI_VIA_HARDWARE_USART)\r


@@ -274,6 +291,11 @@ void PDITarget_SendBreak(void)
 #endif\r
 }\r
 \r
 #endif\r
 }\r
 \r

+/** Busy-waits while the NVM controller is busy performing a NVM operation, such as a FLASH page read or CRC\r
+ *  calculation.\r
+ *\r
+ *  \return Boolean true if the NVM controller became ready within the timeout period, false otherwise\r
+ */\r

 bool PDITarget_WaitWhileNVMBusBusy(void)\r
 {\r
        TCNT0 = 0;\r
 bool PDITarget_WaitWhileNVMBusBusy(void)\r
 {\r
        TCNT0 = 0;\r