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 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.

Module-specific Notes

imp001, imp002

hardware.spiflash is not implemented on these imps.

Other imps

Please see the Design with imp guide for your chosen imp module to learn about its SPI flash requirements.

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: