SpdReaderWriter.ino

/*
    Arduino based EEPROM SPD reader and writer
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   For overclockers and PC hardware enthusiasts

   Repos:   https://github.com/1a2m3/SPD-Reader-Writer
   Support: https://forums.evga.com/FindPost/3053544
   Donate:  https://paypal.me/mik4rt3m

   PS: DO NOT EDIT THIS FILE UNLESS YOU KNOW WHAT YOU ARE DOING!
   CONFIGURABLE SETTINGS ARE IN "SpdReaderWriterSettings.h" FILE

*/

#include <Wire.h>
#include <EEPROM.h>
#include "SpdReaderWriterSettings.h"  // Settings

#define FW_VER 20231207  // Firmware version number (YYYYMMDD)

// RAM RSWP support bitmasks
#define DDR5 _BV(5)  // Offline mode
#define DDR4 _BV(4)  // VHV control
#define DDR3 _BV(3)  // VHV+SA1 controls

// SPD5 hub registers
#define MR0  0x00  // Device Type; Most Significant Byte
#define MR1  0x01  // Device Type; Least Significant Byte
#define MR6  0x06  // Device Write Recovery Time Capability
#define MR11 0x0B  // I2C Legacy Mode Device Configuration
#define MR12 0x0C  // Write Protection For NVM Blocks [7:0]
#define MR13 0x0D  // Write Protection for NVM Blocks [15:8]
#define MR14 0x0E  // Device Configuration - Host and Local Interface IO
#define MR18 0x12  // Device Configuration
#define MR20 0x14  // Clear Register MR52 Error Status Command
#define MR48 0x30  // Device Status
#define MR52 0x34  // Hub, Thermal and NVM Error Status

#define PMIC 0b1001 << 3  // PMIC local device type ID

// SPD5 hub device type data
#define SPD5_NO 0x5108  // SPD5 Hub Device
#define SPD5_TS 0x5118  // SPD5 Hub Device w/ Temp Sensor

// DDR4 EEPROM page commands
#define SPA0 0x6C  // Set Page Address 0
#define SPA1 0x6E  // Set Page Address 1
#define RPA  0x6D  // Read Page Address

// EEPROM RSWP commands
#define RPS0 0x63  // Read SWP0 status      (offsets   0-127) (DDR4/DDR3/DDR2)
#define RPS1 0x69  // Read SWP1 status      (offsets 128-255) (DDR4)
#define RPS2 0x6B  // Read SWP2 status      (offsets 256-383) (DDR4)
#define RPS3 0x61  // Read SWP3 status      (offsets 384-511) (DDR4)

#define SWP0 0x62  // Set RSWP for block 0  (offsets   0-127) (DDR4/DDR3/DDR2) *
#define SWP1 0x68  // Set RSWP for block 1  (offsets 128-255) (DDR4)
#define SWP2 0x6A  // Set RSWP for block 2  (offsets 256-383) (DDR4)
#define SWP3 0x60  // Set RSWP for block 3  (offsets 384-511) (DDR4)           *

#define CWP  0x66  // Clear RSWP                              (DDR4/DDR3/DDR2) *

// EEPROM PSWP commands
#define PWPB 0b0110  // PSWP Device Type Identifier Control Code (bits 7-4) (DDR3/DDR2)

// EEPROM data
#define DNC 0x00  // "Do not care" byte

// Device responses
#define RESPONSE '&'
#define ALERT    '@'
#define UNKNOWN  '?'

// Templates
#define A1_MASK 0b11001100  // ScanBus() bitmask response when SA1 is high: 82-83, 86-87

// Device alerts
#define SLAVEINC '+'
#define SLAVEDEC '-'
#define CLOCKINC '/'
#define CLOCKDEC '\\'

// Device name settings
#define NAMELENGTH 16
char deviceName[NAMELENGTH];

// Device settings
#define DEVICESETTINGS 0x20  // EEPROM location to store device settings
#define CLOCKMODE      0     // Bit position for I2C clock settings
#define FASTMODE       true
#define STDMODE        false

// I2C clock frequencies
int32_t clock[] = { 100000, 400000 };

// Global variables
uint32_t i2cClock = clock[0];  // Initial I2C clock
uint8_t eepromPageAddress;     // Initial EEPROM page address
uint8_t slaveCountCurrent;     // Current number of slave addresses on I2C bus
uint8_t slaveCountLast;        // Last number of slave addresses on I2C bus
bool i2cClockCurrent;          // Current I2C clock mode
bool i2cClockLast;             // Last I2C clock mode
bool cmdExecuting;             // Indicates an input command is being executed
uint8_t responseBuffer[32];    // Response body buffer
uint8_t responseLength;        // Output response body length and index

