Skip to main content

spiflash

Availability

Device

Description

The Spiflash class represents the SPI flash storage device connected to any imp module from the imp003 and above. These modules place no limit on SPI flash size, allowing manufacturers to choose which SPI flash device to attach to the module. If the chip’s storage capacity is large enough, some of this capacity can be made available to Squirrel applications.

If the SPI flash is available to Squirrel then it can be accessed as hardware.spiflash. Where it is not available, an attempt to access the hardware.spiflash object will result in a Squirrel error.

The hardware.spiflash object is only available on the imp003 and above. It is not implemented on the imp001 or imp002. To confirm its presence in code, use the following structure:

if ("spiflash" in hardware) {
  // Running on an imp003 or above...
}

The imp spiflash API provides a relatively low-level interface to the underlying hardware, but wraps up the most common sequences of commands sent to the chip in simple read, write and erase methods. The API also provides address virtualization. For example, if there is 8Mbit of SPI flash available, the imp will reserve the bottom 4Mbit for internal use, and will make the top 4Mbit available to Squirrel.

Module-specific Notes

imp001, imp002

hardware.spiflash is not implemented on these imps.

imp003

With the imp003 (Murata part number LBWA1ZV1CD), you must fit at least 512KB (4Mbit) of SPI flash. impOS™ takes seven-eighths of that (448KB), and the rest (64KB) is available to Squirrel as hardware.spiflash. If you use a SPI flash chip bigger than 512KB, all the extra storage will be available to Squirrel. There is a further restriction: the imp003’s SPI flash chip must support 4KB erases (see below).

imp004m

With the imp004m (Murata part number LBEE5ZZ1MD), you must fit at least 1MB (8Mbit). impOS takes up 776KB; the remainder is available to Squirrel. If you use a SPI flash chip bigger than 1MB, all the additional storage will be available to Squirrel. The imp004m’s SPI flash must support 4KB erases (see below).

impOS 38 will cause certain recommended SPI flash parts to enter deep sleep whenever the imp004m itself enters deep sleep, and to wake the SPI flash when the imp004m wakes. Recommended SPI flash parts are listed in the imp004m datasheet. If you choose SPI flash parts which support sleep/wake but are not recommended by Electric Imp, you must ensure that the chosen parts enter and exit sleep mode in the same way that the recommended parts do, otherwise your product may malfunction. We do not anticipate any such risk if you use SPI flash parts which do not support sleep/wake.

Please see the ‘Designing Hardware with the imp004m’ for information about imp004m SPI flash power requirements.

imp005

With the imp005 (Murata part number LBWA1UZ1GC-901), you must fit at least 4MB (32Mbit) of SPI flash. impOS takes all but 648KB, which is available to Squirrel. If you use a SPI flash chip bigger than 4MB, all the extra storage will be available to Squirrel. The imp005’s SPI flash must support 4KB and 64KB erases (see below).

Notes on SPI flash architecture

In order to use the SPI flash correctly, it is important to understand the nature of the underlying NOR flash hardware. The default state of a NOR flash cell is logically 1 in the binary representation. The cell can be ‘programmed’, ie. cleared to binary 0, but can’t be set to binary 1. Cells can only be set from 0 to 1 (‘erased’) en masse in large, contiguous blocks.

This property of NOR flash has some ramifications. Consider a byte, which is initially erased, ie. its value is b = 0xFF, and located at some address in the flash. The first write to this address will be successful for an arbitrary value, say

b = 0xAA = 0b10101010

because any of the initial 1s can be set to 0. However, the same may not true of a subsequent write. For example,

b = 0xA8 = 0b10101000

succeeds because it only causes the clearing of bit 1 from 1 to 0, which is a permitted NOR flash write operation. However,

b = 0xAB = 0b10101011

will fail because it attempts to set bit 0 from 0 to 1, an operation which is only possible as part of a sector erase. The application developer is responsible for either pre-erasing the sectors that a write will target, or else ensuring that a write cannot possibly attempt to set a bit from 0 to 1.

Member Entities

The spiflash object has the following member methods: