forksand
/
qmk_firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add function documentation to the AVRISP project.

Browse Source
pull/1469/head
Dean Camera 16 years ago
parent 73801c73a1
commit 8aee4cb2f2
7 changed files with 152 additions and 30 deletions
Show Stats Download Patch File Download Diff File

2
Projects/Incomplete/AVRISP/AVRISP.c
Unescape View File

@ -34,11 +34,9 @@
* the project and is responsible for the initial application hardware configuration. * the project and is responsible for the initial application hardware configuration.
*/ */
// TODO: Fix PROGRAM FLASH and PROGRAM EEPROM command processing
// TODO: Add in software SPI for lower programming speeds below 125KHz // TODO: Add in software SPI for lower programming speeds below 125KHz
// TODO: Add in VTARGET detection // TODO: Add in VTARGET detection
// TODO: Add reversed target connector checks // TODO: Add reversed target connector checks
// TODO: Add Doxygen comments to functions
#include "AVRISP.h" #include "AVRISP.h"

52
Projects/Incomplete/AVRISP/Lib/V2Protocol.c
Unescape View File

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

1
Projects/Incomplete/AVRISP/Lib/V2Protocol.h
Unescape View File

@ -49,6 +49,7 @@
/** Programmer ID string, returned to the host during the CMD_SIGN_ON command processing */ /** Programmer ID string, returned to the host during the CMD_SIGN_ON command processing */
#define PROGRAMMER_ID "AVRISP_MK2" #define PROGRAMMER_ID "AVRISP_MK2"
/** Mask for the reading or writing of the high byte in a FLASH word when issuing a low-level programming command */
#define READ_WRITE_HIGH_BYTE_MASK (1 << 3) #define READ_WRITE_HIGH_BYTE_MASK (1 << 3)
#define PROG_MODE_PAGED_WRITES_MASK (1 << 0) #define PROG_MODE_PAGED_WRITES_MASK (1 << 0)

53
Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c
Unescape View File

