jimulatorInterface.cpp

Go to the documentation of this file.

#include "jimulatorInterface.h"
#include <ctype.h>
#include <fcntl.h>
#include <gdk/gdkkeysyms.h>
#include <glib.h>
#include <gtk/gtk.h>
#include <math.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/poll.h>
#include <sys/signal.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <termios.h>
#include <unistd.h>
#include <algorithm>
#include <iomanip>
#include <iostream>
#include <regex>
#include <string>
#include <unordered_map>
#include <vector>
#include <sstream>

constexpr int SOURCE_BYTE_COUNT = 4;

constexpr int SOURCE_FIELD_COUNT = 4;

constexpr int SOURCE_TEXT_LENGTH = 100;

constexpr int IN_POLL_TIMEOUT = 1000;

constexpr int OUT_POLL_TIMEOUT = 100;

constexpr int ADDRESS_BUS_WIDTH = 4;

constexpr int MAX_NUMBER_OF_BREAKPOINTS = 32;

class BreakpointInfo {
 public:
  unsigned char addressA[ADDRESS_BUS_WIDTH];

  unsigned char addressB[ADDRESS_BUS_WIDTH] = {0xFF, 0XFF, 0XFF, 0XFF};

  unsigned char dataA[8] = {0};

  unsigned char dataB[8] = {0};

  unsigned int misc = 0xFFFFFFFF;
};

enum class BoardInstruction : unsigned char {
  // General commands
  START = 0xB0,
  WOT_U_DO = 0x20,
  STOP = 0x21,
  CONTINUE = 0x23,
  RESET = 0x04,

  // Terminal read/write
  FR_WRITE = 0x12,
  FR_READ = 0x13,

  // Breakpoint read/write
  BP_WRITE = 0x30,
  BP_READ = 0x31,
  BP_SET = 0x32,
  BP_GET = 0x33,

  // Register read/write
  GET_REG = 0x5A,
  SET_REG = 0x52,  // Unused

  // Memory read/write
  GET_MEM = 0x4A,
  SET_MEM = 0x40,
};

inline unsigned char operator|(BoardInstruction l, unsigned char r) {
  return static_cast<unsigned char>(l) | r;
}

class SourceFileLine {
 public:
  SourceFileLine* prev;

  SourceFileLine* next;

  bool hasData;

  unsigned int address;

  int dataSize[4];

  int dataValue[4];

  char* text;
};

class sourceFile {
 public:
  SourceFileLine* pStart;

  SourceFileLine* pEnd;
};

sourceFile source;

// ! Forward declaring auxiliary load functions

// Workers

inline void flushSourceFile();
inline const bool readSourceFile(const char* const);
inline const ClientState getBoardStatus();
inline const std::array<unsigned char, 64> readRegistersIntoArray();
constexpr const int disassembleSourceFile(SourceFileLine*, unsigned int);
constexpr const bool moveSrc(bool firstFlag, SourceFileLine** src);
inline const std::string generateMemoryHex(SourceFileLine** src,
                                           const uint32_t s_address,
                                           int* const increment,
                                           const int currentAddressI,
                                           unsigned char (*memdata)[52]);

// Low level sending

inline void sendNBytes(int, int);
inline void sendChar(unsigned char);
inline void sendCharArray(int, unsigned char*);

// Low level receiving

inline const int getNBytes(int*, int);
inline const int getChar(unsigned char*);
inline const int getCharArray(int, unsigned char*);

// Breakpoints

constexpr const int getNextFreeBreakpoint(const int);
inline const bool getBreakpointStatus(unsigned int*, unsigned int*);
inline const bool getBreakpointDefinition(unsigned int, BreakpointInfo*);
inline void setBreakpointStatus(unsigned int, unsigned int);
inline void setBreakpointDefinition(unsigned int, BreakpointInfo*);
inline const std::unordered_map<u_int32_t, bool> getAllBreakpoints();

// Helpers

constexpr void copyStringLiterals(int, unsigned char*, unsigned char*);
constexpr const int numericStringSubtraction(const unsigned char* const,
                                             const unsigned char* const);