// Device commands
enum Command : uint8_t {
  Get     = ((uint8_t)-1), // Gets current value
  Disable = 0,             // Resets variable value to default
  Enable,                  // Modifies variable value

  ReadByte,                // Read byte
  WriteByte,               // Write byte
  WritePage,               // Write page
  WriteTest,               // Write protection test
  Ddr4Detect,              // DDR4 detection
  Ddr5Detect,              // DDR5 detection
  Spd5HubReg,              // Access SPD5 Hub register space
  Size,                    // Get EEPROM size
  ScanBus,                 // Scan I2C bus
  BusClock,                // I2C clock control
  ProbeAddress,            // Probe I2C address
  PinControl,              // Config pin control
  PinReset,                // Reset config pins state to defaults
  Rswp,                    // RSWP operation
  Pswp,                    // PSWP operation
  RswpReport,              // Report current RSWP capabilities
  Version,                 // Get Firmware version
  Test,                    // Device Communication Test
  Name,                    // Name controls
  FactoryReset,            // Restore device settings to default
};

// Config pin enum
enum pin {
  HV_FEEDBACK = -1, // VHV feedback pin
  HV_SWITCH,        // Pin to toggle VHV on SA0 pin
  SA1_SWITCH,       // Pin to toggle SA1 state
};

// Pin data struct
typedef struct {
  pin number;
  const int name;
  bool defaultState;
  uint8_t mode;
} pinData;

// Configuration pins array
pinData ConfigPin[] = {
  { HV_SWITCH,   HV_EN,  false, OUTPUT }, // HV control
  { SA1_SWITCH,  SA1_EN, true,  OUTPUT }, // SA1 control
  { HV_FEEDBACK, HV_FB,  false, INPUT  }, // HV feedback
};

size_t pinCount = sizeof(ConfigPin) / sizeof(ConfigPin[0]);

void setup() {

  // Set up config pins
  for (uint8_t i = 0; i < pinCount; i++) {
    pinMode(ConfigPin[i].name, ConfigPin[i].mode);
  }

  // Reset config pins
  resetPins();

  // Initiate and join the I2C bus as a master
  Wire.begin();

  // Set I2C timeout to 0.01 sec.
  Wire.setWireTimeout(10000, true);

  // Setup I2C clock
  Wire.setClock(clock[getI2cClockMode()]);
  i2cClockCurrent = clock[getI2cClockMode()];
  i2cClockLast = i2cClockCurrent;

  // Scan I2C bus
  slaveCountCurrent = getQuantity();
  slaveCountLast = slaveCountCurrent;

  // Reset DDR4 EEPROM page address
  setDdr4PageAddress(0);

  // Start serial data transmission
  PORT.begin(BAUD_RATE);
  PORT.setTimeout(100);  // Input timeout in ms

  // Wait for serial port connection or initialization
  while (!PORT) {}

  // Check hardware
  #ifndef __AVR__
  PORT.write(UNKNOWN);
  while (true) {}
  #endif

  // Send a true response when the device is ready
  Respond(true);
  OutputResponse();
}

void loop() {

  resetPinsInternal();

  // Wait for input data
  if (PORT.available()) {
    parseCommand();
  }

  // Monitor I2C bus
  i2cMonitor();
}

// Process input commands and data
void parseCommand() {

  if (!PORT.available()) {
    cmdExecuting = false;
    return;
  }

  cmdExecuting = true;

  switch ((uint8_t)PORT.read()) {

    // Read byte
    case Command::ReadByte:
      cmdRead();
      break;

    // Write byte
    case Command::WriteByte:
      cmdWriteByte();
      break;

    // Write page
    case Command::WritePage:
      cmdWritePage();
      break;

    // Scan I2C bus for addresses
    case Command::ScanBus:
      cmdScanBus();
      break;

    // Probe if I2C address is present
    case Command::ProbeAddress:
      cmdProbeBusAddress();
      break;

    // I2C bus settings
    case Command::BusClock:
      cmdBusClock();
      break;

    // Control digital pins
    case Command::PinControl:
      cmdPinControl();
      break;

    case Command::PinReset:
      cmdPinReset();
      break;

    // RSWP controls
    case Command::Rswp:
      cmdRSWP();
      break;

    // PSWP controls
    case Command::Pswp:
      cmdPSWP();
      break;

    case Command::WriteTest:
      cmdWriteTest();
      break;

    // Get Firmware version
    case Command::Version:
      cmdVersion();
      break;

    // Device Communication Test
    case Command::Test:
      cmdTest();
      break;

    // Report supported RSWP capabilities
    case Command::RswpReport:
      cmdRswpRespond();
      break;

    // DDR4 detection test
    case Command::Ddr4Detect:
      cmdDdr4Detect();
      break;

    // DDR5 detection test
    case Command::Ddr5Detect:
      cmdDdr5Detect();
      break;

    // DDR5 Hub register
    case Command::Spd5HubReg:
      cmdSpd5Hub();
      break;

    // Get EEPROM size
    case Command::Size:
      cmdSize();
      break;

    // Device name controls
    case Command::Name:
      cmdName();
      break;

    // Factory defaults restore
    case Command::FactoryReset:
      cmdFactoryReset();
      break;
  }

  // Output response
  OutputResponse();

  cmdExecuting = false;
}


