flash/nor: improved API of flash_driver.info & fixed buffer overruns

[openocd.git] / src / flash / nor / driver.h

diff --git a/src/flash/nor/driver.h b/src/flash/nor/driver.h
index 729c5eb270ba83b7884c93810d1aab21f8b5cd05..7a5be65174a7876acc9fad8df00c4dd286470d0d 100644 (file)
--- a/src/flash/nor/driver.h
+++ b/src/flash/nor/driver.h
@@ -19,8 +19,8 @@
  *   along with this program.  If not, see <http://www.gnu.org/licenses/>. *
  ***************************************************************************/
 
-#ifndef FLASH_NOR_DRIVER_H
-#define FLASH_NOR_DRIVER_H
+#ifndef OPENOCD_FLASH_NOR_DRIVER_H
+#define OPENOCD_FLASH_NOR_DRIVER_H
 
 struct flash_bank;
 
@@ -104,11 +104,14 @@ struct flash_driver {
         * @param last The number of the last sector to erase, typically N-1.
         * @returns ERROR_OK if successful; otherwise, an error code.
         */
-       int (*erase)(struct flash_bank *bank, int first, int last);
+       int (*erase)(struct flash_bank *bank, unsigned int first,
+               unsigned int last);
 
        /**
         * Bank/sector protection routine (target-specific).
         *
+        * If protection is not implemented, set method to NULL
+        *
         * When called, the driver should enable/disable protection
         * for MINIMUM the range covered by first..last sectors
         * inclusive. Some chips have alignment requirements will
@@ -117,11 +120,12 @@ struct flash_driver {
         *
         * @param bank The bank to protect or unprotect.
         * @param set If non-zero, enable protection; if 0, disable it.
-        * @param first The first sector to (un)protect, typicaly 0.
+        * @param first The first sector to (un)protect, typically 0.
         * @param last The last sector to (un)project, typically N-1.
         * @returns ERROR_OK if successful; otherwise, an error code.
         */
-       int (*protect)(struct flash_bank *bank, int set, int first, int last);
+       int (*protect)(struct flash_bank *bank, int set, unsigned int first,
+               unsigned int last);
 
        /**
         * Program data into the flash.  Note CPU address will be
@@ -151,6 +155,20 @@ struct flash_driver {
         int (*read)(struct flash_bank *bank,
                        uint8_t *buffer, uint32_t offset, uint32_t count);
 
+       /**
+        * Verify data in flash.  Note CPU address will be
+        * "bank->base + offset", while the physical address is
+        * dependent upon current target MMU mappings.
+        *
+        * @param bank The bank to verify
+        * @param buffer The data bytes to verify against.
+        * @param offset The offset into the chip to verify.
+        * @param count The number of bytes to verify.
+        * @returns ERROR_OK if successful; otherwise, an error code.
+        */
+       int (*verify)(struct flash_bank *bank,
+                       const uint8_t *buffer, uint32_t offset, uint32_t count);
+
        /**
         * Probe to determine what kind of flash is present.
         * This is invoked by the "probe" script command.
@@ -178,6 +196,8 @@ struct flash_driver {
         * flash_sector_s::is_protected field for each of the flash
         * bank's sectors.
         *
+        * If protection is not implemented, set method to NULL
+        *
         * @param bank - the bank to check
         * @returns ERROR_OK if successful; otherwise, an error code.
         */
@@ -185,30 +205,37 @@ struct flash_driver {
 
        /**
         * Display human-readable information about the flash
-        * bank into the given buffer.  Drivers must be careful to avoid
-        * overflowing the buffer.
+        * bank.
         *
         * @param bank - the bank to get info about
-        * @param char - where to put the text for the human to read
-        * @param buf_size - the size of the human buffer.
+        * @param cmd - command invocation instance for which to generate
+        *              the textual output
         * @returns ERROR_OK if successful; otherwise, an error code.
         */
-       int (*info)(struct flash_bank *bank, char *buf, int buf_size);
+       int (*info)(struct flash_bank *bank, struct command_invocation *cmd);
 
        /**
-        * A more gentle flavor of filash_driver_s::probe, performing
+        * A more gentle flavor of flash_driver_s::probe, performing
         * setup with less noise.  Generally, driver routines should test
         * to see if the bank has already been probed; if it has, the
         * driver probably should not perform its probe a second time.
         *
         * This callback is often called from the inside of other
         * routines (e.g. GDB flash downloads) to autoprobe the flash as
-        * it is programing the flash.
+        * it is programming the flash.
         *
         * @param bank - the bank to probe
         * @returns ERROR_OK if successful; otherwise, an error code.
         */
        int (*auto_probe)(struct flash_bank *bank);
+
+       /**
+        * Deallocates private driver structures.
+        * Use default_flash_free_driver_priv() to simply free(bank->driver_priv)
+        *
+        * @param bank - the bank being destroyed
+        */
+       void (*free_driver_priv)(struct flash_bank *bank);
 };
 
 #define FLASH_BANK_COMMAND_HANDLER(name) \
@@ -219,6 +246,6 @@ struct flash_driver {
  * @param name The name of the requested driver.
  * @returns The flash_driver called @c name, or NULL if not found.
  */
-struct flash_driver *flash_driver_find_by_name(const char *name);
+const struct flash_driver *flash_driver_find_by_name(const char *name);
 
-#endif /* FLASH_NOR_DRIVER_H */
+#endif /* OPENOCD_FLASH_NOR_DRIVER_H */