Implementation of the uC data transfer protocol. More...

#include "dataXferImpl.h"
#include <string.h>

Functions
const char *	getReceiveErrorString ()
	Returns an error string matching the last error code.

Variables
XFER_VAR	xferVar [NUM_XFER_VARS]
	A table to hold the state of transfer variables.

uint8_t	au8_xferVarWriteable [NUM_XFER_VARS/8+((NUM_XFER_VARS % 8) > 0)]

static const char *	apsz_errorDesc [NUM_ERROR_CODES]

Command-finding state machine
static CMD_STATE	cmdState
	The current state of the command-finding state machine.

static CMD_OUTPUT	cmdOutput
	The current output of the command-finding state machine.

void	resetCommandFindMachine ()

CMD_OUTPUT	stepCommandFindMachine (char c_inChar, char *c_outChar)

Receive state machine
#define	B_IS_SPEC b_isSpec

static RECEIVE_STATE	receiveState
	Current state of the receive state machine.

static char	c_outChar

static uint	u_index

static RECEIVE_ERROR	receiveError

static BOOL	b_isSpec

static uint8_t	au8_varSpecData [(UINT8_MAX+1)+3]

static uint	u_specLength
	The length of the var spec data.

RECEIVE_STATE	getReceiveMachineState ()

char	getReceiveMachineOutChar ()

uint	getReceiveMachineIndex ()

RECEIVE_ERROR	getReceiveMachineError ()

BOOL	getReceiveMachineIsSpec ()

void	resetReceiveMachine ()

void	clearReceiveMachineError ()

static void	freeVariable (uint u_index)

void	clearReceiveStruct ()

BOOL	isReceiveMachineChar ()

BOOL	isReceiveMachineData ()

BOOL	isReceiveMachineSpec ()

uint	getVarIndex (char c_cmd)

uint	getVarLength (char c_cmd)

static uint8_t *	validateIndex ()

void	assignBit (uint u_index, BOOL b_bitVal)

BOOL	isVarWriteable (uint u_index)

static BOOL	validateLength (uint u_varLength)

static void	parseVarSpec ()

RECEIVE_ERROR	notifyOfTimeout ()

RECEIVE_ERROR	stepReceiveMachine (char c_inChar)

Detailed Description

Implementation of the uC data transfer protocol.

Definition in file dataXferImpl.c.

Function Documentation

◆ assignBit()

void assignBit	(	uint	u_index,
		BOOL	b_bitVal
	)

Assign a bit in the au8_xferVarWriteable bit field.

Parameters

u_index	The index of the variable to set.
b_bitVal	Bit value to set at this index.

Definition at line 267 of file dataXferImpl.c.

Referenced by specifyVar(), and stepReceiveMachine().

◆ clearReceiveMachineError()

void clearReceiveMachineError ( )

Clear the current receive machine error status; the caller should therefore handle or report this error to a higher level of the program.

Definition at line 169 of file dataXferImpl.c.

◆ clearReceiveStruct()

void clearReceiveStruct ( )

Clear the received data structure, so that no variables are specified.

Definition at line 188 of file dataXferImpl.c.

Referenced by initDataXfer().

◆ freeVariable()

static void freeVariable ( uint u_index )

static

Free memory associted with a variable.

Parameters

u_index A value from 0-NUM_XFER_VARS, unique for each var.

Definition at line 178 of file dataXferImpl.c.

Referenced by clearReceiveStruct(), and parseVarSpec().

◆ getReceiveMachineError()

RECEIVE_ERROR getReceiveMachineError ( )

Return the error last encountered by the receive state machine. See stepReceiveMachine for more information. This also clears the error status.

Definition at line 146 of file dataXferImpl.c.

◆ getReceiveMachineIndex()

uint getReceiveMachineIndex ( )

Return the index output by the receive state machine. See stepReceiveMachine for more information.

Definition at line 141 of file dataXferImpl.c.

◆ getReceiveMachineIsSpec()

BOOL getReceiveMachineIsSpec ( )

Determine if the last data found by the receive state machine was a specification; if not, it was data. See stepReceiveMachine for more information. PC only.

Definition at line 154 of file dataXferImpl.c.

◆ getReceiveMachineOutChar()

char getReceiveMachineOutChar ( )

Return the character output by the receive state machine. See stepReceiveMachine for more information.

Definition at line 137 of file dataXferImpl.c.

◆ getReceiveMachineState()

RECEIVE_STATE getReceiveMachineState ( )

Return the current receive machine state. See stepReceiveMachine for more information.

Definition at line 133 of file dataXferImpl.c.

◆ getVarIndex()

uint getVarIndex ( char c_cmd )

Return the index of a variable in a command byte.

Parameters

c_cmd Command byte.

Returns: Index of the variable.

Definition at line 220 of file dataXferImpl.c.

Referenced by stepReceiveMachine().

◆ getVarLength()

uint getVarLength ( char c_cmd )

Return the number of bytes of a variable in a command byte.

Parameters

c_cmd Command byte.

Returns: Number of bytes.

Definition at line 224 of file dataXferImpl.c.

Referenced by stepReceiveMachine().

◆ isReceiveMachineChar()

BOOL isReceiveMachineChar ( )

Determines if the receive state machine just received a character.

Returns: True when the machine just received a character.

Definition at line 200 of file dataXferImpl.c.

◆ isReceiveMachineData()

BOOL isReceiveMachineData ( )

Determines if the receive state machine just received some data.

Returns: True when the machine just received some data.

Definition at line 206 of file dataXferImpl.c.

◆ isReceiveMachineSpec()

BOOL isReceiveMachineSpec ( )

Determines if the receive state machine just received an updated specification. PC only.

Returns: True when the machine just received an updated spec.

Definition at line 213 of file dataXferImpl.c.

◆ isVarWriteable()

BOOL isVarWriteable ( uint u_index )

Read a bit in the au8_xferVarWriteable bit field.

Parameters

u_index The index of the variable to set.

Returns: The bit value at this index. TRUE indicated the variable is writeable; FALSE indicates a read-only variable: only the microcontroller, but not the PC, may change its value.

Definition at line 279 of file dataXferImpl.c.

Referenced by sendVar(), and validateIndex().

◆ notifyOfTimeout()

RECEIVE_ERROR notifyOfTimeout ( )

Notify the state machine that a timeout occurred between receiving the previous and next character. A timeout may not lead to an error; for example, between two received data packets or two received characters, timeout are allowed.

Returns: An error code; ERROR_NONE (which is false) means no error occurred.

Definition at line 361 of file dataXferImpl.c.

◆ parseVarSpec()

static void parseVarSpec ( )

static

Parses a received variable spec, stored in au8_varSpecData, assigns fields in xferVar, and reports any errors.

Definition at line 315 of file dataXferImpl.c.

Referenced by stepReceiveMachine().

◆ resetCommandFindMachine()

void resetCommandFindMachine ( )

Resets the command-finding state machine; see stepCommandFindMachine for more information.

Definition at line 17 of file dataXferImpl.c.

Referenced by resetReceiveMachine().

◆ resetReceiveMachine()

void resetReceiveMachine ( )

Reset the receive state machine to its initial state and clear the error status. The outputs are not reset, because they will not be valid until after an invocation of the state machine.

Definition at line 160 of file dataXferImpl.c.

Referenced by initDataXfer(), and notifyOfTimeout().

◆ stepCommandFindMachine()

CMD_OUTPUT stepCommandFindMachine	(	char	c_inChar,
		char *	c_outChar
	)

The command-finding state machine looks for commands in the data passed to it. Sequences it recognizes:

c, where c != CMD_TOKEN, outputs the character c.
CMD_TOKEN ESCAPED_CMD outputs the character CMD_TOKEN (known as an escaped command).
CMD_TOKEN c, where c != CMD_TOKEN and c != ESCAPED_CMD, outputs the command c.
CMD_TOKEN CMD_TOKEN ESCAPED_CMD outputs the command CMD_TOKEN (note that the second CMD_TOKEN is "escaped", so it is treated as a character specifying the command, not as the beginning of a command).
CMD_TOKEN CMD_TOKEN CMD_TOKEN outputs a repeated command then waits for the next character. See the state machine sketch below for more information.
CMD_TOKEN CMD_TOKEN c, where c != CMD_TOKEN and c != ESCAPED_CMD, outputs a repeated command c. This is a protocol violation, but must be reported at a higher level; this routine merely reports a repeated command. A sketch of the state machine:
```
case START :
  if (c == CMD_TOKEN) state = WAIT1
  else output c as a character
case WAIT1 :
  if (c == CMD_TOKEN) state = WAIT2
  if (c == ESCAPED_CMD) state = START, output CMD_TOKEN as a character
  else output c as a command
case WAIT2 :
  if (c == ESCAPED_CMD) state = START, output command CMD_TOKEN
  if (c == CMD_TOKEN) output repeated command, remain in this state
  else output repeated command c
```
Parameters

c_inChar A character input to the machine.

c_outChar The character/command output by the machine when the returned state is not CMD_WAIT.

Returns
The output of the machine, which indicates if a command or character is available.

Definition at line 22 of file dataXferImpl.c.

Referenced by stepReceiveMachine().

◆ stepReceiveMachine()

RECEIVE_ERROR stepReceiveMachine ( char c_inChar )

This state machine receives data from the microcontroller. It takes a character received plus an indication if a timeout occurred since the last invocation of this function and advances the machine. The machine produces outputs when the returned state is STATE_RECV_START. Outputs:

c_outChar, set if a character (versus a data packet) was received
u_index, set to the index of the data received
receiveError, an error code
b_isSpec, true if a specification packet was received.
Parameters

