blob: 4e5f1ed521384c8cf1ca32c66328295f46c9ff09 [file] [log] [blame]
# Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
"""ChromeOS Firmware Utilities
This modules provides easy access to ChromeOS firmware.
To access the contents of a firmware image, use FimwareImage().
To access the flash chipset containing firmware, use Flashrom().
To get the content of (cacheable) firmware, use LoadMainFirmware() or
import collections
import logging
import re
import tempfile
import common
import fmap
# Global dict to cache firmware details: {target_name: (chip_id, file handle)}.
_g_firmware_details = {}
# Names to select target bus.
TARGET_MAIN = 'main'
TARGET_EC = 'ec'
# Types of named tuples
WpStatus = collections.namedtuple('WpStatus', 'enabled offset size')
FirmwareContent = collections.namedtuple('FirwmareContent', 'chip_id path')
class Flashrom(object):
"""Wrapper for calling system command flashrom(8)."""
# flashrom(8) command line parameters
_TARGET_MAP = {TARGET_MAIN: "-p internal:bus=spi",
TARGET_EC: "-p internal:bus=lpc"}
_WRITE_FLAGS = "--fast-verify"
def __init__(self, target=None):
self._target = target or TARGET_MAIN
def _InvokeCommand(self, param, ignore_status=False):
command = ' '.join(['flashrom', self._TARGET_MAP[self._target], param])
logging.debug('Flashrom._InvokeCommand: %s', command)
result = common.RunShellCmd(command)
if not (ignore_status or result.success):
raise IOError, "Failed in command: %s\n%s" % (command, result.stderr)
return result
def GetTarget(self):
"""Gets current target (bus) to access."""
return self._target
def SetTarget(self, target):
"""Sets current target (bus) to access."""
assert target in self.VALID_TARGETS, "Unknown target: %s" % target
self._target = target
def GetSize(self):
return int(self._InvokeCommand("--get-size").stdout.splitlines()[-1], 0)
def GetName(self):
"""Returns a key-value dict for chipset info, or None for any failure."""
results = self._InvokeCommand("--flash-name", ignore_status=True).stdout
match_list = re.findall(r'\b(\w+)="([^"]*)"', results)
return dict(match_list) if match_list else None
def Read(self, filename=None, sections=None):
"""Reads whole image from selected flash chipset.
filename: File name to receive image. None to use temporary file.
sections: List of sections to read. None to read whole image.
Image data read from flash chipset.
if filename is None:
with tempfile.NamedTemporaryFile(prefix='fw_%s_' % self._target) as f:
return self.Read(
sections_param = [name % '-i %s' for name in sections or []]
self._InvokeCommand("-r '%s' %s %s" % (filename, ' '.join(sections_param),
with open(filename, 'rb') as file_handle:
def Write(self, data=None, filename=None, sections=None):
"""Writes image into selected flash chipset.
data: Image data to write. None to write given file.
filename: File name of image to write if data is None.
sections: List of sections to write. None to write whole image.
assert (((data is not None) and (filename is None)) or
((data is None) and (filename is not None))), \
"Either data or filename should be None."
if data is not None:
with tempfile.NamedTemporaryFile(prefix='fw_%s_' % self._target) as f:
return self.Write(None,
sections_param = [('-i %s' % name) for name in (sections or [])]
self._InvokeCommand("-w '%s' %s %s" % (filename, ' '.join(sections_param),
def GetWriteProtectionStatus(self):
"""Gets write protection status from selected flash chipset.
Returns: A named tuple with (enabled, offset, size).
# flashrom(8) output: WP: status: 0x80
# WP: status.srp0: 1
# WP: write protect is %s. (disabled/enabled)
# WP: write protect range: start=0x%8x, len=0x%08x
results = self._InvokeCommand("--wp-status").stdout
status = re.findall(r'WP: write protect is (\w+)\.', results)
if len(status) != 1:
raise IOError, "Failed getting write protection status"
status = status[0]
if status not in ('enabled', 'disabled'):
raise ValueError, "Unknown write protection status: %s" % status
wp_range = re.findall(r'WP: write protect range: start=(\w+), len=(\w+)',
if len(wp_range) != 1:
raise IOError, "Failed getting write protection range"
wp_range = wp_range[0]
return WpStatus(True if status == 'enabled' else False,
int(wp_range[0], 0),
int(wp_range[1], 0))
def EnableWriteProtection(self, offset, size):
"""Enables write protection by specified range."""
self._InvokeCommand('--wp-range 0x%06X 0x%06X --wp-enable' % (offset, size))
# Try to verify write protection by attempting to disable it.
self._InvokeCommand('--wp-disable --wp-range 0 0', ignore_status=True)
# Verify the results
result = self.GetWriteProtectionStatus()
if ((not result.enabled) or (result.offset != offset) or
(result.size != size)):
raise IOError, "Failed to enabled write protection."
def DisableWriteProtection(self):
"""Tries to Disable whole write protection range and status."""
self._InvokeCommand('--wp-disable --wp-range 0 0')
result = self.GetWriteProtectionStatus()
if (result.enabled or (result.offset != 0) or (result.size != 0)):
raise IOError, "Failed to disable write protection."
class FirmwareImage(object):
"""Provides access to firmware image via FMAP sections."""
def __init__(self, image_source):
self._image = image_source;
self._fmap = fmap.fmap_decode(self._image)
self._areas = dict(
(entry['name'], [entry['offset'], entry['size']])
for entry in self._fmap['areas'])
def get_size(self):
"""Returns the size of associate firmware image."""
return len(self._image)
def has_section(self, name):
"""Returns if specified section is available in image."""
return name in self._areas
def get_section_area(self, name):
"""Returns the area (offset, size) information of given section."""
if not self.has_section(name):
raise ValueError('get_section_area: invalid section: %s' % name)
return self._areas[name]
def get_section(self, name):
"""Returns the content of specified section."""
area = self.get_section_area(name)
return self._image[area[0]:(area[0] + area[1])]
def get_section_offset(self, name):
area = self.get_section_area(name)
return self._image[area[0]:(area[0] + area[1])]
def put_section(self, name, value):
"""Updates content of specified section in image."""
area = self.get_section_area(name)
if len(value) != area[1]:
raise ValueError("Value size (%d) does not fit into section (%s, %d)" %
(len(value), name, area[1]))
self._image = (self._image[0:area[0]] +
value +
self._image[(area[0] + area[1]):])
return True
def get_fmap_blob(self):
"""Returns the re-encoded fmap blob from firmware image."""
return fmap.fmap_encode(self._fmap)
def LoadFirmware(target):
"""Returns the chipset ID and path to a file containing firmware data.
Runs flashrom twice. First probe for the chip_id. Then, if a chip
is found, dump the contents of flash into a file.
target: Which target to access. For example TARGET_MAIN or TARGET_EC.
FirmwareContent with chipset ID and file path. If given target does not
exist, both ID and path are None.
if target in _g_firmware_details:
chip_id, fw_file = _g_firmware_details[target]
return FirmwareContent(chip_id,
flashrom = Flashrom(target)
info = flashrom.GetName()
chip_id = ' '.join([info['vendor'], info['name']]) if info else None
if chip_id is not None:
fw_file = tempfile.NamedTemporaryFile(prefix='fw_%s_' % target)
_g_firmware_details[target] = (chip_id, fw_file)
return FirmwareContent(chip_id, if fw_file else None)
def LoadEcFirmware():
"""Returns flashrom data from Embedded Controller chipset."""
return LoadFirmware(TARGET_EC)
def LoadMainFirmware():
"""Returns flashrom data from main firmware (also known as BIOS)."""
return LoadFirmware(TARGET_MAIN)