flash/nor: implement flash bank deallocation on OpenOCD exit
[openocd.git] / src / flash / nor / driver.h
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, int first, int last);
108
109 /**
110 * Bank/sector protection routine (target-specific).
111 *
112 * When called, the driver should enable/disable protection
113 * for MINIMUM the range covered by first..last sectors
114 * inclusive. Some chips have alignment requirements will
115 * cause the actual range to be protected / unprotected to
116 * be larger than the first..last range.
117 *
118 * @param bank The bank to protect or unprotect.
119 * @param set If non-zero, enable protection; if 0, disable it.
120 * @param first The first sector to (un)protect, typicaly 0.
121 * @param last The last sector to (un)project, typically N-1.
122 * @returns ERROR_OK if successful; otherwise, an error code.
123 */
124 int (*protect)(struct flash_bank *bank, int set, int first, int last);
125
126 /**
127 * Program data into the flash. Note CPU address will be
128 * "bank->base + offset", while the physical address is
129 * dependent upon current target MMU mappings.
130 *
131 * @param bank The bank to program
132 * @param buffer The data bytes to write.
133 * @param offset The offset into the chip to program.
134 * @param count The number of bytes to write.
135 * @returns ERROR_OK if successful; otherwise, an error code.
136 */
137 int (*write)(struct flash_bank *bank,
138 const uint8_t *buffer, uint32_t offset, uint32_t count);
139
140 /**
141 * Read data from the flash. Note CPU address will be
142 * "bank->base + offset", while the physical address is
143 * dependent upon current target MMU mappings.
144 *
145 * @param bank The bank to read.
146 * @param buffer The data bytes read.
147 * @param offset The offset into the chip to read.
148 * @param count The number of bytes to read.
149 * @returns ERROR_OK if successful; otherwise, an error code.
150 */
151 int (*read)(struct flash_bank *bank,
152 uint8_t *buffer, uint32_t offset, uint32_t count);
153
154 /**
155 * Probe to determine what kind of flash is present.
156 * This is invoked by the "probe" script command.
157 *
158 * @param bank The bank to probe
159 * @returns ERROR_OK if successful; otherwise, an error code.
160 */
161 int (*probe)(struct flash_bank *bank);
162
163 /**
164 * Check the erasure status of a flash bank.
165 * When called, the driver routine must perform the required
166 * checks and then set the @c flash_sector_s::is_erased field
167 * for each of the flash banks's sectors.
168 *
169 * @param bank The bank to check
170 * @returns ERROR_OK if successful; otherwise, an error code.
171 */
172 int (*erase_check)(struct flash_bank *bank);
173
174 /**
175 * Determine if the specific bank is "protected" or not.
176 * When called, the driver routine must must perform the
177 * required protection check(s) and then set the @c
178 * flash_sector_s::is_protected field for each of the flash
179 * bank's sectors.
180 *
181 * @param bank - the bank to check
182 * @returns ERROR_OK if successful; otherwise, an error code.
183 */
184 int (*protect_check)(struct flash_bank *bank);
185
186 /**
187 * Display human-readable information about the flash
188 * bank into the given buffer. Drivers must be careful to avoid
189 * overflowing the buffer.
190 *
191 * @param bank - the bank to get info about
192 * @param char - where to put the text for the human to read
193 * @param buf_size - the size of the human buffer.
194 * @returns ERROR_OK if successful; otherwise, an error code.
195 */
196 int (*info)(struct flash_bank *bank, char *buf, int buf_size);
197
198 /**
199 * A more gentle flavor of filash_driver_s::probe, performing
200 * setup with less noise. Generally, driver routines should test
201 * to see if the bank has already been probed; if it has, the
202 * driver probably should not perform its probe a second time.
203 *
204 * This callback is often called from the inside of other
205 * routines (e.g. GDB flash downloads) to autoprobe the flash as
206 * it is programing the flash.
207 *
208 * @param bank - the bank to probe
209 * @returns ERROR_OK if successful; otherwise, an error code.
210 */
211 int (*auto_probe)(struct flash_bank *bank);
212
213 /**
214 * Deallocates private driver structures.
215 * Use default_flash_free_driver_priv() to simply free(bank->driver_priv)
216 *
217 * @param bank - the bank being destroyed
218 */
219 void (*free_driver_priv)(struct flash_bank *bank);
220 };
221
222 #define FLASH_BANK_COMMAND_HANDLER(name) \
223 static __FLASH_BANK_COMMAND(name)
224
225 /**
226 * Find a NOR flash driver by its name.
227 * @param name The name of the requested driver.
228 * @returns The flash_driver called @c name, or NULL if not found.
229 */
230 struct flash_driver *flash_driver_find_by_name(const char *name);
231
232 #endif /* OPENOCD_FLASH_NOR_DRIVER_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)