Skip to content
GitLab
Commit 8aee4cb2 authored by Dean Camera's avatar Dean Camera
Browse files

Add function documentation to the AVRISP project.

parent 73801c73
Hide whitespace changes
Inline Side-by-side
Projects/Incomplete/AVRISP/AVRISP.c
View file @ 8aee4cb2
......@@ -34,11 +34,9 @@
* 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 VTARGET detection
// TODO: Add reversed target connector checks
// TODO: Add Doxygen comments to functions
#include "AVRISP.h"
......
Projects/Incomplete/AVRISP/Lib/V2Protocol.c
View file @ 8aee4cb2
......@@ -36,6 +36,10 @@
#define INCLUDE_FROM_V2PROTOCOL_C
#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)
{
uint8_t V2Command = Endpoint_Read_Byte();
......@@ -94,6 +98,11 @@ void V2Protocol_ProcessCommand(void)
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)
{
/* Discard all incomming data */
......@@ -110,7 +119,8 @@ static void V2Protocol_Command_Unknown(uint8_t V2Command)
Endpoint_Write_Byte(STATUS_CMD_UNKNOWN);
Endpoint_ClearIN();
}
/** Handler for the CMD_SIGN_ON command, returning the programmer ID string to the host. */
static void V2Protocol_Command_SignOn(void)
{
Endpoint_ClearOUT();
......@@ -123,6 +133,11 @@ static void V2Protocol_Command_SignOn(void)
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)
{
uint8_t ParamID = Endpoint_Read_Byte();
......@@ -156,6 +171,10 @@ static void V2Protocol_Command_GetSetParam(uint8_t V2Command)
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)
{
Endpoint_Read_Stream_BE(&CurrentAddress, sizeof(CurrentAddress));
......@@ -171,6 +190,9 @@ static void V2Protocol_Command_LoadAddress(void)
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)
{
Endpoint_ClearOUT();
......@@ -181,6 +203,9 @@ static void V2Protocol_Command_ResetProtection(void)
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)
{
struct
......@@ -237,6 +262,7 @@ static void V2Protocol_Command_EnterISPMode(void)
Endpoint_ClearIN();
}
/** Handler for the CMD_LEAVE_ISP command, which releases the target from programming mode. */
static void V2Protocol_Command_LeaveISPMode(void)
{
struct
......@@ -260,6 +286,11 @@ static void V2Protocol_Command_LeaveISPMode(void)
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)
{
struct
......@@ -270,7 +301,7 @@ static void V2Protocol_Command_ProgramMemory(uint8_t V2Command)
uint8_t ProgrammingCommands[3];
uint8_t PollValue1;
uint8_t PollValue2;
uint8_t ProgData[256];
uint8_t ProgData[512];
} Write_Memory_Params;
uint8_t* NextWriteByte = Write_Memory_Params.ProgData;
......@@ -380,6 +411,11 @@ static void V2Protocol_Command_ProgramMemory(uint8_t V2Command)
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)
{
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)
{
struct
......@@ -465,6 +502,11 @@ static void V2Protocol_Command_ChipErase(void)
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)
{
struct
......@@ -490,6 +532,11 @@ static void V2Protocol_Command_ReadFuseLockSigOSCCAL(uint8_t V2Command)
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)
{
struct
......@@ -511,6 +558,7 @@ static void V2Protocol_Command_WriteFuseLock(uint8_t V2Command)
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)
{
struct
......
Projects/Incomplete/AVRISP/Lib/V2Protocol.h
View file @ 8aee4cb2
......@@ -49,6 +49,7 @@
/** Programmer ID string, returned to the host during the CMD_SIGN_ON command processing */
#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 PROG_MODE_PAGED_WRITES_MASK (1 << 0)
......
Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.c
View file @ 8aee4cb2
......@@ -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)
{
/* 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);
}
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;
}
/** 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
* getting or setting parameter values in response to requests from the host.
*
* \param ParamID Parameter ID whose privellages are to be retrieved from the table
*
* \return Privellages for the requested parameter, as a mask of PARAM_PRIV_* masks
*/
uint8_t V2Params_GetParameterPrivellages(uint8_t ParamID)
{
ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
......@@ -112,6 +109,12 @@ uint8_t V2Params_GetParameterPrivellages(uint8_t ParamID)
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)
{
ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
......@@ -122,6 +125,13 @@ uint8_t V2Params_GetParameterValue(uint8_t ParamID)
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)
{
ParameterItem_t* ParamInfo = V2Params_GetParamFromTable(ParamID);
......@@ -135,3 +145,22 @@ void V2Params_SetParameterValue(uint8_t ParamID, uint8_t Value)
if (ParamID == PARAM_RESET_POLARITY)
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;
}
Projects/Incomplete/AVRISP/Lib/V2ProtocolParams.h
View file @ 8aee4cb2
......@@ -46,10 +46,10 @@
#include "V2ProtocolConstants.h"
/* 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)
/* 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)
/* Type Defines: */
......
Projects/Incomplete/AVRISP/Lib/V2ProtocolTarget.c
View file @ 8aee4cb2
......@@ -36,20 +36,36 @@
#include "V2ProtocolTarget.h"
/** 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)
{
static const uint8_t SPIMaskFromSCKDuration[TOTAL_PROGRAMMING_SPEEDS] =
{
#if (F_CPU == 8000000)
SPI_SPEED_FCPU_DIV_2,
#endif
SPI_SPEED_FCPU_DIV_2, SPI_SPEED_FCPU_DIV_4, SPI_SPEED_FCPU_DIV_8,
SPI_SPEED_FCPU_DIV_16, SPI_SPEED_FCPU_DIV_32, SPI_SPEED_FCPU_DIV_64
#if (F_CPU == 16000000)
, SPI_SPEED_FCPU_DIV_128
#endif
#if (F_CPU == 8000000)
SPI_SPEED_FCPU_DIV_2, // AVRStudio = 8MHz SPI, Actual = 4MHz SPI
SPI_SPEED_FCPU_DIV_2, // AVRStudio = 4MHz SPI, Actual = 4MHz SPI
SPI_SPEED_FCPU_DIV_4, // AVRStudio = 2MHz SPI, Actual = 2MHz SPI
SPI_SPEED_FCPU_DIV_8, // AVRStudio = 1MHz SPI, Actual = 1MHz SPI
SPI_SPEED_FCPU_DIV_16, // AVRStudio = 500KHz SPI, Actual = 500KHz SPI
SPI_SPEED_FCPU_DIV_32, // AVRStudio = 250KHz SPI, Actual = 250KHz SPI
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);
......@@ -60,6 +76,11 @@ uint8_t V2Protocol_GetSPIPrescalerMask(void)
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)
{
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 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));
if (TCNT0 >= TARGET_BUSY_TIMEOUT_MS)
ProgrammingStatus = STATUS_RDY_BSY_TOUT;
ProgrammingStatus = STATUS_CMD_TOUT;
break;
case PROG_MODE_WORD_READYBUSY_MASK:
......@@ -113,6 +146,11 @@ uint8_t V2Protocol_WaitForProgComplete(uint8_t ProgrammingMode, uint16_t PollAdd
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)
{
TCNT0 = 0;
......@@ -132,6 +170,10 @@ uint8_t V2Protocol_WaitWhileTargetBusy(void)
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)
{
SPI_SendByte(0x4D);
......
Projects/Incomplete/AVRISP/Lib/V2ProtocolTarget.h
View file @ 8aee4cb2
......@@ -58,10 +58,14 @@
extern uint32_t CurrentAddress;
/* 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;
while (TCNT0 < MS);
while (TCNT0 < DelayMS);
}
/* Function Prototypes: */
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment