Diff: I2CEeprom.h

Revision:

10:3824e507953c

Parent:

9:acc133240c9d

Child:

11:c3609e691623

--- a/I2CEeprom.h	Sat Mar 28 16:11:37 2020 +0000
+++ b/I2CEeprom.h	Sat Mar 28 16:42:13 2020 +0000
@@ -1,10 +1,11 @@
 
-/*! \file */ 
-/*! \class I2CEeprom
-/* \ brief Simple access class for I2C EEPROM chips like Microchip 24LC
+/*! \file I2CEeprom.h */ 
+/*! \class I2CEeprom */
+/*! \brief Simple access class for I2C EEPROM chips like Microchip 24LC
  */
  
- * Copyright (c) 2015 Robin Hourahane
+ /* Copyright (c) 2015 Robin Hourahane
+ *  Copyright (c) 2020 Andy Little
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +25,7 @@
 
 #include <mbed.h>
 
-/// Based on the original library by Robin Hourahane.
+/// Based on the original Mbed I2CEeprom library by Robin Hourahane.
 ///
 /// Class to provide simple access to I2C EEPROM chips like Microchip's 24LC 
 /// or AMTELS AT24C series. Chips up to 64Kb in size are directly supported.
@@ -57,7 +58,7 @@
 class I2CEeprom {
 public:
     /// Constructor to create a new instance of the class.
-    /// @param i2c a reference to the i2c bus the chip is connected to.
+    /// @param i2c A reference to the i2c bus the chip is connected to.
     /// @param address The 8bit I2C address of the chip.
     /// @param pageSize The size of the page used in writing to the chip.
     /// @param chipSize The size of the memory in the chip for range check. 
@@ -69,58 +70,57 @@
             size_t chipSize,
             uint8_t writeCycleTime_ms);
     
-    /// Read a single byte from the address in memory.
-    /// @param address Memory address to read from.
-    /// @param value Variable to receive value read.
-    /// @returns Number of bytes read from memory.
+    /// Read a single byte from the EEprom.
+    /// @param address EEprom address to read from.
+    /// @param value Reference of char to read into.
+    /// @returns Number of bytes read .
     size_t read(size_t address, char &value);
     
-    /// Read multiple bytes starting from the address in memory.
-    /// @param address Memory address to start reading from.
-    /// @param buffer Pointer to buffer to hold bytes read from memory.
-    /// @param size Number of bytes to be read from memory.
-    /// @returns Number of bytes read from memory.
+    /// Read multiple bytes starting from EEprom memory.
+    /// @param address EEprom Memory start read address.
+    /// @param buffer Pointer to buffer to hold bytes read.
+    /// @param size Number of bytes to read.
+    /// @returns Number of bytes read.
     size_t read(size_t address, char *buffer, size_t size);
     
-    /// Read either an instance or an array of a POD type from memory.
-    /// Note the value of the type can't contain pointers.
-    /// @param address Start address for reading memory.
-    /// @param value Object to be read from memory.
-    /// @returns Number of bytes read from memory.
+    /// Deserialise object of type T from Eeprom memory.
+    /// @param address Start address of Object in EEprom.
+    /// @param value Reference to Object to deserialise into.
+    /// @returns Number of bytes read.
     template<typename T> size_t read(size_t address, T &value) {
         return read(address, reinterpret_cast<char *>(&value), sizeof(T));
     }
     
-    /// Write a single byte to the address in memory.
-    /// @param address Memory address to write to.
-    /// @param value Value to be written to memory.
-    /// @returns Number of bytes written to memory.
+    /// Write a char to EEprom.
+    /// @param address Eeprom address to write to.
+    /// @param value Value of char to write.
+    /// @returns Number of bytes written.
     size_t write(size_t address, char value);
 
-    /// Write multiple bytes starting from the address in memory.
-    /// Note that in this implementation, a buffer is allocated on the heap
-    /// for the
-    /// @param address Memory address to start writting to.
-    /// @param buffer Pointer to buffer holding the bytes to write to memory.
-    /// @param size Number of bytes to be written to memory.
-    /// @returns Number of bytes written to memory.
+    /// Write multiple bytes to EEprom
+    /// Note that in this implementation, the write is split into chunks
+    /// of up to pageSize and for each chunk a buffer of up to pageSize +2   
+    /// is temporarily allocated on the heap while the write is in progress.
+    /// @param address Start EEprom address.
+    /// @param buffer Buffer holding the bytes to write.
+    /// @param size Number of bytes to write.
+    /// @returns Number of bytes written.
     size_t write(size_t address, const char *buffer, size_t size);
 
-    /// Write either an instance or an array of a POD type to memory.
-    /// Note the value of the type can't contain pointers.
-    /// @param address Start address to write to memory.
-    /// @returns Number of bytes written to memory.
+    /// Serialise an object of type T.
+    /// @param address EEprom write start address.
+    /// @returns Number of bytes written.
     template<typename T> size_t write(size_t address, const T &value) {
         return write(address, reinterpret_cast<const char *>(&value), sizeof(T));
     }
         
 private:
-    // Wait for a write cycle to complete using polling and small waits.
+    /// Sleep thread while write completes.
     void waitForWrite();
+    ///  atomic chunk up to page aize write
     size_t ll_write(size_t address, const char *buffer, size_t size);
     
-    // Validate that the proposed opperation will fit in the size of
-    // the chip.
+    /// Validate that proposed operation is in bounds.
     bool checkSpace(size_t address, size_t size)
     {
        return (address + size) < m_chipSize ;