Add function documentation to the AVRISP project.

[pub/USBasp.git] / Projects / Incomplete / AVRISP / Lib / V2Protocol.c

diff --git a/Projects/Incomplete/AVRISP/Lib/V2Protocol.c b/Projects/Incomplete/AVRISP/Lib/V2Protocol.c
index 08a54e2..248c50d 100644 (file)
--- a/Projects/Incomplete/AVRISP/Lib/V2Protocol.c
+++ b/Projects/Incomplete/AVRISP/Lib/V2Protocol.c
@@ -36,6 +36,10 @@
 #define  INCLUDE_FROM_V2PROTOCOL_C\r
 #include "V2Protocol.h"\r
 \r
+/** Master V2 Protocol packet handler, for receieved V2 Protocol packets from a connected host.\r
+ *  This routine decodes the issued command and passes off the handling of the command to the\r
+ *  appropriate function.\r
+ */\r
 void V2Protocol_ProcessCommand(void)
 {
        uint8_t V2Command = Endpoint_Read_Byte();\r
@@ -94,6 +98,11 @@ void V2Protocol_ProcessCommand(void)
        Endpoint_SetEndpointDirection(ENDPOINT_DIR_OUT);
 }
 \r
+/** Handler for unknown V2 protocol commands. This discards all sent data and returns a\r
+ *  STATUS_CMD_UNKNOWN status back to the host.\r
+ *\r
+ *  \param V2Command  Issued V2 Protocol command byte from the host\r
+ */\r
 static void V2Protocol_Command_Unknown(uint8_t V2Command)\r
 {\r
        /* Discard all incomming data */\r
@@ -110,7 +119,8 @@ static void V2Protocol_Command_Unknown(uint8_t V2Command)
        Endpoint_Write_Byte(STATUS_CMD_UNKNOWN);\r
        Endpoint_ClearIN();\r
 }\r
-
+\r
+/** Handler for the CMD_SIGN_ON command, returning the programmer ID string to the host. */
 static void V2Protocol_Command_SignOn(void)\r
 {\r
        Endpoint_ClearOUT();\r
@@ -123,6 +133,11 @@ static void V2Protocol_Command_SignOn(void)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_SET_PARAMETER and CMD_GET_PARAMETER commands from the host, setting or\r
+ *  getting a device parameter's value from the parameter table.\r
+ *\r
+ *  \param V2Command  Issued V2 Protocol command byte from the host\r
+ */\r
 static void V2Protocol_Command_GetSetParam(uint8_t V2Command)\r
 {\r
        uint8_t ParamID = Endpoint_Read_Byte();\r
@@ -156,6 +171,10 @@ static void V2Protocol_Command_GetSetParam(uint8_t V2Command)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_LOAD_ADDRESS command, loading the given device address into a\r
+ *  global storage variable for later use, and issuing LOAD EXTENDED ADDRESS commands\r
+ *  to the attached device as required.\r
+ */\r
 static void V2Protocol_Command_LoadAddress(void)\r
 {\r
        Endpoint_Read_Stream_BE(&CurrentAddress, sizeof(CurrentAddress));\r
@@ -171,6 +190,9 @@ static void V2Protocol_Command_LoadAddress(void)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_RESET_PROTECTION command, currently implemented as a dummy ACK function\r
+ *  as no ISP short-circuit protection is currently implemented.\r
+ */\r
 static void V2Protocol_Command_ResetProtection(void)\r
 {\r
        Endpoint_ClearOUT();\r
@@ -181,6 +203,9 @@ static void V2Protocol_Command_ResetProtection(void)
        Endpoint_ClearIN();     \r
 }\r
 \r
+/** Handler for the CMD_ENTER_PROGMODE_ISP command, which attempts to enter programming mode on\r
+ *  the attached device, returning success or failure back to the host.\r
+ */\r
 static void V2Protocol_Command_EnterISPMode(void)\r
 {\r
        struct\r
@@ -237,6 +262,7 @@ static void V2Protocol_Command_EnterISPMode(void)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_LEAVE_ISP command, which releases the target from programming mode. */\r
 static void V2Protocol_Command_LeaveISPMode(void)\r
 {\r
        struct\r
@@ -260,6 +286,11 @@ static void V2Protocol_Command_LeaveISPMode(void)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_PROGRAM_FLASH_ISP and CMD_PROGRAM_EEPROM_ISP commands, writing out bytes,\r
+ *  words or pages of data to the attached device.\r
+ *\r
+ *  \param V2Command  Issued V2 Protocol command byte from the host\r
+ */\r
 static void V2Protocol_Command_ProgramMemory(uint8_t V2Command)\r
 {\r
        struct\r
@@ -270,7 +301,7 @@ static void V2Protocol_Command_ProgramMemory(uint8_t V2Command)
                uint8_t  ProgrammingCommands[3];\r
                uint8_t  PollValue1;\r
                uint8_t  PollValue2;\r
-               uint8_t  ProgData[256];\r
+               uint8_t  ProgData[512];\r
        } Write_Memory_Params;\r
        \r
        uint8_t* NextWriteByte = Write_Memory_Params.ProgData;\r
@@ -380,6 +411,11 @@ static void V2Protocol_Command_ProgramMemory(uint8_t V2Command)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_READ_FLASH_ISP and CMD_READ_EEPROM_ISP commands, reading in bytes,\r
+ *  words or pages of data from the attached device.\r
+ *\r
+ *  \param V2Command  Issued V2 Protocol command byte from the host\r
+ */\r
 static void V2Protocol_Command_ReadMemory(uint8_t V2Command)\r
 {\r
        struct\r
@@ -436,6 +472,7 @@ static void V2Protocol_Command_ReadMemory(uint8_t V2Command)
        }\r
 }\r
 \r
+/** Handler for the CMD_CHI_ERASE_ISP command, clearing the target's FLASH memory. */\r
 static void V2Protocol_Command_ChipErase(void)\r
 {\r
        struct\r
@@ -465,6 +502,11 @@ static void V2Protocol_Command_ChipErase(void)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_READ_FUSE_ISP, CMD_READ_LOCK_ISP, CMD_READ_SIGNATURE_ISP and CMD_READ_OSCCAL commands,\r
+ *  reading the requested configuration byte from the device.\r
+ *\r
+ *  \param V2Command  Issued V2 Protocol command byte from the host\r
+ */\r
 static void V2Protocol_Command_ReadFuseLockSigOSCCAL(uint8_t V2Command)\r
 {\r
        struct\r
@@ -490,6 +532,11 @@ static void V2Protocol_Command_ReadFuseLockSigOSCCAL(uint8_t V2Command)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_WRITE_FUSE_ISP and CMD_WRITE_LOCK_ISP commands, writing the requested configuration\r
+ *  byte to the device.\r
+ *\r
+ *  \param V2Command  Issued V2 Protocol command byte from the host\r
+ */\r
 static void V2Protocol_Command_WriteFuseLock(uint8_t V2Command)\r
 {\r
        struct\r
@@ -511,6 +558,7 @@ static void V2Protocol_Command_WriteFuseLock(uint8_t V2Command)
        Endpoint_ClearIN();\r
 }\r
 \r
+/** Handler for the CMD_SPI_MULTI command, writing and reading arbitrary SPI data to and from the attached device. */\r
 static void V2Protocol_Command_SPIMulti(void)\r
 {\r
        struct\r