c_inChar A character for the state machine to process.

Returns
An error code; ERROR_NONE (which is false) means no error occurred.

Definition at line 374 of file dataXferImpl.c.

◆ validateIndex()

static uint8_t* validateIndex ( )

static

Check that the given index is valid. The index is specified by u_index. On error, the receiveError and receiveState variables are updated.

Returns: A pointer to the data corresponding to the index if the index is valid, or NULL if an error occurred.

Definition at line 234 of file dataXferImpl.c.

Referenced by stepReceiveMachine().

◆ validateLength()

static BOOL validateLength ( uint u_varLength )

static

Verify that the length of the variable matches the specified length. Otherwise, issue an error. On error, receiveError and receiveState are set.

Parameters

u_varLength The length of the variable, in bytes.

Returns: TRUE on success, FALSE when the length does not match.

Definition at line 294 of file dataXferImpl.c.

Referenced by stepReceiveMachine().

Variable Documentation

◆ apsz_errorDesc

const char* apsz_errorDesc[NUM_ERROR_CODES]

static

Initial value:

= {
  "no error",
  "repeated command",
  "timeout",
  "interrupted command",
  "unspecified index",
  "index too high",
  "variable size mismatch",
  "read only variable",
  "illegal variable specification",
}

Strings which provide a user-readable version of the error codes in RECEIVE_ERROR.

Definition at line 600 of file dataXferImpl.c.

Referenced by getReceiveErrorString().

◆ au8_varSpecData

uint8_t au8_varSpecData[(UINT8_MAX+1)+3]

static

Temporary storage for a variable spec being received, with enough additional space to terminate 3 unterminated strings for safety.

Definition at line 307 of file dataXferImpl.c.

Referenced by parseVarSpec(), and stepReceiveMachine().

◆ au8_xferVarWriteable

uint8_t au8_xferVarWriteable[NUM_XFER_VARS/8+((NUM_XFER_VARS % 8) > 0)]

An array of isWriteable bits for each var. Each bit is true if the PC is allowed to change this variable; false otherwise. This does NOT restrict the microcontroller to read-only access to this variable.

Definition at line 101 of file dataXferImpl.c.

Referenced by assignBit(), clearReceiveStruct(), and isVarWriteable().

◆ b_isSpec

BOOL b_isSpec

static

True if the data just received by the receive state machine was a specification. See stepReceiveMachine for more information.

Definition at line 126 of file dataXferImpl.c.

Referenced by getReceiveMachineIsSpec(), and stepReceiveMachine().

◆ c_outChar

char c_outChar

static

A character output by the receive state machine. See stepReceiveMachine for more information.

Definition at line 112 of file dataXferImpl.c.

Referenced by getReceiveMachineOutChar(), and stepReceiveMachine().

◆ receiveError

RECEIVE_ERROR receiveError

static

An error code produced by the receive state machine. See stepReceiveMachine for more information.

Definition at line 121 of file dataXferImpl.c.

Referenced by clearReceiveMachineError(), getReceiveErrorString(), getReceiveMachineError(), isReceiveMachineChar(), isReceiveMachineData(), isReceiveMachineSpec(), notifyOfTimeout(), resetReceiveMachine(), stepReceiveMachine(), validateIndex(), and validateLength().

◆ u_index

uint u_index

static

The index of a data item; updated by the receive state machine, or CHAR_RECEIVED_INDEX if a character was received. See stepReceiveMachine for more information.

Definition at line 117 of file dataXferImpl.c.

Referenced by clearReceiveStruct(), getReceiveMachineIndex(), isReceiveMachineChar(), isReceiveMachineData(), isReceiveMachineSpec(), parseVarSpec(), stepReceiveMachine(), validateIndex(), and validateLength().

c_inChar	A character input to the machine.
c_outChar	The character/command output by the machine when the returned state is not CMD_WAIT.

Functions

Variables

Command-finding state machine

Receive state machine

Detailed Description

Function Documentation

◆ assignBit()

◆ clearReceiveMachineError()

◆ clearReceiveStruct()

◆ freeVariable()

◆ getReceiveMachineError()

◆ getReceiveMachineIndex()

◆ getReceiveMachineIsSpec()

◆ getReceiveMachineOutChar()

◆ getReceiveMachineState()

◆ getVarIndex()

◆ getVarLength()

◆ isReceiveMachineChar()

◆ isReceiveMachineData()

◆ isReceiveMachineSpec()

◆ isVarWriteable()

◆ notifyOfTimeout()

◆ parseVarSpec()

◆ resetCommandFindMachine()

◆ resetReceiveMachine()

◆ stepCommandFindMachine()

◆ stepReceiveMachine()

◆ validateIndex()

◆ validateLength()

Variable Documentation

◆ apsz_errorDesc

◆ au8_varSpecData

◆ au8_xferVarWriteable

◆ b_isSpec

◆ c_outChar

◆ receiveError

◆ u_index