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