/*  -=  Response handlers  =-  */

// Put single byte into response
void Respond(uint8_t inputData) {
  responseBuffer[responseLength] = inputData;
  responseLength++;
}

// Put byte array into response
void Respond(uint8_t* inputData, size_t length) {
  for (uint8_t i = 0; i < length; i++) {
    Respond(inputData[i]);
  }
}

// Put string into response
void Respond(String inputData) {
  for (uint8_t i = 0; i < inputData.length(); i++) {
    Respond(inputData[i]);
  }
}

// Output response header, size, contents, and checksum
void OutputResponse() {
  if (responseLength > 0) {

    // Calculate checksum
    uint8_t checkSum = 0;
    for (uint8_t i = 0; i < responseLength; i++) {
      checkSum += responseBuffer[i];
    }

    PORT.write(RESPONSE);
    PORT.write(responseLength);
    PORT.write(responseBuffer, responseLength);
    PORT.write(checkSum);

    // Wait for output to complete
    PORT.flush();

    // Reset response data buffer index
    responseLength = 0;

    // Clear response array
    memset(responseBuffer, 0x00, sizeof(responseBuffer));
  }
}


/*  -=  Command handlers  =-  */

void cmdRead() {
  // Input buffer
  uint8_t buffer[4] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // EEPROM address
  uint8_t address = buffer[0];
  // Offset address
  uint16_t offset = buffer[1] << 8 | buffer[2];
  // Byte count
  uint8_t length  = buffer[3];

  // Output buffer
  uint8_t data[length];
  // Fill the data buffer
  readByte(address, offset, length, data);

  Respond(data, sizeof(data));
}

void cmdWriteByte() {
  // Input buffer
  uint8_t buffer[4] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // EEPROM address
  uint8_t address = buffer[0];
  // Offset address
  uint16_t offset = buffer[1] << 8 | buffer[2];
  // Input byte value
  uint8_t data    = buffer[3];

  Respond(writeByte(address, offset, data));
}

void cmdWritePage() {
  // Input buffer
  uint8_t buffer[4] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // EEPROM address
  uint8_t address = buffer[0];
  // Offset address
  uint16_t offset = buffer[1] << 8 | buffer[2];
  // Bytes count
  uint8_t length  = buffer[3];

  // Validate input length
  if (length == 0) {
    Respond(0);
    return;
  }

  // Input data buffer
  uint8_t data[length];
  PORT.readBytes(data, sizeof(data));

  if (length > 16) {
    Respond(false);
    return;
  }

  Respond(writePage(address, offset, length, data));
}

void cmdScanBus() {
  Respond(scanBus());
}

void cmdTest() {
  Respond(true);
}

void cmdRswpRespond() {
  Respond(rswpSupportTest());
}

void cmdDdr4Detect() {
  // Input buffer
  uint8_t buffer[1] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  uint8_t address = buffer[0];  // I2C address
  Respond(ddr4Detect(address));
}

void cmdDdr5Detect() {
  // Input buffer
  uint8_t buffer[1] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  uint8_t address = buffer[0];  // I2C address
  Respond(ddr5Detect(address));
}

void cmdSpd5Hub() {
  // Input buffer
  uint8_t buffer[3] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  uint8_t address = buffer[0];  // I2C address
  uint8_t memReg  = buffer[1];  // register
  uint8_t command = buffer[2];  // command

  if (!ddr5Detect(address)) {
    Respond(false);
  }

  // Write to register
  if (command == Command::Enable) {
    // Data buffer
    uint8_t data[1] = { 0 };  // Byte value
    PORT.readBytes(data, sizeof(data));
    Respond(writeReg(address, memReg, data[0]));
  }
  // Read from register
  else if (command == Command::Get) {
    Respond(readReg(address, memReg));
  }
  // Unrecognized command
  else {
    Respond(false);
  }
}

