7f5875edde3dd79a2ac331748c81243c8c9629b8
[openocd.git] / src / flash / flash.h
1 /***************************************************************************
2 * Copyright (C) 2005 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
4 * *
5 * Copyright (C) 2007,2008 √ėyvind Harboe *
6 * oyvind.harboe@zylin.com *
7 * *
8 * Copyright (C) 2008 by Spencer Oliver *
9 * spen@spen-soft.co.uk *
10 * *
11 * This program is free software; you can redistribute it and/or modify *
12 * it under the terms of the GNU General Public License as published by *
13 * the Free Software Foundation; either version 2 of the License, or *
14 * (at your option) any later version. *
15 * *
16 * This program is distributed in the hope that it will be useful, *
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
19 * GNU General Public License for more details. *
20 * *
21 * You should have received a copy of the GNU General Public License *
22 * along with this program; if not, write to the *
23 * Free Software Foundation, Inc., *
24 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
25 ***************************************************************************/
26 #ifndef FLASH_H
27 #define FLASH_H
28
29 #include "target.h"
30 #include "log.h"
31
32 struct image_s;
33
34 #define FLASH_MAX_ERROR_STR (128)
35
36 /**
37 * Describes the geometry and status of a single flash sector
38 * within a flash bank. A single bank typically consists of multiple
39 * sectors, each of which can be erased and protected independently.
40 */
41 typedef struct flash_sector_s
42 {
43 /// Bus offset from start of the flash chip (in bytes).
44 uint32_t offset;
45 /// Number of bytes in this flash sector.
46 uint32_t size;
47 /**
48 * Indication of erasure status: 0 = not erased, 1 = erased,
49 * other = unknown. Set by @c flash_driver_s::erase_check.
50 */
51 int is_erased;
52 /**
53 * Indication of protection status: 0 = unprotected/unlocked,
54 * 1 = protected/locked, other = unknown. Set by
55 * @c flash_driver_s::protect_check.
56 */
57 int is_protected;
58 } flash_sector_t;
59
60 struct flash_bank_s;
61
62 /**
63 * @brief Provides the implementation-independent structure that defines
64 * all of the callbacks required by OpenOCD flash drivers.
65 *
66 * Driver authors must implement the routines defined here, providing an
67 * instance with the fields filled out. After that, the instance must
68 * be registered in flash.c, so it can be used by the driver lookup system.
69 *
70 * Specifically, the user can issue the command: @par
71 * @code
72 * flash bank DRIVERNAME ...parameters...
73 * @endcode
74 *
75 * OpenOCD will search for the driver with a @c flash_driver_s::name
76 * that matches @c DRIVERNAME.
77 *
78 * The flash subsystem calls some of the other drivers routines a using
79 * corresponding static <code>flash_driver_<i>callback</i>()</code>
80 * routine in flash.c.
81 */
82 typedef struct flash_driver_s
83 {
84 /**
85 * Gives a human-readable name of this flash driver,
86 * This field is used to select and initialize the driver.
87 */
88 char *name;
89
90 /**
91 * Registers driver-specific commands. When called (during the
92 * "flash bank" command), the driver may register addition
93 * commands to support new flash chip functions.
94 *
95 * @returns ERROR_OK if successful; otherwise, an error code.
96 */
97 int (*register_commands)(struct command_context_s *cmd_ctx);
98
99 /**
100 * Finish the "flash bank" command for @a bank. The
101 * @a bank parameter will have been filled in by the core flash
102 * layer when this routine is called, and the driver can store
103 * additional information in its flash_bank_t::driver_priv field.
104 *
105 * The args are: @par
106 * @code
107 * args[0] = bank
108 * args[1] = drivername {name above}
109 * args[2] = baseaddress
110 * args[3] = lengthbytes
111 * args[4] = chip_width_in bytes
112 * args[5] = bus_width_bytes
113 * args[6] = driver-specific parameters
114 * @endcode
115 *
116 * For example, args[4] = 16 bit flash, args[5] = 32bit bus.
117 *
118 * If extra arguments are provided (@a argc > 6), they will
119 * start in @a args[6]. These can be used to implement
120 * driver-specific extensions.
121 *
122 * @returns ERROR_OK if successful; otherwise, an error code.
123 */
124 int (*flash_bank_command)(struct command_context_s *cmd_ctx,
125 char *cmd, char **args, int argc, struct flash_bank_s *bank);
126
127 /**
128 * Bank/sector erase routine (target-specific). When
129 * called, the flash driver should erase the specified sectors
130 * using whatever means are at its disposal.
131 *
132 * @param bank The bank of flash to be erased.
133 * @param first The number of the first sector to erase, typically 0.
134 * @param last The number of the last sector to erase, typically N-1.
135 * @returns ERROR_OK if successful; otherwise, an error code.
136 */
137 int (*erase)(struct flash_bank_s *bank, int first, int last);
138
139 /**
140 * Bank/sector protection routine (target-specific).
141 * When called, the driver should disable 'flash write' bits (or
142 * enable 'erase protection' bits) for the given @a bank and @a
143 * sectors.
144 *
145 * @param bank The bank to protect or unprotect.
146 * @param set If non-zero, enable protection; if 0, disable it.
147 * @param first The first sector to (un)protect, typicaly 0.
148 * @param last The last sector to (un)project, typically N-1.
149 * @returns ERROR_OK if successful; otherwise, an error code.
150 */
151 int (*protect)(struct flash_bank_s *bank, int set, int first, int last);
152
153 /**
154 * Program data into the flash. Note CPU address will be
155 * "bank->base + offset", while the physical address is
156 * dependent upon current target MMU mappings.
157 *
158 * @param bank The bank to program
159 * @param buffer The data bytes to write.
160 * @param offset The offset into the chip to program.
161 * @param count The number of bytes to write.
162 * @returns ERROR_OK if successful; otherwise, an error code.
163 */
164 int (*write)(struct flash_bank_s *bank,
165 uint8_t *buffer, uint32_t offset, uint32_t count);
166
167 /**
168 * Probe to determine what kind of flash is present.
169 * This is invoked by the "probe" script command.
170 *
171 * @param bank The bank to probe
172 * @returns ERROR_OK if successful; otherwise, an error code.
173 */
174 int (*probe)(struct flash_bank_s *bank);
175
176 /**
177 * Check the erasure status of a flash bank.
178 * When called, the driver routine must perform the required
179 * checks and then set the @c flash_sector_s::is_erased field
180 * for each of the flash banks's sectors.
181 *
182 * @param bank The bank to check
183 * @returns ERROR_OK if successful; otherwise, an error code.
184 */
185 int (*erase_check)(struct flash_bank_s *bank);
186
187 /**
188 * Determine if the specific bank is "protected" or not.
189 * When called, the driver routine must must perform the
190 * required protection check(s) and then set the @c
191 * flash_sector_s::is_protected field for each of the flash
192 * bank's sectors.
193 *
194 * @param bank - the bank to check
195 * @returns ERROR_OK if successful; otherwise, an error code.
196 */
197 int (*protect_check)(struct flash_bank_s *bank);
198
199 /**
200 * Display human-readable information about the flash
201 * bank into the given buffer. Drivers must be careful to avoid
202 * overflowing the buffer.
203 *
204 * @param bank - the bank to get info about
205 * @param char - where to put the text for the human to read
206 * @param buf_size - the size of the human buffer.
207 * @returns ERROR_OK if successful; otherwise, an error code.
208 */
209 int (*info)(struct flash_bank_s *bank, char *buf, int buf_size);
210
211 /**
212 * A more gentle flavor of filash_driver_s::probe, performing
213 * setup with less noise. Generally, driver routines should test
214 * to seee if the bank has already been probed; if it has, the
215 * driver probably should not perform its probe a second time.
216 *
217 * This callback is often called from the inside of other
218 * routines (e.g. GDB flash downloads) to autoprobe the flash as
219 * it is programing the flash.
220 *
221 * @param bank - the bank to probe
222 * @returns ERROR_OK if successful; otherwise, an error code.
223 */
224 int (*auto_probe)(struct flash_bank_s *bank);
225 } flash_driver_t;
226
227 /**
228 * Provides details of a flash bank, available either on-chip or through
229 * a major interface.
230 *
231 * This structure will be passed as a parameter to the callbacks in the
232 * flash_driver_s structure, some of which may modify the contents of
233 * this structure of the area of flash that it defines. Driver writers
234 * may use the @c driver_priv member to store additional data on a
235 * per-bank basis, if required.
236 */
237 typedef struct flash_bank_s
238 {
239 struct target_s *target; /**< Target to which this bank belongs. */
240
241 flash_driver_t *driver; /**< Driver for this bank. */
242 void *driver_priv; /**< Private driver storage pointer */
243
244 int bank_number; /**< The 'bank' (or chip number) of this instance. */
245 uint32_t base; /**< The base address of this bank */
246 uint32_t size; /**< The size of this chip bank, in bytes */
247
248 int chip_width; /**< Width of the chip in bytes (1,2,4 bytes) */
249 int bus_width; /**< Maximum bus width, in bytes (1,2,4 bytes) */
250
251 /**
252 * The number of sectors on this chip. This value will
253 * be set intially to 0, and the flash driver must set this to
254 * some non-zero value during "probe()" or "auto_probe()".
255 */
256 int num_sectors;
257 /// Array of sectors, allocated and initilized by the flash driver
258 flash_sector_t *sectors;
259
260 struct flash_bank_s *next; /**< The next flash bank on this chip */
261 } flash_bank_t;
262
263 /// Registers the 'flash' subsystem commands
264 int flash_register_commands(struct command_context_s *cmd_ctx);
265 /// Initializes the 'flash' subsystem drivers
266 int flash_init_drivers(struct command_context_s *cmd_ctx);
267
268 /**
269 * Erases @a length bytes in the @a target flash, starting at @a addr.
270 * @returns ERROR_OK if successful; otherwise, an error code.
271 */
272 int flash_erase_address_range(struct target_s *target,
273 uint32_t addr, uint32_t length);
274 /**
275 * Writes @a image into the @a target flash. The @a written parameter
276 * will contain the
277 * @param target The target with the flash to be programmed.
278 * @param image The image that will be programmed to flash.
279 * @param written On return, contains the number of bytes written.
280 * @param erase If non-zero, indicates the flash driver should first
281 * erase the corresponding banks or sectors before programming.
282 * @returns ERROR_OK if successful; otherwise, an error code.
283 */
284 int flash_write(struct target_s *target,
285 struct image_s *image, uint32_t *written, int erase);
286 /**
287 * Forces targets to re-examine their erase/protection state.
288 * This routine must be called when the system may modify the status.
289 */
290 void flash_set_dirty(void);
291 /// @returns The number of flash banks currently defined.
292 int flash_get_bank_count(void);
293 /**
294 * Provides default erased-bank check handling. Checks to see if
295 * the flash driver knows they are erased; if things look uncertain,
296 * this routine will call default_flash_mem_blank_check() to confirm.
297 * @returns ERROR_OK if successful; otherwise, an error code.
298 */
299 int default_flash_blank_check(struct flash_bank_s *bank);
300 /**
301 * Provides a default blank flash memory check. Ensures the contents
302 * of the given bank have truly been erased.
303 * @param bank The flash bank.
304 * @returns ERROR_OK if successful; otherwise, an error code.
305 */
306 int default_flash_mem_blank_check(struct flash_bank_s *bank);
307
308 /**
309 * Returns a flash bank by the specified flash_bank_s bank_number, @a num.
310 * @param num The flash bank number.
311 * @returns A flash_bank_t for flash bank @a num, or NULL
312 */
313 flash_bank_t *get_flash_bank_by_num(int num);
314 /**
315 * Retreives @a bank from a command argument, reporting errors parsing
316 * the bank identifier or retreiving the specified bank.
317 * @param cmd_ctx The command context for reporting errors.
318 * @param str The string containing the bank identifier.
319 * @param bank On output, contians a pointer to the bank or NULL.
320 * @returns ERROR_OK on success, or an error indicating the problem.
321 */
322 int flash_command_get_bank_by_num(struct command_context_s *cmd_ctx,
323 const char *str, flash_bank_t **bank);
324 /**
325 * Returns the flash bank like get_flash_bank_by_num(), without probing.
326 * @param num The flash bank number.
327 * @returns A flash_bank_t for flash bank @a num, or NULL.
328 */
329 flash_bank_t *get_flash_bank_by_num_noprobe(int num);
330 /**
331 * Returns the flash bank located at a specified address.
332 * @param target The target, presumed to contain one or more banks.
333 * @param addr An address that is within the range of the bank.
334 * @returns The flash_bank_t located at @a addr, or NULL.
335 */
336 flash_bank_t *get_flash_bank_by_addr(struct target_s *target, uint32_t addr);
337
338 #define ERROR_FLASH_BANK_INVALID (-900)
339 #define ERROR_FLASH_SECTOR_INVALID (-901)
340 #define ERROR_FLASH_OPERATION_FAILED (-902)
341 #define ERROR_FLASH_DST_OUT_OF_BANK (-903)
342 #define ERROR_FLASH_DST_BREAKS_ALIGNMENT (-904)
343 #define ERROR_FLASH_BUSY (-905)
344 #define ERROR_FLASH_SECTOR_NOT_ERASED (-906)
345 #define ERROR_FLASH_BANK_NOT_PROBED (-907)
346
347 #endif /* FLASH_H */

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read https://review.openocd.org/login/?link to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)