@ -84,24 +84,21 @@ static ParameterItem_t ParameterTable[] =
}; };
/** Loads saved non-volatile parameter values from the EEPROM into the parameter table, as needed. */
void V2Params_LoadEEPROMParamValues(void) void V2Params_LoadEEPROMParamValues(void)
{ {
/* Target RESET line polarity is a non-volatile value, retrieve current parameter value from EEPROM */ /* Target RESET line polarity is a non-volatile value, retrieve current parameter value from EEPROM */
V2Params_GetParamFromTable(PARAM_RESET_POLARITY)->ParamValue = eeprom_read_byte(&EEPROM_Rest_Polarity); V2Params_GetParamFromTable(PARAM_RESET_POLARITY)->ParamValue = eeprom_read_byte(&EEPROM_Rest_Polarity);
} }
static ParameterItem_t* V2Params_GetParamFromTable(uint8_t ParamID) /** Retrieves the host PC read/write privellages for a given parameter in the parameter table. This should
{ * be called before calls to \ref V2Params_GetParameterValue() or \ref V2Params_SetParameterValue() when
/* Find the parameter in the parameter table if present */ * getting or setting parameter values in response to requests from the host.
for (uint8_t TableIndex = 0; TableIndex < (sizeof(ParameterTable) / sizeof(ParameterTable[0])); TableIndex++) *
{ * \param ParamID Parameter ID whose privellages are to be retrieved from the table
if (ParamID == ParameterTable[TableIndex].ParamID) *
return &ParameterTable[TableIndex]; * \return Privellages for the requested parameter, as a mask of PARAM_PRIV_* masks
} */
return NULL;
}
uint8_t V2Params_GetParameterPrivellages(uint8_t ParamID) uint8_t V2Params_GetParameterPrivellages(uint8_t ParamID)
{ {
ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID); ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
@ -112,6 +109,12 @@ uint8_t V2Params_GetParameterPrivellages(uint8_t ParamID)
return ParamInfo->ParamPrivellages; return ParamInfo->ParamPrivellages;
} }
/** Retrieves the current value for a given parameter in the parameter table.
*
* \param ParamID Parameter ID whose value is to be retrieved from the table
*
* \return Current value of the parameter in the table, or 0 if not found
*/
uint8_t V2Params_GetParameterValue(uint8_t ParamID) uint8_t V2Params_GetParameterValue(uint8_t ParamID)
{ {
ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID); ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
@ -122,6 +125,13 @@ uint8_t V2Params_GetParameterValue(uint8_t ParamID)
return ParamInfo->ParamValue; return ParamInfo->ParamValue;
} }
/** Sets the value for a given parameter in the parameter table.
*
* \param ParamID Parameter ID whose value is to be set in the table
* \param Value New value to set the parameter to
*
* \return Pointer to the associated parameter information from the parameter table if found, NULL otherwise
*/
void V2Params_SetParameterValue(uint8_t ParamID, uint8_t Value) void V2Params_SetParameterValue(uint8_t ParamID, uint8_t Value)
{ {
ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID); ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
@ -135,3 +145,22 @@ void V2Params_SetParameterValue(uint8_t ParamID, uint8_t Value)
if (ParamID == PARAM_RESET_POLARITY) if (ParamID == PARAM_RESET_POLARITY)
eeprom_write_byte(&EEPROM_Rest_Polarity, Value); eeprom_write_byte(&EEPROM_Rest_Polarity, Value);
} }
/** Retrieves a parameter entry (including ID, value and privellages) from the parameter table that matches the given
* parameter ID.
*
* \param ParamID Parameter ID to find in the table
*
* \return Pointer to the associated parameter information from the parameter table if found, NULL otherwise
*/
static ParameterItem_t* V2Params_GetParamFromTable(uint8_t ParamID)
{
/* Find the parameter in the parameter table if present */
for (uint8_t TableIndex = 0; TableIndex < (sizeof(ParameterTable) / sizeof(ParameterTable[0])); TableIndex++)
{
if (ParamID == ParameterTable[TableIndex].ParamID)
return &ParameterTable[TableIndex];
}
return NULL;
}

4
Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.h
Unescape View File

@ -46,10 +46,10 @@
#include "V2ProtocolConstants.h" #include "V2ProtocolConstants.h"
/* Macros: */ /* Macros: */
/* Parameter privellage mask to allow the host PC to read the parameter's value */ /** Parameter privellage mask to allow the host PC to read the parameter's value */
#define PARAM_PRIV_READ (1 << 0) #define PARAM_PRIV_READ (1 << 0)
/* Parameter privellage mask to allow the host PC to change the parameter's value */ /** Parameter privellage mask to allow the host PC to change the parameter's value */
#define PARAM_PRIV_WRITE (1 << 1) #define PARAM_PRIV_WRITE (1 << 1)
/* Type Defines: */ /* Type Defines: */

62
Projects/Incomplete/AVRISP/Lib/V2ProtocolTarget.c
Unescape View File