void cmdSize() {
  // Input buffer
  uint8_t buffer[1] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  uint8_t address = buffer[0];  // I2C address

  uint16_t size = 0; // 0

  if (probeBusAddress(address)) {
    if (validateEepromAddress(address)) { // EEPROM
      if (ddr5Detect(address)) {
        size = 1024;  // 3
      }
      else {
        if (getQuantity() == 1) {
          if (ddr4Detect()) {
            size = 512;  // 2
          }
          else {
            size = 256;  // 1
          }
        }
        else if (getQuantity() > 1) {
          if (!ddr4Detect()) {
            size = 256;  // 1
          }
        }
      }
    }
    else if (validatePmicAddress(address)) { // PMIC
      size = 256;  // 1
    }
  }

  if (!size) {
    // Read byte 0x02
    uint8_t keyByte[1] = { 0 };
    readByte(address, 0x02, 1, keyByte);
    if (0x0C <= keyByte[0] && keyByte[0] <= 0x11) {
      // DDR4, DDR4E, LPDDR3, LPDDR4, and LPDDR4X
      size = 512;  // 2
    }
  }

  // Return bit position matching SpdReaderWriterDll.Spd.DataLength.Length array index
  for (uint8_t i = 0; i <= 3; i++) {
    if(bitRead(highByte(size), i)) {
      Respond(i + 1);
      return;
    }
  }

  Respond(0);
}

void cmdVersion() {

  uint8_t verLength = sizeof(FW_VER);
  uint8_t data[verLength];

  for (int8_t i = verLength; i > 0; i--) {
    data[i - 1] = FW_VER >> (8 * (i - 1));
  }

  Respond(data, verLength);
}

void cmdName() {
  // Data buffer for command byte
  uint8_t buffer[1] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // Get name
  if (buffer[0] == Command::Get) {
    Respond(getName());
  }
  // Set name
  else if (buffer[0] > 0 && buffer[0] <= NAMELENGTH) {
    // prepare name buffer
    char name[buffer[0] + 1];
    // read name and put it into buffer
    PORT.readBytes(name, buffer[0]);
    // set last byte to \0 where the string ends
    name[buffer[0]] = 0;

    Respond(setName(name));
  }
  // Invalid command
  else {
    Respond(false);
  }
}

void cmdProbeBusAddress() {
  // Data buffer for address
  uint8_t buffer[1] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  uint8_t address = buffer[0];  // I2C address
  Respond(probeBusAddress(address));
}

void cmdBusClock() {
  // Data buffer for clock mode
  uint8_t buffer[1] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // Set I2C clock
  if (buffer[0] == FASTMODE || buffer[0] == STDMODE) {
    setI2cClockMode(buffer[0]);
    Respond(getI2cClockMode() == buffer[0]);
  }
  // Get current I2C clock
  else if (buffer[0] == Command::Get) {
    Respond(getI2cClockMode());
  }
  // Unrecognized command
  else {
    Respond(false);
  }
}

void cmdFactoryReset() {
  Respond(factoryReset());
}

void cmdRSWP() {
  // Data buffer
  uint8_t buffer[3] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // I2C address
  uint8_t address = buffer[0];
  // Block number
  uint8_t block   = buffer[1];
  // Block state
  char state      = buffer[2];

  // enable RSWP
  if (state == Command::Enable) {
    Respond(setRswp(address, block));
  }
  // clear RSWP (all blocks)
  else if (state == Command::Disable) {
    Respond(clearRswp(address));
  }
  // get RSWP status
  else if (state == Command::Get) {
    Respond(getRswp(address, block));
  }
  // unrecognized RSWP command
  else {
    Respond(false);
  }
}

void cmdPSWP() {
  // Data buffer
  uint8_t buffer[2] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // EEPROM address
  uint8_t address = buffer[0];
  // PSWP state
  char state      = buffer[1];

  // enable PSWP
  if (state == Command::Enable) {
    Respond(setPswp(address));
  }
  // read PSWP
  else if (state == Command::Get) {
    Respond(getPswp(address));
  }
  // unknown state
  else {
    Respond(false);
  }
}

void cmdWriteTest() {
  // Data buffer
  uint8_t buffer[3] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // EEPROM address
  uint8_t address = buffer[0];
  // Offset address
  uint16_t offset = buffer[1] << 8 | buffer[2];

  uint8_t data[1];
  Respond(readByte(address, offset, 1, data) && writeByte(address, offset, data[0]));
}

void cmdPinControl() {
  // Data buffer
  uint8_t buffer[2] = { 0 };
  PORT.readBytes(buffer, sizeof(buffer));

  // Pin number
  uint8_t pin = buffer[0];
  // Pin state
  uint8_t state = buffer[1];

  // SA1 controls
  if (pin == SA1_SWITCH) {
    // Toggle SA1 state
    if (state == Command::Enable || state == Command::Disable) {
      Respond(setConfigPin(SA1_EN, state));
    }
    // Get SA1 state
    else if (state == Command::Get) {
      Respond(getConfigPin(SA1_EN));
    }
    // Unknown state
    else {
      Respond(false);
    }
  }
  // VHV 9V controls
  else if (pin == HV_SWITCH) {
    // Toggle HV state
    if (state == Command::Enable || state == Command::Disable) {
      Respond(setHighVoltage(state));
    }
    // Get HV state
    else if (state == Command::Get) {
      Respond(getHighVoltage());
    }
    // Unknown state
    else {
      Respond(0);
    }
  }
  // Unknown pin
  else {
    Respond(false);
  }
}

