You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

227 lines
8.5 KiB

  1. /***************************************************************************
  2. * Copyright (C) 2005 by Dominic Rath <Dominic.Rath@gmx.de> *
  3. * Copyright (C) 2007,2008 √ėyvind Harboe <oyvind.harboe@zylin.com> *
  4. * Copyright (C) 2008 by Spencer Oliver <spen@spen-soft.co.uk> *
  5. * Copyright (C) 2009 Zachary T Welch <zw@superlucidity.net> *
  6. * Copyright (C) 2010 by Antonio Borneo <borneo.antonio@gmail.com> *
  7. * *
  8. * This program is free software; you can redistribute it and/or modify *
  9. * it under the terms of the GNU General Public License as published by *
  10. * the Free Software Foundation; either version 2 of the License, or *
  11. * (at your option) any later version. *
  12. * *
  13. * This program is distributed in the hope that it will be useful, *
  14. * but WITHOUT ANY WARRANTY; without even the implied warranty of *
  15. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
  16. * GNU General Public License for more details. *
  17. * *
  18. * You should have received a copy of the GNU General Public License *
  19. * along with this program; if not, write to the *
  20. * Free Software Foundation, Inc., *
  21. * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. *
  22. ***************************************************************************/
  23. #ifndef FLASH_NOR_DRIVER_H
  24. #define FLASH_NOR_DRIVER_H
  25. struct flash_bank;
  26. #define __FLASH_BANK_COMMAND(name) \
  27. COMMAND_HELPER(name, struct flash_bank *bank)
  28. /**
  29. * @brief Provides the implementation-independent structure that defines
  30. * all of the callbacks required by OpenOCD flash drivers.
  31. *
  32. * Driver authors must implement the routines defined here, providing an
  33. * instance with the fields filled out. After that, the instance must
  34. * be registered in flash.c, so it can be used by the driver lookup system.
  35. *
  36. * Specifically, the user can issue the command: @par
  37. * @code
  38. * flash bank DRIVERNAME ...parameters...
  39. * @endcode
  40. *
  41. * OpenOCD will search for the driver with a @c flash_driver_s::name
  42. * that matches @c DRIVERNAME.
  43. *
  44. * The flash subsystem calls some of the other drivers routines a using
  45. * corresponding static <code>flash_driver_<i>callback</i>()</code>
  46. * routine in flash.c.
  47. */
  48. struct flash_driver {
  49. /**
  50. * Gives a human-readable name of this flash driver,
  51. * This field is used to select and initialize the driver.
  52. */
  53. const char *name;
  54. /**
  55. * Gives a human-readable description of arguments.
  56. */
  57. const char *usage;
  58. /**
  59. * An array of driver-specific commands to register. When called
  60. * during the "flash bank" command, the driver can register addition
  61. * commands to support new flash chip functions.
  62. */
  63. const struct command_registration *commands;
  64. /**
  65. * Finish the "flash bank" command for @a bank. The
  66. * @a bank parameter will have been filled in by the core flash
  67. * layer when this routine is called, and the driver can store
  68. * additional information in its struct flash_bank::driver_priv field.
  69. *
  70. * The CMD_ARGV are: @par
  71. * @code
  72. * CMD_ARGV[0] = bank
  73. * CMD_ARGV[1] = drivername {name above}
  74. * CMD_ARGV[2] = baseaddress
  75. * CMD_ARGV[3] = lengthbytes
  76. * CMD_ARGV[4] = chip_width_in bytes
  77. * CMD_ARGV[5] = bus_width_in_bytes
  78. * CMD_ARGV[6] = driver-specific parameters
  79. * @endcode
  80. *
  81. * For example, CMD_ARGV[4] = 2 (for 16 bit flash),
  82. * CMD_ARGV[5] = 4 (for 32 bit bus).
  83. *
  84. * If extra arguments are provided (@a CMD_ARGC > 6), they will
  85. * start in @a CMD_ARGV[6]. These can be used to implement
  86. * driver-specific extensions.
  87. *
  88. * @returns ERROR_OK if successful; otherwise, an error code.
  89. */
  90. __FLASH_BANK_COMMAND((*flash_bank_command));
  91. /**
  92. * Bank/sector erase routine (target-specific). When
  93. * called, the flash driver should erase the specified sectors
  94. * using whatever means are at its disposal.
  95. *
  96. * @param bank The bank of flash to be erased.
  97. * @param first The number of the first sector to erase, typically 0.
  98. * @param last The number of the last sector to erase, typically N-1.
  99. * @returns ERROR_OK if successful; otherwise, an error code.
  100. */
  101. int (*erase)(struct flash_bank *bank, int first, int last);
  102. /**
  103. * Bank/sector protection routine (target-specific).
  104. *
  105. * When called, the driver should enable/disable protection
  106. * for MINIMUM the range covered by first..last sectors
  107. * inclusive. Some chips have alignment requirements will
  108. * cause the actual range to be protected / unprotected to
  109. * be larger than the first..last range.
  110. *
  111. * @param bank The bank to protect or unprotect.
  112. * @param set If non-zero, enable protection; if 0, disable it.
  113. * @param first The first sector to (un)protect, typicaly 0.
  114. * @param last The last sector to (un)project, typically N-1.
  115. * @returns ERROR_OK if successful; otherwise, an error code.
  116. */
  117. int (*protect)(struct flash_bank *bank, int set, int first, int last);
  118. /**
  119. * Program data into the flash. Note CPU address will be
  120. * "bank->base + offset", while the physical address is
  121. * dependent upon current target MMU mappings.
  122. *
  123. * @param bank The bank to program
  124. * @param buffer The data bytes to write.
  125. * @param offset The offset into the chip to program.
  126. * @param count The number of bytes to write.
  127. * @returns ERROR_OK if successful; otherwise, an error code.
  128. */
  129. int (*write)(struct flash_bank *bank,
  130. uint8_t *buffer, uint32_t offset, uint32_t count);
  131. /**
  132. * Read data from the flash. Note CPU address will be
  133. * "bank->base + offset", while the physical address is
  134. * dependent upon current target MMU mappings.
  135. *
  136. * @param bank The bank to read.
  137. * @param buffer The data bytes read.
  138. * @param offset The offset into the chip to read.
  139. * @param count The number of bytes to read.
  140. * @returns ERROR_OK if successful; otherwise, an error code.
  141. */
  142. int (*read)(struct flash_bank *bank,
  143. uint8_t *buffer, uint32_t offset, uint32_t count);
  144. /**
  145. * Probe to determine what kind of flash is present.
  146. * This is invoked by the "probe" script command.
  147. *
  148. * @param bank The bank to probe
  149. * @returns ERROR_OK if successful; otherwise, an error code.
  150. */
  151. int (*probe)(struct flash_bank *bank);
  152. /**
  153. * Check the erasure status of a flash bank.
  154. * When called, the driver routine must perform the required
  155. * checks and then set the @c flash_sector_s::is_erased field
  156. * for each of the flash banks's sectors.
  157. *
  158. * @param bank The bank to check
  159. * @returns ERROR_OK if successful; otherwise, an error code.
  160. */
  161. int (*erase_check)(struct flash_bank *bank);
  162. /**
  163. * Determine if the specific bank is "protected" or not.
  164. * When called, the driver routine must must perform the
  165. * required protection check(s) and then set the @c
  166. * flash_sector_s::is_protected field for each of the flash
  167. * bank's sectors.
  168. *
  169. * @param bank - the bank to check
  170. * @returns ERROR_OK if successful; otherwise, an error code.
  171. */
  172. int (*protect_check)(struct flash_bank *bank);
  173. /**
  174. * Display human-readable information about the flash
  175. * bank into the given buffer. Drivers must be careful to avoid
  176. * overflowing the buffer.
  177. *
  178. * @param bank - the bank to get info about
  179. * @param char - where to put the text for the human to read
  180. * @param buf_size - the size of the human buffer.
  181. * @returns ERROR_OK if successful; otherwise, an error code.
  182. */
  183. int (*info)(struct flash_bank *bank, char *buf, int buf_size);
  184. /**
  185. * A more gentle flavor of filash_driver_s::probe, performing
  186. * setup with less noise. Generally, driver routines should test
  187. * to see if the bank has already been probed; if it has, the
  188. * driver probably should not perform its probe a second time.
  189. *
  190. * This callback is often called from the inside of other
  191. * routines (e.g. GDB flash downloads) to autoprobe the flash as
  192. * it is programing the flash.
  193. *
  194. * @param bank - the bank to probe
  195. * @returns ERROR_OK if successful; otherwise, an error code.
  196. */
  197. int (*auto_probe)(struct flash_bank *bank);
  198. };
  199. #define FLASH_BANK_COMMAND_HANDLER(name) \
  200. static __FLASH_BANK_COMMAND(name)
  201. /**
  202. * Find a NOR flash driver by its name.
  203. * @param name The name of the requested driver.
  204. * @returns The flash_driver called @c name, or NULL if not found.
  205. */
  206. struct flash_driver *flash_driver_find_by_name(const char *name);
  207. #endif /* FLASH_NOR_DRIVER_H */