constexpr const int numericStringToInt(int, const unsigned char* const);
constexpr void numericStringAndIntAddition(unsigned char* const, int);
inline const std::string integerArrayToHexString(int,
                                                 unsigned char* const,
                                                 const bool = false);
constexpr const char getLeastSignificantByte(const int);

void Jimulator::compileJimulator(const char* const pathToBin,
                                 const char* const pathToS,
                                 const char* const pathToKMD) {
  close(1);
  dup2(compilerCommunication[1], 1);
  close(2);
  dup2(compilerCommunication[1], 2);
  execlp(pathToBin, "aasm", "-lk", pathToKMD, pathToS, (char*)0);
}

const bool Jimulator::loadJimulator(const char* const pathToKMD) {
  flushSourceFile();
  return readSourceFile(pathToKMD);
}

void Jimulator::startJimulator(const int steps) {
  if (checkBoardState() == ClientState::NORMAL ||
      Jimulator::checkBoardState() == ClientState::BREAKPOINT) {
    sendChar(static_cast<unsigned char>(BoardInstruction::START));
    sendNBytes(steps, 4);  // Send step count
  }
}

void Jimulator::continueJimulator() {
  if (Jimulator::checkBoardState() == ClientState::NORMAL ||
      Jimulator::checkBoardState() == ClientState::BREAKPOINT) {
    sendChar(static_cast<unsigned char>(BoardInstruction::CONTINUE));
  }
}

void Jimulator::pauseJimulator() {
  sendChar(static_cast<unsigned char>(BoardInstruction::STOP));
}

void Jimulator::resetJimulator() {
  sendChar(static_cast<unsigned char>(BoardInstruction::RESET));
}

const bool Jimulator::setBreakpoint(const uint32_t addr) {
  unsigned int wordA = 0, wordB = 0;
  unsigned char address[ADDRESS_BUS_WIDTH] = {0};

  // Unpack address to byte array
  for (int i = 0; i < ADDRESS_BUS_WIDTH; i++) {
    address[i] = getLeastSignificantByte(addr >> (8 * i));
  }

  // Reads the breakpoints
  if (not getBreakpointStatus(&wordA, &wordB)) {
    return false;
  }

  // Checks to see if a breakpoint exists at this address and turns it off if so
  for (int i = 0; i < MAX_NUMBER_OF_BREAKPOINTS; i++) {
    if (((wordA >> i) & 1) != 0) {
      BreakpointInfo bp;

      // Gets breakpoint i from the list;
      // checks if that breakpoint is set for current address;
      // turns it off if so
      if (getBreakpointDefinition(i, &bp) &&
          (numericStringSubtraction(address, bp.addressA) == 0)) {
        setBreakpointStatus(0, 1 << i);
        return false;
      }
    }
  }

  // See if there are any more breakpoints to be set, return if not
  int temp = (~wordA) & wordB;
  if (temp == 0) {
    return false;
  }

  // Set the breakpoint
  BreakpointInfo bp;
  copyStringLiterals(ADDRESS_BUS_WIDTH, address, bp.addressA);

  int i = getNextFreeBreakpoint(temp);
  setBreakpointDefinition(i, &bp);
  return true;
}

const ClientState Jimulator::checkBoardState() {
  const auto board_state = getBoardStatus();

  // Check and log error states
  switch (board_state) {
    case ClientState::RUNNING_SWI:
      break;
    case ClientState::RUNNING:
      break;
    case ClientState::STEPPING:
      break;
    case ClientState::MEMFAULT:
      break;
    case ClientState::BUSY:
      break;
    case ClientState::FINISHED:
      break;
    case ClientState::BREAKPOINT:
      break;
    default:
      return ClientState::NORMAL;
      break;
  }

  return board_state;
}

const std::array<std::string, 16> Jimulator::getJimulatorRegisterValues() {
  auto bytes = readRegistersIntoArray();

  std::array<std::string, 16> ret;  // vector of strings

  // Loop through the array
  for (long unsigned int i = 0; i < ret.size(); i++) {
    ret[i] = integerArrayToHexString(4, &bytes[i * 4], true);
  }

  return ret;
}