void cmdPinReset() {
  Respond(resetPins());
}

/*  -=  Read/Write functions  =-  */

// Reads bytes from EEPROM into data buffer
bool readByte(uint8_t address, uint16_t offset, uint8_t length, uint8_t* data) {

  uint8_t _offset = lowByte(offset);

  if (ddr5Detect(address)) {
    _offset |= 0x80;
  }

  adjustPageAddress(address, offset);

  Wire.beginTransmission(address);
  Wire.write(_offset);

  if (Wire.endTransmission(false) != 0) {
    return false;
  }

  Wire.requestFrom(address, length);

  while (Wire.available() < length) {}

  // Fill data buffer
  for (uint8_t i = 0; i < length; i++) {
    while (!Wire.available()) {}
    data[i] = Wire.read();
  }

  return true;
}

// Writes a single byte to EEPROM
bool writeByte(uint8_t address, uint16_t offset, uint8_t data) {

  uint8_t input[1] = { data };
  return writePage(address, offset, 1, input);
}

// Writes a page (multiple bytes) to EEPROM
bool writePage(uint8_t address, uint16_t offset, uint8_t length, uint8_t* data) {

  // Check offset and length to avoid page or block boundary overlapping
  if ((offset % 16 + length) > 16) {
    return false;
  }

  // Check if the block is write protected
  if (ddr5Detect(address) && ddr5GetOfflineMode()) {
    uint8_t block = offset / 64;
    if (getRswp(address, block)) {
      return false;
    }
  }

  uint16_t _offset = offset;

  if (ddr5Detect(address)) {
    _offset |= 0x80;

    // Wait for write completion
    while (bitRead(readReg(address, MR48), 3)) {}
  }

  adjustPageAddress(address, offset);

  Wire.beginTransmission(address);
  Wire.write((uint8_t)(_offset));
  Wire.write(data, length);
  uint8_t status = Wire.endTransmission();

  delay(10);

  return status == 0;
}

// Reads data from SPD5 hub register (/w reset page fix)
uint8_t readReg(uint8_t address, uint8_t memReg) {
  return readReg(address, memReg, true);
}

// Reads data from SPD5 hub register
uint8_t readReg(uint8_t address, uint8_t memReg, bool resetPage) {

  if (memReg >= 128) {
    return false;
  }

  if (resetPage) {
    // Reset page to 0
    adjustPageAddress(address, 0);
  }

  Wire.beginTransmission(address);
  Wire.write(memReg & 0x7F);
  uint8_t status = Wire.endTransmission(false);

  if (status != 0) {
    return false;
  }

  Wire.requestFrom(address, (uint8_t)1);

  // Fill data buffer
  while (!Wire.available()) {}
  uint8_t output = Wire.read();

  return output;
}

// Writes data to SPD5 hub register
bool writeReg(uint8_t address, uint8_t memReg, uint8_t value) {

  if ( memReg >= 128 || !(MR11 <= memReg && memReg <= MR13)) {
    return false;
  }

  Wire.beginTransmission(address);
  Wire.write(memReg);
  Wire.write(value);

  // Writing to MR12/MR13 registers must be followed by Stop operation to allow SPD hub to update
  uint8_t status = Wire.endTransmission();

  // The SPD5 Hub device does not incur any delay to switch from one page to another page
  delay(memReg == MR11 ? 0 : 10);

  return status == 0;
}


/*  -=  RSWP functions  =-  */

// Sets reversible write protection on specified block
bool setRswp(uint8_t address, uint8_t block) {

  if (block > 15) {
    return false;
  }

  // DDR5 RSWP
  if (ddr5Detect(address)) {
    // Select register
    uint8_t memReg = MR12 + bitRead(block, 3);
    // Existing RSWP value
    uint8_t currentValue = readReg(address, memReg);
    // Updated RSWP value
    uint8_t updatedValue = 1 << (block & 0b111);

    return writeReg(address, memReg, currentValue | updatedValue);
  }

  // DDR4 & older RSWP
  uint8_t commands[] = { SWP0, SWP1, SWP2, SWP3 };
  uint8_t cmd = commands[(0 < block && block <= 3) ? block : 0];

  bool result = false;

  if (setHighVoltage(true)) {
    if (block == 0) {
      setConfigPin(SA1_EN, false);  // Required for pre-DDR4
    }
    if (block > 0 && !ddr4Detect()) {
      result = false;
    }
    else {
      result = probeDeviceTypeId(cmd);
    }
    resetPins();
  }

  return result;
}

// Reads reversible write protection status
bool getRswp(uint8_t address, uint8_t block) {

  if (ddr5Detect(address)) {
    return (block <= 15)
      ? readReg(address, MR12 + bitRead(block, 3)) & (1 << (block & 0b111))
      : false;
  }

  uint8_t commands[] = { RPS0, RPS1, RPS2, RPS3 };
  uint8_t cmd = (0 < block && block <= 3) ? commands[block] : commands[0];

  // Jedec EE1002(A), TSE2002av compliance
  if (block == 0 && !ddr4Detect()) {
    setHighVoltage(true);
  }

  bool status = probeDeviceTypeId(cmd);  // true/ack = not protected

  resetPins();

  return !status;  // true = protected or rswp not supported; false = unprotected
}

// Clears reversible software write protection
bool clearRswp(uint8_t address) {

  if (ddr5Detect(address)) {
    return ddr5GetOfflineMode()
      ? writeReg(address, MR12, 0) && readReg(address, MR12) == 0 &&
        writeReg(address, MR13, 0) && readReg(address, MR13) == 0
      : false;
  }

  if (!ddr4Detect(address)) {
    setConfigPin(SA1_EN, true); // Required for pre-DDR4
  }

  if (setHighVoltage(true)) {
    bool result = probeDeviceTypeId(CWP);
    resetPins();

    return result;
  }

  return false;
}

// Test RSWP support capabilities
uint8_t rswpSupportTest() {

  // Reset config pins and HV state
  resetPins();

  // Scan I2C bus
  if (!scanBus()) {
    return 0;
  }

  // Supported RAM value
  uint8_t rswpSupport = 0;

  // RSWP DDR5 test
  if (ddr5GetOfflineMode()) {
    rswpSupport |= DDR5;
  }

  // RSWP VHV test
  if (setHighVoltage(true)) {
    rswpSupport |= DDR4;

    // RSWP SA1 test
    if ((setConfigPin(SA1_EN, true) && setConfigPin(SA1_EN, false))) {
      rswpSupport |= DDR3;
    }
  }

  resetPins();

  return rswpSupport;
}


/*  -=  High Voltage (9V) functions  =-  */

// Controls HV source (set state to ON to turn on, or OFF to turn off)
bool setHighVoltage(bool state) {

  digitalWrite(HV_EN, state);

  uint64_t timeout = millis() + 25;

  while (millis() < timeout) {
    if (getHighVoltage() == state) {
      return true;
    }
  }

  return false;
}

// Returns HV status by reading HV_FB
bool getHighVoltage() {
  return getConfigPin(HV_FB);
}


/*  -=  PSWP functions  =-  */

// Sets permanent write protection on supported EEPROMs
bool setPswp(uint8_t address) {

  if (ddr4Detect(address) || ddr5Detect(address)) {
    return false;
  }

  // Keep address bits (SA0-SA2) intact and change bits 7-4 to '0110'
  uint8_t cmd = (address & 0b111) | (PWPB << 3);

  Wire.beginTransmission(cmd);
  // Write 2 DNC bytes to force LSB to set to 0
  Wire.write(DNC);
  Wire.write(DNC);
  int status = Wire.endTransmission();

  return status == 0;

  //uint8_t cmd = (address & 0b111) << 1 | (PWPB << 4);
  //return probeDeviceTypeId(cmd << 1);
}

// Read permanent write protection status
bool getPswp(uint8_t address) {

  // Keep address bits (SA0-SA2) intact and change bits 7-4 to '0110'
  uint8_t cmd = (address & 0b111) | (PWPB << 3);

  Wire.beginTransmission(cmd);
  // Write 1 DNC byte to force LSB to set to 1
  Wire.write(DNC);
  int status = Wire.endTransmission();

  return status == 0;  // returns true if PSWP is not set

  //uint8_t cmd = (address & 0b111) << 1 | (PWPB << 4);
  //return probeDeviceTypeId(cmd << 1 | 1);
}


/*  -=  EEPROM Page functions  =-  */

