# Block words

The block interface is written for the STM32F746 DISCOVERY board and the Raspberry Pico (along with other RP2040 boards with Quad SPI flash compatible with the Winbond Quad SPI flash used by the Raspberry Pi Pico). It provides a convenient interface for turning the Quad SPI flash functionality into a map of block id's to 1K blocks of memory.

Note that block ids start from zero, unlike on many Forths where they traditionally started from one.

### `forth`

The following words are in `forth`:

##### `load`
( id -- )

Evaluate each 64-byte line in a block with the given id from first to last; if the block does not exist `x-block-not-found` is raised.

##### `load-range`
( start-id end-id -- )

Evaluate each 64-byte line from first to last in each block, if it exists, in the range from `start-id` to `end-id`.

##### `list`
( id -- )

Display each 64-byte line in a block with the given id from first to last; if the block does not exist `x-block-not-found` is raised.

##### `list-range`
( start-id end-id -- )

Display each 64-byte line from first to last in each block, if it exists, in the range from `start-id` to `end-id`.

### `block`

The following words are in `block`:

##### `block-size`
( --  bytes )

The block size in bytes, currently 1024 bytes.

##### `x-invalid-block-id`
( -- )

Exception raised when an invalid block id (presently only $FFFFFFFF) is used.

##### `x-block-write-fail`

Exception when `block!` is unable to write a given block, due to no free space being available and not being unable to free up space due to no completely used sectors existing.

##### `x-block-not-found`

Exception when attempting to delete, load, or list a nonexistent block.

##### `find-block`
( id -- addr | 0 )

Find a block in the memory-mapped Quad SPI flash space by id, or return 0 if no such block can be found.

##### `block?`
( id -- flag )

Return whether a block by a given id exists.

##### `block!`
( addr id -- )

Attempt to write a the 1K buffer at the specified address to a block with a given id; this may fail and raise `x-block-write-fail`. Note that this is not friendly to realtime performance, especially when it has to reclaim existing used sectors

##### `copy-block`
( src-id dest-id -- )

Copy the block with id `src-id` to `dest-id`; if the block does not exist, delete `dest-id`

##### `copy-blocks`
( src-id dest-id count -- )

Copy `count-blocks` from the sequence of blocks starting with id `src-id` to the sequence of blocks starting with id `dest-id`; note that nonexistent blocks in the first range resulting in the corresponding blocks in the second range being deleted, and overlapping ranges of blocks are treated correctly.

##### `insert-blocks`
( start-id count -- )

Insert `count` nonexistent blocks starting at id `start-id`, displacing any extant blocks in that range to higher ids (note that nonexistent blocks are ignored and may be eliminated in the process).

##### `delete-block`
( id -- )

Attempt to delete a block with the given id; if the block does not exist, `x-block-not-found` is raised.

##### `delete-blocks`
( start-id count -- )

Delete `count` blocks starting with id `start-id` ascending; note that non-existent blocks are ignored.

##### `erase-all-blocks`
( -- )

Erase all blocks. Note that this is not friendly to realtime performance.