const std::string Jimulator::getJimulatorTerminalMessages() {
  unsigned char string[256];  // Arbitrary size
  unsigned char length = 1;

  std::string output("");

  while (length > 0) {
    sendChar(static_cast<unsigned char>(BoardInstruction::FR_READ));
    sendChar(0);  // send the terminal number
    sendChar(32);
    getChar(&length);  // get length of message

    // non-zero received from board - not an empty packet
    if (length != 0) {
      getCharArray(length, string);  // Store the message
      string[length] = '\0';
      output.append((char*)string);
    }
  }

  return output;
}

const bool Jimulator::sendTerminalInputToJimulator(const unsigned int val) {
  unsigned int key_pressed = val;
  unsigned char res = 0;

  // Translate key codes if necessary and understood
  switch (key_pressed) {
    case GDK_KEY_Return:
    case GDK_KEY_KP_Enter:
      key_pressed = '\n';
      break;
    case GDK_KEY_BackSpace:
      key_pressed = '\b';
      break;
    case GDK_KEY_Tab:
      key_pressed = '\t';
      break;
    case GDK_KEY_Escape:
      key_pressed = 0x1B;
      break;
    case GDK_KEY_KP_0:
    case GDK_KEY_KP_1:
    case GDK_KEY_KP_2:
    case GDK_KEY_KP_3:
    case GDK_KEY_KP_4:
    case GDK_KEY_KP_5:
    case GDK_KEY_KP_6:
    case GDK_KEY_KP_7:
    case GDK_KEY_KP_8:
    case GDK_KEY_KP_9:
      key_pressed = key_pressed - GDK_KEY_KP_0 + '0';
      break;
    case GDK_KEY_KP_Add:
      key_pressed = '+';
      break;
    case GDK_KEY_KP_Subtract:
      key_pressed = '-';
      break;
    case GDK_KEY_KP_Multiply:
      key_pressed = '*';
      break;
    case GDK_KEY_KP_Divide:
      key_pressed = '/';
      break;
    case GDK_KEY_KP_Decimal:
      key_pressed = '.';
      break;
    default:
      break;
  }

  // Sending keys to Jimulator
  if (((key_pressed >= ' ') && (key_pressed <= 0x7F)) ||
      (key_pressed == '\n') || (key_pressed == '\b') || (key_pressed == '\t') ||
      (key_pressed == '\a')) {
    sendChar(static_cast<unsigned char>(
        BoardInstruction::FR_WRITE));  // begins a write
    sendChar(0);                       // tells where to send it
    sendChar(1);                       // send length 1
    sendChar(key_pressed);             // send the message - 1 char currently
    getChar(&res);                     // Read the result
    return true;
  }

  return false;
}

std::array<Jimulator::MemoryValues, 13> Jimulator::getJimulatorMemoryValues(
    const uint32_t s_address) {
  constexpr int count = 13;  // How many values displayed in the memory window
  constexpr int bytecount = count * ADDRESS_BUS_WIDTH;  // bytes to read

  // Bit level hacking happening here - converting the integer address into
  // an array of characters.
  unsigned char* p = (unsigned char*)&s_address;
  unsigned char currentAddressS[ADDRESS_BUS_WIDTH] = {p[0], p[1], p[2], p[3]};
  currentAddressS[0] &= -4;  // Normalise address down

  // Reading data into arrays!
  unsigned char memdata[bytecount];
  sendChar(static_cast<unsigned char>(BoardInstruction::GET_MEM));
  sendCharArray(ADDRESS_BUS_WIDTH, currentAddressS);
  sendNBytes(count, 2);
  getCharArray(bytecount, memdata);

  SourceFileLine* src = NULL;
  bool firstFlag = false;

  // Moves our src line to the relevant line of the src file
  if (source.pStart != NULL) {
    src = source.pStart;  // Known to be valid
    while ((src != NULL) && ((src->address < s_address) || not src->hasData)) {
      src = src->next;
    }

    // We fell off the end; wrap to start
    if (src == NULL) {
      src = source.pStart;
      firstFlag = true;

      // Find a record with some data
      while ((src != NULL) && not src->hasData) {
        src = src->next;
      }
    }
  }

  // ! Building an array of memory values from here
  // Data is read into this array
  std::array<Jimulator::MemoryValues, 13> readValues;
  const auto bps = getAllBreakpoints();

  // Iterate over display rows
  for (long unsigned int i = 0; i < readValues.size(); i++) {
    int increment = 0;
    unsigned int currentAddressI =
        numericStringToInt(ADDRESS_BUS_WIDTH, currentAddressS);
    readValues[i].address = currentAddressI;
    readValues[i].hex = std::string("00000000");
    readValues[i].disassembly = std::string("...");

    // Generate the hex
    if (src != NULL && currentAddressI == src->address) {
      readValues[i].disassembly =
          std::regex_replace(std::string(src->text), std::regex(";.*$"), "");
      readValues[i].hex = generateMemoryHex(&src, s_address, &increment,
                                            currentAddressI, &memdata);

      firstFlag = moveSrc(firstFlag, &src);
    }

    // Find if a breakpoint is set on this line
    // if the iterator is not at the end of the map, the breakpoint was found
    // and can be set
    auto iter = bps.find(readValues[i].address);
    if (iter != bps.end()) {
      readValues[i].breakpoint = true;
    }

    // Calculate where the next address is and move the address there
    increment = disassembleSourceFile(src, currentAddressI);
    numericStringAndIntAddition(currentAddressS, increment);
  }

  return readValues;
}

// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! //
// !!!!!!!!!! Functions below are not included in the header file !!!!!!!!!! //
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! //

constexpr const int getNextFreeBreakpoint(const int v) {
  int i = 0;
  for (; (((v >> i) & 1) == 0); i++)
    ;

  return i;
}

constexpr const char getLeastSignificantByte(const int val) {
  return val & 0xFF;
}

constexpr const int rotateRight1Byte(const int val) {
  return val >> 8;
}

constexpr const int rotateLeft1Byte(const int val) {
  return val << 8;
}

inline const bool getBreakpointStatus(unsigned int* wordA,
                                      unsigned int* wordB) {
  sendChar(static_cast<unsigned char>(BoardInstruction::BP_GET));
  return not((getNBytes((int*)wordA, 4) != 4) ||
             (getNBytes((int*)wordB, 4) != 4));
}

constexpr const bool moveSrc(bool firstFlag, SourceFileLine** src) {
  do {
    if ((*src)->next != NULL) {
      (*src) = (*src)->next;
    } else {
      if (not firstFlag) {
        (*src) = source.pStart;
        firstFlag = true;
      } else {
        (*src) = NULL;
      }
    }
  } while (((*src) != NULL) && not(*src)->hasData);

  return firstFlag;
}

inline const std::string generateMemoryHex(SourceFileLine** src,
                                           const uint32_t s_address,
                                           int* const increment,
                                           const int currentAddressI,
                                           unsigned char (*memdata)[52]) {
  std::string hex = "";

  for (int i = 0; i < SOURCE_FIELD_COUNT; i++) {
    if ((*src)->dataSize[i] > 0) {
      char spaces[5] = {0};

      // Get the data string
      auto data = integerArrayToHexString(
          (*src)->dataSize[i],
          &((*memdata)[currentAddressI - s_address + *increment]));

      int j = 0;
      for (; j < (*src)->dataSize[i]; j++) {
        spaces[j] = ' ';
      }

      // Append to the string
      spaces[j] = '\0';
      hex += data;
      hex += spaces;
    }

    // Increase the increment
    *increment = *increment + (*src)->dataSize[i];
  }

  return hex;
}

inline const bool getBreakpointDefinition(unsigned int breakpointlistIndex,
                                          BreakpointInfo* bp) {
  sendChar(static_cast<unsigned char>(BoardInstruction::BP_READ));
  sendChar(breakpointlistIndex);  // send the number of the definition

  if ((2 != getNBytes((int*)&(bp->misc), 2)) ||
      (4 != getCharArray(4, bp->addressA)) ||
      (4 != getCharArray(4, bp->addressB)) ||
      (8 != getCharArray(8, bp->dataA)) || (8 != getCharArray(8, bp->dataB))) {
    return false;
  } else {
    return true;
  }
}

