blob: cda79e3923d453ecb6a9da768e156ba05bf7d0a2 [file] [log] [blame]
Adam Kaufman064b1f22007-02-06 19:47:50 +00001/*
Uwe Hermannd1107642007-08-29 17:52:32 +00002 * This file is part of the flashrom project.
Adam Kaufman064b1f22007-02-06 19:47:50 +00003 *
Uwe Hermannd22a1d42007-09-09 20:21:05 +00004 * Copyright (C) 2000 Silicon Integrated System Corporation
5 * Copyright (C) 2000 Ronald G. Minnich <rminnich@gmail.com>
Stefan Reinauer8fa64812009-08-12 09:27:45 +00006 * Copyright (C) 2005-2009 coresystems GmbH
Carl-Daniel Hailfingera0a6ae92009-06-15 12:10:57 +00007 * Copyright (C) 2006-2009 Carl-Daniel Hailfinger
Adam Kaufman064b1f22007-02-06 19:47:50 +00008 *
Uwe Hermannd1107642007-08-29 17:52:32 +00009 * 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.
Adam Kaufman064b1f22007-02-06 19:47:50 +000013 *
Uwe Hermannd1107642007-08-29 17:52:32 +000014 * 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.
Adam Kaufman064b1f22007-02-06 19:47:50 +000018 */
19
Ronald G. Minnicheaab50b2003-09-12 22:41:53 +000020#ifndef __FLASH_H__
21#define __FLASH_H__ 1
22
Stefan Taunerb0eee9b2015-01-10 09:32:50 +000023#include "platform.h"
24
Stefan Tauner0466c812013-06-16 10:30:08 +000025#include <inttypes.h>
Carl-Daniel Hailfinger11990da2013-07-13 23:21:05 +000026#include <stdio.h>
Ollie Lho184a4042005-11-26 21:55:36 +000027#include <stdint.h>
Carl-Daniel Hailfingerdd128c92010-06-03 00:49:50 +000028#include <stddef.h>
Nico Huber18781102012-12-10 13:34:12 +000029#include <stdarg.h>
Stefan Tauner682122b2013-06-23 22:15:39 +000030#include <stdbool.h>
Stefan Taunerb0eee9b2015-01-10 09:32:50 +000031#if IS_WINDOWS
Patrick Georgie48654c2010-01-06 22:14:39 +000032#include <windows.h>
33#undef min
34#undef max
35#endif
Andriy Gapon65c1b862008-05-22 13:22:45 +000036
Nico Huberd152fb92017-06-19 12:57:10 +020037#include "libflashrom.h"
Nico Huber3a9939b2016-04-27 15:56:14 +020038#include "layout.h"
Nikolai Artemievc6c3f282021-10-20 23:34:15 +110039#include "writeprotect.h"
Nico Huber3a9939b2016-04-27 15:56:14 +020040
Nico Huberd8b2e802019-06-18 23:39:56 +020041#define KiB (1024)
42#define MiB (1024 * KiB)
43
44/* Assumes `n` and `a` are at most 64-bit wide (to avoid typeof() operator). */
45#define ALIGN_DOWN(n, a) ((n) & ~((uint64_t)(a) - 1))
46
Patrick Georgied7a9642010-09-25 22:53:44 +000047#define ERROR_PTR ((void*)-1)
48
Carl-Daniel Hailfinger174f55b2010-10-08 00:37:55 +000049/* Error codes */
Carl-Daniel Hailfinger316fdfb2012-06-08 15:27:47 +000050#define ERROR_OOM -100
Carl-Daniel Hailfinger174f55b2010-10-08 00:37:55 +000051#define TIMEOUT_ERROR -101
52
Stefan Taunerc2333752013-07-13 23:31:37 +000053/* TODO: check using code for correct usage of types */
54typedef uintptr_t chipaddr;
Stefan Tauner305e0b92013-07-17 23:46:44 +000055#define PRIxPTR_WIDTH ((int)(sizeof(uintptr_t)*2))
Carl-Daniel Hailfinger5820f422009-05-16 21:22:56 +000056
David Hendricks8bb20212011-06-14 01:35:36 +000057int register_shutdown(int (*function) (void *data), void *data);
Stefan Tauner2a1ed772014-08-31 00:09:21 +000058int shutdown_free(void *data);
Stefan Tauner305e0b92013-07-17 23:46:44 +000059void *programmer_map_flash_region(const char *descr, uintptr_t phys_addr, size_t len);
Uwe Hermann09e04f72009-05-16 22:36:00 +000060void programmer_unmap_flash_region(void *virt_addr, size_t len);
Stefan Taunerf80419c2014-05-02 15:41:42 +000061void programmer_delay(unsigned int usecs);
Carl-Daniel Hailfinger61a8bd22009-03-05 19:24:22 +000062
Uwe Hermanne5ac1642008-03-12 11:54:51 +000063#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
64
Carl-Daniel Hailfinger1dfe0ff2009-05-31 17:57:34 +000065enum chipbustype {
Carl-Daniel Hailfinger1a227952011-07-27 07:13:06 +000066 BUS_NONE = 0,
67 BUS_PARALLEL = 1 << 0,
68 BUS_LPC = 1 << 1,
69 BUS_FWH = 1 << 2,
70 BUS_SPI = 1 << 3,
Carl-Daniel Hailfinger532c7172011-11-04 21:35:26 +000071 BUS_PROG = 1 << 4,
Carl-Daniel Hailfinger1a227952011-07-27 07:13:06 +000072 BUS_NONSPI = BUS_PARALLEL | BUS_LPC | BUS_FWH,
Carl-Daniel Hailfinger1dfe0ff2009-05-31 17:57:34 +000073};
74
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +000075/*
Stefan Tauner02437452013-04-01 19:34:53 +000076 * The following enum defines possible write granularities of flash chips. These tend to reflect the properties
Martin Rothf6c1cb12022-03-15 10:55:25 -060077 * of the actual hardware not necessarily the write function(s) defined by the respective struct flashchip.
Stefan Tauner02437452013-04-01 19:34:53 +000078 * The latter might (and should) be more precisely specified, e.g. they might bail out early if their execution
79 * would result in undefined chip contents.
Stefan Taunereb582572012-09-21 12:52:50 +000080 */
81enum write_granularity {
Stefan Tauner02437452013-04-01 19:34:53 +000082 /* We assume 256 byte granularity by default. */
83 write_gran_256bytes = 0,/* If less than 256 bytes are written, the unwritten bytes are undefined. */
84 write_gran_1bit, /* Each bit can be cleared individually. */
85 write_gran_1byte, /* A byte can be written once. Further writes to an already written byte cause
86 * its contents to be either undefined or to stay unchanged. */
Paul Kocialkowskic8305e12015-10-16 02:16:20 +000087 write_gran_128bytes, /* If less than 128 bytes are written, the unwritten bytes are undefined. */
Stefan Tauner02437452013-04-01 19:34:53 +000088 write_gran_264bytes, /* If less than 264 bytes are written, the unwritten bytes are undefined. */
89 write_gran_512bytes, /* If less than 512 bytes are written, the unwritten bytes are undefined. */
90 write_gran_528bytes, /* If less than 528 bytes are written, the unwritten bytes are undefined. */
91 write_gran_1024bytes, /* If less than 1024 bytes are written, the unwritten bytes are undefined. */
92 write_gran_1056bytes, /* If less than 1056 bytes are written, the unwritten bytes are undefined. */
Carl-Daniel Hailfinger1b0e9fc2014-06-16 22:36:17 +000093 write_gran_1byte_implicit_erase, /* EEPROMs and other chips with implicit erase and 1-byte writes. */
Stefan Taunereb582572012-09-21 12:52:50 +000094};
95
96/*
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +000097 * How many different contiguous runs of erase blocks with one size each do
98 * we have for a given erase function?
99 */
100#define NUM_ERASEREGIONS 5
101
102/*
103 * How many different erase functions do we have per chip?
Nico Huberaac81422017-11-10 22:54:13 +0100104 * Macronix MX25L25635F has 8 different functions.
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000105 */
Nico Huberaac81422017-11-10 22:54:13 +0100106#define NUM_ERASEFUNCTIONS 8
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000107
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100108#define MAX_CHIP_RESTORE_FUNCTIONS 4
109
Stefan Tauner0554ca52013-07-25 22:54:25 +0000110/* Feature bits used for non-SPI only */
Carl-Daniel Hailfinger4bf4e792010-01-09 03:15:50 +0000111#define FEATURE_REGISTERMAP (1 << 0)
Sean Nelson35727f72010-01-28 23:55:12 +0000112#define FEATURE_LONG_RESET (0 << 4)
113#define FEATURE_SHORT_RESET (1 << 4)
114#define FEATURE_EITHER_RESET FEATURE_LONG_RESET
Sean Nelsonf59e2632010-10-20 21:13:19 +0000115#define FEATURE_RESET_MASK (FEATURE_LONG_RESET | FEATURE_SHORT_RESET)
Carl-Daniel Hailfinger4bf4e792010-01-09 03:15:50 +0000116#define FEATURE_ADDR_FULL (0 << 2)
117#define FEATURE_ADDR_MASK (3 << 2)
Sean Nelson35727f72010-01-28 23:55:12 +0000118#define FEATURE_ADDR_2AA (1 << 2)
119#define FEATURE_ADDR_AAA (2 << 2)
Michael Karcherad0010a2010-04-03 10:27:08 +0000120#define FEATURE_ADDR_SHIFTED (1 << 5)
Stefan Tauner0554ca52013-07-25 22:54:25 +0000121/* Feature bits used for SPI only */
Carl-Daniel Hailfingerfd7075a2010-07-29 13:09:18 +0000122#define FEATURE_WRSR_EWSR (1 << 6)
123#define FEATURE_WRSR_WREN (1 << 7)
Stefan Tauner0554ca52013-07-25 22:54:25 +0000124#define FEATURE_WRSR_EITHER (FEATURE_WRSR_EWSR | FEATURE_WRSR_WREN)
Daniel Lenski65922a32012-02-15 23:40:23 +0000125#define FEATURE_OTP (1 << 8)
Vincent Palatinf800f552013-03-15 02:03:16 +0000126#define FEATURE_QPI (1 << 9)
Nico Huberfe34d2a2017-11-10 21:10:20 +0100127#define FEATURE_4BA_ENTER (1 << 10) /**< Can enter/exit 4BA mode with instructions 0xb7/0xe9 w/o WREN */
128#define FEATURE_4BA_ENTER_WREN (1 << 11) /**< Can enter/exit 4BA mode with instructions 0xb7/0xe9 after WREN */
Nico Huber86bddb52018-03-13 18:14:52 +0100129#define FEATURE_4BA_ENTER_EAR7 (1 << 12) /**< Can enter/exit 4BA mode by setting bit7 of the ext addr reg */
Nico Huber542b1f02022-05-24 14:30:12 +0200130#define FEATURE_4BA_EAR_C5C8 (1 << 13) /**< Regular 3-byte operations can be used by writing the most
131 significant address byte into an extended address register
132 (using 0xc5/0xc8 instructions). */
Nico Huber9bb8a322022-05-24 15:07:34 +0200133#define FEATURE_4BA_EAR_1716 (1 << 14) /**< Like FEATURE_4BA_EAR_C5C8 but with 0x17/0x16 instructions. */
134#define FEATURE_4BA_READ (1 << 15) /**< Native 4BA read instruction (0x13) is supported. */
135#define FEATURE_4BA_FAST_READ (1 << 16) /**< Native 4BA fast read instruction (0x0c) is supported. */
136#define FEATURE_4BA_WRITE (1 << 17) /**< Native 4BA byte program (0x12) is supported. */
Nico Huberaac81422017-11-10 22:54:13 +0100137/* 4BA Shorthands */
Nico Huber9bb8a322022-05-24 15:07:34 +0200138#define FEATURE_4BA_EAR_ANY (FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_EAR_1716)
Nico Huberaac81422017-11-10 22:54:13 +0100139#define FEATURE_4BA_NATIVE (FEATURE_4BA_READ | FEATURE_4BA_FAST_READ | FEATURE_4BA_WRITE)
Nico Huber542b1f02022-05-24 14:30:12 +0200140#define FEATURE_4BA (FEATURE_4BA_ENTER | FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_NATIVE)
141#define FEATURE_4BA_WREN (FEATURE_4BA_ENTER_WREN | FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_NATIVE)
142#define FEATURE_4BA_EAR7 (FEATURE_4BA_ENTER_EAR7 | FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_NATIVE)
Paul Kocialkowski995f7552018-01-15 01:06:09 +0300143/*
144 * Most flash chips are erased to ones and programmed to zeros. However, some
145 * other flash chips, such as the ENE KB9012 internal flash, work the opposite way.
146 */
Nico Huber9bb8a322022-05-24 15:07:34 +0200147#define FEATURE_ERASED_ZERO (1 << 18)
148#define FEATURE_NO_ERASE (1 << 19)
Paul Kocialkowski995f7552018-01-15 01:06:09 +0300149
Nico Huber9bb8a322022-05-24 15:07:34 +0200150#define FEATURE_WRSR_EXT2 (1 << 20)
151#define FEATURE_WRSR2 (1 << 21)
152#define FEATURE_WRSR_EXT3 ((1 << 22) | FEATURE_WRSR_EXT2)
153#define FEATURE_WRSR3 (1 << 23)
Nikolai Artemiev9de3f872021-10-20 22:32:25 +1100154
Paul Kocialkowski995f7552018-01-15 01:06:09 +0300155#define ERASED_VALUE(flash) (((flash)->chip->feature_bits & FEATURE_ERASED_ZERO) ? 0x00 : 0xff)
Sean Nelsonc57a9202010-01-04 17:15:23 +0000156
Stefan Tauner6455dff2014-05-26 00:36:24 +0000157enum test_state {
158 OK = 0,
159 NT = 1, /* Not tested */
160 BAD, /* Known to not work */
161 DEP, /* Support depends on configuration (e.g. Intel flash descriptor) */
162 NA, /* Not applicable (e.g. write support on ROM chips) */
163};
164
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300165#define TEST_UNTESTED (struct tested){ .probe = NT, .read = NT, .erase = NT, .write = NT, .wp = NT }
Stefan Tauner6455dff2014-05-26 00:36:24 +0000166
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300167#define TEST_OK_PROBE (struct tested){ .probe = OK, .read = NT, .erase = NT, .write = NT, .wp = NT }
168#define TEST_OK_PR (struct tested){ .probe = OK, .read = OK, .erase = NT, .write = NT, .wp = NT }
169#define TEST_OK_PRE (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = NT, .wp = NT }
170#define TEST_OK_PREW (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = OK, .wp = NT }
171#define TEST_OK_PREWB (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = OK, .wp = OK }
Stefan Tauner6455dff2014-05-26 00:36:24 +0000172
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300173#define TEST_BAD_PROBE (struct tested){ .probe = BAD, .read = NT, .erase = NT, .write = NT, .wp = NT }
174#define TEST_BAD_PR (struct tested){ .probe = BAD, .read = BAD, .erase = NT, .write = NT, .wp = NT }
175#define TEST_BAD_PRE (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = NT, .wp = NT }
176#define TEST_BAD_PREW (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .wp = NT }
177#define TEST_BAD_PREWB (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .wp = BAD }
Stefan Tauner6455dff2014-05-26 00:36:24 +0000178
Nico Huber454f6132012-12-10 13:34:10 +0000179struct flashrom_flashctx;
Martin Rothf6c1cb12022-03-15 10:55:25 -0600180#define flashctx flashrom_flashctx /* TODO: Agree on a name and convert all occurrences. */
Carl-Daniel Hailfinger5a7cb842012-08-25 01:17:58 +0000181typedef int (erasefunc_t)(struct flashctx *flash, unsigned int addr, unsigned int blocklen);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000182
Nikolai Artemiev01675222021-10-20 22:30:41 +1100183enum flash_reg {
184 INVALID_REG = 0,
185 STATUS1,
186 STATUS2,
Sergii Dmytruk0b2e7dd2021-12-19 18:37:51 +0200187 STATUS3,
Nikolai Artemiev01675222021-10-20 22:30:41 +1100188 MAX_REGISTERS
189};
190
Nikolai Artemievc6c3f282021-10-20 23:34:15 +1100191struct reg_bit_info {
192 /* Register containing the bit */
193 enum flash_reg reg;
194
195 /* Bit index within register */
196 uint8_t bit_index;
197
198 /*
199 * Writability of the bit. RW does not guarantee the bit will be
200 * writable, for example if status register protection is enabled.
201 */
202 enum {
203 RO, /* Read only */
204 RW, /* Readable and writable */
205 OTP /* One-time programmable */
206 } writability;
207};
208
Nikolai Artemievc9feb1b2021-10-21 01:35:13 +1100209struct wp_bits;
210
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000211struct flashchip {
Uwe Hermann76158682008-03-14 23:55:58 +0000212 const char *vendor;
Uwe Hermann372eeb52007-12-04 21:49:06 +0000213 const char *name;
Carl-Daniel Hailfinger1dfe0ff2009-05-31 17:57:34 +0000214
215 enum chipbustype bustype;
216
Uwe Hermann394131e2008-10-18 21:14:13 +0000217 /*
218 * With 32bit manufacture_id and model_id we can cover IDs up to
Carl-Daniel Hailfingerae8afa92007-12-31 01:49:00 +0000219 * (including) the 4th bank of JEDEC JEP106W Standard Manufacturer's
220 * Identification code.
221 */
222 uint32_t manufacture_id;
223 uint32_t model_id;
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000224
Stefan Taunerc0aaf952011-05-19 02:58:17 +0000225 /* Total chip size in kilobytes */
Stefan Taunerc69c9c82011-11-23 09:13:48 +0000226 unsigned int total_size;
Stefan Taunerc0aaf952011-05-19 02:58:17 +0000227 /* Chip page size in bytes */
Stefan Taunerc69c9c82011-11-23 09:13:48 +0000228 unsigned int page_size;
Sean Nelsonc57a9202010-01-04 17:15:23 +0000229 int feature_bits;
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000230
Stefan Tauner6455dff2014-05-26 00:36:24 +0000231 /* Indicate how well flashrom supports different operations of this flash chip. */
232 struct tested {
233 enum test_state probe;
234 enum test_state read;
235 enum test_state erase;
236 enum test_state write;
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300237 enum test_state wp;
Stefan Tauner6455dff2014-05-26 00:36:24 +0000238 } tested;
Peter Stuge1159d582008-05-03 04:34:37 +0000239
Mike Banon31b5e3b2018-01-15 01:10:00 +0300240 /*
241 * Group chips that have common command sets. This should ensure that
242 * no chip gets confused by a probing command for a very different class
243 * of chips.
244 */
245 enum {
246 /* SPI25 is very common. Keep it at zero so we don't have
247 to specify it for each and every chip in the database.*/
248 SPI25 = 0,
Paul Kocialkowski80ae14e2018-01-15 01:07:46 +0300249 SPI_EDI = 1,
Mike Banon31b5e3b2018-01-15 01:10:00 +0300250 } spi_cmd_set;
251
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000252 int (*probe) (struct flashctx *flash);
Maciej Pijankac6e11112009-06-03 14:46:22 +0000253
Stefan Taunerc69c9c82011-11-23 09:13:48 +0000254 /* Delay after "enter/exit ID mode" commands in microseconds.
255 * NB: negative values have special meanings, see TIMING_* below.
256 */
257 signed int probe_timing;
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000258
259 /*
Carl-Daniel Hailfinger63ce4bb2009-12-22 13:04:53 +0000260 * Erase blocks and associated erase function. Any chip erase function
261 * is stored as chip-sized virtual block together with said function.
Stefan Taunerc0aaf952011-05-19 02:58:17 +0000262 * The first one that fits will be chosen. There is currently no way to
263 * influence that behaviour. For testing just comment out the other
264 * elements or set the function pointer to NULL.
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000265 */
266 struct block_eraser {
Stefan Tauner6697f712014-08-06 15:09:15 +0000267 struct eraseblock {
Stefan Taunerd06d9412011-06-12 19:47:55 +0000268 unsigned int size; /* Eraseblock size in bytes */
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000269 unsigned int count; /* Number of contiguous blocks with that size */
270 } eraseblocks[NUM_ERASEREGIONS];
Stefan Tauner355cbfd2011-05-28 02:37:14 +0000271 /* a block_erase function should try to erase one block of size
272 * 'blocklen' at address 'blockaddr' and return 0 on success. */
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000273 int (*block_erase) (struct flashctx *flash, unsigned int blockaddr, unsigned int blocklen);
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000274 } block_erasers[NUM_ERASEFUNCTIONS];
275
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000276 int (*printlock) (struct flashctx *flash);
277 int (*unlock) (struct flashctx *flash);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000278 int (*write) (struct flashctx *flash, const uint8_t *buf, unsigned int start, unsigned int len);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000279 int (*read) (struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
280 struct voltage {
Steven Zakuleccbe370e2011-06-03 07:26:31 +0000281 uint16_t min;
282 uint16_t max;
283 } voltage;
Stefan Tauner50d67aa2013-03-03 23:49:48 +0000284 enum write_granularity gran;
Nico Huber57dbd642018-03-13 18:01:05 +0100285
Nikolai Artemievc6c3f282021-10-20 23:34:15 +1100286 struct reg_bit_map {
287 /* Status register protection bit (SRP) */
288 struct reg_bit_info srp;
289
290 /* Status register lock bit (SRP) */
291 struct reg_bit_info srl;
292
293 /*
294 * Note: some datasheets refer to configuration bits that
295 * function like TB/SEC/CMP bits as BP bits (e.g. BP3 for a bit
296 * that functions like TB).
297 *
298 * As a convention, any config bit that functions like a
299 * TB/SEC/CMP bit should be assigned to the respective
300 * tb/sec/cmp field in this structure, even if the datasheet
301 * uses a different name.
302 */
303
304 /* Block protection bits (BP) */
305 /* Extra element for terminator */
306 struct reg_bit_info bp[MAX_BP_BITS + 1];
307
308 /* Top/bottom protection bit (TB) */
309 struct reg_bit_info tb;
310
311 /* Sector/block protection bit (SEC) */
312 struct reg_bit_info sec;
313
314 /* Complement bit (CMP) */
315 struct reg_bit_info cmp;
Sergii Dmytruk801fcd02021-12-19 18:45:16 +0200316
317 /* Write Protect Selection (per sector protection when set) */
318 struct reg_bit_info wps;
Nikolai Artemievc6c3f282021-10-20 23:34:15 +1100319 } reg_bits;
Nikolai Artemievc9feb1b2021-10-21 01:35:13 +1100320
321 /* Function that takes a set of WP config bits (e.g. BP, SEC, TB, etc) */
322 /* and determines what protection range they select. */
323 void (*decode_range)(size_t *start, size_t *len, const struct wp_bits *, size_t chip_len);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000324};
Ronald G. Minnicheaab50b2003-09-12 22:41:53 +0000325
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100326typedef int (*chip_restore_fn_cb_t)(struct flashctx *flash, uint8_t status);
327
Nico Huber454f6132012-12-10 13:34:10 +0000328struct flashrom_flashctx {
Carl-Daniel Hailfinger5a7cb842012-08-25 01:17:58 +0000329 struct flashchip *chip;
Stefan Tauner4e32ec12014-08-30 23:39:51 +0000330 /* FIXME: The memory mappings should be saved in a more structured way. */
331 /* The physical_* fields store the respective addresses in the physical address space of the CPU. */
332 uintptr_t physical_memory;
333 /* The virtual_* fields store where the respective physical address is mapped into flashrom's address
334 * space. A value equivalent to (chipaddr)ERROR_PTR indicates an invalid mapping (or none at all). */
Carl-Daniel Hailfinger5820f422009-05-16 21:22:56 +0000335 chipaddr virtual_memory;
Stefan Tauner4e32ec12014-08-30 23:39:51 +0000336 /* Some flash devices have an additional register space; semantics are like above. */
337 uintptr_t physical_registers;
Carl-Daniel Hailfinger5820f422009-05-16 21:22:56 +0000338 chipaddr virtual_registers;
Carl-Daniel Hailfingera5bcbce2014-07-19 22:03:29 +0000339 struct registered_master *mst;
Nico Huber7af0e792016-04-29 16:40:15 +0200340 const struct flashrom_layout *layout;
Nico Huber5bd990c2019-06-16 19:46:46 +0200341 struct flashrom_layout *default_layout;
Nico Huber454f6132012-12-10 13:34:10 +0000342 struct {
343 bool force;
344 bool force_boardmismatch;
345 bool verify_after_write;
346 bool verify_whole_chip;
347 } flags;
Nico Huberf43c6542017-10-14 17:47:28 +0200348 /* We cache the state of the extended address register (highest byte
349 of a 4BA for 3BA instructions) and the state of the 4BA mode here.
350 If possible, we enter 4BA mode early. If that fails, we make use
351 of the extended address register. */
352 int address_high_byte;
353 bool in_4ba_mode;
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100354
355 int chip_restore_fn_count;
356 struct chip_restore_func_data {
357 chip_restore_fn_cb_t func;
358 uint8_t status;
359 } chip_restore_fn[MAX_CHIP_RESTORE_FUNCTIONS];
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000360};
361
Maciej Pijankac6e11112009-06-03 14:46:22 +0000362/* Timing used in probe routines. ZERO is -2 to differentiate between an unset
363 * field and zero delay.
Paul Kocialkowski80ae14e2018-01-15 01:07:46 +0300364 *
Maciej Pijankac6e11112009-06-03 14:46:22 +0000365 * SPI devices will always have zero delay and ignore this field.
366 */
367#define TIMING_FIXME -1
368/* this is intentionally same value as fixme */
369#define TIMING_IGNORED -1
370#define TIMING_ZERO -2
371
Carl-Daniel Hailfinger4c823182011-05-04 00:39:50 +0000372extern const struct flashchip flashchips[];
Stefan Tauner96658be2014-05-26 22:05:31 +0000373extern const unsigned int flashchips_size;
Ollie Lho184a4042005-11-26 21:55:36 +0000374
Carl-Daniel Hailfinger8a3c60c2011-12-18 15:01:24 +0000375void chip_writeb(const struct flashctx *flash, uint8_t val, chipaddr addr);
376void chip_writew(const struct flashctx *flash, uint16_t val, chipaddr addr);
377void chip_writel(const struct flashctx *flash, uint32_t val, chipaddr addr);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000378void chip_writen(const struct flashctx *flash, const uint8_t *buf, chipaddr addr, size_t len);
Carl-Daniel Hailfinger8a3c60c2011-12-18 15:01:24 +0000379uint8_t chip_readb(const struct flashctx *flash, const chipaddr addr);
380uint16_t chip_readw(const struct flashctx *flash, const chipaddr addr);
381uint32_t chip_readl(const struct flashctx *flash, const chipaddr addr);
382void chip_readn(const struct flashctx *flash, uint8_t *buf, const chipaddr addr, size_t len);
383
Uwe Hermannba290d12009-06-17 12:07:12 +0000384/* print.c */
Niklas Söderlundede2fa42012-10-23 13:06:46 +0000385int print_supported(void);
Carl-Daniel Hailfingerf5292052009-11-17 09:57:34 +0000386void print_supported_wiki(void);
Uwe Hermann515ab3d2009-05-15 17:02:34 +0000387
Stefan Tauner6ad6e012014-06-12 00:04:32 +0000388/* helpers.c */
389uint32_t address_to_bits(uint32_t addr);
Nico Huber519be662018-12-23 20:03:35 +0100390unsigned int bitcount(unsigned long a);
391#undef MIN
392#define MIN(a, b) ((a) < (b) ? (a) : (b))
393#undef MAX
394#define MAX(a, b) ((a) > (b) ? (a) : (b))
Stefan Tauner6ad6e012014-06-12 00:04:32 +0000395int max(int a, int b);
396int min(int a, int b);
397char *strcat_realloc(char *dest, const char *src);
398void tolower_string(char *str);
Marc Schink7ecfe482016-03-17 16:07:23 +0100399uint8_t reverse_byte(uint8_t x);
400void reverse_bytes(uint8_t *dst, const uint8_t *src, size_t length);
Stefan Taunerb41d8472014-11-01 22:56:06 +0000401#ifdef __MINGW32__
402char* strtok_r(char *str, const char *delim, char **nextp);
Miklós Márton8900d6c2019-07-30 00:03:22 +0200403char *strndup(const char *str, size_t size);
Stefan Taunerb41d8472014-11-01 22:56:06 +0000404#endif
Nico Huber2d625722016-05-03 10:48:02 +0200405#if defined(__DJGPP__) || (!defined(__LIBPAYLOAD__) && !defined(HAVE_STRNLEN))
Stefan Taunerdc627932015-01-27 18:07:50 +0000406size_t strnlen(const char *str, size_t n);
407#endif
Stefan Tauner6ad6e012014-06-12 00:04:32 +0000408
Uwe Hermann0846f892007-08-23 13:34:59 +0000409/* flashrom.c */
Mathias Krausea60faab2011-01-17 07:50:42 +0000410extern const char flashrom_version[];
Nico Huberbcb2e5a2012-12-30 01:23:17 +0000411extern const char *chip_to_probe;
Nico Huber2d625722016-05-03 10:48:02 +0200412char *flashbuses_to_text(enum chipbustype bustype);
Stefan Tauner4e32ec12014-08-30 23:39:51 +0000413int map_flash(struct flashctx *flash);
414void unmap_flash(struct flashctx *flash);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000415int read_memmapped(struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
416int erase_flash(struct flashctx *flash);
Carl-Daniel Hailfingera5bcbce2014-07-19 22:03:29 +0000417int probe_flash(struct registered_master *mst, int startchip, struct flashctx *fill_flash, int force);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000418int read_flash_to_file(struct flashctx *flash, const char *filename);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000419int verify_range(struct flashctx *flash, const uint8_t *cmpbuf, unsigned int start, unsigned int len);
Carl-Daniel Hailfingera84835a2010-01-07 03:24:05 +0000420void print_version(void);
Carl-Daniel Hailfinger1c155482012-06-06 09:17:06 +0000421void print_buildinfo(void);
Carl-Daniel Hailfinger8841d3e2010-05-15 15:04:37 +0000422void print_banner(void);
Carl-Daniel Hailfingera73fb492010-10-06 23:48:34 +0000423void list_programmers_linebreak(int startcol, int cols, int paren);
Carl-Daniel Hailfingera84835a2010-01-07 03:24:05 +0000424int selfcheck(void);
Stefan Tauner66652442011-06-26 17:38:17 +0000425int read_buf_from_file(unsigned char *buf, unsigned long size, const char *filename);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000426int write_buf_to_file(const unsigned char *buf, unsigned long size, const char *filename);
Nico Huber305f4172013-06-14 11:55:26 +0200427int prepare_flash_access(struct flashctx *, bool read_it, bool write_it, bool erase_it, bool verify_it);
428void finalize_flash_access(struct flashctx *);
Nico Huber899e4ec2016-04-29 18:39:01 +0200429int do_read(struct flashctx *, const char *filename);
430int do_erase(struct flashctx *);
Paul Kocialkowskif701f342018-01-15 01:10:36 +0300431int do_write(struct flashctx *, const char *const filename, const char *const referencefile);
Nico Huber899e4ec2016-04-29 18:39:01 +0200432int do_verify(struct flashctx *, const char *const filename);
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100433int register_chip_restore(chip_restore_fn_cb_t func, struct flashctx *flash, uint8_t status);
Uwe Hermannba290d12009-06-17 12:07:12 +0000434
Tadas Slotkusad470342011-09-03 17:15:00 +0000435/* Something happened that shouldn't happen, but we can go on. */
Michael Karchera4448d92010-07-22 18:04:15 +0000436#define ERROR_NONFATAL 0x100
437
Tadas Slotkusad470342011-09-03 17:15:00 +0000438/* Something happened that shouldn't happen, we'll abort. */
439#define ERROR_FATAL -0xee
Carl-Daniel Hailfingerc40cff72011-12-20 00:19:29 +0000440#define ERROR_FLASHROM_BUG -200
441/* We reached one of the hardcoded limits of flashrom. This can be fixed by
442 * increasing the limit of a compile-time allocation or by switching to dynamic
443 * allocation.
444 * Note: If this warning is triggered, check first for runaway registrations.
445 */
446#define ERROR_FLASHROM_LIMIT -201
Tadas Slotkusad470342011-09-03 17:15:00 +0000447
Stefan Tauner9b32de92014-08-08 23:52:33 +0000448/* cli_common.c */
Stefan Tauner9b32de92014-08-08 23:52:33 +0000449void print_chip_support_status(const struct flashchip *chip);
450
Sean Nelson51e97d72010-01-07 20:09:33 +0000451/* cli_output.c */
Nico Huberd152fb92017-06-19 12:57:10 +0200452extern enum flashrom_log_level verbose_screen;
453extern enum flashrom_log_level verbose_logfile;
Carl-Daniel Hailfinger1c155482012-06-06 09:17:06 +0000454#ifndef STANDALONE
455int open_logfile(const char * const filename);
456int close_logfile(void);
457void start_logging(void);
458#endif
Nico Huberd152fb92017-06-19 12:57:10 +0200459int flashrom_print_cb(enum flashrom_log_level level, const char *fmt, va_list ap);
Carl-Daniel Hailfinger9f5f2152010-06-04 23:20:21 +0000460/* Let gcc and clang check for correct printf-style format strings. */
Nico Huberd152fb92017-06-19 12:57:10 +0200461int print(enum flashrom_log_level level, const char *fmt, ...)
Carl-Daniel Hailfinger11990da2013-07-13 23:21:05 +0000462#ifdef __MINGW32__
Antonio Ospiteb6e3d252018-03-03 18:40:24 +0100463# ifndef __MINGW_PRINTF_FORMAT
464# define __MINGW_PRINTF_FORMAT gnu_printf
465# endif
Stefan Taunerf268d8b2017-10-26 18:45:00 +0200466__attribute__((format(__MINGW_PRINTF_FORMAT, 2, 3)));
Carl-Daniel Hailfinger11990da2013-07-13 23:21:05 +0000467#else
468__attribute__((format(printf, 2, 3)));
469#endif
Nico Huberd152fb92017-06-19 12:57:10 +0200470#define msg_gerr(...) print(FLASHROM_MSG_ERROR, __VA_ARGS__) /* general errors */
471#define msg_perr(...) print(FLASHROM_MSG_ERROR, __VA_ARGS__) /* programmer errors */
472#define msg_cerr(...) print(FLASHROM_MSG_ERROR, __VA_ARGS__) /* chip errors */
473#define msg_gwarn(...) print(FLASHROM_MSG_WARN, __VA_ARGS__) /* general warnings */
474#define msg_pwarn(...) print(FLASHROM_MSG_WARN, __VA_ARGS__) /* programmer warnings */
475#define msg_cwarn(...) print(FLASHROM_MSG_WARN, __VA_ARGS__) /* chip warnings */
476#define msg_ginfo(...) print(FLASHROM_MSG_INFO, __VA_ARGS__) /* general info */
477#define msg_pinfo(...) print(FLASHROM_MSG_INFO, __VA_ARGS__) /* programmer info */
478#define msg_cinfo(...) print(FLASHROM_MSG_INFO, __VA_ARGS__) /* chip info */
479#define msg_gdbg(...) print(FLASHROM_MSG_DEBUG, __VA_ARGS__) /* general debug */
480#define msg_pdbg(...) print(FLASHROM_MSG_DEBUG, __VA_ARGS__) /* programmer debug */
481#define msg_cdbg(...) print(FLASHROM_MSG_DEBUG, __VA_ARGS__) /* chip debug */
482#define msg_gdbg2(...) print(FLASHROM_MSG_DEBUG2, __VA_ARGS__) /* general debug2 */
483#define msg_pdbg2(...) print(FLASHROM_MSG_DEBUG2, __VA_ARGS__) /* programmer debug2 */
484#define msg_cdbg2(...) print(FLASHROM_MSG_DEBUG2, __VA_ARGS__) /* chip debug2 */
485#define msg_gspew(...) print(FLASHROM_MSG_SPEW, __VA_ARGS__) /* general debug spew */
486#define msg_pspew(...) print(FLASHROM_MSG_SPEW, __VA_ARGS__) /* programmer debug spew */
487#define msg_cspew(...) print(FLASHROM_MSG_SPEW, __VA_ARGS__) /* chip debug spew */
Sean Nelson51e97d72010-01-07 20:09:33 +0000488
Carl-Daniel Hailfinger00f911e2007-10-15 21:44:47 +0000489/* spi.c */
Carl-Daniel Hailfingerd0478292009-07-10 21:08:55 +0000490struct spi_command {
491 unsigned int writecnt;
492 unsigned int readcnt;
493 const unsigned char *writearr;
494 unsigned char *readarr;
495};
Nico Hubera3140d02017-10-15 11:20:58 +0200496#define NULL_SPI_CMD { 0, 0, NULL, NULL, }
Edward O'Callaghan5eca4272020-04-12 17:27:53 +1000497int spi_send_command(const struct flashctx *flash, unsigned int writecnt, unsigned int readcnt, const unsigned char *writearr, unsigned char *readarr);
498int spi_send_multicommand(const struct flashctx *flash, struct spi_command *cmds);
Mats Erik Andersson44e1a192008-09-26 13:19:02 +0000499
Carl-Daniel Hailfingerc40cff72011-12-20 00:19:29 +0000500enum chipbustype get_buses_supported(void);
Ollie Lho761bf1b2004-03-20 16:46:10 +0000501#endif /* !__FLASH_H__ */