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