/*
 * 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());
        }
    }
}

/// A translation of the flashrom_flag type
///
/// Keep this list in sync with libflashrom.h
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub enum FlashromFlag {
    FlashromFlagForce,
    FlashromFlagForceBoardmismatch,
    FlashromFlagVerifyAfterWrite,
    FlashromFlagVerifyWholeChip,
    FlashromFlagSkipUnreadableRegions,
    FlashromFlagSkipUnwritableRegions,
}

impl From<FlashromFlag> for libflashrom_sys::flashrom_flag {
    fn from(e: FlashromFlag) -> Self {
        match e {
            FlashromFlag::FlashromFlagForce => libflashrom_sys::flashrom_flag::FLASHROM_FLAG_FORCE,
            FlashromFlag::FlashromFlagForceBoardmismatch => {
                libflashrom_sys::flashrom_flag::FLASHROM_FLAG_FORCE_BOARDMISMATCH
            }
            FlashromFlag::FlashromFlagVerifyAfterWrite => {
                libflashrom_sys::flashrom_flag::FLASHROM_FLAG_VERIFY_AFTER_WRITE
            }
            FlashromFlag::FlashromFlagVerifyWholeChip => {
                libflashrom_sys::flashrom_flag::FLASHROM_FLAG_VERIFY_WHOLE_CHIP
            }
            FlashromFlag::FlashromFlagSkipUnreadableRegions => {
                libflashrom_sys::flashrom_flag::FLASHROM_FLAG_SKIP_UNREADABLE_REGIONS
            }
            FlashromFlag::FlashromFlagSkipUnwritableRegions => {
                libflashrom_sys::flashrom_flag::FLASHROM_FLAG_SKIP_UNWRITABLE_REGIONS
            }
        }
    }
}

/// Various flags of the flashrom context
///
/// Keep the struct in sync with the flags in flash.h
#[derive(Debug)]
pub struct FlashromFlags {
    pub force: bool,
    pub force_boardmismatch: bool,
    pub verify_after_write: bool,
    pub verify_whole_chip: bool,
    pub skip_unreadable_regions: bool,
    pub skip_unwritable_regions: bool,
}

/// Keep the default values in sync with cli_classic.c
impl Default for FlashromFlags {
    fn default() -> Self {
        Self {
            force: false,
            force_boardmismatch: false,
            verify_after_write: true,
            verify_whole_chip: true,
            // These flags are introduced to address issues related to CSME locking parts. Setting
            // them to true as default values
            skip_unreadable_regions: true,
            skip_unwritable_regions: true,
        }
    }
}

impl fmt::Display for FlashromFlags {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "FlashromFlags {{ force: {}, force_boardmismatch: {}, verify_after_write: {}, verify_whole_chip: {}, skip_unreadable_regions: {}, skip_unwritable_regions: {} }}",
            self.force,
            self.force_boardmismatch,
            self.verify_after_write,
            self.verify_whole_chip,
            self.skip_unreadable_regions,
            self.skip_unwritable_regions,
        )
    }
}

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,
            })
        }
    }

    /// Set a flag in the given flash context
    pub fn flag_set(&mut self, flag: FlashromFlag, value: bool) -> () {
        unsafe { libflashrom_sys::flashrom_flag_set(self.ctx.as_mut(), flag.into(), value) }
    }
}

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);
        }
    }
}