1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3 /***************************************************************************
4 * Copyright (C) 2005 by Dominic Rath <Dominic.Rath@gmx.de> *
5 * Copyright (C) 2007,2008 Øyvind Harboe <oyvind.harboe@zylin.com> *
6 * Copyright (C) 2008 by Spencer Oliver <spen@spen-soft.co.uk> *
7 * Copyright (C) 2009 Zachary T Welch <zw@superlucidity.net> *
8 * Copyright (C) 2010 by Antonio Borneo <borneo.antonio@gmail.com> *
9 ***************************************************************************/
11 #ifndef OPENOCD_FLASH_NOR_DRIVER_H
12 #define OPENOCD_FLASH_NOR_DRIVER_H
16 #define __FLASH_BANK_COMMAND(name) \
17 COMMAND_HELPER(name, struct flash_bank *bank)
20 * @brief Provides the implementation-independent structure that defines
21 * all of the callbacks required by OpenOCD flash drivers.
23 * Driver authors must implement the routines defined here, providing an
24 * instance with the fields filled out. After that, the instance must
25 * be registered in flash.c, so it can be used by the driver lookup system.
27 * Specifically, the user can issue the command: @par
29 * flash bank DRIVERNAME ...parameters...
32 * OpenOCD will search for the driver with a @c flash_driver::name
33 * that matches @c DRIVERNAME.
35 * The flash subsystem calls some of the other drivers routines a using
36 * corresponding static <code>flash_driver_<i>callback</i>()</code>
41 * Gives a human-readable name of this flash driver,
42 * This field is used to select and initialize the driver.
47 * Gives a human-readable description of arguments.
52 * An array of driver-specific commands to register. When called
53 * during the "flash bank" command, the driver can register addition
54 * commands to support new flash chip functions.
56 const struct command_registration
*commands
;
59 * Finish the "flash bank" command for @a bank. The
60 * @a bank parameter will have been filled in by the core flash
61 * layer when this routine is called, and the driver can store
62 * additional information in its struct flash_bank::driver_priv field.
64 * The CMD_ARGV are: @par
67 * CMD_ARGV[1] = drivername {name above}
68 * CMD_ARGV[2] = baseaddress
69 * CMD_ARGV[3] = lengthbytes
70 * CMD_ARGV[4] = chip_width_in bytes
71 * CMD_ARGV[5] = bus_width_in_bytes
72 * CMD_ARGV[6] = driver-specific parameters
75 * For example, CMD_ARGV[4] = 2 (for 16 bit flash),
76 * CMD_ARGV[5] = 4 (for 32 bit bus).
78 * If extra arguments are provided (@a CMD_ARGC > 6), they will
79 * start in @a CMD_ARGV[6]. These can be used to implement
80 * driver-specific extensions.
82 * @returns ERROR_OK if successful; otherwise, an error code.
84 __FLASH_BANK_COMMAND((*flash_bank_command
));
87 * Bank/sector erase routine (target-specific). When
88 * called, the flash driver should erase the specified sectors
89 * using whatever means are at its disposal.
91 * @param bank The bank of flash to be erased.
92 * @param first The number of the first sector to erase, typically 0.
93 * @param last The number of the last sector to erase, typically N-1.
94 * @returns ERROR_OK if successful; otherwise, an error code.
96 int (*erase
)(struct flash_bank
*bank
, unsigned int first
,
100 * Bank/sector protection routine (target-specific).
102 * If protection is not implemented, set method to NULL
104 * When called, the driver should enable/disable protection
105 * for MINIMUM the range covered by first..last sectors
106 * inclusive. Some chips have alignment requirements will
107 * cause the actual range to be protected / unprotected to
108 * be larger than the first..last range.
110 * @param bank The bank to protect or unprotect.
111 * @param set If non-zero, enable protection; if 0, disable it.
112 * @param first The first sector to (un)protect, typically 0.
113 * @param last The last sector to (un)project, typically N-1.
114 * @returns ERROR_OK if successful; otherwise, an error code.
116 int (*protect
)(struct flash_bank
*bank
, int set
, unsigned int first
,
120 * Program data into the flash. Note CPU address will be
121 * "bank->base + offset", while the physical address is
122 * dependent upon current target MMU mappings.
124 * @param bank The bank to program
125 * @param buffer The data bytes to write.
126 * @param offset The offset into the chip to program.
127 * @param count The number of bytes to write.
128 * @returns ERROR_OK if successful; otherwise, an error code.
130 int (*write
)(struct flash_bank
*bank
,
131 const uint8_t *buffer
, uint32_t offset
, uint32_t count
);
134 * Read data from the flash. Note CPU address will be
135 * "bank->base + offset", while the physical address is
136 * dependent upon current target MMU mappings.
138 * @param bank The bank to read.
139 * @param buffer The data bytes read.
140 * @param offset The offset into the chip to read.
141 * @param count The number of bytes to read.
142 * @returns ERROR_OK if successful; otherwise, an error code.
144 int (*read
)(struct flash_bank
*bank
,
145 uint8_t *buffer
, uint32_t offset
, uint32_t count
);
148 * Verify data in flash. Note CPU address will be
149 * "bank->base + offset", while the physical address is
150 * dependent upon current target MMU mappings.
152 * @param bank The bank to verify
153 * @param buffer The data bytes to verify against.
154 * @param offset The offset into the chip to verify.
155 * @param count The number of bytes to verify.
156 * @returns ERROR_OK if successful; otherwise, an error code.
158 int (*verify
)(struct flash_bank
*bank
,
159 const uint8_t *buffer
, uint32_t offset
, uint32_t count
);
162 * Probe to determine what kind of flash is present.
163 * This is invoked by the "probe" script command.
165 * @param bank The bank to probe
166 * @returns ERROR_OK if successful; otherwise, an error code.
168 int (*probe
)(struct flash_bank
*bank
);
171 * Check the erasure status of a flash bank.
172 * When called, the driver routine must perform the required
173 * checks and then set the @c flash_sector::is_erased field
174 * for each of the flash banks's sectors.
176 * @param bank The bank to check
177 * @returns ERROR_OK if successful; otherwise, an error code.
179 int (*erase_check
)(struct flash_bank
*bank
);
182 * Determine if the specific bank is "protected" or not.
183 * When called, the driver routine must must perform the
184 * required protection check(s) and then set the @c
185 * flash_sector::is_protected field for each of the flash
188 * If protection is not implemented, set method to NULL
190 * @param bank - the bank to check
191 * @returns ERROR_OK if successful; otherwise, an error code.
193 int (*protect_check
)(struct flash_bank
*bank
);
196 * Display human-readable information about the flash
199 * @param bank - the bank to get info about
200 * @param cmd - command invocation instance for which to generate
202 * @returns ERROR_OK if successful; otherwise, an error code.
204 int (*info
)(struct flash_bank
*bank
, struct command_invocation
*cmd
);
207 * A more gentle flavor of flash_driver::probe, performing
208 * setup with less noise. Generally, driver routines should test
209 * to see if the bank has already been probed; if it has, the
210 * driver probably should not perform its probe a second time.
212 * This callback is often called from the inside of other
213 * routines (e.g. GDB flash downloads) to autoprobe the flash as
214 * it is programming the flash.
216 * @param bank - the bank to probe
217 * @returns ERROR_OK if successful; otherwise, an error code.
219 int (*auto_probe
)(struct flash_bank
*bank
);
222 * Deallocates private driver structures.
223 * Use default_flash_free_driver_priv() to simply free(bank->driver_priv)
225 * @param bank - the bank being destroyed
227 void (*free_driver_priv
)(struct flash_bank
*bank
);
230 #define FLASH_BANK_COMMAND_HANDLER(name) \
231 static __FLASH_BANK_COMMAND(name)
234 * Find a NOR flash driver by its name.
235 * @param name The name of the requested driver.
236 * @returns The flash_driver called @c name, or NULL if not found.
238 const struct flash_driver
*flash_driver_find_by_name(const char *name
);
240 extern const struct flash_driver aduc702x_flash
;
241 extern const struct flash_driver aducm360_flash
;
242 extern const struct flash_driver ambiqmicro_flash
;
243 extern const struct flash_driver at91sam3_flash
;
244 extern const struct flash_driver at91sam4_flash
;
245 extern const struct flash_driver at91sam4l_flash
;
246 extern const struct flash_driver at91sam7_flash
;
247 extern const struct flash_driver at91samd_flash
;
248 extern const struct flash_driver ath79_flash
;
249 extern const struct flash_driver atsame5_flash
;
250 extern const struct flash_driver atsamv_flash
;
251 extern const struct flash_driver avr_flash
;
252 extern const struct flash_driver bluenrgx_flash
;
253 extern const struct flash_driver cc26xx_flash
;
254 extern const struct flash_driver cc3220sf_flash
;
255 extern const struct flash_driver cfi_flash
;
256 extern const struct flash_driver dsp5680xx_flash
;
257 extern const struct flash_driver efm32_flash
;
258 extern const struct flash_driver em357_flash
;
259 extern const struct flash_driver eneispif_flash
;
260 extern const struct flash_driver esirisc_flash
;
261 extern const struct flash_driver faux_flash
;
262 extern const struct flash_driver fespi_flash
;
263 extern const struct flash_driver fm3_flash
;
264 extern const struct flash_driver fm4_flash
;
265 extern const struct flash_driver jtagspi_flash
;
266 extern const struct flash_driver kinetis_flash
;
267 extern const struct flash_driver kinetis_ke_flash
;
268 extern const struct flash_driver lpc2000_flash
;
269 extern const struct flash_driver lpc288x_flash
;
270 extern const struct flash_driver lpc2900_flash
;
271 extern const struct flash_driver lpcspifi_flash
;
272 extern const struct flash_driver max32xxx_flash
;
273 extern const struct flash_driver mdr_flash
;
274 extern const struct flash_driver mrvlqspi_flash
;
275 extern const struct flash_driver msp432_flash
;
276 extern const struct flash_driver niietcm4_flash
;
277 extern const struct flash_driver npcx_flash
;
278 extern const struct flash_driver nrf51_flash
;
279 extern const struct flash_driver nrf5_flash
;
280 extern const struct flash_driver numicro_flash
;
281 extern const struct flash_driver ocl_flash
;
282 extern const struct flash_driver pic32mx_flash
;
283 extern const struct flash_driver psoc4_flash
;
284 extern const struct flash_driver psoc5lp_eeprom_flash
;
285 extern const struct flash_driver psoc5lp_flash
;
286 extern const struct flash_driver psoc5lp_nvl_flash
;
287 extern const struct flash_driver psoc6_flash
;
288 extern const struct flash_driver qn908x_flash
;
289 extern const struct flash_driver renesas_rpchf_flash
;
290 extern const struct flash_driver rp2040_flash
;
291 extern const struct flash_driver rsl10_flash
;
292 extern const struct flash_driver sh_qspi_flash
;
293 extern const struct flash_driver sim3x_flash
;
294 extern const struct flash_driver stellaris_flash
;
295 extern const struct flash_driver stm32f1x_flash
;
296 extern const struct flash_driver stm32f2x_flash
;
297 extern const struct flash_driver stm32h7x_flash
;
298 extern const struct flash_driver stm32l4x_flash
;
299 extern const struct flash_driver stm32lx_flash
;
300 extern const struct flash_driver stmqspi_flash
;
301 extern const struct flash_driver stmsmi_flash
;
302 extern const struct flash_driver str7x_flash
;
303 extern const struct flash_driver str9x_flash
;
304 extern const struct flash_driver str9xpec_flash
;
305 extern const struct flash_driver swm050_flash
;
306 extern const struct flash_driver tms470_flash
;
307 extern const struct flash_driver virtual_flash
;
308 extern const struct flash_driver w600_flash
;
309 extern const struct flash_driver xcf_flash
;
310 extern const struct flash_driver xmc1xxx_flash
;
311 extern const struct flash_driver xmc4xxx_flash
;
313 #endif /* OPENOCD_FLASH_NOR_DRIVER_H */