bootloader_protocol.hpp

Go to the documentation of this file.

 
#pragma once
#include "bootloader_utils.hpp"
#include <array>
#include <cstddef>
#include <cstdint>
 
namespace tmc9660 {
 
enum class BootloaderStatus : uint8_t {
  OK = 0,                
  CMD_NOT_FOUND = 1,     
  INVALID_ADDR = 3,      
  INVALID_VALUE = 4,     
  INVALID_BANK = 14,     
  BUSY = 15,             
  MEM_UNCONFIGURED = 17, 
  OTP_ERROR = 18,        
  SESSION_START = 19,    
  CMD_NOT_AVAILABLE = 20, 
  BOOTLOADER_RESUMED =
      21 
};
 
enum class BootloaderCommand : uint8_t {
  GET_INFO = 0,            
  GET_BANK = 8,            
  SET_BANK = 9,            
  GET_ADDRESS = 10,        
  SET_ADDRESS = 11,        
  READ_32 = 12,            
  READ_32_INC = 13,        
  READ_16 = 14,            
  READ_16_INC = 15,        
  READ_8 = 16,             
  READ_8_INC = 17,         
  WRITE_32 = 18,           
  WRITE_32_INC = 19,       
  WRITE_16 = 20,           
  WRITE_16_INC = 21,       
  WRITE_8 = 22,            
  WRITE_8_INC = 23,        
  NO_OP = 29,              
  OTP_LOAD = 30,           
  OTP_BURN = 31,           
  MEM_IS_CONFIGURED = 32,  
  MEM_IS_CONNECTED = 33,   
  FLASH_SEND_CMD = 36,     
  FLASH_ERASE_SECTOR = 37, 
  MEM_IS_BUSY = 40,        
  BOOTSTRAP_RS485 = 255    
};
 
enum class MemoryBank : uint8_t {
  RAM = 0,        
  OTP = 1,        
  SPI_FLASH = 2,  
  I2C_EEPROM = 3, 
  RESERVED = 4,   
  CONFIG = 5      
};
 
enum class InfoQuery : uint32_t {
  CHIP_TYPE = 0,       
  BL_VERSION = 1,      
  FEATURES = 2,        
  GIT_INFO = 12,       
  CHIP_VERSION = 13,   
  CHIP_FREQUENCY = 14, 
  CONFIG_MEM_START = 17,   
  CONFIG_MEM_SIZE = 18,    
  OTP_MEM_SIZE = 19,       
  I2C_MEM_SIZE = 20,       
  SPI_MEM_SIZE = 21,       
  PARTITION_VERSION = 22,  
  SPI_MEM_PARTITIONS = 25, 
  I2C_MEM_PARTITIONS = 26, 
  CHIP_VARIANT = 28        
};
 
struct BootloaderVersion {
  uint16_t major; 
  uint16_t minor; 
 
  static BootloaderVersion fromValue(uint32_t value) noexcept {
    BootloaderVersion v;
    v.major = static_cast<uint16_t>(value >> 16);
    v.minor = static_cast<uint16_t>(value & 0xFFFF);
    return v;
  }
};
 
struct BootloaderFeatures {
  bool sram_support; 
  bool rom;          
  bool otp;          
  bool spi_flash;    
  bool i2c_eeprom;   
 
  static BootloaderFeatures fromValue(uint32_t value) noexcept {
    BootloaderFeatures f;
    f.sram_support = (value & (1u << 0)) != 0;
    f.rom = (value & (1u << 1)) != 0;
    f.otp = (value & (1u << 2)) != 0;
    f.spi_flash = (value & (1u << 3)) != 0;
    f.i2c_eeprom = (value & (1u << 4)) != 0;
    return f;
  }
};
 
struct GitInfo {
  bool dirty;           
  uint32_t commit_hash; 
 
  static GitInfo fromValue(uint32_t value) noexcept {
    GitInfo g;
    g.dirty = (value & (1u << 28)) != 0;
    g.commit_hash = value & 0x0FFFFFFF;
    return g;
  }
};
 
struct PartitionVersion {
  uint8_t major; 
  uint8_t minor; 
 
  static PartitionVersion fromValue(uint32_t value) noexcept {
    PartitionVersion v;
    v.major = static_cast<uint8_t>((value >> 8) & 0xFF);
    v.minor = static_cast<uint8_t>(value & 0xFF);
    return v;
  }
};
 
struct OtpLoadResult {
  uint8_t errorCount; 
  uint8_t pageTag;    
 
  static OtpLoadResult fromValue(uint32_t value) noexcept {
    OtpLoadResult result;
    result.errorCount = static_cast<uint8_t>((value >> 8) & 0xFF);
    result.pageTag = static_cast<uint8_t>(value & 0xFF);
    return result;
  }
};
 
enum class OtpBurnError : int8_t {
  INVALID_PAGE = -1,          
  NO_MORE_BURNS = -2,         
  CHARGE_PUMP_FAILED = -3,    
  BURN_PROCEDURE_FAILED = -4, 
  CLOCK_SETUP_FAILED = -5,    
  CLOCK_RESTORE_FAILED = -6   
};
 
struct OtpBurnResult {
  bool isSuccess;               
  OtpBurnError errorCode;       
  const char* errorDescription; 
 
