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, see <http://www.gnu.org/licenses/>. * 20 ***************************************************************************/ 21 22 #ifndef OPENOCD_FLASH_NOR_DRIVER_H 23 #define OPENOCD_FLASH_NOR_DRIVER_H 24 25 struct flash_bank; 26 27 #define __FLASH_BANK_COMMAND(name) \ 28 COMMAND_HELPER(name, struct flash_bank *bank) 29 30 /** 31 * @brief Provides the implementation-independent structure that defines 32 * all of the callbacks required by OpenOCD flash drivers. 33 * 34 * Driver authors must implement the routines defined here, providing an 35 * instance with the fields filled out. After that, the instance must 36 * be registered in flash.c, so it can be used by the driver lookup system. 37 * 38 * Specifically, the user can issue the command: @par 39 * @code 40 * flash bank DRIVERNAME ...parameters... 41 * @endcode 42 * 43 * OpenOCD will search for the driver with a @c flash_driver_s::name 44 * that matches @c DRIVERNAME. 45 * 46 * The flash subsystem calls some of the other drivers routines a using 47 * corresponding static <code>flash_driver_<i>callback</i>()</code> 48 * routine in flash.c. 49 */ 50 struct flash_driver { 51 /** 52 * Gives a human-readable name of this flash driver, 53 * This field is used to select and initialize the driver. 54 */ 55 const char *name; 56 57 /** 58 * Gives a human-readable description of arguments. 59 */ 60 const char *usage; 61 62 /** 63 * An array of driver-specific commands to register. When called 64 * during the "flash bank" command, the driver can register addition 65 * commands to support new flash chip functions. 66 */ 67 const struct command_registration *commands; 68 69 /** 70 * Finish the "flash bank" command for @a bank. The 71 * @a bank parameter will have been filled in by the core flash 72 * layer when this routine is called, and the driver can store 73 * additional information in its struct flash_bank::driver_priv field. 74 * 75 * The CMD_ARGV are: @par 76 * @code 77 * CMD_ARGV[0] = bank 78 * CMD_ARGV[1] = drivername {name above} 79 * CMD_ARGV[2] = baseaddress 80 * CMD_ARGV[3] = lengthbytes 81 * CMD_ARGV[4] = chip_width_in bytes 82 * CMD_ARGV[5] = bus_width_in_bytes 83 * CMD_ARGV[6] = driver-specific parameters 84 * @endcode 85 * 86 * For example, CMD_ARGV[4] = 2 (for 16 bit flash), 87 * CMD_ARGV[5] = 4 (for 32 bit bus). 88 * 89 * If extra arguments are provided (@a CMD_ARGC > 6), they will 90 * start in @a CMD_ARGV[6]. These can be used to implement 91 * driver-specific extensions. 92 * 93 * @returns ERROR_OK if successful; otherwise, an error code. 94 */ 95 __FLASH_BANK_COMMAND((*flash_bank_command)); 96 97 /** 98 * Bank/sector erase routine (target-specific). When 99 * called, the flash driver should erase the specified sectors 100 * using whatever means are at its disposal. 101 * 102 * @param bank The bank of flash to be erased. 103 * @param first The number of the first sector to erase, typically 0. 104 * @param last The number of the last sector to erase, typically N-1. 105 * @returns ERROR_OK if successful; otherwise, an error code. 106 */ 107 int (*erase)(struct flash_bank *bank, unsigned int first, 108 unsigned int last); 109 110 /** 111 * Bank/sector protection routine (target-specific). 112 * 113 * If protection is not implemented, set method to NULL 114 * 115 * When called, the driver should enable/disable protection 116 * for MINIMUM the range covered by first..last sectors 117 * inclusive. Some chips have alignment requirements will 118 * cause the actual range to be protected / unprotected to 119 * be larger than the first..last range. 120 * 121 * @param bank The bank to protect or unprotect. 122 * @param set If non-zero, enable protection; if 0, disable it. 123 * @param first The first sector to (un)protect, typically 0. 124 * @param last The last sector to (un)project, typically N-1. 125 * @returns ERROR_OK if successful; otherwise, an error code. 126 */ 127 int (*protect)(struct flash_bank *bank, int set, unsigned int first, 128 unsigned int last); 129 130 /** 131 * Program data into the flash. Note CPU address will be 132 * "bank->base + offset", while the physical address is 133 * dependent upon current target MMU mappings. 134 * 135 * @param bank The bank to program 136 * @param buffer The data bytes to write. 137 * @param offset The offset into the chip to program. 138 * @param count The number of bytes to write. 139 * @returns ERROR_OK if successful; otherwise, an error code. 140 */ 141 int (*write)(struct flash_bank *bank, 142 const uint8_t *buffer, uint32_t offset, uint32_t count); 143 144 /** 145 * Read data from the flash. Note CPU address will be 146 * "bank->base + offset", while the physical address is 147 * dependent upon current target MMU mappings. 148 * 149 * @param bank The bank to read. 150 * @param buffer The data bytes read. 151 * @param offset The offset into the chip to read. 152 * @param count The number of bytes to read. 153 * @returns ERROR_OK if successful; otherwise, an error code. 154 */ 155 int (*read)(struct flash_bank *bank, 156 uint8_t *buffer, uint32_t offset, uint32_t count); 157 158 /** 159 * Verify data in flash. Note CPU address will be 160 * "bank->base + offset", while the physical address is 161 * dependent upon current target MMU mappings. 162 * 163 * @param bank The bank to verify 164 * @param buffer The data bytes to verify against. 165 * @param offset The offset into the chip to verify. 166 * @param count The number of bytes to verify. 167 * @returns ERROR_OK if successful; otherwise, an error code. 168 */ 169 int (*verify)(struct flash_bank *bank, 170 const uint8_t *buffer, uint32_t offset, uint32_t count); 171 172 /** 173 * Probe to determine what kind of flash is present. 174 * This is invoked by the "probe" script command. 175 * 176 * @param bank The bank to probe 177 * @returns ERROR_OK if successful; otherwise, an error code. 178 */ 179 int (*probe)(struct flash_bank *bank); 180 181 /** 182 * Check the erasure status of a flash bank. 183 * When called, the driver routine must perform the required 184 * checks and then set the @c flash_sector_s::is_erased field 185 * for each of the flash banks's sectors. 186 * 187 * @param bank The bank to check 188 * @returns ERROR_OK if successful; otherwise, an error code. 189 */ 190 int (*erase_check)(struct flash_bank *bank); 191 192 /** 193 * Determine if the specific bank is "protected" or not. 194 * When called, the driver routine must must perform the 195 * required protection check(s) and then set the @c 196 * flash_sector_s::is_protected field for each of the flash 197 * bank's sectors. 198 * 199 * If protection is not implemented, set method to NULL 200 * 201 * @param bank - the bank to check 202 * @returns ERROR_OK if successful; otherwise, an error code. 203 */ 204 int (*protect_check)(struct flash_bank *bank); 205 206 /** 207 * Display human-readable information about the flash 208 * bank into the given buffer. Drivers must be careful to avoid 209 * overflowing the buffer. 210 * 211 * @param bank - the bank to get info about 212 * @param char - where to put the text for the human to read 213 * @param buf_size - the size of the human buffer. 214 * @returns ERROR_OK if successful; otherwise, an error code. 215 */ 216 int (*info)(struct flash_bank *bank, char *buf, int buf_size); 217 218 /** 219 * A more gentle flavor of flash_driver_s::probe, performing 220 * setup with less noise. Generally, driver routines should test 221 * to see if the bank has already been probed; if it has, the 222 * driver probably should not perform its probe a second time. 223 * 224 * This callback is often called from the inside of other 225 * routines (e.g. GDB flash downloads) to autoprobe the flash as 226 * it is programming the flash. 227 * 228 * @param bank - the bank to probe 229 * @returns ERROR_OK if successful; otherwise, an error code. 230 */ 231 int (*auto_probe)(struct flash_bank *bank); 232 233 /** 234 * Deallocates private driver structures. 235 * Use default_flash_free_driver_priv() to simply free(bank->driver_priv) 236 * 237 * @param bank - the bank being destroyed 238 */ 239 void (*free_driver_priv)(struct flash_bank *bank); 240 }; 241 242 #define FLASH_BANK_COMMAND_HANDLER(name) \ 243 static __FLASH_BANK_COMMAND(name) 244 245 /** 246 * Find a NOR flash driver by its name. 247 * @param name The name of the requested driver. 248 * @returns The flash_driver called @c name, or NULL if not found. 249 */ 250 const struct flash_driver *flash_driver_find_by_name(const char *name); 251 252 #endif /* OPENOCD_FLASH_NOR_DRIVER_H */ 253