constexpr const int numericStringSubtraction(const unsigned char* const s1,
                                             const unsigned char* const s2) {
  int ret = 0;

  for (int i = ADDRESS_BUS_WIDTH; i--;) {
    ret = rotateLeft1Byte(ret) + (int)s1[i] - (int)s2[i];
  }
  return ret;
}

constexpr void copyStringLiterals(int i,
                                  unsigned char* source,
                                  unsigned char* dest) {
  while (i--) {
    dest[i] = source[i];
  }
}

inline void setBreakpointStatus(unsigned int wordA, unsigned int wordB) {
  sendChar(static_cast<unsigned char>(BoardInstruction::BP_SET));
  sendNBytes(wordA, 4);  // send word a
  sendNBytes(wordB, 4);  // send word b
}

inline void setBreakpointDefinition(unsigned int breakpointIndex,
                                    BreakpointInfo* bp) {
  sendChar(static_cast<unsigned char>(BoardInstruction::BP_WRITE));
  sendChar(breakpointIndex);  // send the list index of the breakpoint
  sendNBytes(bp->misc, 2);
  sendCharArray(ADDRESS_BUS_WIDTH, bp->addressA);
  sendCharArray(ADDRESS_BUS_WIDTH, bp->addressB);
  sendCharArray(8, bp->dataA);
  sendCharArray(8, bp->dataB);
}

inline void sendCharArray(int length, unsigned char* data) {
  struct pollfd pollfd;
  pollfd.fd = writeToJimulator;
  pollfd.events = POLLOUT;

  // See if output possible
  if (not poll(&pollfd, 1, OUT_POLL_TIMEOUT)) {
    std::cout << "Client system not responding!\n";  // communication problem
  }

  // Write char_number bytes
  if (write(writeToJimulator, data, length) == -1) {
    std::cout << "Pipe write error!\n";
  }
}

inline void sendChar(unsigned char data) {
  sendCharArray(1, &data);
}

inline void sendNBytes(int data, int n) {
  if (n > ADDRESS_BUS_WIDTH) {
    n = ADDRESS_BUS_WIDTH;  // Clip n
  }

  unsigned char buffer[n];

  // Conversion to little endian
  for (auto& c : buffer) {
    c = getLeastSignificantByte(data);
    data = rotateRight1Byte(data);
  }

  sendCharArray(n, buffer);
}

inline const int getCharArray(int length, unsigned char* data) {
  int reply_count;  // Number of chars fetched in latest attempt
  int reply_total = 0;
  struct pollfd pollfd;

  pollfd.fd = readFromJimulator;
  pollfd.events = POLLIN;

  // while there is more to get
  while (length > 0) {
    // If nothing available
    if (not poll(&pollfd, 1, IN_POLL_TIMEOUT)) {
      reply_count = 0;  // Will force loop termination
    }

    // attempt to read the number of bytes requested  and store the number of
    // bytes received
    else {
      reply_count = read(readFromJimulator, data, length);
    }

    if (reply_count == 0) {
      length = -1;  // Set to terminate
    }

    // Set minimum to 0
    if (reply_count < 0) {
      reply_count = 0;
    }

    reply_total += reply_count;
    length -= reply_count;  // Update No. bytes that are still required
    data += reply_count;    // Move the data pointer to its new location
  }

  return reply_total;  // return the number of bytes received
}

inline const int getChar(unsigned char* data) {
  return getCharArray(1, data);
}

inline const int getNBytes(int* data, int n) {
  if (n > ADDRESS_BUS_WIDTH) {
    n = ADDRESS_BUS_WIDTH;  // Clip, just in case
  }

  char unsigned buffer[ADDRESS_BUS_WIDTH];
  int numberOfReceivedBytes = getCharArray(n, buffer);
  *data = 0;

  for (int i = 0; i < numberOfReceivedBytes; i++) {
    *data = *data | (getLeastSignificantByte(buffer[i]) << (i * 8));
  }

  return numberOfReceivedBytes;
}

