diff options
Diffstat (limited to 'bindings/rust/libflashrom/src/lib.rs')
| -rw-r--r-- | bindings/rust/libflashrom/src/lib.rs | 1124 |
1 files changed, 1124 insertions, 0 deletions
diff --git a/bindings/rust/libflashrom/src/lib.rs b/bindings/rust/libflashrom/src/lib.rs new file mode 100644 index 000000000..3f3fbc076 --- /dev/null +++ b/bindings/rust/libflashrom/src/lib.rs @@ -0,0 +1,1124 @@ +/* + * This file is part of the flashrom project. + * + * Copyright (C) 2022 The Chromium OS Authors + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + */ + +//! # libflashrom +//! +//! The `libflashrom` library is a rust FFI binding to the flashrom library. +//! libflashrom can be used to read write and modify some settings of flash chips. +//! The library closely follows the libflashrom C API, but exports a `safe` interface +//! including automatic resource management and forced error checking. +//! +//! libflashrom does not support threading, all usage of this library must occur on one thread. +//! +//! Most of the library functionality is defined on the [`Chip`] type. +//! +//! Example: +//! +//! ``` +//! use libflashrom::*; +//! let mut chip = Chip::new( +//! Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap(), +//! Some("W25Q128.V") +//! ).unwrap(); +//! let mut buf = chip.image_read(None).unwrap(); +//! buf[0] = 0xFE; +//! chip.image_write(&mut buf, None).unwrap(); +//! ``` + +use once_cell::sync::Lazy; +use regex::Regex; +use std::error; +use std::ffi::c_void; +use std::ffi::CStr; +use std::ffi::CString; +use std::fmt; +use std::io::Write; +use std::ptr::null; +use std::ptr::null_mut; +use std::ptr::NonNull; +use std::sync::Mutex; +use std::sync::Once; + +pub use libflashrom_sys::{ + flashrom_log_level, FLASHROM_MSG_DEBUG, FLASHROM_MSG_DEBUG2, FLASHROM_MSG_ERROR, + FLASHROM_MSG_INFO, FLASHROM_MSG_SPEW, FLASHROM_MSG_WARN, +}; + +pub use libflashrom_sys::flashrom_wp_mode; + +// libflashrom uses (start, len) or inclusive [start, end] for ranges. +// This type exists to rust RangeBounds types to a convenient internal format. +#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] +struct RangeInternal { + start: usize, + len: usize, +} + +/// The type returned for write protect and layout queries +pub type Range = std::ops::Range<usize>; + +impl<T> From<T> for RangeInternal +where + T: std::ops::RangeBounds<usize>, +{ + fn from(range: T) -> Self { + let start = match range.start_bound() { + std::ops::Bound::Included(start) => *start, + std::ops::Bound::Excluded(start) => *start + 1, + std::ops::Bound::Unbounded => 0, + }; + RangeInternal { + start, + len: match range.end_bound() { + std::ops::Bound::Included(end) => *end - start + 1, + std::ops::Bound::Excluded(end) => *end - start, + std::ops::Bound::Unbounded => usize::MAX - start, + }, + } + } +} + +impl RangeInternal { + // inclusive end for libflashrom + fn end(&self) -> usize { + self.start + self.len - 1 + } +} + +// log_c is set to be the callback at [`Programmer`] init. It deals with va_list and calls log_rust. +// log_rust calls a user defined function, or by default log_eprint. +// log_eprint just writes to stderr. +extern "C" { + fn set_log_callback(); + // Modifying and reading current_level is not thread safe, but neither is + // the libflashrom implementation, so we shouldnt be using threads anyway. + static mut current_level: libflashrom_sys::flashrom_log_level; +} + +/// Callers can use this function to log to the [`Logger`] they have set via [`set_log_level`] +/// +/// However from rust it is likely easier to call the [`Logger`] directly. +#[no_mangle] +pub extern "C" fn log_rust( + level: libflashrom_sys::flashrom_log_level, + format: &std::os::raw::c_char, +) { + // Because this function is called from C, it must not panic. + // SAFETY: log_c always provides a non null ptr to a null terminated string + // msg does not outlive format. + let msg = unsafe { CStr::from_ptr(format) }.to_string_lossy(); + // Locking can fail if a thread panics while holding the lock. + match LOG_FN.lock() { + Ok(g) => (*g)(level, msg.as_ref()), + Err(_) => eprintln!("ERROR: libflashrom log failure to lock function"), + }; +} + +fn log_eprint(_level: libflashrom_sys::flashrom_log_level, msg: &str) { + // Because this function is called from C, it must not panic. + // Ignore the error. + let _ = std::io::stderr().write_all(msg.as_bytes()); +} + +// Can't directly atexit(flashrom_shutdown) because it is unsafe +extern "C" fn shutdown_wrapper() { + unsafe { + libflashrom_sys::flashrom_shutdown(); + } +} + +/// A callback to log flashrom messages. This must not panic. +pub type Logger = fn(libflashrom_sys::flashrom_log_level, &str); + +static LOG_FN: Lazy<Mutex<Logger>> = Lazy::new(|| Mutex::new(log_eprint)); + +/// Set the maximum log message level that will be passed to [`Logger`] +/// +/// log_rust and therefore the provided [`Logger`] will only be called for messages +/// greater or equal to the provided priority. +/// +/// ``` +/// use libflashrom::set_log_level; +/// use libflashrom::FLASHROM_MSG_SPEW; +/// // Disable logging. +/// set_log_level(None); +/// // Log all messages at priority FLASHROM_MSG_SPEW and above. +/// set_log_level(Some(FLASHROM_MSG_SPEW)); +/// ``` +pub fn set_log_level(level: Option<libflashrom_sys::flashrom_log_level>) { + // SAFETY: current_level is only read by log_c, in this thread. + match level { + Some(level) => unsafe { current_level = level + 1 }, + None => unsafe { current_level = 0 }, + }; +} + +/// Set a [`Logger`] logging callback function +/// +/// Provided function must not panic, as it is called from C. +pub fn set_log_function(logger: Logger) { + *LOG_FN.lock().unwrap() = logger; +} + +/// A type holding the error code returned by libflashrom and the function that returned the error. +/// +/// The error codes returned from each function differ in meaning, see libflashrom.h +#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] +pub struct ErrorCode { + function: &'static str, + code: i32, +} + +impl fmt::Display for ErrorCode { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "libflashrom: {} returned {}", self.function, self.code) + } +} + +impl error::Error for ErrorCode {} + +impl From<ErrorCode> for String { + fn from(e: ErrorCode) -> Self { + format!("{}", e) + } +} + +/// Errors from initialising libflashrom or a [`Programmer`] +#[derive(Clone, Debug, Eq, PartialEq)] +pub enum InitError { + DuplicateInit, + FlashromInit(ErrorCode), + InvalidName(std::ffi::NulError), + ProgrammerInit(ErrorCode), +} + +impl fmt::Display for InitError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{:?}", self) + } +} + +impl error::Error for InitError {} + +impl From<InitError> for String { + fn from(e: InitError) -> Self { + format!("{:?}", e) + } +} + +impl From<std::ffi::NulError> for InitError { + fn from(err: std::ffi::NulError) -> InitError { + InitError::InvalidName(err) + } +} + +/// Errors from probing a [`Chip`] +#[derive(Clone, Debug, Eq, PartialEq)] +pub enum ChipInitError { + InvalidName(std::ffi::NulError), + NoChipError, + MultipleChipsError, + ProbeError, +} + +impl fmt::Display for ChipInitError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{:?}", self) + } +} + +impl error::Error for ChipInitError {} + +impl From<ChipInitError> for String { + fn from(e: ChipInitError) -> Self { + format!("{:?}", e) + } +} + +impl From<std::ffi::NulError> for ChipInitError { + fn from(err: std::ffi::NulError) -> ChipInitError { + ChipInitError::InvalidName(err) + } +} + +#[derive(Clone, Debug, Eq, PartialEq)] +pub enum RegionError { + ErrorCode(ErrorCode), + InvalidName(std::ffi::NulError), +} + +impl fmt::Display for RegionError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{:?}", self) + } +} + +impl error::Error for RegionError {} + +impl From<RegionError> for String { + fn from(e: RegionError) -> Self { + format!("{:?}", e) + } +} + +impl From<std::ffi::NulError> for RegionError { + fn from(err: std::ffi::NulError) -> RegionError { + RegionError::InvalidName(err) + } +} + +#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] +pub struct ParseLayoutError(String); + +impl fmt::Display for ParseLayoutError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{:?}", self) + } +} + +impl error::Error for ParseLayoutError {} + +impl From<ParseLayoutError> for String { + fn from(e: ParseLayoutError) -> Self { + format!("{:?}", e) + } +} + +/// A translation of the flashrom_wp_result type +/// +/// WpOK is omitted, as it is not an error. +/// WpErrUnknown is used for an unknown error type. +/// Keep this list in sync with libflashrom.h +#[derive(Clone, Debug, Eq, Hash, PartialEq)] +pub enum WPError { + WpErrChipUnsupported, + WpErrOther, + WpErrReadFailed, + WpErrWriteFailed, + WpErrVerifyFailed, + WpErrRangeUnsupported, + WpErrModeUnsupported, + WpErrRangeListUnavailable, + WpErrUnsupportedState, + WpErrUnknown(libflashrom_sys::flashrom_wp_result), +} + +impl From<libflashrom_sys::flashrom_wp_result> for WPError { + fn from(e: libflashrom_sys::flashrom_wp_result) -> Self { + assert!(e != libflashrom_sys::flashrom_wp_result::FLASHROM_WP_OK); + match e { + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_CHIP_UNSUPPORTED => { + WPError::WpErrChipUnsupported + } + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_OTHER => WPError::WpErrOther, + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_READ_FAILED => { + WPError::WpErrReadFailed + } + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_WRITE_FAILED => { + WPError::WpErrWriteFailed + } + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_VERIFY_FAILED => { + WPError::WpErrVerifyFailed + } + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_RANGE_UNSUPPORTED => { + WPError::WpErrRangeUnsupported + } + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_MODE_UNSUPPORTED => { + WPError::WpErrModeUnsupported + } + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_RANGE_LIST_UNAVAILABLE => { + WPError::WpErrRangeListUnavailable + } + libflashrom_sys::flashrom_wp_result::FLASHROM_WP_ERR_UNSUPPORTED_STATE => { + WPError::WpErrUnsupportedState + } + _ => WPError::WpErrUnknown(e), // this could also be a panic + } + } +} + +impl fmt::Display for WPError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{:?}", self) + } +} + +impl error::Error for WPError {} + +impl From<WPError> for String { + fn from(e: WPError) -> Self { + format!("{:?}", e) + } +} + +/// Return a rust sanitised string derived from flashrom_version_info. +pub fn flashrom_version_info() -> Option<String> { + let p = unsafe { libflashrom_sys::flashrom_version_info() }; + if p.is_null() { + None + } else { + // SAFETY: flashrom_version_info returns a global `const char flashrom_version[]` + // derived from `-DFLASHROM_VERSION`, this is not guaranteed to be + // null terminated, but is in a normal build. + Some(unsafe { CStr::from_ptr(p) }.to_string_lossy().into_owned()) + } +} + +/// Structure for an initialised flashrom_programmer +// flashrom_programmer_init returns a pointer accepted by flashrom_flash_probe +// but this is not implemented at time of writing. When implemented the pointer +// can be stored here. +#[derive(Debug)] +pub struct Programmer {} + +/// Structure for an initialised flashrom chip, or flashrom_flashctx +// As returned by flashrom_flash_probe +// The layout is owned here as the chip only stores a pointer when a layout is set. +#[derive(Debug)] +pub struct Chip { + ctx: NonNull<libflashrom_sys::flashrom_flashctx>, + _programmer: Programmer, + layout: Option<Layout>, +} + +impl Programmer { + /// Initialise libflashrom and a programmer + /// + /// See libflashrom.h flashrom_programmer_init for argument documentation. + /// + /// Panics: + /// + /// If this libflashrom implementation returns a programmer pointer. + pub fn new( + programmer_name: &str, + programmer_options: Option<&str>, + ) -> Result<Programmer, InitError> { + static ONCE: Once = Once::new(); + if ONCE.is_completed() { + // Flashrom does not currently support concurrent programmers + // Flashrom also does not currently support initialising a second programmer after a first has been initialised. + // This is used to warn the user if they try to initialise a second programmer. + return Err(InitError::DuplicateInit); + } + ONCE.call_once(|| {}); + + static INIT_RES: Lazy<Result<(), InitError>> = Lazy::new(|| { + unsafe { set_log_callback() }; + // always perform_selfcheck + let res = unsafe { libflashrom_sys::flashrom_init(1) }; + if res == 0 { + let res = unsafe { libc::atexit(shutdown_wrapper) }; + if res == 0 { + Ok(()) + } else { + unsafe { libflashrom_sys::flashrom_shutdown() }; + Err(InitError::FlashromInit(ErrorCode { + function: "atexit", + code: res, + })) + } + } else { + Err(InitError::FlashromInit(ErrorCode { + function: "flashrom_init", + code: res, + })) + } + }); + (*INIT_RES).clone()?; + + let mut programmer: *mut libflashrom_sys::flashrom_programmer = null_mut(); + let programmer_name = CString::new(programmer_name)?; + let programmer_options = match programmer_options { + Some(programmer_options) => Some(CString::new(programmer_options)?), + None => None, + }; + let res = unsafe { + libflashrom_sys::flashrom_programmer_init( + &mut programmer, + programmer_name.as_ptr(), + programmer_options.as_ref().map_or(null(), |x| x.as_ptr()), + ) + }; + if res != 0 { + Err(InitError::ProgrammerInit(ErrorCode { + function: "flashrom_programmer_init", + code: res, + })) + } else if !programmer.is_null() { + panic!("flashrom_programmer_init returning a programmer pointer is not supported") + } else { + Ok(Programmer {}) + } + } +} + +impl Drop for Programmer { + fn drop(&mut self) { + unsafe { + libflashrom_sys::flashrom_programmer_shutdown(null_mut()); + } + } +} + +impl Chip { + /// Probe for a chip + /// + /// See libflashrom.h flashrom_flash_probe for argument documentation. + pub fn new(programmer: Programmer, chip_name: Option<&str>) -> Result<Chip, ChipInitError> { + let mut flash_ctx: *mut libflashrom_sys::flashrom_flashctx = null_mut(); + let chip_name = match chip_name { + Some(chip_name) => Some(CString::new(chip_name)?), + None => None, + }; + match unsafe { + libflashrom_sys::flashrom_flash_probe( + &mut flash_ctx, + null(), + chip_name.as_ref().map_or(null(), |x| x.as_ptr()), + ) + } { + 0 => Ok(Chip { + ctx: NonNull::new(flash_ctx).expect("flashrom_flash_probe returned null"), + _programmer: programmer, + layout: None, + }), + 3 => Err(ChipInitError::MultipleChipsError), + 2 => Err(ChipInitError::NoChipError), + _ => Err(ChipInitError::ProbeError), + } + } + + pub fn get_size(&self) -> usize { + unsafe { libflashrom_sys::flashrom_flash_getsize(self.ctx.as_ref()) } + } + + /// Read the write protect config of this [`Chip`] + pub fn get_wp(&mut self) -> std::result::Result<WriteProtectCfg, WPError> { + let mut cfg = WriteProtectCfg::new()?; + let res = + unsafe { libflashrom_sys::flashrom_wp_read_cfg(cfg.wp.as_mut(), self.ctx.as_mut()) }; + if res != libflashrom_sys::flashrom_wp_result::FLASHROM_WP_OK { + return Err(res.into()); + } + Ok(cfg) + } + + /// Set the write protect config of this [`Chip`] + pub fn set_wp(&mut self, wp: &WriteProtectCfg) -> std::result::Result<(), WPError> { + let res = + unsafe { libflashrom_sys::flashrom_wp_write_cfg(self.ctx.as_mut(), wp.wp.as_ref()) }; + if res != libflashrom_sys::flashrom_wp_result::FLASHROM_WP_OK { + return Err(res.into()); + } + Ok(()) + } + + /// Read the write protect ranges of this [`Chip`] + /// + /// # Panics + /// + /// Panics if flashrom_wp_get_available_ranges returns FLASHROM_WP_OK and a NULL pointer. + pub fn get_wp_ranges(&mut self) -> std::result::Result<Vec<Range>, WPError> { + let mut ranges: *mut libflashrom_sys::flashrom_wp_ranges = null_mut(); + let res = unsafe { + libflashrom_sys::flashrom_wp_get_available_ranges(&mut ranges, self.ctx.as_mut()) + }; + if res != libflashrom_sys::flashrom_wp_result::FLASHROM_WP_OK { + return Err(res.into()); + } + let ranges = WriteProtectRanges { + ranges: NonNull::new(ranges).expect("flashrom_wp_get_available_ranges returned null"), + }; + + let count = + unsafe { libflashrom_sys::flashrom_wp_ranges_get_count(ranges.ranges.as_ref()) }; + let mut ret = Vec::with_capacity(count); + for index in 0..count { + let mut start = 0; + let mut len = 0; + let res = unsafe { + libflashrom_sys::flashrom_wp_ranges_get_range( + &mut start, + &mut len, + ranges.ranges.as_ref(), + // TODO: fix after https://review.coreboot.org/c/flashrom/+/64996 + index + .try_into() + .expect("flashrom_wp_ranges_get_count does not fit in a u32"), + ) + }; + if res != libflashrom_sys::flashrom_wp_result::FLASHROM_WP_OK { + return Err(res.into()); + } + ret.push(start..(start + len)) + } + Ok(ret) + } + + /// Returns the layout read from the fmap of this [`Chip`] + /// + /// # Panics + /// + /// Panics if flashrom_layout_read_fmap_from_rom returns FLASHROM_WP_OK and a NULL pointer. + pub fn layout_read_fmap_from_rom(&mut self) -> std::result::Result<Layout, ErrorCode> { + let mut layout: *mut libflashrom_sys::flashrom_layout = null_mut(); + let err = unsafe { + libflashrom_sys::flashrom_layout_read_fmap_from_rom( + &mut layout, + self.ctx.as_mut(), + 0, + self.get_size(), + ) + }; + if err != 0 { + return Err(ErrorCode { + function: "flashrom_layout_read_fmap_from_rom", + code: err, + }); + } + Ok(Layout { + layout: NonNull::new(layout).expect("flashrom_layout_read_fmap_from_rom returned null"), + }) + } + + /// Sets the layout of this [`Chip`] + /// + /// [`Chip`] takes ownership of Layout to ensure it is not released before the [`Chip`]. + fn set_layout(&mut self, layout: Layout) { + unsafe { libflashrom_sys::flashrom_layout_set(self.ctx.as_mut(), layout.layout.as_ref()) }; + self.layout = Some(layout) + } + + fn unset_layout(&mut self) -> Option<Layout> { + unsafe { libflashrom_sys::flashrom_layout_set(self.ctx.as_mut(), null()) }; + self.layout.take() + } + + /// Read the whole [`Chip`], or a portion specified in a Layout + pub fn image_read( + &mut self, + layout: Option<Layout>, + ) -> std::result::Result<Vec<u8>, ErrorCode> { + if let Some(layout) = layout { + self.set_layout(layout); + } + let len = self.get_size(); + let mut buf = vec![0; len]; + let res = unsafe { + libflashrom_sys::flashrom_image_read( + self.ctx.as_mut(), + buf.as_mut_ptr() as *mut c_void, + len, + ) + }; + self.unset_layout(); + + if res == 0 { + Ok(buf) + } else { + Err(ErrorCode { + function: "flashrom_image_read", + code: res, + }) + } + } + + /// Write the whole [`Chip`], or a portion specified in a Layout + pub fn image_write( + &mut self, + buf: &mut [u8], + layout: Option<Layout>, + ) -> std::result::Result<(), ErrorCode> { + if let Some(layout) = layout { + self.set_layout(layout); + } + let res = unsafe { + libflashrom_sys::flashrom_image_write( + self.ctx.as_mut(), + buf.as_mut_ptr() as *mut c_void, + buf.len(), + null(), + ) + }; + self.unset_layout(); + + if res == 0 { + Ok(()) + } else { + Err(ErrorCode { + function: "flashrom_image_write", + code: res, + }) + } + } + + /// Verify the whole [`Chip`], or a portion specified in a Layout + pub fn image_verify( + &mut self, + buf: &[u8], + layout: Option<Layout>, + ) -> std::result::Result<(), ErrorCode> { + if let Some(layout) = layout { + self.set_layout(layout); + } + let res = unsafe { + libflashrom_sys::flashrom_image_verify( + self.ctx.as_mut(), + buf.as_ptr() as *const c_void, + buf.len(), + ) + }; + self.unset_layout(); + + if res == 0 { + Ok(()) + } else { + Err(ErrorCode { + function: "flashrom_image_verify", + code: res, + }) + } + } + + /// Erase the whole [`Chip`] + pub fn erase(&mut self) -> std::result::Result<(), ErrorCode> { + let res = unsafe { libflashrom_sys::flashrom_flash_erase(self.ctx.as_mut()) }; + if res == 0 { + Ok(()) + } else { + Err(ErrorCode { + function: "flashrom_flash_erase", + code: res, + }) + } + } +} + +impl Drop for Chip { + fn drop(&mut self) { + unsafe { + libflashrom_sys::flashrom_flash_release(self.ctx.as_mut()); + } + } +} + +/// Structure for an initialised flashrom_wp_cfg +#[derive(Debug)] +pub struct WriteProtectCfg { + wp: NonNull<libflashrom_sys::flashrom_wp_cfg>, +} + +impl WriteProtectCfg { + /// Create an empty [`WriteProtectCfg`] + /// + /// # Panics + /// + /// Panics if flashrom_wp_cfg_new returns FLASHROM_WP_OK and a NULL pointer. + pub fn new() -> std::result::Result<WriteProtectCfg, WPError> { + let mut cfg: *mut libflashrom_sys::flashrom_wp_cfg = null_mut(); + let res = unsafe { libflashrom_sys::flashrom_wp_cfg_new(&mut cfg) }; + if res != libflashrom_sys::flashrom_wp_result::FLASHROM_WP_OK { + return Err(res.into()); + } + Ok(WriteProtectCfg { + wp: NonNull::new(cfg).expect("flashrom_wp_cfg_new returned null"), + }) + } + + pub fn get_mode(&self) -> libflashrom_sys::flashrom_wp_mode { + unsafe { libflashrom_sys::flashrom_wp_get_mode(self.wp.as_ref()) } + } + + pub fn set_mode(&mut self, mode: libflashrom_sys::flashrom_wp_mode) { + unsafe { libflashrom_sys::flashrom_wp_set_mode(self.wp.as_mut(), mode) } + } + + pub fn get_range(&self) -> Range { + let mut start = 0; + let mut len = 0; + unsafe { libflashrom_sys::flashrom_wp_get_range(&mut start, &mut len, self.wp.as_ref()) }; + start..(start + len) + } + + pub fn set_range<T>(&mut self, range: T) + where + T: std::ops::RangeBounds<usize>, + { + let range: RangeInternal = range.into(); + unsafe { libflashrom_sys::flashrom_wp_set_range(self.wp.as_mut(), range.start, range.len) } + } +} + +impl Drop for WriteProtectCfg { + fn drop(&mut self) { + unsafe { + libflashrom_sys::flashrom_wp_cfg_release(self.wp.as_mut()); + } + } +} + +impl fmt::Display for WriteProtectCfg { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "range:{:?} mode:{:?}", self.get_range(), self.get_mode()) + } +} + +#[derive(Debug)] +struct WriteProtectRanges { + ranges: NonNull<libflashrom_sys::flashrom_wp_ranges>, +} + +impl WriteProtectRanges {} + +impl Drop for WriteProtectRanges { + fn drop(&mut self) { + unsafe { + libflashrom_sys::flashrom_wp_ranges_release(self.ranges.as_mut()); + } + } +} + +/// Structure for an initialised flashrom_layout +#[derive(Debug)] +pub struct Layout { + layout: NonNull<libflashrom_sys::flashrom_layout>, +} + +impl Layout { + /// Create an empty [`Layout`] + /// + /// # Panics + /// + /// Panics if flashrom_layout_new returns 0 and a NULL pointer. + pub fn new() -> std::result::Result<Layout, ErrorCode> { + let mut layout: *mut libflashrom_sys::flashrom_layout = null_mut(); + let err = unsafe { libflashrom_sys::flashrom_layout_new(&mut layout) }; + if err != 0 { + Err(ErrorCode { + function: "flashrom_layout_new", + code: err, + }) + } else { + Ok(Layout { + layout: NonNull::new(layout).expect("flashrom_layout_new returned null"), + }) + } + } + + /// Add a region to the [`Layout`] + /// + /// Not the region will not be 'included', include_region must be called to include the region. + /// + /// # Errors + /// + /// This function will return an error if the region is not a valid CString, + /// or if libflashrom returns an error. + pub fn add_region<T>(&mut self, region: &str, range: T) -> std::result::Result<(), RegionError> + where + T: std::ops::RangeBounds<usize>, + { + let range: RangeInternal = range.into(); + let err = { + let region = CString::new(region)?; + unsafe { + libflashrom_sys::flashrom_layout_add_region( + self.layout.as_mut(), + range.start, + range.end(), + region.as_ptr(), + ) + } + }; + + if err != 0 { + Err(RegionError::ErrorCode(ErrorCode { + function: "flashrom_layout_add_region", + code: err, + })) + } else { + Ok(()) + } + } + + /// Include a region + /// + /// # Errors + /// + /// This function will return an error if the region is not a valid CString, + /// or if libflashrom returns an error. + pub fn include_region(&mut self, region: &str) -> std::result::Result<(), RegionError> { + let err = { + let region = CString::new(region)?; + unsafe { + libflashrom_sys::flashrom_layout_include_region( + self.layout.as_mut(), + region.as_ptr(), + ) + } + }; + if err != 0 { + Err(RegionError::ErrorCode(ErrorCode { + function: "flashrom_layout_include_region", + code: err, + })) + } else { + Ok(()) + } + } + + /// Exclude a region + /// + /// # Errors + /// + /// This function will return an error if the region is not a valid CString, + /// or if libflashrom returns an error. + pub fn exclude_region(&mut self, region: &str) -> std::result::Result<(), RegionError> { + let err = { + let region = CString::new(region)?; + unsafe { + libflashrom_sys::flashrom_layout_exclude_region( + self.layout.as_mut(), + region.as_ptr(), + ) + } + }; + if err != 0 { + Err(RegionError::ErrorCode(ErrorCode { + function: "flashrom_layout_exclude_region", + code: err, + })) + } else { + Ok(()) + } + } + + /// Get the [`Range`] for the given region + /// + /// # Errors + /// + /// This function will return an error if the region is not a valid CString, + /// or if libflashrom returns an error. + pub fn get_region_range(&mut self, region: &str) -> std::result::Result<Range, RegionError> { + let mut start: std::os::raw::c_uint = 0; + let mut len: std::os::raw::c_uint = 0; + let err = { + let region = CString::new(region)?; + unsafe { + libflashrom_sys::flashrom_layout_get_region_range( + self.layout.as_mut(), + region.as_ptr(), + &mut start, + &mut len, + ) + } + }; + if err != 0 { + Err(RegionError::ErrorCode(ErrorCode { + function: "flashrom_layout_get_region_range", + code: err, + })) + } else { + // should be safe to assume sizeof(size_t) >= sizeof(unsigned int) + // TODO: fix after https://review.coreboot.org/c/flashrom/+/65944 + Ok(start.try_into().unwrap()..(start + len).try_into().unwrap()) + } + } +} + +// TODO this will be replaced with an API implementation: https://review.coreboot.org/c/flashrom/+/65999 +impl std::str::FromStr for Layout { + type Err = Box<dyn error::Error>; + + /// This will attempt to parse the [`Layout`] file format into a [`Layout`] + /// + /// The format is documented in the flashrom man page. + fn from_str(s: &str) -> std::result::Result<Self, Self::Err> { + let mut ret = Layout::new()?; + + // format is hex:hex name + // flashrom layout.c seems to allow any characters in the name string + // I am restricting here to non whitespace + let re = Regex::new(r"^([0-9A-Za-z]+):([0-9A-Za-z]+)\s+(\S+)$").unwrap(); + + // we dont use captures_iter else we would ignore incorrect lines + for line in s.lines() { + let (start, end, name) = match re.captures(line) { + Some(caps) => ( + caps.get(1).unwrap(), + caps.get(2).unwrap(), + caps.get(3).unwrap(), + ), + None => Err(ParseLayoutError(format!("failed to parse: {:?}", line)))?, + }; + let start = usize::from_str_radix(start.as_str(), 16)?; + let end = usize::from_str_radix(end.as_str(), 16)?; + ret.add_region(name.as_str(), start..=end)?; + } + + Ok(ret) + } +} + +impl Drop for Layout { + fn drop(&mut self) { + unsafe { + libflashrom_sys::flashrom_layout_release(self.layout.as_mut()); + } + } +} + +#[cfg(test)] +mod tests { + use gag::BufferRedirect; + use std::io::Read; + + use super::flashrom_version_info; + use super::set_log_level; + use super::Chip; + use super::ChipInitError; + use super::InitError; + use crate::set_log_function; + use crate::Layout; + use crate::Programmer; + use crate::WriteProtectCfg; + + // flashrom contains global state, which prevents correct initialisation of + // a second programmer or probing of a second chip. Run all unit tests in + // forked subprocesses to avoid this issue. + use rusty_fork::rusty_fork_test; + rusty_fork_test! { + + #[test] + fn version() { + // There is no version requirement yet, but for example: + // assert!(flashrom_version_info().contains("v1.2")) + assert!(!flashrom_version_info().unwrap().is_empty()) + } + + #[test] + fn only_one_programmer() { + { + let _1 = Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap(); + // Only one programmer can be initialised at a time. + assert_eq!(Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap_err(), InitError::DuplicateInit) + } + // Only one programmer can ever be initialised + assert_eq!(Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap_err(), InitError::DuplicateInit) + } + + #[test] + fn programmer_bad_cstring_name() { + assert!(matches!(Programmer::new("dummy\0", None).unwrap_err(), InitError::InvalidName(_))) + } + + #[test] + fn chip_none() { + // Not specifying a chip will select one if there is one. + Chip::new(Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap(), None).unwrap(); + } + + #[test] + fn chip_some() { + // Specifying a valid chip. + Chip::new(Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap(), Some("W25Q128.V")).unwrap(); + } + + #[test] + fn chip_nochip() { + // Choosing a non existent chip fails. + assert_eq!( + Chip::new(Programmer::new("dummy", None).unwrap(), Some("W25Q128.V")).unwrap_err(), + ChipInitError::NoChipError + ); + } + + #[test] + fn logging_stderr() { + let mut buf = BufferRedirect::stderr().unwrap(); + let mut fc = Chip::new(Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap(), Some("W25Q128.V")).unwrap(); + + set_log_level(Some(libflashrom_sys::FLASHROM_MSG_INFO)); + fc.image_read(None).unwrap(); + let mut stderr = String::new(); + if buf.read_to_string(&mut stderr).unwrap() == 0 { + panic!("stderr empty when it should have some messages"); + } + + set_log_level(None); + fc.image_read(None).unwrap(); + if buf.read_to_string(&mut stderr).unwrap() != 0 { + panic!("stderr not empty when it should be silent"); + } + } + + #[test] + fn logging_custom() { + // Check that a custom logging callback works + static mut BUF: String = String::new(); + fn logger( + _: libflashrom_sys::flashrom_log_level, + format: &str, + ) { + unsafe {BUF.push_str(format)} + } + set_log_function(logger); + set_log_level(Some(libflashrom_sys::FLASHROM_MSG_SPEW)); + Chip::new(Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap(), Some("W25Q128.V")).unwrap(); + assert_ne!(unsafe{BUF.len()}, 0); + } + + #[test] + fn flashchip() { + // basic tests of the flashchip methods + let mut fc = Chip::new(Programmer::new("dummy", Some("emulate=W25Q128FV")).unwrap(), Some("W25Q128.V")).unwrap(); + fc.get_size(); + + let mut wp = fc.get_wp().unwrap(); + wp.set_mode(libflashrom_sys::flashrom_wp_mode::FLASHROM_WP_MODE_DISABLED); + fc.set_wp(&wp).unwrap(); + fc.get_wp_ranges().unwrap(); + + fn test_layout() -> Layout { + let mut layout = Layout::new().unwrap(); + layout.add_region("xyz", 100..200).unwrap(); + layout.include_region("xyz").unwrap(); + layout.add_region("abc", 100..200).unwrap(); + layout + } + + fc.image_read(None).unwrap(); + fc.image_read(Some(test_layout())).unwrap(); + + let mut buf = vec![0; fc.get_size()]; + fc.image_write(&mut buf, None).unwrap(); + fc.image_write(&mut buf, Some(test_layout())).unwrap(); + + fc.image_verify(&buf, None).unwrap(); + fc.image_verify(&buf, Some(test_layout())).unwrap(); + + fc.erase().unwrap(); + } + + #[test] + fn write_protect() { + let mut wp = WriteProtectCfg::new().unwrap(); + wp.set_mode(libflashrom_sys::flashrom_wp_mode::FLASHROM_WP_MODE_DISABLED); + wp.set_range(100..200); + assert_eq!(wp.get_mode(), libflashrom_sys::flashrom_wp_mode::FLASHROM_WP_MODE_DISABLED); + assert_eq!(wp.get_range(), 100..200); + } + } +} |