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

[pub/USBasp.git] / Projects / AVRISP / Lib / PDITarget.c

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