core/flash: Add flash API

We'd like to enable access to the system PNOR, on platforms where its
present. This change introduces an API for global flash operations:

 opal_flash_read
 opal_flash_erase
 opal_flash_write

- plus device-tree bindings to expose the flash details.

Since there are other components of the system that use the PNOR (NVRAM
and pnor_load_resource), upcoming changes will port this these over to
use the new interface.

Signed-off-by: Jeremy Kerr <jk@ozlabs.org>
Reviewed-by: Joel Stanley <joel@jms.id.au>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

2 files changed, 107 insertions, 0 deletions

diff --git a/doc/device-tree/ibm,opal/flash.txt b/doc/device-tree/ibm,opal/flash.txt
new file mode 100644
index 0000000..872d623
--- /dev/null
+++ b/doc/device-tree/ibm,opal/flash.txt
@@ -0,0 +1,35 @@
+ibm,opal/flash device tree entries
+----------------------------------
+
+The flash@<n> nodes under ibm,opal describe flash devices that can be
+accessed through the OPAL_FLASH_{READ,ERASE,WRITE} interface.
+
+These interfaces take an 'id' parameter, which corresponds to the ibm,opal-id
+property of the node.
+
+The properties under a flash node are:
+
+ compatible = "ibm,opal-flash"
+ 
+ ibm,opal-id = <id>
+   - provides the index used for the OPAL_FLASH_ calls to reference this
+     flash device
+
+ reg = <0 size>
+   - the offset and size of the flash device
+
+ ibm,flash-block-size
+   - the read/write/erase block size for the flash interface. Calls
+     to read/write/erase must be aligned to the block size.
+
+ #address-cells = <1>
+ #size-cells = <1>
+   - flash devices are currently 32-bit addressable
+
+
+If valid partitions are found on the flash device, then partition@<offset>
+sub-nodes are added to the flash node. These match the Linux binding for
+flash partitions; the reg parameter contains the offset and size of the
+partition.
+
+
diff --git a/doc/opal-api/opal-flash-110-111-112.txt b/doc/opal-api/opal-flash-110-111-112.txt
new file mode 100644
index 0000000..860172b
--- /dev/null
+++ b/doc/opal-api/opal-flash-110-111-112.txt
@@ -0,0 +1,72 @@
+
+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 much match an ID found in the corresponding ibm,opal/flash@n
+device tree node. See doc/device-tree/ibm,opal/flash.txt 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.
+
+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
+---------------
+
+Parameters:
+	uint64_t id
+	uint64_t offset
+	uint64_t buffer
+	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
+---------------
+
+Parameters:
+	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
+---------------
+
+Parameters:
+	uint64_t id
+	uint64_t offset
+	uint64_t buffer
+	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.
+