inline const ClientState getBoardStatus() {
  unsigned char clientStatus = 0;
  int stepsSinceReset;
  int leftOfWalk;

  // If the board sends back the wrong the amount of data
  sendChar(static_cast<unsigned char>(BoardInstruction::WOT_U_DO));

  if (getChar(&clientStatus) != 1 ||
      getNBytes(&leftOfWalk, 4) != 4 ||       // Steps remaining
      getNBytes(&stepsSinceReset, 4) != 4) {  // Steps since reset
    std::cout << "board not responding\n";
    return ClientState::BROKEN;
  }

  // TODO: clientStatus represents what the board is doing and why - can be
  //       reflected in the view? and the same with stepsSinceReset

  return static_cast<ClientState>(clientStatus);
}

inline const std::array<unsigned char, 64> readRegistersIntoArray() {
  unsigned char data[64];

  sendChar(static_cast<unsigned char>(BoardInstruction::GET_REG));
  sendNBytes(0, 4);
  sendNBytes(16, 2);
  getCharArray(64, data);

  std::array<unsigned char, 64> ret;
  std::copy(std::begin(data), std::end(data), std::begin(ret));
  return ret;
}

inline const std::string integerArrayToHexString(int i,
                                                 unsigned char* const v,
                                                 const bool prepend0x) {
  std::stringstream ss;

  if (prepend0x) {
    ss << "0x";
  }

  while (i--) {
    ss << std::setfill('0') << std::setw(2) << std::uppercase << std::hex
       << (int)v[i];
  }

  return ss.str();
}

constexpr const int numericStringToInt(int i, const unsigned char* const s) {
  int ret = 0;

  while (i--) {
    ret = rotateLeft1Byte(ret) + (s[i]);
  }

  return ret;
}

constexpr void numericStringAndIntAddition(unsigned char* const s, int n) {
  int temp = 0;

  for (int i = 0; i < ADDRESS_BUS_WIDTH; i++) {
    temp = s[i] + getLeastSignificantByte(n);
    s[i] = getLeastSignificantByte(temp);
    n = rotateRight1Byte(n);  // Shift to next byte
    if (temp >= 0x100) {
      n++;  // Propagate carry
    }
  }
}

constexpr const int disassembleSourceFile(SourceFileLine* src,
                                          unsigned int addr) {
  if (src == NULL || src == nullptr) {
    return 4;
  }

  unsigned int diff = src->address - addr;  // How far to next line start?

  // Do have a source line, but shan't use it
  if (diff == 0) {
    src = src->next;  // Use the one after
    if (src != NULL) {
      diff = src->address - addr;  // if present
    } else {
      diff = 1000;  // Effectively infinity
    }
  }

  if (diff < 4) {
    return diff;  // Next source entry
  } else {
    return 4 - (addr % 4);  // To next word alignment
  }
}

inline const std::unordered_map<u_int32_t, bool> getAllBreakpoints() {
  std::unordered_map<u_int32_t, bool> breakpointAddresses;
  unsigned int wordA, wordB;
  bool error = false;

  // If reading the breakpoints was a success, loops through all of the possible
  // breakpoints - if they are active, add them to the map.
  if (getBreakpointStatus(&wordA, &wordB)) {
    for (int i = 0; (i < MAX_NUMBER_OF_BREAKPOINTS) && not error; i++) {
      if (((wordA >> i) & 1) != 0) {
        BreakpointInfo bp;

        if (getBreakpointDefinition(i, &bp)) {
          u_int32_t addr = numericStringToInt(4, bp.addressA);
          breakpointAddresses.insert({addr, true});
        } else {
          error = true;  // Read failure causes loop termination
        }
      }
    }
  }

  return breakpointAddresses;
}

// ! COMPILING STUFF BELOW! !
// ! COMPILING STUFF BELOW! !
// ! COMPILING STUFF BELOW! !

