OPAL Flash calls

There are three OPAL calls for interacting with flash devices:

#define OPAL_FLASH_READ        110
#define OPAL_FLASH_WRITE       111
#define OPAL_FLASH_ERASE       112

Multiple flash devices are supported by OPAL - each of these calls takes an id parameter, which must match an ID found in the corresponding ibm,opal/flash@n device tree node. See ibm,opal/flash device tree entries for details of the device tree bindings.

All operations on the flash device must be aligned to the block size of the flash. This applies to both offset and size arguments.

This interface is asynchronous; all calls require a ‘token’ argument. On success, the calls will return OPAL_ASYNC_COMPLETION, and an opal_async_completion message will be sent (with the appropriate token argument) when the operation completes.

Note

These calls can have higher than normal latency, spending many milliseconds inside OPAL. This is due to the OPAL_FLASH_* calls typically being backed by flash on the other side of the LPC bus, which has a maximum transfer rate of 5MB/sec, or to/from flash attached to the ast2400/ast2500 (the typical setup for OpenPOWER systems) of only 1.75MB/sec.

All calls share the same return values:

OPAL_ASYNC_COMPLETION

operation started, an async completion will be triggered with the token argument

OPAL_PARAMETER

invalid flash id

OPAL_PARAMETER

invalid size or offset (alignment, or access beyond end of device)

OPAL_BUSY

flash in use

OPAL_HARDWARE

error accessing flash device

OPAL_FLASH_READ

#define OPAL_FLASH_READ     110

int64_t opal_flash_read(uint64_t id, uint64_t offset, uint64_t buf,
                        uint64_t size, uint64_t token);

Reads from the specified flash id, at the specified offset, into the buffer. Will trigger an async completion with token when completed.

OPAL_FLASH_ERASE

#define OPAL_FLASH_ERASE     112

int64_t opal_flash_erase(uint64_t id, uint64_t offset, uint64_t size,
                         uint64_t token);

Erases the specified flash id, at the specified offset and size. Will trigger an async completion with token when completed.

OPAL_FLASH_WRITE

#define OPAL_FLASH_WRITE     111

int64_t opal_flash_write(uint64_t id, uint64_t offset, uint64_t buf,
                         uint64_t size, uint64_t token);

Writes buffer to the specified flash id, at the specified offset and size. The flash must be erased before being written. Will trigger an async completion with token when completed.