// Get active DDR4 page address
uint8_t getPageAddress(bool lowLevel = false) {

  if (!lowLevel) {
    return eepromPageAddress;
  }

  int8_t status = -1;

  // Send start condition
  TWCR = _BV(TWEN) | _BV(TWINT) | _BV(TWEA) | _BV(TWSTA);

  // Wait for TWINT flag set
  while (!(TWCR & (_BV(TWINT)))) {}

  // Wait for start
  while ((TWSR & 0xF8) != 0x08) {}

  // Load RPA command into data register
  TWDR = RPA;

  // Transmit address
  TWCR = _BV(TWEN) | _BV(TWEA) | _BV(TWINT);

  // Wait to transmit address
  while (!(TWCR & (_BV(TWINT)))) {}

  // Check status (0x40 = ACK = page 0; 0x48 = NACK = page 1)
  status = (TWSR & 0xF8);

  // Write 2xDNC after control byte
  if (status == 0x40) {
    for (int i = 0; i < 2; i++) {
      TWDR = DNC;
      TWCR = _BV(TWEN) | _BV(TWEA) | _BV(TWINT);
      while (!(TWCR & (_BV(TWINT)))) {}
    }
  }

  // Send stop condition
  TWCR = _BV(TWEN) | _BV(TWINT) | _BV(TWEA) | _BV(TWSTO);

  // Return the result
  switch (status) {
    case 0x40: return 0;
    case 0x48: return 1;
    default: return status;
  }
}

// Sets DDR4 page address to access lower or upper 256 bytes of DDR4 SPD
void setDdr4PageAddress(uint8_t pageNumber) {
  probeDeviceTypeId((pageNumber == 0) ? SPA0 : SPA1);
  eepromPageAddress = pageNumber;
}

// Adjusts page address according to byte offset specified
void adjustPageAddress(uint8_t address, uint16_t offset) {

  if (!validateEepromAddress(address) || offset >= 1024) {
    return;
  }

  int8_t page;

  // Check if DDR5 is present and adjust page number and addressing mode
  if (ddr5Detect(address)) {
    page = offset >> 7;  // DDR5 page

    // Write DDR5 page address to MR11[2:0]
    writeReg(address, MR11, page);

    return;
  }

  // Assume DDR4 is present
  if (offset < 512) {
    page = bitRead(offset, 8);  // DDR4 page
    if (getPageAddress() != page) {
      setDdr4PageAddress(page);
      eepromPageAddress = page;
    }
  }
}


/*  -=  Device settings functions =-  */

// Assign a new name
bool setName(String name) {

  for (uint8_t i = 0; i < name.length(); i++) {
    EEPROM.update(i, name[i]);
  }
  EEPROM.update(name.length(), 0);

  return name == getName();
}

// Get device's name
String getName() {

  char deviceNameChar[NAMELENGTH + 1];

  for (uint8_t i = 0; i < NAMELENGTH; i++) {
    deviceNameChar[i] = EEPROM.read(i);
  }
  // set last byte to zero
  deviceNameChar[NAMELENGTH] = 0;

  return deviceNameChar;
}

// Read device settings
bool getSettings(uint8_t name) {
  return bitRead(EEPROM.read(DEVICESETTINGS), name);
}

// Save device settings
bool saveSettings(uint8_t name, uint8_t value) {

  uint8_t currentSettings = EEPROM.read(DEVICESETTINGS);
  EEPROM.update(DEVICESETTINGS, bitWrite(currentSettings, name, value));

  return getSettings(name) == value;
}


/*  -=  I2C bus functions  =-  */

// Set I2C bus clock mode
bool setI2cClockMode(bool mode) {
  saveSettings(CLOCKMODE, mode ? FASTMODE : STDMODE);
  Wire.setClock(clock[mode]);

  return getI2cClockMode() == mode;
}

// Gets saved I2C clock mode (true=fast mode, false=std mode)
bool getI2cClockMode() {
  return getSettings(CLOCKMODE);
}

// Scans I2C bus range 80-87
uint8_t scanBus() {
  return scanBus(80, 87);
}

// Scans I2C bus specified range
uint8_t scanBus(uint8_t startAddress, uint8_t endAddress) {

  uint8_t totalAddresses = endAddress - startAddress;

  if (totalAddresses > 7) {
    return 0;
  }

  uint8_t response = 0;

  for (uint8_t i = 0; i <= totalAddresses; i++) {
    if (probeBusAddress(i + startAddress)) {
      response |= 1 << i;
    }
  }

  return response;
}

// Gets the number of devices on I2C bus
uint8_t getQuantity() {
  return bitCount(scanBus());
}

// Gets the number of bits in bitmask
uint8_t bitCount(uint8_t bitMask) {
  if (bitMask == 0) {
    return 0;
  }

  uint8_t quantity = 0;

  for (uint8_t i = 0; i <= 7; i++) {
    if (bitRead(bitMask, i)) {
      quantity++;
    }
  }

  return quantity;
}