inline void flushSourceFile() {
  SourceFileLine* old = source.pStart;
  source.pStart = NULL;
  source.pEnd = NULL;

  while (old != NULL) {
    if (old->text != NULL) {
      g_free(old->text);
    }

    SourceFileLine* trash = old;
    old = old->next;
    g_free(trash);
  }
}

constexpr const int checkHexCharacter(const char character) {
  if ((character >= '0') && (character <= '9')) {
    return character - '0';
  } else if ((character >= 'A') && (character <= 'F')) {
    return character - 'A' + 10;
  } else if ((character >= 'a') && (character <= 'f')) {
    return character - 'a' + 10;
  } else {
    return -1;
  }
}

constexpr const int readNumberFromFile(FILE* const f,
                                       char* const c,
                                       unsigned int* const n) {
  while ((*c == ' ') || (*c == '\t')) {
    *c = getc(f);  // Skip spaces
  }

  int j = 0, value = 0;
  for (int digit = checkHexCharacter(*c); digit >= 0;
       digit = checkHexCharacter(*c), j++) {
    value = (value << 4) | digit;  // Accumulate digit
    *c = getc(f);                  // Get next character
  }  // Exits at first non-hex character (which is discarded)

  j = (j + 1) / 2;  // Round digit count to bytes

  int k = 0;
  if (j == 0) {
    k = 0;
  } else {
    *n = value;  // Only if n found

    if (j > 4) {
      k = 4;  // Currently clips at 32-bit
    } else {
      for (k = 1; k < j; k = k << 1) {
        ;  // Round j to 2^N
      }
    }
  }

  return k;
}

constexpr const unsigned int boardTranslateMemsize(const int size) {
  switch (size) {
    case 1:
      return 0;
    case 2:
      return 1;
    case 4:
      return 2;
    case 8:
      return 3;
    default:
      return 0;
  }
}

inline void boardSetMemory(unsigned char* const address,
                           unsigned char* const value,
                           const int size) {
  sendChar(BoardInstruction::SET_MEM | boardTranslateMemsize(size));
  sendCharArray(ADDRESS_BUS_WIDTH, address);  // send address
  sendNBytes(1, 2);                           // send width
  sendCharArray(size, value);
}

