blob: db19566f788b3160b732fecfc653b9345ad30255 [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 Tauner0466c812013-06-16 10:30:08 +000023#include <inttypes.h>
Carl-Daniel Hailfinger11990da2013-07-13 23:21:05 +000024#include <stdio.h>
Ollie Lho184a4042005-11-26 21:55:36 +000025#include <stdint.h>
Carl-Daniel Hailfingerdd128c92010-06-03 00:49:50 +000026#include <stddef.h>
Nico Huber18781102012-12-10 13:34:12 +000027#include <stdarg.h>
Stefan Tauner682122b2013-06-23 22:15:39 +000028#include <stdbool.h>
Stefan Taunerb0eee9b2015-01-10 09:32:50 +000029#if IS_WINDOWS
Patrick Georgie48654c2010-01-06 22:14:39 +000030#include <windows.h>
31#undef min
32#undef max
33#endif
Andriy Gapon65c1b862008-05-22 13:22:45 +000034
Nico Huberd152fb92017-06-19 12:57:10 +020035#include "libflashrom.h"
Nico Huber3a9939b2016-04-27 15:56:14 +020036#include "layout.h"
Nikolai Artemievc6c3f282021-10-20 23:34:15 +110037#include "writeprotect.h"
Nico Huber3a9939b2016-04-27 15:56:14 +020038
Nico Huberd8b2e802019-06-18 23:39:56 +020039#define KiB (1024)
40#define MiB (1024 * KiB)
41
Edward O'Callaghandd9d0c52022-06-04 20:23:57 +100042#define BIT(x) (1<<(x))
43
Nico Huberd8b2e802019-06-18 23:39:56 +020044/* 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
Nico Huber3ac761c2023-01-16 02:43:17 +010096size_t gran_to_bytes(enum write_granularity);
97
Stefan Taunereb582572012-09-21 12:52:50 +000098/*
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +000099 * How many different contiguous runs of erase blocks with one size each do
100 * we have for a given erase function?
101 */
102#define NUM_ERASEREGIONS 5
103
104/*
105 * How many different erase functions do we have per chip?
Nico Huberaac81422017-11-10 22:54:13 +0100106 * Macronix MX25L25635F has 8 different functions.
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000107 */
Nico Huberaac81422017-11-10 22:54:13 +0100108#define NUM_ERASEFUNCTIONS 8
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000109
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100110#define MAX_CHIP_RESTORE_FUNCTIONS 4
111
Stefan Tauner0554ca52013-07-25 22:54:25 +0000112/* Feature bits used for non-SPI only */
Carl-Daniel Hailfinger4bf4e792010-01-09 03:15:50 +0000113#define FEATURE_REGISTERMAP (1 << 0)
Sean Nelson35727f72010-01-28 23:55:12 +0000114#define FEATURE_LONG_RESET (0 << 4)
115#define FEATURE_SHORT_RESET (1 << 4)
116#define FEATURE_EITHER_RESET FEATURE_LONG_RESET
Sean Nelsonf59e2632010-10-20 21:13:19 +0000117#define FEATURE_RESET_MASK (FEATURE_LONG_RESET | FEATURE_SHORT_RESET)
Carl-Daniel Hailfinger4bf4e792010-01-09 03:15:50 +0000118#define FEATURE_ADDR_FULL (0 << 2)
119#define FEATURE_ADDR_MASK (3 << 2)
Sean Nelson35727f72010-01-28 23:55:12 +0000120#define FEATURE_ADDR_2AA (1 << 2)
121#define FEATURE_ADDR_AAA (2 << 2)
Michael Karcherad0010a2010-04-03 10:27:08 +0000122#define FEATURE_ADDR_SHIFTED (1 << 5)
Stefan Tauner0554ca52013-07-25 22:54:25 +0000123/* Feature bits used for SPI only */
Carl-Daniel Hailfingerfd7075a2010-07-29 13:09:18 +0000124#define FEATURE_WRSR_EWSR (1 << 6)
125#define FEATURE_WRSR_WREN (1 << 7)
Stefan Tauner0554ca52013-07-25 22:54:25 +0000126#define FEATURE_WRSR_EITHER (FEATURE_WRSR_EWSR | FEATURE_WRSR_WREN)
Daniel Lenski65922a32012-02-15 23:40:23 +0000127#define FEATURE_OTP (1 << 8)
Vincent Palatinf800f552013-03-15 02:03:16 +0000128#define FEATURE_QPI (1 << 9)
Nico Huberfe34d2a2017-11-10 21:10:20 +0100129#define FEATURE_4BA_ENTER (1 << 10) /**< Can enter/exit 4BA mode with instructions 0xb7/0xe9 w/o WREN */
130#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 +0100131#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 +0200132#define FEATURE_4BA_EAR_C5C8 (1 << 13) /**< Regular 3-byte operations can be used by writing the most
133 significant address byte into an extended address register
134 (using 0xc5/0xc8 instructions). */
Nico Huber9bb8a322022-05-24 15:07:34 +0200135#define FEATURE_4BA_EAR_1716 (1 << 14) /**< Like FEATURE_4BA_EAR_C5C8 but with 0x17/0x16 instructions. */
136#define FEATURE_4BA_READ (1 << 15) /**< Native 4BA read instruction (0x13) is supported. */
137#define FEATURE_4BA_FAST_READ (1 << 16) /**< Native 4BA fast read instruction (0x0c) is supported. */
138#define FEATURE_4BA_WRITE (1 << 17) /**< Native 4BA byte program (0x12) is supported. */
Nico Huberaac81422017-11-10 22:54:13 +0100139/* 4BA Shorthands */
Nico Huber9bb8a322022-05-24 15:07:34 +0200140#define FEATURE_4BA_EAR_ANY (FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_EAR_1716)
Nico Huberaac81422017-11-10 22:54:13 +0100141#define FEATURE_4BA_NATIVE (FEATURE_4BA_READ | FEATURE_4BA_FAST_READ | FEATURE_4BA_WRITE)
Nico Huber542b1f02022-05-24 14:30:12 +0200142#define FEATURE_4BA (FEATURE_4BA_ENTER | FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_NATIVE)
143#define FEATURE_4BA_WREN (FEATURE_4BA_ENTER_WREN | FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_NATIVE)
144#define FEATURE_4BA_EAR7 (FEATURE_4BA_ENTER_EAR7 | FEATURE_4BA_EAR_C5C8 | FEATURE_4BA_NATIVE)
Paul Kocialkowski995f7552018-01-15 01:06:09 +0300145/*
146 * Most flash chips are erased to ones and programmed to zeros. However, some
147 * other flash chips, such as the ENE KB9012 internal flash, work the opposite way.
148 */
Nico Huber9bb8a322022-05-24 15:07:34 +0200149#define FEATURE_ERASED_ZERO (1 << 18)
150#define FEATURE_NO_ERASE (1 << 19)
Paul Kocialkowski995f7552018-01-15 01:06:09 +0300151
Nico Huber9bb8a322022-05-24 15:07:34 +0200152#define FEATURE_WRSR_EXT2 (1 << 20)
153#define FEATURE_WRSR2 (1 << 21)
154#define FEATURE_WRSR_EXT3 ((1 << 22) | FEATURE_WRSR_EXT2)
155#define FEATURE_WRSR3 (1 << 23)
Nikolai Artemiev9de3f872021-10-20 22:32:25 +1100156
Paul Kocialkowski995f7552018-01-15 01:06:09 +0300157#define ERASED_VALUE(flash) (((flash)->chip->feature_bits & FEATURE_ERASED_ZERO) ? 0x00 : 0xff)
Sean Nelsonc57a9202010-01-04 17:15:23 +0000158
Stefan Tauner6455dff2014-05-26 00:36:24 +0000159enum test_state {
160 OK = 0,
161 NT = 1, /* Not tested */
162 BAD, /* Known to not work */
163 DEP, /* Support depends on configuration (e.g. Intel flash descriptor) */
164 NA, /* Not applicable (e.g. write support on ROM chips) */
165};
166
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300167#define TEST_UNTESTED (struct tested){ .probe = NT, .read = NT, .erase = NT, .write = NT, .wp = NT }
Stefan Tauner6455dff2014-05-26 00:36:24 +0000168
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300169#define TEST_OK_PROBE (struct tested){ .probe = OK, .read = NT, .erase = NT, .write = NT, .wp = NT }
170#define TEST_OK_PR (struct tested){ .probe = OK, .read = OK, .erase = NT, .write = NT, .wp = NT }
171#define TEST_OK_PRE (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = NT, .wp = NT }
172#define TEST_OK_PREW (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = OK, .wp = NT }
173#define TEST_OK_PREWB (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = OK, .wp = OK }
Stefan Tauner6455dff2014-05-26 00:36:24 +0000174
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300175#define TEST_BAD_PROBE (struct tested){ .probe = BAD, .read = NT, .erase = NT, .write = NT, .wp = NT }
176#define TEST_BAD_PR (struct tested){ .probe = BAD, .read = BAD, .erase = NT, .write = NT, .wp = NT }
177#define TEST_BAD_PRE (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = NT, .wp = NT }
178#define TEST_BAD_PREW (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .wp = NT }
179#define TEST_BAD_PREWB (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .wp = BAD }
Stefan Tauner6455dff2014-05-26 00:36:24 +0000180
Nico Huber454f6132012-12-10 13:34:10 +0000181struct flashrom_flashctx;
Martin Rothf6c1cb12022-03-15 10:55:25 -0600182#define flashctx flashrom_flashctx /* TODO: Agree on a name and convert all occurrences. */
Carl-Daniel Hailfinger5a7cb842012-08-25 01:17:58 +0000183typedef int (erasefunc_t)(struct flashctx *flash, unsigned int addr, unsigned int blocklen);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000184
Nikolai Artemiev01675222021-10-20 22:30:41 +1100185enum flash_reg {
186 INVALID_REG = 0,
187 STATUS1,
188 STATUS2,
Sergii Dmytruk0b2e7dd2021-12-19 18:37:51 +0200189 STATUS3,
Nikolai Artemiev01675222021-10-20 22:30:41 +1100190 MAX_REGISTERS
191};
192
Nikolai Artemievc6c3f282021-10-20 23:34:15 +1100193struct reg_bit_info {
194 /* Register containing the bit */
195 enum flash_reg reg;
196
197 /* Bit index within register */
198 uint8_t bit_index;
199
200 /*
201 * Writability of the bit. RW does not guarantee the bit will be
202 * writable, for example if status register protection is enabled.
203 */
204 enum {
205 RO, /* Read only */
206 RW, /* Readable and writable */
207 OTP /* One-time programmable */
208 } writability;
209};
210
Nikolai Artemievc9feb1b2021-10-21 01:35:13 +1100211struct wp_bits;
212
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000213struct flashchip {
Uwe Hermann76158682008-03-14 23:55:58 +0000214 const char *vendor;
Uwe Hermann372eeb52007-12-04 21:49:06 +0000215 const char *name;
Carl-Daniel Hailfinger1dfe0ff2009-05-31 17:57:34 +0000216
217 enum chipbustype bustype;
218
Uwe Hermann394131e2008-10-18 21:14:13 +0000219 /*
220 * With 32bit manufacture_id and model_id we can cover IDs up to
Carl-Daniel Hailfingerae8afa92007-12-31 01:49:00 +0000221 * (including) the 4th bank of JEDEC JEP106W Standard Manufacturer's
222 * Identification code.
223 */
224 uint32_t manufacture_id;
225 uint32_t model_id;
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000226
Stefan Taunerc0aaf952011-05-19 02:58:17 +0000227 /* Total chip size in kilobytes */
Stefan Taunerc69c9c82011-11-23 09:13:48 +0000228 unsigned int total_size;
Stefan Taunerc0aaf952011-05-19 02:58:17 +0000229 /* Chip page size in bytes */
Stefan Taunerc69c9c82011-11-23 09:13:48 +0000230 unsigned int page_size;
Sean Nelsonc57a9202010-01-04 17:15:23 +0000231 int feature_bits;
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000232
Stefan Tauner6455dff2014-05-26 00:36:24 +0000233 /* Indicate how well flashrom supports different operations of this flash chip. */
234 struct tested {
235 enum test_state probe;
236 enum test_state read;
237 enum test_state erase;
238 enum test_state write;
Sergii Dmytrukc720b6e2022-10-06 15:17:52 +0300239 enum test_state wp;
Stefan Tauner6455dff2014-05-26 00:36:24 +0000240 } tested;
Peter Stuge1159d582008-05-03 04:34:37 +0000241
Mike Banon31b5e3b2018-01-15 01:10:00 +0300242 /*
243 * Group chips that have common command sets. This should ensure that
244 * no chip gets confused by a probing command for a very different class
245 * of chips.
246 */
247 enum {
248 /* SPI25 is very common. Keep it at zero so we don't have
249 to specify it for each and every chip in the database.*/
250 SPI25 = 0,
Paul Kocialkowski80ae14e2018-01-15 01:07:46 +0300251 SPI_EDI = 1,
Mike Banon31b5e3b2018-01-15 01:10:00 +0300252 } spi_cmd_set;
253
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000254 int (*probe) (struct flashctx *flash);
Maciej Pijankac6e11112009-06-03 14:46:22 +0000255
Stefan Taunerc69c9c82011-11-23 09:13:48 +0000256 /* Delay after "enter/exit ID mode" commands in microseconds.
257 * NB: negative values have special meanings, see TIMING_* below.
258 */
259 signed int probe_timing;
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000260
261 /*
Carl-Daniel Hailfinger63ce4bb2009-12-22 13:04:53 +0000262 * Erase blocks and associated erase function. Any chip erase function
263 * is stored as chip-sized virtual block together with said function.
Stefan Taunerc0aaf952011-05-19 02:58:17 +0000264 * The first one that fits will be chosen. There is currently no way to
265 * influence that behaviour. For testing just comment out the other
266 * elements or set the function pointer to NULL.
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000267 */
268 struct block_eraser {
Stefan Tauner6697f712014-08-06 15:09:15 +0000269 struct eraseblock {
Stefan Taunerd06d9412011-06-12 19:47:55 +0000270 unsigned int size; /* Eraseblock size in bytes */
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000271 unsigned int count; /* Number of contiguous blocks with that size */
272 } eraseblocks[NUM_ERASEREGIONS];
Stefan Tauner355cbfd2011-05-28 02:37:14 +0000273 /* a block_erase function should try to erase one block of size
274 * 'blocklen' at address 'blockaddr' and return 0 on success. */
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000275 int (*block_erase) (struct flashctx *flash, unsigned int blockaddr, unsigned int blocklen);
Carl-Daniel Hailfingerf38431a2009-09-05 02:30:58 +0000276 } block_erasers[NUM_ERASEFUNCTIONS];
277
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000278 int (*printlock) (struct flashctx *flash);
279 int (*unlock) (struct flashctx *flash);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000280 int (*write) (struct flashctx *flash, const uint8_t *buf, unsigned int start, unsigned int len);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000281 int (*read) (struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
282 struct voltage {
Steven Zakuleccbe370e2011-06-03 07:26:31 +0000283 uint16_t min;
284 uint16_t max;
285 } voltage;
Stefan Tauner50d67aa2013-03-03 23:49:48 +0000286 enum write_granularity gran;
Nico Huber57dbd642018-03-13 18:01:05 +0100287
Nikolai Artemievc6c3f282021-10-20 23:34:15 +1100288 struct reg_bit_map {
289 /* Status register protection bit (SRP) */
290 struct reg_bit_info srp;
291
292 /* Status register lock bit (SRP) */
293 struct reg_bit_info srl;
294
295 /*
296 * Note: some datasheets refer to configuration bits that
297 * function like TB/SEC/CMP bits as BP bits (e.g. BP3 for a bit
298 * that functions like TB).
299 *
300 * As a convention, any config bit that functions like a
301 * TB/SEC/CMP bit should be assigned to the respective
302 * tb/sec/cmp field in this structure, even if the datasheet
303 * uses a different name.
304 */
305
306 /* Block protection bits (BP) */
307 /* Extra element for terminator */
308 struct reg_bit_info bp[MAX_BP_BITS + 1];
309
310 /* Top/bottom protection bit (TB) */
311 struct reg_bit_info tb;
312
313 /* Sector/block protection bit (SEC) */
314 struct reg_bit_info sec;
315
316 /* Complement bit (CMP) */
317 struct reg_bit_info cmp;
Sergii Dmytruk801fcd02021-12-19 18:45:16 +0200318
319 /* Write Protect Selection (per sector protection when set) */
320 struct reg_bit_info wps;
Nikolai Artemievc6c3f282021-10-20 23:34:15 +1100321 } reg_bits;
Nikolai Artemievc9feb1b2021-10-21 01:35:13 +1100322
323 /* Function that takes a set of WP config bits (e.g. BP, SEC, TB, etc) */
324 /* and determines what protection range they select. */
325 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 +0000326};
Ronald G. Minnicheaab50b2003-09-12 22:41:53 +0000327
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100328typedef int (*chip_restore_fn_cb_t)(struct flashctx *flash, uint8_t status);
329
Nico Huber454f6132012-12-10 13:34:10 +0000330struct flashrom_flashctx {
Carl-Daniel Hailfinger5a7cb842012-08-25 01:17:58 +0000331 struct flashchip *chip;
Stefan Tauner4e32ec12014-08-30 23:39:51 +0000332 /* FIXME: The memory mappings should be saved in a more structured way. */
333 /* The physical_* fields store the respective addresses in the physical address space of the CPU. */
334 uintptr_t physical_memory;
335 /* The virtual_* fields store where the respective physical address is mapped into flashrom's address
336 * space. A value equivalent to (chipaddr)ERROR_PTR indicates an invalid mapping (or none at all). */
Carl-Daniel Hailfinger5820f422009-05-16 21:22:56 +0000337 chipaddr virtual_memory;
Stefan Tauner4e32ec12014-08-30 23:39:51 +0000338 /* Some flash devices have an additional register space; semantics are like above. */
339 uintptr_t physical_registers;
Carl-Daniel Hailfinger5820f422009-05-16 21:22:56 +0000340 chipaddr virtual_registers;
Carl-Daniel Hailfingera5bcbce2014-07-19 22:03:29 +0000341 struct registered_master *mst;
Nico Huber7af0e792016-04-29 16:40:15 +0200342 const struct flashrom_layout *layout;
Nico Huber5bd990c2019-06-16 19:46:46 +0200343 struct flashrom_layout *default_layout;
Nico Huber454f6132012-12-10 13:34:10 +0000344 struct {
345 bool force;
346 bool force_boardmismatch;
347 bool verify_after_write;
348 bool verify_whole_chip;
349 } flags;
Nico Huberf43c6542017-10-14 17:47:28 +0200350 /* We cache the state of the extended address register (highest byte
351 of a 4BA for 3BA instructions) and the state of the 4BA mode here.
352 If possible, we enter 4BA mode early. If that fails, we make use
353 of the extended address register. */
354 int address_high_byte;
355 bool in_4ba_mode;
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100356
357 int chip_restore_fn_count;
358 struct chip_restore_func_data {
359 chip_restore_fn_cb_t func;
360 uint8_t status;
361 } chip_restore_fn[MAX_CHIP_RESTORE_FUNCTIONS];
Ronald G. Minnich5e5f75e2002-01-29 18:21:41 +0000362};
363
Maciej Pijankac6e11112009-06-03 14:46:22 +0000364/* Timing used in probe routines. ZERO is -2 to differentiate between an unset
365 * field and zero delay.
Paul Kocialkowski80ae14e2018-01-15 01:07:46 +0300366 *
Maciej Pijankac6e11112009-06-03 14:46:22 +0000367 * SPI devices will always have zero delay and ignore this field.
368 */
369#define TIMING_FIXME -1
370/* this is intentionally same value as fixme */
371#define TIMING_IGNORED -1
372#define TIMING_ZERO -2
373
Carl-Daniel Hailfinger4c823182011-05-04 00:39:50 +0000374extern const struct flashchip flashchips[];
Stefan Tauner96658be2014-05-26 22:05:31 +0000375extern const unsigned int flashchips_size;
Ollie Lho184a4042005-11-26 21:55:36 +0000376
Edward O'Callaghan63f6a372022-08-12 12:56:43 +1000377/* parallel.c */
Carl-Daniel Hailfinger8a3c60c2011-12-18 15:01:24 +0000378void chip_writeb(const struct flashctx *flash, uint8_t val, chipaddr addr);
379void chip_writew(const struct flashctx *flash, uint16_t val, chipaddr addr);
380void chip_writel(const struct flashctx *flash, uint32_t val, chipaddr addr);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000381void chip_writen(const struct flashctx *flash, const uint8_t *buf, chipaddr addr, size_t len);
Carl-Daniel Hailfinger8a3c60c2011-12-18 15:01:24 +0000382uint8_t chip_readb(const struct flashctx *flash, const chipaddr addr);
383uint16_t chip_readw(const struct flashctx *flash, const chipaddr addr);
384uint32_t chip_readl(const struct flashctx *flash, const chipaddr addr);
385void chip_readn(const struct flashctx *flash, uint8_t *buf, const chipaddr addr, size_t len);
386
Uwe Hermannba290d12009-06-17 12:07:12 +0000387/* print.c */
Edward O'Callaghan3b64d812022-08-12 13:07:51 +1000388void print_buildinfo(void);
389void print_version(void);
390void print_banner(void);
Niklas Söderlundede2fa42012-10-23 13:06:46 +0000391int print_supported(void);
Carl-Daniel Hailfingerf5292052009-11-17 09:57:34 +0000392void print_supported_wiki(void);
Uwe Hermann515ab3d2009-05-15 17:02:34 +0000393
Stefan Tauner6ad6e012014-06-12 00:04:32 +0000394/* helpers.c */
395uint32_t address_to_bits(uint32_t addr);
Nico Huber519be662018-12-23 20:03:35 +0100396unsigned int bitcount(unsigned long a);
397#undef MIN
398#define MIN(a, b) ((a) < (b) ? (a) : (b))
399#undef MAX
400#define MAX(a, b) ((a) > (b) ? (a) : (b))
Stefan Tauner6ad6e012014-06-12 00:04:32 +0000401int max(int a, int b);
402int min(int a, int b);
403char *strcat_realloc(char *dest, const char *src);
404void tolower_string(char *str);
Marc Schink7ecfe482016-03-17 16:07:23 +0100405uint8_t reverse_byte(uint8_t x);
406void reverse_bytes(uint8_t *dst, const uint8_t *src, size_t length);
Stefan Taunerb41d8472014-11-01 22:56:06 +0000407#ifdef __MINGW32__
408char* strtok_r(char *str, const char *delim, char **nextp);
Miklós Márton8900d6c2019-07-30 00:03:22 +0200409char *strndup(const char *str, size_t size);
Stefan Taunerb41d8472014-11-01 22:56:06 +0000410#endif
Nico Huber2d625722016-05-03 10:48:02 +0200411#if defined(__DJGPP__) || (!defined(__LIBPAYLOAD__) && !defined(HAVE_STRNLEN))
Stefan Taunerdc627932015-01-27 18:07:50 +0000412size_t strnlen(const char *str, size_t n);
413#endif
Stefan Tauner6ad6e012014-06-12 00:04:32 +0000414
Uwe Hermann0846f892007-08-23 13:34:59 +0000415/* flashrom.c */
Mathias Krausea60faab2011-01-17 07:50:42 +0000416extern const char flashrom_version[];
Nico Huberbcb2e5a2012-12-30 01:23:17 +0000417extern const char *chip_to_probe;
Nico Huber2d625722016-05-03 10:48:02 +0200418char *flashbuses_to_text(enum chipbustype bustype);
Stefan Tauner4e32ec12014-08-30 23:39:51 +0000419int map_flash(struct flashctx *flash);
420void unmap_flash(struct flashctx *flash);
Carl-Daniel Hailfinger63fd9022011-12-14 22:25:15 +0000421int read_memmapped(struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
422int erase_flash(struct flashctx *flash);
Carl-Daniel Hailfingera5bcbce2014-07-19 22:03:29 +0000423int probe_flash(struct registered_master *mst, int startchip, struct flashctx *fill_flash, int force);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000424int verify_range(struct flashctx *flash, const uint8_t *cmpbuf, unsigned int start, unsigned int len);
Edward O'Callaghanc72d20a2021-12-13 12:30:03 +1100425void emergency_help_message(void);
Carl-Daniel Hailfingera73fb492010-10-06 23:48:34 +0000426void list_programmers_linebreak(int startcol, int cols, int paren);
Carl-Daniel Hailfingera84835a2010-01-07 03:24:05 +0000427int selfcheck(void);
Stefan Tauner66652442011-06-26 17:38:17 +0000428int read_buf_from_file(unsigned char *buf, unsigned long size, const char *filename);
Mark Marshallf20b7be2014-05-09 21:16:21 +0000429int write_buf_to_file(const unsigned char *buf, unsigned long size, const char *filename);
Nico Huber305f4172013-06-14 11:55:26 +0200430int prepare_flash_access(struct flashctx *, bool read_it, bool write_it, bool erase_it, bool verify_it);
431void finalize_flash_access(struct flashctx *);
Nikolai Artemiev4ad48642020-11-05 13:54:27 +1100432int register_chip_restore(chip_restore_fn_cb_t func, struct flashctx *flash, uint8_t status);
Uwe Hermannba290d12009-06-17 12:07:12 +0000433
Tadas Slotkusad470342011-09-03 17:15:00 +0000434/* Something happened that shouldn't happen, but we can go on. */
Michael Karchera4448d92010-07-22 18:04:15 +0000435#define ERROR_NONFATAL 0x100
436
Tadas Slotkusad470342011-09-03 17:15:00 +0000437/* Something happened that shouldn't happen, we'll abort. */
438#define ERROR_FATAL -0xee
Carl-Daniel Hailfingerc40cff72011-12-20 00:19:29 +0000439#define ERROR_FLASHROM_BUG -200
440/* We reached one of the hardcoded limits of flashrom. This can be fixed by
441 * increasing the limit of a compile-time allocation or by switching to dynamic
442 * allocation.
443 * Note: If this warning is triggered, check first for runaway registrations.
444 */
445#define ERROR_FLASHROM_LIMIT -201
Tadas Slotkusad470342011-09-03 17:15:00 +0000446
Stefan Tauner9b32de92014-08-08 23:52:33 +0000447/* cli_common.c */
Stefan Tauner9b32de92014-08-08 23:52:33 +0000448void print_chip_support_status(const struct flashchip *chip);
449
Sean Nelson51e97d72010-01-07 20:09:33 +0000450/* cli_output.c */
Nico Huberd152fb92017-06-19 12:57:10 +0200451extern enum flashrom_log_level verbose_screen;
452extern enum flashrom_log_level verbose_logfile;
Carl-Daniel Hailfinger1c155482012-06-06 09:17:06 +0000453int open_logfile(const char * const filename);
454int close_logfile(void);
455void start_logging(void);
Nico Huberd152fb92017-06-19 12:57:10 +0200456int flashrom_print_cb(enum flashrom_log_level level, const char *fmt, va_list ap);
Carl-Daniel Hailfinger9f5f2152010-06-04 23:20:21 +0000457/* Let gcc and clang check for correct printf-style format strings. */
Nico Huberd152fb92017-06-19 12:57:10 +0200458int print(enum flashrom_log_level level, const char *fmt, ...)
Carl-Daniel Hailfinger11990da2013-07-13 23:21:05 +0000459#ifdef __MINGW32__
Antonio Ospiteb6e3d252018-03-03 18:40:24 +0100460# ifndef __MINGW_PRINTF_FORMAT
461# define __MINGW_PRINTF_FORMAT gnu_printf
462# endif
Stefan Taunerf268d8b2017-10-26 18:45:00 +0200463__attribute__((format(__MINGW_PRINTF_FORMAT, 2, 3)));
Carl-Daniel Hailfinger11990da2013-07-13 23:21:05 +0000464#else
465__attribute__((format(printf, 2, 3)));
466#endif
Nico Huberd152fb92017-06-19 12:57:10 +0200467#define msg_gerr(...) print(FLASHROM_MSG_ERROR, __VA_ARGS__) /* general errors */
468#define msg_perr(...) print(FLASHROM_MSG_ERROR, __VA_ARGS__) /* programmer errors */
469#define msg_cerr(...) print(FLASHROM_MSG_ERROR, __VA_ARGS__) /* chip errors */
470#define msg_gwarn(...) print(FLASHROM_MSG_WARN, __VA_ARGS__) /* general warnings */
471#define msg_pwarn(...) print(FLASHROM_MSG_WARN, __VA_ARGS__) /* programmer warnings */
472#define msg_cwarn(...) print(FLASHROM_MSG_WARN, __VA_ARGS__) /* chip warnings */
473#define msg_ginfo(...) print(FLASHROM_MSG_INFO, __VA_ARGS__) /* general info */
474#define msg_pinfo(...) print(FLASHROM_MSG_INFO, __VA_ARGS__) /* programmer info */
475#define msg_cinfo(...) print(FLASHROM_MSG_INFO, __VA_ARGS__) /* chip info */
476#define msg_gdbg(...) print(FLASHROM_MSG_DEBUG, __VA_ARGS__) /* general debug */
477#define msg_pdbg(...) print(FLASHROM_MSG_DEBUG, __VA_ARGS__) /* programmer debug */
478#define msg_cdbg(...) print(FLASHROM_MSG_DEBUG, __VA_ARGS__) /* chip debug */
479#define msg_gdbg2(...) print(FLASHROM_MSG_DEBUG2, __VA_ARGS__) /* general debug2 */
480#define msg_pdbg2(...) print(FLASHROM_MSG_DEBUG2, __VA_ARGS__) /* programmer debug2 */
481#define msg_cdbg2(...) print(FLASHROM_MSG_DEBUG2, __VA_ARGS__) /* chip debug2 */
482#define msg_gspew(...) print(FLASHROM_MSG_SPEW, __VA_ARGS__) /* general debug spew */
483#define msg_pspew(...) print(FLASHROM_MSG_SPEW, __VA_ARGS__) /* programmer debug spew */
484#define msg_cspew(...) print(FLASHROM_MSG_SPEW, __VA_ARGS__) /* chip debug spew */
Sean Nelson51e97d72010-01-07 20:09:33 +0000485
Carl-Daniel Hailfinger00f911e2007-10-15 21:44:47 +0000486/* spi.c */
Carl-Daniel Hailfingerd0478292009-07-10 21:08:55 +0000487struct spi_command {
488 unsigned int writecnt;
489 unsigned int readcnt;
490 const unsigned char *writearr;
491 unsigned char *readarr;
492};
Nico Hubera3140d02017-10-15 11:20:58 +0200493#define NULL_SPI_CMD { 0, 0, NULL, NULL, }
Edward O'Callaghan5eca4272020-04-12 17:27:53 +1000494int spi_send_command(const struct flashctx *flash, unsigned int writecnt, unsigned int readcnt, const unsigned char *writearr, unsigned char *readarr);
495int spi_send_multicommand(const struct flashctx *flash, struct spi_command *cmds);
Mats Erik Andersson44e1a192008-09-26 13:19:02 +0000496
Carl-Daniel Hailfingerc40cff72011-12-20 00:19:29 +0000497enum chipbustype get_buses_supported(void);
Ollie Lho761bf1b2004-03-20 16:46:10 +0000498#endif /* !__FLASH_H__ */