// I2C monitor
void i2cMonitor() {

  if (cmdExecuting) {
    return;
  }

  bool i2cPause = false;

  // Slave address monitor
  if (!digitalRead(HV_EN) && !digitalRead(HV_FB)) {
    slaveCountCurrent = getQuantity();

    if (slaveCountCurrent != slaveCountLast) {
      uint8_t buffer[] = { ALERT, (uint8_t)(slaveCountCurrent < slaveCountLast ? SLAVEDEC : SLAVEINC) };
      PORT.write(buffer, sizeof(buffer));
      slaveCountLast = slaveCountCurrent;
      i2cPause = true;
    }
  }

  // I2C clock monitor
  i2cClockCurrent = getI2cClockMode();

  if (i2cClockCurrent != i2cClockLast) {
    uint8_t buffer[] = { ALERT, (uint8_t)(i2cClockCurrent < i2cClockLast ? CLOCKDEC : CLOCKINC) };
    PORT.write(buffer, sizeof(buffer));
    i2cClockLast = i2cClockCurrent;
  }

  // Hot plugged DDR5 isn't detected without this pause,
  // because PMIC behind SPD5 hub stays invisible to probeBusAddress()
  if (i2cPause) {
    delay(10);
  }

  PORT.flush();
}

// Control config pins
bool setConfigPin(uint8_t pin, bool state) {
  digitalWrite(pin, state);

  if (pin == SA1_EN) {

    uint64_t timeout = millis() + 10;

    while (millis() < timeout) {
      if (scanBus() & (state ? A1_MASK : ~A1_MASK)) {
        return true;
      }
    }

    return false;
  }

  return getConfigPin(pin) == state;
}

// Get config pin state
bool getConfigPin(uint8_t pin) {
  return pin == SA1_EN ? scanBus() & A1_MASK : digitalRead(pin);
}

// Reset config pins w/ feedback
bool resetPins() {
  return setHighVoltage(ConfigPin[HV_SWITCH].defaultState) &&
         setConfigPin(ConfigPin[SA1_SWITCH].name, ConfigPin[SA1_SWITCH].defaultState);
}

// Reset config pins w/o feedback
void resetPinsInternal() {
  for (uint8_t i = 0; i < pinCount; i++) {
    if (ConfigPin[i].mode == OUTPUT) {
      digitalWrite(ConfigPin[i].name, ConfigPin[i].defaultState);
    }
  }
}

// Get DDR5 offline mode
bool ddr5GetOfflineMode() {
  return ddr5Detect(80) && bitRead(readReg(80, MR48), 2);
}

// Tests if device address is present on I2C bus
bool probeBusAddress(uint8_t address) {
  Wire.beginTransmission(address);
  return Wire.endTransmission(false) == 0;
}

// Tests if device select code returns ACK (true), or NACK (false)
bool probeDeviceTypeId(uint8_t deviceSelectCode) {

  uint8_t status = 0;

  // Check the LSB of DSC, if it is 0 (write), then we need to write DNC address + DNC data
  bool writeBit = !bitRead(deviceSelectCode, 0);

  // Wire library uses 7 bit address, so we strip the LSB from the DSC by bitshifting right by 1
  uint8_t cmd = deviceSelectCode >> 1;

  Wire.beginTransmission(cmd);
  if (writeBit) {
    Wire.write(DNC);
    Wire.write(DNC);
  }
  status = Wire.endTransmission();

  if (writeBit) {
    return status == 0;
  }

  return Wire.requestFrom(cmd, (uint8_t)1) > 0;  // true when ACK is received after control byte
}

// DDR4 detection test (address)
bool ddr4Detect(uint8_t address) {
  if (!address) {
    return ddr4Detect();
  }

  return probeBusAddress(address) && ddr4Detect() && !ddr5Detect(address);
}

// DDR4 detection test (generic)
bool ddr4Detect() {
  // Only SPA0 is tested, RPA returns NACK after SPA1 regardless of RAM type
  setDdr4PageAddress(0);
  return getQuantity() > 0 && getPageAddress(true) == 0;
}

// DDR5 detection test (address)
bool ddr5Detect(uint8_t address) {

  if (!validateEepromAddress(address) ||
      !probeBusAddress(address) ||
      !probeBusAddress((address & 0b111) | PMIC)) {
    return false;
  }

  // Reset page to 0 (SPD5118-Y1B000NCG fix)
  writeReg(address, MR11, 0);
  
  if (readReg(address, MR0, false) == highByte(SPD5_TS)) {
    uint8_t mr1 = readReg(address, MR1, false);
    return mr1 == lowByte(SPD5_TS) || mr1 == lowByte(SPD5_NO);
  }

  return false;
}

// Validates EEPROM address
bool validateEepromAddress(uint8_t address) {
  return address >> 3 == 0b1010;
}

// Validates PMIC address
bool validatePmicAddress(uint8_t address) {
  return address >> 3 == PMIC >> 3;
}

// Restores device's default settings
bool factoryReset() {
  for (uint8_t i = 0; i <= 32; i++) {
    EEPROM.update(i, 0);
  }
  for (uint8_t i = 0; i <= 32; i++) {
    if (EEPROM.read(i) != 0) {
      return false;
    }
  }
  return true;
}