1# This file describes eFuses for ESP32-C3 chip 2# 3# SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD 4# 5# SPDX-License-Identifier: GPL-2.0-or-later 6 7import binascii 8import struct 9import sys 10import time 11 12from bitstring import BitArray 13 14import esptool 15 16import reedsolo 17 18from .mem_definition import EfuseDefineBlocks, EfuseDefineFields, EfuseDefineRegisters 19from .. import base_fields 20from .. import util 21 22 23class EfuseBlock(base_fields.EfuseBlockBase): 24 def len_of_burn_unit(self): 25 # The writing register window is 8 registers for any blocks. 26 # len in bytes 27 return 8 * 4 28 29 def __init__(self, parent, param, skip_read=False): 30 parent.read_coding_scheme() 31 super(EfuseBlock, self).__init__(parent, param, skip_read=skip_read) 32 33 def apply_coding_scheme(self): 34 data = self.get_raw(from_read=False)[::-1] 35 if len(data) < self.len_of_burn_unit(): 36 add_empty_bytes = self.len_of_burn_unit() - len(data) 37 data = data + (b"\x00" * add_empty_bytes) 38 if self.get_coding_scheme() == self.parent.REGS.CODING_SCHEME_RS: 39 # takes 32 bytes 40 # apply RS encoding 41 rs = reedsolo.RSCodec(12) 42 # 32 byte of data + 12 bytes RS 43 encoded_data = rs.encode([x for x in data]) 44 words = struct.unpack("<" + "I" * 11, encoded_data) 45 # returns 11 words (8 words of data + 3 words of RS coding) 46 else: 47 # takes 32 bytes 48 words = struct.unpack("<" + ("I" * (len(data) // 4)), data) 49 # returns 8 words 50 return words 51 52 53class EspEfuses(base_fields.EspEfusesBase): 54 """ 55 Wrapper object to manage the efuse fields in a connected ESP bootloader 56 """ 57 58 debug = False 59 do_not_confirm = False 60 61 def __init__( 62 self, 63 esp, 64 skip_connect=False, 65 debug=False, 66 do_not_confirm=False, 67 extend_efuse_table=None, 68 ): 69 self.Blocks = EfuseDefineBlocks() 70 self.Fields = EfuseDefineFields(extend_efuse_table) 71 self.REGS = EfuseDefineRegisters 72 self.BURN_BLOCK_DATA_NAMES = self.Blocks.get_burn_block_data_names() 73 self.BLOCKS_FOR_KEYS = self.Blocks.get_blocks_for_keys() 74 self._esp = esp 75 self.debug = debug 76 self.do_not_confirm = do_not_confirm 77 if esp.CHIP_NAME != "ESP32-C3": 78 raise esptool.FatalError( 79 "Expected the 'esp' param for ESP32-C3 chip but got for '%s'." 80 % (esp.CHIP_NAME) 81 ) 82 if not skip_connect: 83 flags = self._esp.get_security_info()["flags"] 84 GET_SECURITY_INFO_FLAG_SECURE_DOWNLOAD_ENABLE = 1 << 2 85 if flags & GET_SECURITY_INFO_FLAG_SECURE_DOWNLOAD_ENABLE: 86 raise esptool.FatalError( 87 "Secure Download Mode is enabled. The tool can not read eFuses." 88 ) 89 self.blocks = [ 90 EfuseBlock(self, self.Blocks.get(block), skip_read=skip_connect) 91 for block in self.Blocks.BLOCKS 92 ] 93 if not skip_connect: 94 self.get_coding_scheme_warnings() 95 self.efuses = [EfuseField.convert(self, efuse) for efuse in self.Fields.EFUSES] 96 self.efuses += [ 97 EfuseField.convert(self, efuse) for efuse in self.Fields.KEYBLOCKS 98 ] 99 if skip_connect: 100 self.efuses += [ 101 EfuseField.convert(self, efuse) 102 for efuse in self.Fields.BLOCK2_CALIBRATION_EFUSES 103 ] 104 else: 105 if self["BLK_VERSION_MAJOR"].get() == 1: 106 self.efuses += [ 107 EfuseField.convert(self, efuse) 108 for efuse in self.Fields.BLOCK2_CALIBRATION_EFUSES 109 ] 110 self.efuses += [ 111 EfuseField.convert(self, efuse) for efuse in self.Fields.CALC 112 ] 113 114 def __getitem__(self, efuse_name): 115 """Return the efuse field with the given name""" 116 for e in self.efuses: 117 if efuse_name == e.name or any(x == efuse_name for x in e.alt_names): 118 return e 119 new_fields = False 120 for efuse in self.Fields.BLOCK2_CALIBRATION_EFUSES: 121 if efuse.name == efuse_name or any( 122 x == efuse_name for x in efuse.alt_names 123 ): 124 self.efuses += [ 125 EfuseField.convert(self, efuse) 126 for efuse in self.Fields.BLOCK2_CALIBRATION_EFUSES 127 ] 128 new_fields = True 129 if new_fields: 130 for e in self.efuses: 131 if efuse_name == e.name or any(x == efuse_name for x in e.alt_names): 132 return e 133 raise KeyError 134 135 def read_coding_scheme(self): 136 self.coding_scheme = self.REGS.CODING_SCHEME_RS 137 138 def print_status_regs(self): 139 print("") 140 self.blocks[0].print_block(self.blocks[0].err_bitarray, "err__regs", debug=True) 141 print( 142 "{:27} 0x{:08x}".format( 143 "EFUSE_RD_RS_ERR0_REG", self.read_reg(self.REGS.EFUSE_RD_RS_ERR0_REG) 144 ) 145 ) 146 print( 147 "{:27} 0x{:08x}".format( 148 "EFUSE_RD_RS_ERR1_REG", self.read_reg(self.REGS.EFUSE_RD_RS_ERR1_REG) 149 ) 150 ) 151 152 def efuse_controller_setup(self): 153 self.set_efuse_timing() 154 self.clear_pgm_registers() 155 self.wait_efuse_idle() 156 157 def write_efuses(self, block): 158 self.efuse_program(block) 159 return self.get_coding_scheme_warnings(silent=True) 160 161 def clear_pgm_registers(self): 162 self.wait_efuse_idle() 163 for r in range( 164 self.REGS.EFUSE_PGM_DATA0_REG, self.REGS.EFUSE_PGM_DATA0_REG + 32, 4 165 ): 166 self.write_reg(r, 0) 167 168 def wait_efuse_idle(self): 169 deadline = time.time() + self.REGS.EFUSE_BURN_TIMEOUT 170 while time.time() < deadline: 171 cmds = self.REGS.EFUSE_PGM_CMD | self.REGS.EFUSE_READ_CMD 172 if self.read_reg(self.REGS.EFUSE_CMD_REG) & cmds == 0: 173 if self.read_reg(self.REGS.EFUSE_CMD_REG) & cmds == 0: 174 # Due to a hardware error, we have to read READ_CMD again 175 # to make sure the efuse clock is normal. 176 # For PGM_CMD it is not necessary. 177 return 178 raise esptool.FatalError( 179 "Timed out waiting for Efuse controller command to complete" 180 ) 181 182 def efuse_program(self, block): 183 self.wait_efuse_idle() 184 self.write_reg(self.REGS.EFUSE_CONF_REG, self.REGS.EFUSE_WRITE_OP_CODE) 185 self.write_reg(self.REGS.EFUSE_CMD_REG, self.REGS.EFUSE_PGM_CMD | (block << 2)) 186 self.wait_efuse_idle() 187 self.clear_pgm_registers() 188 self.efuse_read() 189 190 def efuse_read(self): 191 self.wait_efuse_idle() 192 self.write_reg(self.REGS.EFUSE_CONF_REG, self.REGS.EFUSE_READ_OP_CODE) 193 # need to add a delay after triggering EFUSE_READ_CMD, as ROM loader checks some 194 # efuse registers after each command is completed 195 # if ENABLE_SECURITY_DOWNLOAD or DIS_DOWNLOAD_MODE is enabled by the current cmd, then we need to try to reconnect to the chip. 196 try: 197 self.write_reg( 198 self.REGS.EFUSE_CMD_REG, self.REGS.EFUSE_READ_CMD, delay_after_us=1000 199 ) 200 self.wait_efuse_idle() 201 except esptool.FatalError: 202 secure_download_mode_before = self._esp.secure_download_mode 203 204 try: 205 self._esp = self.reconnect_chip(self._esp) 206 except esptool.FatalError: 207 print("Can not re-connect to the chip") 208 if not self["DIS_DOWNLOAD_MODE"].get() and self[ 209 "DIS_DOWNLOAD_MODE" 210 ].get(from_read=False): 211 print( 212 "This is the correct behavior as we are actually burning " 213 "DIS_DOWNLOAD_MODE which disables the connection to the chip" 214 ) 215 print("DIS_DOWNLOAD_MODE is enabled") 216 print("Successful") 217 sys.exit(0) # finish without errors 218 raise 219 220 print("Established a connection with the chip") 221 if self._esp.secure_download_mode and not secure_download_mode_before: 222 print("Secure download mode is enabled") 223 if not self["ENABLE_SECURITY_DOWNLOAD"].get() and self[ 224 "ENABLE_SECURITY_DOWNLOAD" 225 ].get(from_read=False): 226 print( 227 "espefuse tool can not continue to work in Secure download mode" 228 ) 229 print("ENABLE_SECURITY_DOWNLOAD is enabled") 230 print("Successful") 231 sys.exit(0) # finish without errors 232 raise 233 234 def set_efuse_timing(self): 235 """Set timing registers for burning efuses""" 236 # Configure clock 237 apb_freq = self.get_crystal_freq() 238 if apb_freq != 40: 239 raise esptool.FatalError( 240 "The eFuse supports only xtal=40M (xtal was %d)" % apb_freq 241 ) 242 243 self.update_reg(self.REGS.EFUSE_DAC_CONF_REG, self.REGS.EFUSE_DAC_NUM_M, 0xFF) 244 self.update_reg( 245 self.REGS.EFUSE_DAC_CONF_REG, self.REGS.EFUSE_DAC_CLK_DIV_M, 0x28 246 ) 247 self.update_reg( 248 self.REGS.EFUSE_WR_TIM_CONF1_REG, self.REGS.EFUSE_PWR_ON_NUM_M, 0x3000 249 ) 250 self.update_reg( 251 self.REGS.EFUSE_WR_TIM_CONF2_REG, self.REGS.EFUSE_PWR_OFF_NUM_M, 0x190 252 ) 253 254 def get_coding_scheme_warnings(self, silent=False): 255 """Check if the coding scheme has detected any errors.""" 256 ret_fail = False 257 for block in self.blocks: 258 if block.id == 0: 259 words = [ 260 self.read_reg(self.REGS.EFUSE_RD_REPEAT_ERR0_REG + offs * 4) 261 for offs in range(5) 262 ] 263 block.err_bitarray.pos = 0 264 for word in reversed(words): 265 block.err_bitarray.overwrite(BitArray("uint:32=%d" % word)) 266 block.num_errors = block.err_bitarray.count(True) 267 block.fail = block.num_errors != 0 268 else: 269 addr_reg_f, fail_bit = self.REGS.BLOCK_FAIL_BIT[block.id] 270 if fail_bit is None: 271 block.fail = False 272 else: 273 block.fail = self.read_reg(addr_reg_f) & (1 << fail_bit) != 0 274 275 addr_reg_n, num_mask, num_offs = self.REGS.BLOCK_NUM_ERRORS[block.id] 276 if num_mask is None or num_offs is None: 277 block.num_errors = 0 278 else: 279 block.num_errors = ( 280 self.read_reg(addr_reg_n) >> num_offs 281 ) & num_mask 282 283 ret_fail |= block.fail 284 if not silent and (block.fail or block.num_errors): 285 print( 286 "Error(s) in BLOCK%d [ERRORS:%d FAIL:%d]" 287 % (block.id, block.num_errors, block.fail) 288 ) 289 if (self.debug or ret_fail) and not silent: 290 self.print_status_regs() 291 return ret_fail 292 293 def summary(self): 294 # TODO add support set_flash_voltage - "Flash voltage (VDD_SPI)" 295 return "" 296 297 298class EfuseField(base_fields.EfuseFieldBase): 299 @staticmethod 300 def convert(parent, efuse): 301 return { 302 "mac": EfuseMacField, 303 "keypurpose": EfuseKeyPurposeField, 304 "t_sensor": EfuseTempSensor, 305 "adc_tp": EfuseAdcPointCalibration, 306 "wafer": EfuseWafer, 307 }.get(efuse.class_type, EfuseField)(parent, efuse) 308 309 310class EfuseWafer(EfuseField): 311 def get(self, from_read=True): 312 hi_bits = self.parent["WAFER_VERSION_MINOR_HI"].get(from_read) 313 assert self.parent["WAFER_VERSION_MINOR_HI"].bit_len == 1 314 lo_bits = self.parent["WAFER_VERSION_MINOR_LO"].get(from_read) 315 assert self.parent["WAFER_VERSION_MINOR_LO"].bit_len == 3 316 return (hi_bits << 3) + lo_bits 317 318 def save(self, new_value): 319 raise esptool.FatalError("Burning %s is not supported" % self.name) 320 321 322class EfuseTempSensor(EfuseField): 323 def get(self, from_read=True): 324 value = self.get_bitstring(from_read) 325 sig = -1 if value[0] else 1 326 return sig * value[1:].uint * 0.1 327 328 329class EfuseAdcPointCalibration(EfuseField): 330 def get(self, from_read=True): 331 STEP_SIZE = 4 332 value = self.get_bitstring(from_read) 333 sig = -1 if value[0] else 1 334 return sig * value[1:].uint * STEP_SIZE 335 336 337class EfuseMacField(EfuseField): 338 def check_format(self, new_value_str): 339 if new_value_str is None: 340 raise esptool.FatalError( 341 "Required MAC Address in AA:CD:EF:01:02:03 format!" 342 ) 343 if new_value_str.count(":") != 5: 344 raise esptool.FatalError( 345 "MAC Address needs to be a 6-byte hexadecimal format " 346 "separated by colons (:)!" 347 ) 348 hexad = new_value_str.replace(":", "") 349 if len(hexad) != 12: 350 raise esptool.FatalError( 351 "MAC Address needs to be a 6-byte hexadecimal number " 352 "(12 hexadecimal characters)!" 353 ) 354 # order of bytearray = b'\xaa\xcd\xef\x01\x02\x03', 355 bindata = binascii.unhexlify(hexad) 356 # unicast address check according to 357 # https://tools.ietf.org/html/rfc7042#section-2.1 358 if esptool.util.byte(bindata, 0) & 0x01: 359 raise esptool.FatalError("Custom MAC must be a unicast MAC!") 360 return bindata 361 362 def check(self): 363 errs, fail = self.parent.get_block_errors(self.block) 364 if errs != 0 or fail: 365 output = "Block%d has ERRORS:%d FAIL:%d" % (self.block, errs, fail) 366 else: 367 output = "OK" 368 return "(" + output + ")" 369 370 def get(self, from_read=True): 371 if self.name == "CUSTOM_MAC": 372 mac = self.get_raw(from_read)[::-1] 373 else: 374 mac = self.get_raw(from_read) 375 return "%s %s" % (util.hexify(mac, ":"), self.check()) 376 377 def save(self, new_value): 378 def print_field(e, new_value): 379 print( 380 " - '{}' ({}) {} -> {}".format( 381 e.name, e.description, e.get_bitstring(), new_value 382 ) 383 ) 384 385 if self.name == "CUSTOM_MAC": 386 bitarray_mac = self.convert_to_bitstring(new_value) 387 print_field(self, bitarray_mac) 388 super(EfuseMacField, self).save(new_value) 389 else: 390 # Writing the BLOCK1 (MAC_SPI_8M_0) default MAC is not possible, 391 # as it's written in the factory. 392 raise esptool.FatalError("Writing Factory MAC address is not supported") 393 394 395# fmt: off 396class EfuseKeyPurposeField(EfuseField): 397 KEY_PURPOSES = [ 398 ("USER", 0, None, None, "no_need_rd_protect"), # User purposes (software-only use) 399 ("RESERVED", 1, None, None, "no_need_rd_protect"), # Reserved 400 ("XTS_AES_128_KEY", 4, None, "Reverse", "need_rd_protect"), # XTS_AES_128_KEY (flash/PSRAM encryption) 401 ("HMAC_DOWN_ALL", 5, None, None, "need_rd_protect"), # HMAC Downstream mode 402 ("HMAC_DOWN_JTAG", 6, None, None, "need_rd_protect"), # JTAG soft enable key (uses HMAC Downstream mode) 403 ("HMAC_DOWN_DIGITAL_SIGNATURE", 7, None, None, "need_rd_protect"), # Digital Signature peripheral key (uses HMAC Downstream mode) 404 ("HMAC_UP", 8, None, None, "need_rd_protect"), # HMAC Upstream mode 405 ("SECURE_BOOT_DIGEST0", 9, "DIGEST", None, "no_need_rd_protect"), # SECURE_BOOT_DIGEST0 (Secure Boot key digest) 406 ("SECURE_BOOT_DIGEST1", 10, "DIGEST", None, "no_need_rd_protect"), # SECURE_BOOT_DIGEST1 (Secure Boot key digest) 407 ("SECURE_BOOT_DIGEST2", 11, "DIGEST", None, "no_need_rd_protect"), # SECURE_BOOT_DIGEST2 (Secure Boot key digest) 408 ] 409# fmt: on 410 KEY_PURPOSES_NAME = [name[0] for name in KEY_PURPOSES] 411 DIGEST_KEY_PURPOSES = [name[0] for name in KEY_PURPOSES if name[2] == "DIGEST"] 412 413 def check_format(self, new_value_str): 414 # str convert to int: "XTS_AES_128_KEY" - > str(4) 415 # if int: 4 -> str(4) 416 raw_val = new_value_str 417 for purpose_name in self.KEY_PURPOSES: 418 if purpose_name[0] == new_value_str: 419 raw_val = str(purpose_name[1]) 420 break 421 if raw_val.isdigit(): 422 if int(raw_val) not in [p[1] for p in self.KEY_PURPOSES if p[1] > 0]: 423 raise esptool.FatalError("'%s' can not be set (value out of range)" % raw_val) 424 else: 425 raise esptool.FatalError("'%s' unknown name" % raw_val) 426 return raw_val 427 428 def need_reverse(self, new_key_purpose): 429 for key in self.KEY_PURPOSES: 430 if key[0] == new_key_purpose: 431 return key[3] == "Reverse" 432 433 def need_rd_protect(self, new_key_purpose): 434 for key in self.KEY_PURPOSES: 435 if key[0] == new_key_purpose: 436 return key[4] == "need_rd_protect" 437 438 def get(self, from_read=True): 439 for p in self.KEY_PURPOSES: 440 if p[1] == self.get_raw(from_read): 441 return p[0] 442 return "FORBIDDEN_STATE" 443 444 def get_name(self, raw_val): 445 for key in self.KEY_PURPOSES: 446 if key[1] == raw_val: 447 return key[0] 448 449 def save(self, new_value): 450 raw_val = int(self.check_format(str(new_value))) 451 str_new_value = self.get_name(raw_val) 452 if self.name == "KEY_PURPOSE_5" and str_new_value.startswith("XTS_AES"): 453 raise esptool.FatalError(f"{self.name} can not have {str_new_value} key due to a hardware bug (please see TRM for more details)") 454 return super(EfuseKeyPurposeField, self).save(raw_val) 455
