Device
The Spiflash class represents the SPI flash storage device connected to any imp module from the imp003 and up. 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, starting at the virtual address 0x00000, though the actual address of the first byte of user-accessible data is 0x80000.
hardware.spiflash is not implemented on these imps.
Please see the Design with imp guide for your chosen imp module to learn about its SPI flash requirements.
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.
The spiflash object has the following member methods: