flash/nor/core.h: clarify comment flash_sector::is_erased
[openocd.git] / src / flash / nor / core.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_CORE_H
23 #define OPENOCD_FLASH_NOR_CORE_H
24
25 #include <flash/common.h>
26
27 /**
28 * @file
29 * Upper level NOR flash interfaces.
30 */
31
32 struct image;
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 struct flash_sector {
42 /** Bus offset from start of the flash chip (in bytes). */
43 uint32_t offset;
44 /** Number of bytes in this flash sector. */
45 uint32_t size;
46 /**
47 * Indication of erasure status: 0 = not erased, 1 = erased,
48 * other = unknown. Set by @c flash_driver_s::erase_check only.
49 *
50 * This information must be considered stale immediately.
51 * Don't set it in flash_driver_s::erase or a device mass_erase
52 * Don't clear it in flash_driver_s::write
53 * The flag is not used in a protection block
54 */
55 int is_erased;
56 /**
57 * Indication of protection status: 0 = unprotected/unlocked,
58 * 1 = protected/locked, other = unknown. Set by
59 * @c flash_driver_s::protect_check.
60 *
61 * This information must be considered stale immediately.
62 * A million things could make it stale: power cycle,
63 * reset of target, code running on target, etc.
64 *
65 * If a flash_bank uses an extra array of protection blocks,
66 * protection flag is not valid in sector array
67 */
68 int is_protected;
69 };
70
71 /** Special value for write_start_alignment and write_end_alignment field */
72 #define FLASH_WRITE_ALIGN_SECTOR UINT32_MAX
73
74 /** Special values for minimal_write_gap field */
75 #define FLASH_WRITE_CONTINUOUS 0
76 #define FLASH_WRITE_GAP_SECTOR UINT32_MAX
77
78 /**
79 * Provides details of a flash bank, available either on-chip or through
80 * a major interface.
81 *
82 * This structure will be passed as a parameter to the callbacks in the
83 * flash_driver_s structure, some of which may modify the contents of
84 * this structure of the area of flash that it defines. Driver writers
85 * may use the @c driver_priv member to store additional data on a
86 * per-bank basis, if required.
87 */
88 struct flash_bank {
89 char *name;
90
91 struct target *target; /**< Target to which this bank belongs. */
92
93 const struct flash_driver *driver; /**< Driver for this bank. */
94 void *driver_priv; /**< Private driver storage pointer */
95
96 int bank_number; /**< The 'bank' (or chip number) of this instance. */
97 target_addr_t base; /**< The base address of this bank */
98 uint32_t size; /**< The size of this chip bank, in bytes */
99
100 int chip_width; /**< Width of the chip in bytes (1,2,4 bytes) */
101 int bus_width; /**< Maximum bus width, in bytes (1,2,4 bytes) */
102
103 /** Erased value. Defaults to 0xFF. */
104 uint8_t erased_value;
105
106 /** Default padded value used, normally this matches the flash
107 * erased value. Defaults to 0xFF. */
108 uint8_t default_padded_value;
109
110 /** Required alignment of flash write start address.
111 * Default 0, no alignment. Can be any power of two or FLASH_WRITE_ALIGN_SECTOR */
112 uint32_t write_start_alignment;
113 /** Required alignment of flash write end address.
114 * Default 0, no alignment. Can be any power of two or FLASH_WRITE_ALIGN_SECTOR */
115 uint32_t write_end_alignment;
116 /** Minimal gap between sections to discontinue flash write
117 * Default FLASH_WRITE_GAP_SECTOR splits the write if one or more untouched
118 * sectors in between.
119 * Can be size in bytes or FLASH_WRITE_CONTINUOUS */
120 uint32_t minimal_write_gap;
121
122 /**
123 * The number of sectors on this chip. This value will
124 * be set intially to 0, and the flash driver must set this to
125 * some non-zero value during "probe()" or "auto_probe()".
126 */
127 int num_sectors;
128 /** Array of sectors, allocated and initialized by the flash driver */
129 struct flash_sector *sectors;
130
131 /**
132 * The number of protection blocks in this bank. This value
133 * is set intially to 0 and sectors are used as protection blocks.
134 * Driver probe can set protection blocks array to work with
135 * protection granularity different than sector size.
136 */
137 int num_prot_blocks;
138 /** Array of protection blocks, allocated and initilized by the flash driver */
139 struct flash_sector *prot_blocks;
140
141 struct flash_bank *next; /**< The next flash bank on this chip */
142 };
143
144 /** Registers the 'flash' subsystem commands */
145 int flash_register_commands(struct command_context *cmd_ctx);
146
147 /**
148 * Erases @a length bytes in the @a target flash, starting at @a addr.
149 * The range @a addr to @a addr + @a length - 1 must be strictly
150 * sector aligned, unless @a pad is true. Setting @a pad true extends
151 * the range, at beginning and/or end, if needed for sector alignment.
152 * @returns ERROR_OK if successful; otherwise, an error code.
153 */
154 int flash_erase_address_range(struct target *target,
155 bool pad, target_addr_t addr, uint32_t length);
156
157 int flash_unlock_address_range(struct target *target, target_addr_t addr,
158 uint32_t length);
159
160 /**
161 * Align start address of a flash write region according to bank requirements.
162 * @param bank Pointer to bank descriptor structure
163 * @param addr Address to align
164 * @returns Aligned address
165 */
166 target_addr_t flash_write_align_start(struct flash_bank *bank, target_addr_t addr);
167 /**
168 * Align end address of a flash write region according to bank requirements.
169 * Note: Use address of the last byte to write, not the next after the region.
170 * @param bank Pointer to bank descriptor structure
171 * @param addr Address to align (address of the last byte to write)
172 * @returns Aligned address (address of the last byte of padded region)
173 */
174 target_addr_t flash_write_align_end(struct flash_bank *bank, target_addr_t addr);
175
176 /**
177 * Writes @a image into the @a target flash. The @a written parameter
178 * will contain the
179 * @param target The target with the flash to be programmed.
180 * @param image The image that will be programmed to flash.
181 * @param written On return, contains the number of bytes written.
182 * @param erase If non-zero, indicates the flash driver should first
183 * erase the corresponding banks or sectors before programming.
184 * @returns ERROR_OK if successful; otherwise, an error code.
185 */
186 int flash_write(struct target *target,
187 struct image *image, uint32_t *written, int erase);
188
189 /**
190 * Forces targets to re-examine their erase/protection state.
191 * This routine must be called when the system may modify the status.
192 */
193 void flash_set_dirty(void);
194
195 /** @returns The number of flash banks currently defined. */
196 int flash_get_bank_count(void);
197
198 /** Deallocates bank->driver_priv */
199 void default_flash_free_driver_priv(struct flash_bank *bank);
200
201 /** Deallocates all flash banks */
202 void flash_free_all_banks(void);
203 /**
204 * Provides default read implementation for flash memory.
205 * @param bank The bank to read.
206 * @param buffer The data bytes read.
207 * @param offset The offset into the chip to read.
208 * @param count The number of bytes to read.
209 * @returns ERROR_OK if successful; otherwise, an error code.
210 */
211 int default_flash_read(struct flash_bank *bank,
212 uint8_t *buffer, uint32_t offset, uint32_t count);
213 /**
214 * Provides default erased-bank check handling. Checks to see if
215 * the flash driver knows they are erased; if things look uncertain,
216 * this routine will call default_flash_mem_blank_check() to confirm.
217 * @returns ERROR_OK if successful; otherwise, an error code.
218 */
219 int default_flash_blank_check(struct flash_bank *bank);
220
221 /**
222 * Returns the flash bank specified by @a name, which matches the
223 * driver name and a suffix (option) specify the driver-specific
224 * bank number. The suffix consists of the '.' and the driver-specific
225 * bank number: when two str9x banks are defined, then 'str9x.1' refers
226 * to the second.
227 */
228 int get_flash_bank_by_name(const char *name, struct flash_bank **bank_result);
229 /**
230 * Returns the flash bank specified by @a name, which matches the
231 * driver name and a suffix (option) specify the driver-specific
232 * bank number. The suffix consists of the '.' and the driver-specific
233 * bank number: when two str9x banks are defined, then 'str9x.1' refers
234 * to the second.
235 */
236 struct flash_bank *get_flash_bank_by_name_noprobe(const char *name);
237 /**
238 * Returns the flash bank like get_flash_bank_by_name(), without probing.
239 * @param num The flash bank number.
240 * @param bank returned bank if fn returns ERROR_OK
241 * @returns ERROR_OK if successful
242 */
243 int get_flash_bank_by_num(int num, struct flash_bank **bank);
244 /**
245 * Retreives @a bank from a command argument, reporting errors parsing
246 * the bank identifier or retreiving the specified bank. The bank
247 * may be identified by its bank number or by @c name.instance, where
248 * @a instance is driver-specific.
249 * @param name_index The index to the string in args containing the
250 * bank identifier.
251 * @param bank On output, contians a pointer to the bank or NULL.
252 * @returns ERROR_OK on success, or an error indicating the problem.
253 */
254 COMMAND_HELPER(flash_command_get_bank, unsigned name_index,
255 struct flash_bank **bank);
256 /**
257 * Returns the flash bank like get_flash_bank_by_num(), without probing.
258 * @param num The flash bank number.
259 * @returns A struct flash_bank for flash bank @a num, or NULL.
260 */
261 struct flash_bank *get_flash_bank_by_num_noprobe(int num);
262 /**
263 * Returns the flash bank located at a specified address.
264 * @param target The target, presumed to contain one or more banks.
265 * @param addr An address that is within the range of the bank.
266 * @param check return ERROR_OK and result_bank NULL if the bank does not exist
267 * @returns The struct flash_bank located at @a addr, or NULL.
268 */
269 int get_flash_bank_by_addr(struct target *target, target_addr_t addr, bool check,
270 struct flash_bank **result_bank);
271 /**
272 * Allocate and fill an array of sectors or protection blocks.
273 * @param offset Offset of first block.
274 * @param size Size of each block.
275 * @param num_blocks Number of blocks in array.
276 * @returns A struct flash_sector pointer or NULL when allocation failed.
277 */
278 struct flash_sector *alloc_block_array(uint32_t offset, uint32_t size, int num_blocks);
279
280 #endif /* OPENOCD_FLASH_NOR_CORE_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)