inline const bool readSourceFile(const char* const pathToKMD) {
  // TODO: this function is a jumbled mess, refactor and remove sections
  unsigned int oldAddress, dSize[SOURCE_FIELD_COUNT],
      dValue[SOURCE_FIELD_COUNT];
  int byteTotal, textLength;
  char buffer[SOURCE_TEXT_LENGTH + 1];  // + 1 for terminator
  SourceFileLine* currentLine;

  // `system` runs the paramter string as a shell command (i.e. it launches a
  // new process) `pidof` checks to see if a process by the name `jimulator` is
  // running. If it fails (non-zero) It will print an error and return failure.
  if (system("pidof -x jimulator > /dev/null")) {
    std::cout << "Jimulator is not running!\n";
    return false;
  }

  // If file cannot be read, return false
  FILE* komodoSource = fopen(pathToKMD, "r");
  if (komodoSource == NULL) {
    std::cout << "Source could not be opened!\n";
    return false;
  }

  bool hasOldAddress = false;  // Don't know where we start

  // Repeat until end of file
  while (not feof(komodoSource)) {
    unsigned int address = 0;     // Really needed?
    bool flag = false;            // Haven't found an address yet
    char c = getc(komodoSource);  // The current character being parsed

    // If the first character is a colon, read a symbol record
    if (c == ':') {
      hasOldAddress = false;  // Don't retain position
    }

    // Read a source line record
    else {
      for (int j = 0; j < SOURCE_FIELD_COUNT; j++) {
        dSize[j] = 0;
        dValue[j] = 0;
      }

      byteTotal = 0;
      flag = readNumberFromFile(komodoSource, &c, &address) != 0;

      // Read a new address - and if we got an address, try for data fields
      if (flag) {
        if (c == ':') {
          c = getc(komodoSource);  // Skip colon
        }

        // Loop on data fields
        // repeat several times or until `illegal' character met
        for (int j = 0; j < SOURCE_FIELD_COUNT; j++) {
          dSize[j] = readNumberFromFile(komodoSource, &c, &dValue[j]);

          if (dSize[j] == 0) {
            break;  // Quit if nothing found
          }

          byteTotal = byteTotal + dSize[j];  // Total input
        }

        oldAddress = address + byteTotal;  // Predicted -next- address
        hasOldAddress = true;
      }
      // Address field not found  Maybe something useable?
      else if (hasOldAddress) {
        address = oldAddress;  // Use predicted address
        flag = true;           // Note we do have an address
      }

      // We have a record with an address
      if (flag) {
        while ((c != ';') && (c != '\n') && not feof(komodoSource)) {
          c = getc(komodoSource);
        }

        // Check for field separator
        if (c == ';') {
          c = getc(komodoSource);
          if (c == ' ') {
            c = getc(komodoSource);  // Skip formatting space
          }

          textLength = 0;  // Measure (& buffer) source line

          // Everything to end of line (or clip)
          while ((c != '\n') && not feof(komodoSource) &&
                 (textLength < SOURCE_TEXT_LENGTH)) {
            buffer[textLength++] = c;
            c = getc(komodoSource);
          }

          buffer[textLength++] = '\0';  // textLength now length incl. '\0'
          currentLine = g_new(SourceFileLine, 1);  // Create new record
          currentLine->address = address;

          byteTotal = 0;  // Inefficient
          for (int j = 0; j < SOURCE_FIELD_COUNT; j++) {
            currentLine->dataSize[j] = dSize[j];  // Bytes, not digits
            currentLine->dataValue[j] = dValue[j];

            if ((currentLine->dataSize[j] > 0) &&
                ((currentLine->dataSize[j] + byteTotal) <= SOURCE_BYTE_COUNT)) {
              unsigned char addr[4], data[4];

              for (int i = 0; i < 4; i++) {
                addr[i] =
                    getLeastSignificantByte((address + byteTotal) >> (8 * i));
              }
              for (int i = 0; i < currentLine->dataSize[j]; i++) {
                data[i] = getLeastSignificantByte(currentLine->dataValue[j] >>
                                                  (8 * i));
              }

              // Ignore Boolean error return value for now
              boardSetMemory(addr, data, currentLine->dataSize[j]);
            }

            byteTotal = byteTotal + currentLine->dataSize[j];
            currentLine->hasData = (byteTotal != 0);  // If blank line
          }

          // clips source record - essential
          if (byteTotal > SOURCE_BYTE_COUNT) {
            int m = 0;

            for (int j = 0; j < SOURCE_FIELD_COUNT; j++) {
              m = m + currentLine->dataSize[j];
              if (m <= SOURCE_BYTE_COUNT) {
                dSize[j] = 0;
                byteTotal = byteTotal - currentLine->dataSize[j];
              } else {
                dSize[j] = currentLine->dataSize[j];  // Bytes, not digits
                currentLine->dataSize[j] = 0;
              }
            }

            // error here?
            std::cout << "OVERFLOW " << dSize[0] << " " << dSize[1] << " "
                      << dSize[2] << " " << dSize[3] << " " << byteTotal
                      << std::endl;
          }

          // Copy text to buffer
          currentLine->text = g_new(char, textLength);
          for (int j = 0; j < textLength; j++) {
            currentLine->text[j] = buffer[j];
          }

          SourceFileLine* temp1 = source.pStart;
          SourceFileLine* temp2 = NULL;

          while ((temp1 != NULL) && (address >= temp1->address)) {
            temp2 = temp1;
            temp1 = temp1->next;
          }

          currentLine->next = temp1;
          currentLine->prev = temp2;

          if (temp1 != NULL) {
            temp1->prev = currentLine;
          } else {
            source.pEnd = currentLine;
          }

          if (temp2 != NULL) {
            temp2->next = currentLine;
          } else {
            source.pStart = currentLine;
          }
        }
      }  // Source line
    }

    // Get the next relevant character
    while ((c != '\n') && not feof(komodoSource)) {
      c = getc(komodoSource);
    }
  }

  fclose(komodoSource);
  return true;
}