flashrom 

flashrom Svn Source Tree

Root/trunk/flash.h

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
1/*
2 * This file is part of the flashrom project.
3 *
4 * Copyright (C) 2000 Silicon Integrated System Corporation
5 * Copyright (C) 2000 Ronald G. Minnich <rminnich@gmail.com>
6 * Copyright (C) 2005-2009 coresystems GmbH
7 * Copyright (C) 2006-2009 Carl-Daniel Hailfinger
8 *
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef __FLASH_H__
25#define __FLASH_H__ 1
26
27#include "platform.h"
28
29#include <inttypes.h>
30#include <stdio.h>
31#include <stdint.h>
32#include <stddef.h>
33#include <stdbool.h>
34#if IS_WINDOWS
35#include <windows.h>
36#undef min
37#undef max
38#endif
39
40#define ERROR_PTR ((void*)-1)
41
42/* Error codes */
43#define ERROR_OOM-100
44#define TIMEOUT_ERROR-101
45
46/* TODO: check using code for correct usage of types */
47typedef uintptr_t chipaddr;
48#define PRIxPTR_WIDTH ((int)(sizeof(uintptr_t)*2))
49
50/* Types and macros regarding the maximum flash space size supported by generic code. */
51typedef uint32_t chipoff_t; /* Able to store any addressable offset within a supported flash memory. */
52typedef uint32_t chipsize_t; /* Able to store the number of bytes of any supported flash memory. */
53#define FL_MAX_CHIPOFF_BITS (24)
54#define FL_MAX_CHIPOFF ((chipoff_t)(1ULL<<FL_MAX_CHIPOFF_BITS)-1)
55#define PRIxCHIPOFF "06"PRIx32
56#define PRIuCHIPSIZE PRIu32
57
58int register_shutdown(int (*function) (void *data), void *data);
59int shutdown_free(void *data);
60void *programmer_map_flash_region(const char *descr, uintptr_t phys_addr, size_t len);
61void programmer_unmap_flash_region(void *virt_addr, size_t len);
62void programmer_delay(unsigned int usecs);
63
64#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
65
66enum chipbustype {
67BUS_NONE= 0,
68BUS_PARALLEL= 1 << 0,
69BUS_LPC= 1 << 1,
70BUS_FWH= 1 << 2,
71BUS_SPI= 1 << 3,
72BUS_PROG= 1 << 4,
73BUS_NONSPI= BUS_PARALLEL | BUS_LPC | BUS_FWH,
74};
75
76/*
77 * The following enum defines possible write granularities of flash chips. These tend to reflect the properties
78 * of the actual hardware not necesserily the write function(s) defined by the respective struct flashchip.
79 * The latter might (and should) be more precisely specified, e.g. they might bail out early if their execution
80 * would result in undefined chip contents.
81 */
82enum write_granularity {
83/* We assume 256 byte granularity by default. */
84write_gran_256bytes = 0,/* If less than 256 bytes are written, the unwritten bytes are undefined. */
85write_gran_1bit,/* Each bit can be cleared individually. */
86write_gran_1byte,/* A byte can be written once. Further writes to an already written byte cause
87 * its contents to be either undefined or to stay unchanged. */
88write_gran_128bytes,/* If less than 128 bytes are written, the unwritten bytes are undefined. */
89write_gran_264bytes,/* If less than 264 bytes are written, the unwritten bytes are undefined. */
90write_gran_512bytes,/* If less than 512 bytes are written, the unwritten bytes are undefined. */
91write_gran_528bytes,/* If less than 528 bytes are written, the unwritten bytes are undefined. */
92write_gran_1024bytes,/* If less than 1024 bytes are written, the unwritten bytes are undefined. */
93write_gran_1056bytes,/* If less than 1056 bytes are written, the unwritten bytes are undefined. */
94write_gran_1byte_implicit_erase, /* EEPROMs and other chips with implicit erase and 1-byte writes. */
95};
96
97/*
98 * How many different contiguous runs of erase blocks with one size each do
99 * we have for a given erase function?
100 */
101#define NUM_ERASEREGIONS 5
102
103/*
104 * How many different erase functions do we have per chip?
105 * Atmel AT25FS010 has 6 different functions.
106 */
107#define NUM_ERASEFUNCTIONS 6
108
109/* Feature bits used for non-SPI only */
110#define FEATURE_REGISTERMAP(1 << 0)
111#define FEATURE_LONG_RESET(0 << 4)
112#define FEATURE_SHORT_RESET(1 << 4)
113#define FEATURE_EITHER_RESETFEATURE_LONG_RESET
114#define FEATURE_RESET_MASK(FEATURE_LONG_RESET | FEATURE_SHORT_RESET)
115#define FEATURE_ADDR_FULL(0 << 2)
116#define FEATURE_ADDR_MASK(3 << 2)
117#define FEATURE_ADDR_2AA(1 << 2)
118#define FEATURE_ADDR_AAA(2 << 2)
119#define FEATURE_ADDR_SHIFTED(1 << 5)
120/* Feature bits used for SPI only */
121#define FEATURE_WRSR_EWSR(1 << 6)
122#define FEATURE_WRSR_WREN(1 << 7)
123#define FEATURE_WRSR_EITHER(FEATURE_WRSR_EWSR | FEATURE_WRSR_WREN)
124#define FEATURE_OTP(1 << 8)
125#define FEATURE_QPI(1 << 9)
126
127enum test_state {
128OK = 0,
129NT = 1,/* Not tested */
130BAD,/* Known to not work */
131DEP,/* Support depends on configuration (e.g. Intel flash descriptor) */
132NA,/* Not applicable (e.g. write support on ROM chips) */
133};
134
135#define TEST_UNTESTED(struct tested){ .probe = NT, .read = NT, .erase = NT, .write = NT }
136
137#define TEST_OK_PROBE(struct tested){ .probe = OK, .read = NT, .erase = NT, .write = NT }
138#define TEST_OK_PR(struct tested){ .probe = OK, .read = OK, .erase = NT, .write = NT }
139#define TEST_OK_PRE(struct tested){ .probe = OK, .read = OK, .erase = OK, .write = NT }
140#define TEST_OK_PREW(struct tested){ .probe = OK, .read = OK, .erase = OK, .write = OK }
141
142#define TEST_BAD_PROBE(struct tested){ .probe = BAD, .read = NT, .erase = NT, .write = NT }
143#define TEST_BAD_PR(struct tested){ .probe = BAD, .read = BAD, .erase = NT, .write = NT }
144#define TEST_BAD_PRE(struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = NT }
145#define TEST_BAD_PREW(struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = BAD }
146
147struct flashctx;
148typedef int (erasefunc_t)(struct flashctx *flash, unsigned int addr, unsigned int blocklen);
149
150struct flashchip {
151const char *vendor;
152const char *name;
153
154enum chipbustype bustype;
155
156/*
157 * With 32bit manufacture_id and model_id we can cover IDs up to
158 * (including) the 4th bank of JEDEC JEP106W Standard Manufacturer's
159 * Identification code.
160 */
161uint32_t manufacture_id;
162uint32_t model_id;
163
164/* Total chip size in kilobytes */
165unsigned int total_size;
166/* Chip page size in bytes */
167unsigned int page_size;
168int feature_bits;
169
170/* Indicate how well flashrom supports different operations of this flash chip. */
171struct tested {
172enum test_state probe;
173enum test_state read;
174enum test_state erase;
175enum test_state write;
176} tested;
177
178int (*probe) (struct flashctx *flash);
179
180/* Delay after "enter/exit ID mode" commands in microseconds.
181 * NB: negative values have special meanings, see TIMING_* below.
182 */
183signed int probe_timing;
184
185/*
186 * Erase blocks and associated erase function. Any chip erase function
187 * is stored as chip-sized virtual block together with said function.
188 * The first one that fits will be chosen. There is currently no way to
189 * influence that behaviour. For testing just comment out the other
190 * elements or set the function pointer to NULL.
191 */
192struct block_eraser {
193struct eraseblock {
194unsigned int size; /* Eraseblock size in bytes */
195unsigned int count; /* Number of contiguous blocks with that size */
196} eraseblocks[NUM_ERASEREGIONS];
197/* a block_erase function should try to erase one block of size
198 * 'blocklen' at address 'blockaddr' and return 0 on success. */
199int (*block_erase) (struct flashctx *flash, unsigned int blockaddr, unsigned int blocklen);
200} block_erasers[NUM_ERASEFUNCTIONS];
201
202int (*printlock) (struct flashctx *flash);
203int (*unlock) (struct flashctx *flash);
204int (*write) (struct flashctx *flash, const uint8_t *buf, unsigned int start, unsigned int len);
205int (*read) (struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
206struct voltage {
207uint16_t min;
208uint16_t max;
209} voltage;
210enum write_granularity gran;
211};
212
213struct flashctx {
214struct flashchip *chip;
215/* FIXME: The memory mappings should be saved in a more structured way. */
216/* The physical_* fields store the respective addresses in the physical address space of the CPU. */
217uintptr_t physical_memory;
218/* The virtual_* fields store where the respective physical address is mapped into flashrom's address
219 * space. A value equivalent to (chipaddr)ERROR_PTR indicates an invalid mapping (or none at all). */
220chipaddr virtual_memory;
221/* Some flash devices have an additional register space; semantics are like above. */
222uintptr_t physical_registers;
223chipaddr virtual_registers;
224struct registered_master *mst;
225};
226
227/* Timing used in probe routines. ZERO is -2 to differentiate between an unset
228 * field and zero delay.
229 *
230 * SPI devices will always have zero delay and ignore this field.
231 */
232#define TIMING_FIXME-1
233/* this is intentionally same value as fixme */
234#define TIMING_IGNORED-1
235#define TIMING_ZERO-2
236
237extern const struct flashchip flashchips[];
238extern const unsigned int flashchips_size;
239
240void chip_writeb(const struct flashctx *flash, uint8_t val, chipaddr addr);
241void chip_writew(const struct flashctx *flash, uint16_t val, chipaddr addr);
242void chip_writel(const struct flashctx *flash, uint32_t val, chipaddr addr);
243void chip_writen(const struct flashctx *flash, const uint8_t *buf, chipaddr addr, size_t len);
244uint8_t chip_readb(const struct flashctx *flash, const chipaddr addr);
245uint16_t chip_readw(const struct flashctx *flash, const chipaddr addr);
246uint32_t chip_readl(const struct flashctx *flash, const chipaddr addr);
247void chip_readn(const struct flashctx *flash, uint8_t *buf, const chipaddr addr, size_t len);
248
249/* print.c */
250int print_supported(void);
251void print_supported_wiki(void);
252
253/* helpers.c */
254uint32_t address_to_bits(uint32_t addr);
255int bitcount(unsigned long a);
256int max(int a, int b);
257int min(int a, int b);
258char *strcat_realloc(char *dest, const char *src);
259void tolower_string(char *str);
260#ifdef __MINGW32__
261char* strtok_r(char *str, const char *delim, char **nextp);
262#endif
263#if defined(__DJGPP__) || !defined(HAVE_STRNLEN)
264size_t strnlen(const char *str, size_t n);
265#endif
266
267/* flashrom.c */
268extern const char flashrom_version[];
269extern const char *chip_to_probe;
270int map_flash(struct flashctx *flash);
271void unmap_flash(struct flashctx *flash);
272int read_memmapped(struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
273int erase_flash(struct flashctx *flash);
274int probe_flash(struct registered_master *mst, int startchip, struct flashctx *fill_flash, int force);
275int read_flash_to_file(struct flashctx *flash, const char *filename);
276char *extract_param(const char *const *haystack, const char *needle, const char *delim);
277int verify_range(struct flashctx *flash, const uint8_t *cmpbuf, unsigned int start, unsigned int len);
278int need_erase(const uint8_t *have, const uint8_t *want, unsigned int len, enum write_granularity gran);
279void print_version(void);
280void print_buildinfo(void);
281void print_banner(void);
282void list_programmers_linebreak(int startcol, int cols, int paren);
283int selfcheck(void);
284int doit(struct flashctx *flash, int force, const char *filename, int read_it, int write_it, int erase_it, int verify_it);
285int read_buf_from_file(unsigned char *buf, unsigned long size, const char *filename);
286int write_buf_to_file(const unsigned char *buf, unsigned long size, const char *filename);
287
288/* Something happened that shouldn't happen, but we can go on. */
289#define ERROR_NONFATAL 0x100
290
291/* Something happened that shouldn't happen, we'll abort. */
292#define ERROR_FATAL -0xee
293#define ERROR_FLASHROM_BUG -200
294/* We reached one of the hardcoded limits of flashrom. This can be fixed by
295 * increasing the limit of a compile-time allocation or by switching to dynamic
296 * allocation.
297 * Note: If this warning is triggered, check first for runaway registrations.
298 */
299#define ERROR_FLASHROM_LIMIT -201
300
301/* cli_common.c */
302char *flashbuses_to_text(enum chipbustype bustype);
303void print_chip_support_status(const struct flashchip *chip);
304
305/* cli_output.c */
306extern int verbose_screen;
307extern int verbose_logfile;
308#ifndef STANDALONE
309int open_logfile(const char * const filename);
310int close_logfile(void);
311void start_logging(void);
312#endif
313enum msglevel {
314MSG_ERROR= 0,
315MSG_WARN= 1,
316MSG_INFO= 2,
317MSG_DEBUG= 3,
318MSG_DEBUG2= 4,
319MSG_SPEW= 5,
320};
321/* Let gcc and clang check for correct printf-style format strings. */
322int print(enum msglevel level, const char *fmt, ...)
323#ifdef __MINGW32__
324__attribute__((format(gnu_printf, 2, 3)));
325#else
326__attribute__((format(printf, 2, 3)));
327#endif
328#define msg_gerr(...)print(MSG_ERROR, __VA_ARGS__)/* general errors */
329#define msg_perr(...)print(MSG_ERROR, __VA_ARGS__)/* programmer errors */
330#define msg_cerr(...)print(MSG_ERROR, __VA_ARGS__)/* chip errors */
331#define msg_gwarn(...)print(MSG_WARN, __VA_ARGS__)/* general warnings */
332#define msg_pwarn(...)print(MSG_WARN, __VA_ARGS__)/* programmer warnings */
333#define msg_cwarn(...)print(MSG_WARN, __VA_ARGS__)/* chip warnings */
334#define msg_ginfo(...)print(MSG_INFO, __VA_ARGS__)/* general info */
335#define msg_pinfo(...)print(MSG_INFO, __VA_ARGS__)/* programmer info */
336#define msg_cinfo(...)print(MSG_INFO, __VA_ARGS__)/* chip info */
337#define msg_gdbg(...)print(MSG_DEBUG, __VA_ARGS__)/* general debug */
338#define msg_pdbg(...)print(MSG_DEBUG, __VA_ARGS__)/* programmer debug */
339#define msg_cdbg(...)print(MSG_DEBUG, __VA_ARGS__)/* chip debug */
340#define msg_gdbg2(...)print(MSG_DEBUG2, __VA_ARGS__)/* general debug2 */
341#define msg_pdbg2(...)print(MSG_DEBUG2, __VA_ARGS__)/* programmer debug2 */
342#define msg_cdbg2(...)print(MSG_DEBUG2, __VA_ARGS__)/* chip debug2 */
343#define msg_gspew(...)print(MSG_SPEW, __VA_ARGS__)/* general debug spew */
344#define msg_pspew(...)print(MSG_SPEW, __VA_ARGS__)/* programmer debug spew */
345#define msg_cspew(...)print(MSG_SPEW, __VA_ARGS__)/* chip debug spew */
346
347/* layout.c */
348int register_include_arg(char *name);
349int process_include_args(void);
350int read_romlayout(const char *name);
351int normalize_romentries(const struct flashctx *flash);
352int build_new_image(struct flashctx *flash, bool oldcontents_valid, uint8_t *oldcontents, uint8_t *newcontents);
353void layout_cleanup(void);
354
355/* spi.c */
356struct spi_command {
357unsigned int writecnt;
358unsigned int readcnt;
359const unsigned char *writearr;
360unsigned char *readarr;
361};
362int spi_send_command(struct flashctx *flash, unsigned int writecnt, unsigned int readcnt, const unsigned char *writearr, unsigned char *readarr);
363int spi_send_multicommand(struct flashctx *flash, struct spi_command *cmds);
364uint32_t spi_get_valid_read_addr(struct flashctx *flash);
365
366enum chipbustype get_buses_supported(void);
367#endif/* !__FLASH_H__ */

Archive Download this file

Revision: HEAD