dataXferImpl.c File Reference

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

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

Go to the source code of this file.

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 au8_xferVarWriteable [NUM_XFER_VARS/8+((NUM_XFER_VARS%8) > 0)]
static const char * apsz_errorDesc [NUM_ERROR_CODES]

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 au8_varSpecData [256+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 ()
void clearReceiveStruct ()
BOOL isReceiveMachineChar (char *c_receivedChar)
BOOL isReceiveMachineData (uint *u_receivedIndex)
BOOL isReceiveMachineSpec (uint *u_receivedIndex)
uint getVarIndex (char c_cmd)
uint getVarLength (char c_cmd)
static uint8validateIndex ()
void assignBit (uint u_index, BOOL b_bitVal)
BOOL isVarWriteable (uint u_index)
static BOOL validateLength (uint u_varLength)
static void parseVarSpec ()
RECEIVE_ERROR stepReceiveMachine (char c_inChar, BOOL b_isTimeout)

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)


Detailed Description

Implementation of the uC data transfer protocol.

Definition in file dataXferImpl.c.


Function Documentation

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 356 of file dataXferImpl.c.

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 236 of file dataXferImpl.c.

void clearReceiveStruct (  ) 

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

Definition at line 243 of file dataXferImpl.c.

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 202 of file dataXferImpl.c.

uint getReceiveMachineIndex (  ) 

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

Definition at line 193 of file dataXferImpl.c.

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 214 of file dataXferImpl.c.

char getReceiveMachineOutChar (  ) 

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

Definition at line 186 of file dataXferImpl.c.

RECEIVE_STATE getReceiveMachineState (  ) 

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

Definition at line 179 of file dataXferImpl.c.

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 299 of file dataXferImpl.c.

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 308 of file dataXferImpl.c.

BOOL isReceiveMachineChar ( char *  c_receivedChar  ) 

Determines if the receive state machine just received a character; also returns that character.

Parameters:
c_receivedChar The character received is placed here. If the return value if false, this variable is overwritten with an undefined value.
Returns:
True when the machine just received a character.

Definition at line 255 of file dataXferImpl.c.

BOOL isReceiveMachineData ( uint u_receivedIndex  ) 

Determines if the receive state machine just received some data; also returns the index of the data.

Parameters:
u_receivedIndex The index to the data received is placed here. If the return value if false, this variable is overwritten with an undefined value.
Returns:
True when the machine just received some data.

Definition at line 270 of file dataXferImpl.c.

BOOL isReceiveMachineSpec ( uint u_receivedIndex  ) 

Determines if the receive state machine just received an updated specification; also returns the index of the updated spec. PC only.

Parameters:
u_receivedIndex The index to the spec received is placed here. If the return value if false, this variable is overwritten with an undefined value.
Returns:
True when the machine just received an updated spec.

Definition at line 286 of file dataXferImpl.c.

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 PIC, but not the PC, may change its value.

Definition at line 375 of file dataXferImpl.c.

static void parseVarSpec (  )  [static]

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

Definition at line 411 of file dataXferImpl.c.

void resetCommandFindMachine (  ) 

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

Definition at line 19 of file dataXferImpl.c.

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 224 of file dataXferImpl.c.

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 62 of file dataXferImpl.c.

RECEIVE_ERROR stepReceiveMachine ( char  c_inChar,
BOOL  b_isTimeout 
)

This state machine receives data from the PIC. 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.
    b_isTimeout True if a timeout occurred between reception of the previous character and this character.
    Returns:
    An error code; ERROR_NONE (which is false) means no error occurred.

Definition at line 475 of file dataXferImpl.c.

static uint8* 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 319 of file dataXferImpl.c.

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 390 of file dataXferImpl.c.


Variable Documentation

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 717 of file dataXferImpl.c.

uint8 au8_varSpecData[256+3] [static]

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

Definition at line 403 of file dataXferImpl.c.

uint8 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 PIC to read-only access to this variable.

Definition at line 143 of file dataXferImpl.c.

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 170 of file dataXferImpl.c.

char c_outChar [static]

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

Definition at line 156 of file dataXferImpl.c.

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

Definition at line 165 of file dataXferImpl.c.

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 161 of file dataXferImpl.c.


Generated on Mon Oct 18 07:40:48 2010 for Python-on-a-chip by  doxygen 1.5.9