diff --git a/openrtx/include/interfaces/nvmem.h b/openrtx/include/interfaces/nvmem.h index 700e2f41..b6bb6b91 100644 --- a/openrtx/include/interfaces/nvmem.h +++ b/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.