/* 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. */ /* Flash memory module for Chrome EC */ #ifndef __CROS_EC_FLASH_H #define __CROS_EC_FLASH_H #include "common.h" /*****************************************************************************/ /* Low-level methods, for use by flash_common. */ /* Return the write / erase / protect block size, in bytes. Operations must be * aligned to and multiples of the granularity. For example, erase operations * must have offset and size which are multiples of the erase block size. */ int flash_get_write_block_size(void); int flash_get_erase_block_size(void); int flash_get_protect_block_size(void); /* Return the physical size of flash in bytes */ int flash_physical_size(void); /* Read bytes of data from offset into . */ int flash_physical_read(int offset, int size, char *data); /* Write bytes of data to flash at byte offset . * must be 32-bit aligned. */ int flash_physical_write(int offset, int size, const char *data); /* Erase bytes of flash at byte offset . */ int flash_physical_erase(int offset, int size); /* Return non-zero if block is protected until reboot. */ int flash_physical_get_protect(int block); /* Protects the block until reboot. */ void flash_physical_set_protect(int block); /*****************************************************************************/ /* High-level interface for use by other modules. */ /* Initializes the module. */ int flash_pre_init(void); /* Returns the usable size of flash in bytes. Note that this is * smaller than the actual flash size, */ int flash_get_size(void); /* Reads bytes of data from offset into . */ int flash_read(int offset, int size, char *data); /* Writes bytes of data to flash at byte offset . * must be 32-bit aligned. */ int flash_write(int offset, int size, const char *data); /* Erases bytes of flash at byte offset . */ int flash_erase(int offset, int size); /* Flash protection APIs * * Flash can be protected on a per-block basis at any point by calling * flash_protect_until_reboot(). Once a block is protected, it will stay * protected until reboot. This function may be called at any time, regardless * of the persistent flash protection state, and protection will be applied * immediately. * * Flash may also be protected in a persistent fashion by calling * flash_set_protect(). This sets a persistent flag for each block which is * checked at boot time and applied if the hardware write protect pin is * enabled. * * The flash persistent protection settings are themselves protected by a lock, * which can be set via flash_lock_protect(). Once the protection settings are * locked: * * (1) They will be immediately applied (as if flash_protect_until_reboot() * had been called). * * (2) The persistent settings cannot be changed. That is, subsequent calls * to flash_set_protect() and flash_lock_protect() will fail. * * The lock can be bypassed by cold-booting the system with the hardware write * protect pin deasserted. In this case, the persistent settings and lock * state may be changed until flash_lock_protect(non-zero) is called, or until * the system is rebooted with the write protect pin asserted - at which point, * protection is re-applied. */ /* Write-protect bytes of flash at byte offset until next * reboot. */ int flash_protect_until_reboot(int offset, int size); /* Higher-level APIs to emulate SPI write protect */ /* Set (enable=1) or clear (enable=0) the persistent write protect setting for * the specified range. This will only succeed if write protect is unlocked. * This will take effect on the next boot, or when flash_lock_protect(1) is * called. */ int flash_set_protect(int offset, int size, int enable); /* Lock or unlock the persistent write protect settings. Once the write * protect settings are locked, they will STAY locked until the system is * cold-booted with the hardware write protect pin disabled. * * If called with lock!=0, this will also immediately protect all * persistently-protected blocks. */ int flash_lock_protect(int lock); /* Flags for flash_get_protect() and flash_get_protect_array(). */ /* Protected persistently. Note that if the write protect pin was deasserted * at boot time, a block may have the FLASH_PROTECT_PERSISTENT flag indicating * the block would be protected on a normal boot, but may not have the * FLASH_PROTECT_UNTIL_REBOOT flag indicating it's actually protected right * now. */ #define FLASH_PROTECT_PERSISTENT 0x01 /* Protected until reboot. This will be set for persistently-protected blocks * as soon as the flash module protects them, and for non-persistent protection * after flash_protect_until_reboot() is called on a block. */ #define FLASH_PROTECT_UNTIL_REBOOT 0x02 /* Return a copy of the current write protect state. This is an array of * per-protect-block flags. The data is valid until the next call to a flash * function. */ const uint8_t *flash_get_protect_array(void); /* Return the lowest amount of protection for any flash block in the specified * range. That is, if any byte in the range is not protected until reboot, * FLASH_PROTECT_UNTIL_REBOOT will not be set. */ int flash_get_protect(int offset, int size); /* Flags for flash_get_protect_lock() */ /* Flash protection lock has been set. Note that if the write protect pin was * deasserted at boot time, this simply indicates the state of the lock * setting, and not whether blocks are actually protected. */ #define FLASH_PROTECT_LOCK_SET 0x01 /* Flash protection lock has actually been applied. All blocks with FLASH_PROTECT_PERSISTENT have been protected, and flash protection cannot be unlocked. */ #define FLASH_PROTECT_LOCK_APPLIED 0x02 /* Write protect pin is currently asserted */ #define FLASH_PROTECT_PIN_ASSERTED 0x04 /* Return the flash protect lock status. */ int flash_get_protect_lock(void); #endif /* __CROS_EC_FLASH_H */