  static OtpBurnResult createSuccess() noexcept {
    OtpBurnResult result;
    result.isSuccess = true;
    result.errorCode = static_cast<OtpBurnError>(0);
    result.errorDescription = "Success";
    return result;
  }
 
  static OtpBurnResult createError(OtpBurnError code) noexcept {
    OtpBurnResult result;
    result.isSuccess = false;
    result.errorCode = code;
 
    switch (code) {
    case OtpBurnError::INVALID_PAGE:
      result.errorDescription = "Invalid OTP page number";
      break;
    case OtpBurnError::NO_MORE_BURNS:
      result.errorDescription = "Last OTP page burnt, no more burns possible";
      break;
    case OtpBurnError::CHARGE_PUMP_FAILED:
      result.errorDescription = "Setting up internal OTP charge pump failed";
      break;
    case OtpBurnError::BURN_PROCEDURE_FAILED:
      result.errorDescription = "The burn procedure failed";
      break;
    case OtpBurnError::CLOCK_SETUP_FAILED:
      result.errorDescription = "Internal clock setup for OTP operation failed";
      break;
    case OtpBurnError::CLOCK_RESTORE_FAILED:
      result.errorDescription = "Restoring original clock setup after OTP operation failed";
      break;
    default:
      result.errorDescription = "Unknown error";
      break;
    }
 
    return result;
  }
};
 
struct BootloaderCommandSPI {
  uint8_t command; 
  uint32_t value;  
 
  void toBuffer(std::array<uint8_t, 5>& out) const noexcept {
    out[0] = command;
    out[1] = static_cast<uint8_t>(value >> 24);
    out[2] = static_cast<uint8_t>(value >> 16);
    out[3] = static_cast<uint8_t>(value >> 8);
    out[4] = static_cast<uint8_t>(value);
  }
};
 
struct BootloaderCommandUART {
  uint8_t deviceAddr; 
  uint8_t command;    
  uint32_t value;     
 
  void toBuffer(std::array<uint8_t, 8>& out) const noexcept {
    out[0] = 0x55; // Sync byte
    out[1] = deviceAddr;
    out[2] = command;
    out[3] = static_cast<uint8_t>(value >> 24); // MSB first
    out[4] = static_cast<uint8_t>(value >> 16);
    out[5] = static_cast<uint8_t>(value >> 8);
    out[6] = static_cast<uint8_t>(value);
    out[7] = crc8Bootloader(out.data(), 7); // CRC over first 7 bytes
  }
};
 
struct BootloaderReplySPI {
  uint8_t status; 
  uint32_t value; 
 
  static BootloaderReplySPI fromBuffer(const std::array<uint8_t, 5>& in) noexcept {
    BootloaderReplySPI r;
    r.status = in[0];
    r.value = (static_cast<uint32_t>(in[1]) << 24) | (static_cast<uint32_t>(in[2]) << 16) |
              (static_cast<uint32_t>(in[3]) << 8) | static_cast<uint32_t>(in[4]);
    return r;
  }
 
  bool isOK() const noexcept {
    return status == static_cast<uint8_t>(BootloaderStatus::OK) ||
           status == static_cast<uint8_t>(BootloaderStatus::SESSION_START) ||
           status == static_cast<uint8_t>(BootloaderStatus::BOOTLOADER_RESUMED);
  }
 
  BootloaderStatus getStatus() const noexcept {
    return static_cast<BootloaderStatus>(status);
  }
};
 
struct BootloaderReplyUART {
  uint8_t hostAddr;   
  uint8_t deviceAddr; 
  uint8_t status;     
  uint32_t value;     
 
  static BootloaderReplyUART fromBuffer(const std::array<uint8_t, 8>& in) noexcept {
    BootloaderReplyUART r;
    // UART protocol: [HOST_ADDR] [DEVICE_ADDR] [STATUS] [VALUE(32)] [CRC8]
    // (No SYNC byte in reply, unlike the request which has 0x55 as first byte)
    r.hostAddr = in[0];
    r.deviceAddr = in[1];
    r.status = in[2];
    r.value = (static_cast<uint32_t>(in[3]) << 24) | // MSB first
              (static_cast<uint32_t>(in[4]) << 16) | (static_cast<uint32_t>(in[5]) << 8) |
              static_cast<uint32_t>(in[6]);
    // Note: in[7] is CRC8, should be verified
    return r;
  }
 
  bool verifyCRC(const std::array<uint8_t, 8>& in) const noexcept {
    uint8_t calculatedCRC = crc8Bootloader(in.data(), 7);
    return calculatedCRC == in[7];
  }
 
  bool isOK() const noexcept {
    return status == static_cast<uint8_t>(BootloaderStatus::OK);
  }
 
  BootloaderStatus getStatus() const noexcept {
    return static_cast<BootloaderStatus>(status);
  }
};
 
} // namespace tmc9660