@ -36,20 +36,36 @@
#include "V2ProtocolTarget.h" #include "V2ProtocolTarget.h"
/** Current memory address for FLASH/EEPROM memory read/write commands */ /** Current memory address for FLASH/EEPROM memory read/write commands */
uint32_t CurrentAddress; uint32_t CurrentAddress;
/** Converts the given AVR Studio SCK duration parameter (set by a SET PARAM command from the host) to the nearest
* possible SPI clock prescaler mask for passing to the SPI_Init() routine.
*
* \return Nearest SPI prescaler mask for the given SCK frequency
*/
uint8_t V2Protocol_GetSPIPrescalerMask(void) uint8_t V2Protocol_GetSPIPrescalerMask(void)
{ {
static const uint8_t SPIMaskFromSCKDuration[TOTAL_PROGRAMMING_SPEEDS] = static const uint8_t SPIMaskFromSCKDuration[TOTAL_PROGRAMMING_SPEEDS] =
{ {
#if (F_CPU == 8000000) #if (F_CPU == 8000000)
SPI_SPEED_FCPU_DIV_2, SPI_SPEED_FCPU_DIV_2, // AVRStudio = 8MHz SPI, Actual = 4MHz SPI
#endif SPI_SPEED_FCPU_DIV_2, // AVRStudio = 4MHz SPI, Actual = 4MHz SPI
SPI_SPEED_FCPU_DIV_2, SPI_SPEED_FCPU_DIV_4, SPI_SPEED_FCPU_DIV_8, SPI_SPEED_FCPU_DIV_4, // AVRStudio = 2MHz SPI, Actual = 2MHz SPI
SPI_SPEED_FCPU_DIV_16, SPI_SPEED_FCPU_DIV_32, SPI_SPEED_FCPU_DIV_64 SPI_SPEED_FCPU_DIV_8, // AVRStudio = 1MHz SPI, Actual = 1MHz SPI
#if (F_CPU == 16000000) SPI_SPEED_FCPU_DIV_16, // AVRStudio = 500KHz SPI, Actual = 500KHz SPI
, SPI_SPEED_FCPU_DIV_128 SPI_SPEED_FCPU_DIV_32, // AVRStudio = 250KHz SPI, Actual = 250KHz SPI
#endif SPI_SPEED_FCPU_DIV_64 // AVRStudio = 125KHz SPI, Actual = 125KHz SPI
#if (F_CPU == 16000000)
SPI_SPEED_FCPU_DIV_2, // AVRStudio = 8MHz SPI, Actual = 8MHz SPI
SPI_SPEED_FCPU_DIV_4, // AVRStudio = 4MHz SPI, Actual = 4MHz SPI
SPI_SPEED_FCPU_DIV_8, // AVRStudio = 2MHz SPI, Actual = 2MHz SPI
SPI_SPEED_FCPU_DIV_16, // AVRStudio = 1MHz SPI, Actual = 1MHz SPI
SPI_SPEED_FCPU_DIV_32, // AVRStudio = 500KHz SPI, Actual = 500KHz SPI
SPI_SPEED_FCPU_DIV_64, // AVRStudio = 250KHz SPI, Actual = 250KHz SPI
SPI_SPEED_FCPU_DIV_128 // AVRStudio = 125KHz SPI, Actual = 125KHz SPI
#else
#error No SPI prescaler masks for chosen F_CPU speed.
#endif
}; };
uint8_t SCKDuration = V2Params_GetParameterValue(PARAM_SCK_DURATION); uint8_t SCKDuration = V2Params_GetParameterValue(PARAM_SCK_DURATION);
@ -60,6 +76,11 @@ uint8_t V2Protocol_GetSPIPrescalerMask(void)
return SPIMaskFromSCKDuration[SCKDuration]; return SPIMaskFromSCKDuration[SCKDuration];
} }
/** Asserts or deasserts the target's reset line, using the correct polarity as set by the host using a SET PARAM command.
* When not asserted, the line is tristated so as not to intefere with normal device operation.
*
* \param ResetTarget Boolean true when the target should be held in reset, false otherwise
*/
void V2Protocol_ChangeTargetResetLine(bool ResetTarget) void V2Protocol_ChangeTargetResetLine(bool ResetTarget)
{ {
if (ResetTarget) if (ResetTarget)
@ -76,6 +97,18 @@ void V2Protocol_ChangeTargetResetLine(bool ResetTarget)
} }
} }
/** Waits until the last issued target memory programming command has completed, via the check mode given and using
* the given parameters.
*
* \param ProgrammingMode Programming mode used and completion check to use, a mask of PROG_MODE_* constants
* \param PollAddress Memory address to poll for completion if polling check mode used
* \param PollValue Poll value to check against if polling check mode used
* \param DelayMS Milliseconds to delay before returning if delay check mode used
* \param ReadMemCommand Device low-level READ MEMORY command to send if value check mode used
*
* \return V2 Protocol status \ref STATUS_CMD_OK if the no timeout occurred, \ref STATUS_RDY_BSY_TOUT or
* \ref STATUS_CMD_TOUT otherwise
*/
uint8_t V2Protocol_WaitForProgComplete(uint8_t ProgrammingMode, uint16_t PollAddress, uint8_t PollValue, uint8_t V2Protocol_WaitForProgComplete(uint8_t ProgrammingMode, uint16_t PollAddress, uint8_t PollValue,
uint8_t DelayMS, uint8_t ReadMemCommand) uint8_t DelayMS, uint8_t ReadMemCommand)
{ {
@ -101,7 +134,7 @@ uint8_t V2Protocol_WaitForProgComplete(uint8_t ProgrammingMode, uint16_t PollAdd
while ((SPI_TransferByte(0x00) != PollValue) && (TCNT0 < TARGET_BUSY_TIMEOUT_MS)); while ((SPI_TransferByte(0x00) != PollValue) && (TCNT0 < TARGET_BUSY_TIMEOUT_MS));
if (TCNT0 >= TARGET_BUSY_TIMEOUT_MS) if (TCNT0 >= TARGET_BUSY_TIMEOUT_MS)
ProgrammingStatus = STATUS_RDY_BSY_TOUT; ProgrammingStatus = STATUS_CMD_TOUT;
break; break;
case PROG_MODE_WORD_READYBUSY_MASK: case PROG_MODE_WORD_READYBUSY_MASK:
@ -113,6 +146,11 @@ uint8_t V2Protocol_WaitForProgComplete(uint8_t ProgrammingMode, uint16_t PollAdd
return ProgrammingStatus; return ProgrammingStatus;
} }
/** Waits until the target has completed the last operation, by continuously polling the device's
* BUSY flag until it is cleared, or until the \ref TARGET_BUSY_TIMEOUT_MS timeout period has expired.
*
* \return V2 Protocol status \ref STATUS_CMD_OK if the no timeout occurred, \ref STATUS_RDY_BSY_TOUT otherwise
*/
uint8_t V2Protocol_WaitWhileTargetBusy(void) uint8_t V2Protocol_WaitWhileTargetBusy(void)
{ {
TCNT0 = 0; TCNT0 = 0;
@ -132,6 +170,10 @@ uint8_t V2Protocol_WaitWhileTargetBusy(void)
return STATUS_CMD_OK; return STATUS_CMD_OK;
} }
/** Sends a low-level LOAD EXTENDED ADDRESS command to the target, for addressing of memory beyond the
* 64KB boundary. This sends the command with the correct address as indicated by the current address
* pointer variable set by the host when a SET ADDRESS command is issued.
*/
void V2Protocol_LoadExtendedAddress(void) void V2Protocol_LoadExtendedAddress(void)
{ {
SPI_SendByte(0x4D); SPI_SendByte(0x4D);

8
Projects/Incomplete/AVRISP/Lib/V2ProtocolTarget.h
Unescape View File

@ -58,10 +58,14 @@
extern uint32_t CurrentAddress; extern uint32_t CurrentAddress;
/* Inline Functions: */ /* Inline Functions: */
static inline void V2Protocol_DelayMS(uint8_t MS) /** Blocking delay for a given number of milliseconds, via a hardware timer.
*
* \param DelayMS Number of milliseconds to delay for
*/
static inline void V2Protocol_DelayMS(uint8_t DelayMS)
{ {
TCNT0 = 0; TCNT0 = 0;
while (TCNT0 < MS); while (TCNT0 < DelayMS);
} }
/* Function Prototypes: */ /* Function Prototypes: */

Write Preview
Loading…
Cancel
Save