Standard interface for non volatile memory devices

openrtx/include/interfaces/nvmem.h

@@ -31,9 +31,122 @@ extern "C" {
 #endif
 
 /**
- * Interface for nonvolatile memory management, usually an external SPI flash
- * memory, containing calibration, contact data and so on.
+ * Enumeration field for nonvolatile memory device type.
  */
+enum nvmType
+{
+    NVM_FLASH  = 0,   ///< FLASH type non volatile memory
+    NVM_EEPROM        ///< EEPROM type non volatile memory
+};
+
+/**
+ * Nonvolatile memory device parameters. The content of this data structure is
+ * filled by the device driver and then kept constant.
+ */
+struct nvmParams
+{
+    size_t  write_size;    ///< Minimum write size (write unit)
+    size_t  erase_size;    ///< Minimum erase size (erase unit)
+    size_t  erase_cycles;  ///< Maximum allowed erase cycles of a block
+    uint8_t type;          ///< Device type
+};
+
+struct nvmDevice;
+
+/**
+ * Standard API for nonvolatile memory driver.
+ */
+struct nvmApi
+{
+    /**
+     * Read data from nonvolatile memory device.
+     *
+     * @param dev: pointer to NVM device descriptor.
+     * @param offset: offset to read, byte aligned.
+     * @param data: destination buffer for data read.
+     * @param len: number of bytes to read.
+     * @return 0 on success, negative errno code on fail.
+     */
+    int (*read)(const struct nvmDevice *dev, uint32_t offset, void *data, size_t len);
+
+    /**
+     * Write data to nonvolatile memory device. On flash memory devices the area
+     * has to be erased before the write. This function pointer may be set to
+     * NULL if the device does not support writing.
+     *
+     * @param dev: pointer to NVM device descriptor.
+     * @param offset: starting offset for the write, byte aligned.
+     * @param data: data to write.
+     * @param len: number of bytes to write.
+     * @return 0 on success, negative errno code on fail.
+     */
+    int (*write)(const struct nvmDevice *dev, uint32_t offset, const void *data, size_t len);
+
+    /**
+     * Erase part or all of the nonvolatile memory.
+     * Acceptable values of erase size and offset are subject to hardware-specific
+     * multiples of page size and offset. If the device does not support erase
+     * this function pointer is set to NULL.
+     *
+     * @param dev: pointer to NVM device descriptor.
+     * @param offset: starting offset for the erase, byte aligned.
+     * @param size: size of the area to be erased.
+     * @return 0 on success, negative errno code on fail.
+     */
+    int (*erase)(const struct nvmDevice *dev, uint32_t offset, size_t size);
+
+    /**
+     * Sync device cache and state to its underlying hardware.
+     * If the device does not support sync this function pointer is set to NULL.
+     *
+     * @param dev: pointer to NVM device descriptor.
+     * @return 0 on success, negative errno code on fail.
+     */
+    int (*sync)(const struct nvmDevice *dev);
+
+    /**
+     * Get device parameters.
+     *
+     * @param dev: pointer to NVM device descriptor.
+     * @return pointer to the device parameters' data structure.
+     */
+    const struct nvmParams *(*params)(const struct nvmDevice *dev);
+};
+
+/**
+ * Nonvolatile memory device driver.
+ */
+struct nvmDevice
+{
+    const struct nvmApi *api;       ///< Driver API
+    const void          *config;    ///< Driver configuration data
+    void  *const         priv;      ///< Driver runtime data
+};
+
+/**
+ * Data structure representing a partition of a NVM area. The offset of the
+ * partition is referred to the beginning of the area itself.
+ */
+struct nvmPartition
+{
+    const size_t offset;    ///< Offset from the beginning of the NVM area
+    const size_t size;      ///< Size in bytes
+};
+
+/**
+ * Nonvolatile memory area descriptor. This data structure contains all the data
+ * relative to an area of nonvolatile memory with a fixed size, managed by a
+ * given device and with zero or more partition.
+ */
+struct nvmArea
+{
+    const char                *name;          ///< Area name
+    const struct nvmDevice    *dev;           ///< Device driver to manage the area
+    const size_t               startAddr;     ///< Start address of the area from the beginning of the device
+    const size_t               size;          ///< Size of the area, in bytes
+    const struct nvmPartition *partitions;    ///< List of partitions
+};
+
 
 /**
  * Initialise NVM driver.