flash.h

   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 <stdint.h>
  28 #include <stddef.h>
  29 #ifdef _WIN32
  30 #include <windows.h>
  31 #undef min
  32 #undef max
  33 #endif
  34
  35 #define ERROR_PTR ((void*)-1)
  36
  37 /* Error codes */
  38 #define ERROR_OOM       -100
  39 #define TIMEOUT_ERROR   -101
  40
  41 typedef unsigned long chipaddr;
  42
  43 int register_shutdown(int (*function) (void *data), void *data);
  44 void *programmer_map_flash_region(const char *descr, unsigned long phys_addr,
  45                                   size_t len);
  46 void programmer_unmap_flash_region(void *virt_addr, size_t len);
  47 void programmer_delay(int usecs);
  48
  49 #define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
  50
  51 enum chipbustype {
  52         BUS_NONE        = 0,
  53         BUS_PARALLEL    = 1 << 0,
  54         BUS_LPC         = 1 << 1,
  55         BUS_FWH         = 1 << 2,
  56         BUS_SPI         = 1 << 3,
  57         BUS_PROG        = 1 << 4,
  58         BUS_NONSPI      = BUS_PARALLEL | BUS_LPC | BUS_FWH,
  59 };
  60
  61 /*
  62  * How many different contiguous runs of erase blocks with one size each do
  63  * we have for a given erase function?
  64  */
  65 #define NUM_ERASEREGIONS 5
  66
  67 /*
  68  * How many different erase functions do we have per chip?
  69  * Atmel AT25FS010 has 6 different functions.
  70  */
  71 #define NUM_ERASEFUNCTIONS 6
  72
  73 #define FEATURE_REGISTERMAP     (1 << 0)
  74 #define FEATURE_BYTEWRITES      (1 << 1)
  75 #define FEATURE_LONG_RESET      (0 << 4)
  76 #define FEATURE_SHORT_RESET     (1 << 4)
  77 #define FEATURE_EITHER_RESET    FEATURE_LONG_RESET
  78 #define FEATURE_RESET_MASK      (FEATURE_LONG_RESET | FEATURE_SHORT_RESET)
  79 #define FEATURE_ADDR_FULL       (0 << 2)
  80 #define FEATURE_ADDR_MASK       (3 << 2)
  81 #define FEATURE_ADDR_2AA        (1 << 2)
  82 #define FEATURE_ADDR_AAA        (2 << 2)
  83 #define FEATURE_ADDR_SHIFTED    (1 << 5)
  84 #define FEATURE_WRSR_EWSR       (1 << 6)
  85 #define FEATURE_WRSR_WREN       (1 << 7)
  86 #define FEATURE_OTP             (1 << 8)
  87 #define FEATURE_WRSR_EITHER     (FEATURE_WRSR_EWSR | FEATURE_WRSR_WREN)
  88
  89 struct flashctx;
  90
  91 struct flashchip {
  92         const char *vendor;
  93         const char *name;
  94
  95         enum chipbustype bustype;
  96
  97         /*
  98          * With 32bit manufacture_id and model_id we can cover IDs up to
  99          * (including) the 4th bank of JEDEC JEP106W Standard Manufacturer's
 100          * Identification code.
 101          */
 102         uint32_t manufacture_id;
 103         uint32_t model_id;
 104
 105         /* Total chip size in kilobytes */
 106         unsigned int total_size;
 107         /* Chip page size in bytes */
 108         unsigned int page_size;
 109         int feature_bits;
 110
 111         /*
 112          * Indicate if flashrom has been tested with this flash chip and if
 113          * everything worked correctly.
 114          */
 115         uint32_t tested;
 116
 117         int (*probe) (struct flashctx *flash);
 118
 119         /* Delay after "enter/exit ID mode" commands in microseconds.
 120          * NB: negative values have special meanings, see TIMING_* below.
 121          */
 122         signed int probe_timing;
 123
 124         /*
 125          * Erase blocks and associated erase function. Any chip erase function
 126          * is stored as chip-sized virtual block together with said function.
 127          * The first one that fits will be chosen. There is currently no way to
 128          * influence that behaviour. For testing just comment out the other
 129          * elements or set the function pointer to NULL.
 130          */
 131         struct block_eraser {
 132                 struct eraseblock{
 133                         unsigned int size; /* Eraseblock size in bytes */
 134                         unsigned int count; /* Number of contiguous blocks with that size */
 135                 } eraseblocks[NUM_ERASEREGIONS];
 136                 /* a block_erase function should try to erase one block of size
 137                  * 'blocklen' at address 'blockaddr' and return 0 on success. */
 138                 int (*block_erase) (struct flashctx *flash, unsigned int blockaddr, unsigned int blocklen);
 139         } block_erasers[NUM_ERASEFUNCTIONS];
 140
 141         int (*printlock) (struct flashctx *flash);
 142         int (*unlock) (struct flashctx *flash);
 143         int (*write) (struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
 144         int (*read) (struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
 145         struct voltage {
 146                 uint16_t min;
 147                 uint16_t max;
 148         } voltage;
 149 };
 150
 151 /* struct flashctx must always contain struct flashchip at the beginning. */
 152 struct flashctx {
 153         const char *vendor;
 154         const char *name;
 155         enum chipbustype bustype;
 156         uint32_t manufacture_id;
 157         uint32_t model_id;
 158         int total_size;
 159         int page_size;
 160         int feature_bits;
 161         uint32_t tested;
 162         int (*probe) (struct flashctx *flash);
 163         int probe_timing;
 164         struct block_eraser block_erasers[NUM_ERASEFUNCTIONS];
 165         int (*printlock) (struct flashctx *flash);
 166         int (*unlock) (struct flashctx *flash);
 167         int (*write) (struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
 168         int (*read) (struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
 169         struct voltage voltage;
 170         /* struct flashchip ends here. */
 171
 172         chipaddr virtual_memory;
 173         /* Some flash devices have an additional register space. */
 174         chipaddr virtual_registers;
 175         struct registered_programmer *pgm;
 176 };
 177
 178 typedef int (erasefunc_t)(struct flashctx *flash, unsigned int addr, unsigned int blocklen);
 179
 180 #define TEST_UNTESTED   0
 181
 182 #define TEST_OK_PROBE   (1 << 0)
 183 #define TEST_OK_READ    (1 << 1)
 184 #define TEST_OK_ERASE   (1 << 2)
 185 #define TEST_OK_WRITE   (1 << 3)
 186 #define TEST_OK_PR      (TEST_OK_PROBE | TEST_OK_READ)
 187 #define TEST_OK_PRE     (TEST_OK_PROBE | TEST_OK_READ | TEST_OK_ERASE)
 188 #define TEST_OK_PRW     (TEST_OK_PROBE | TEST_OK_READ | TEST_OK_WRITE)
 189 #define TEST_OK_PREW    (TEST_OK_PROBE | TEST_OK_READ | TEST_OK_ERASE | TEST_OK_WRITE)
 190 #define TEST_OK_MASK    0x0f
 191
 192 #define TEST_BAD_PROBE  (1 << 4)
 193 #define TEST_BAD_READ   (1 << 5)
 194 #define TEST_BAD_ERASE  (1 << 6)
 195 #define TEST_BAD_WRITE  (1 << 7)
 196 #define TEST_BAD_PREW   (TEST_BAD_PROBE | TEST_BAD_READ | TEST_BAD_ERASE | TEST_BAD_WRITE)
 197 #define TEST_BAD_MASK   0xf0
 198
 199 /* Timing used in probe routines. ZERO is -2 to differentiate between an unset
 200  * field and zero delay.
 201  *
 202  * SPI devices will always have zero delay and ignore this field.
 203  */
 204 #define TIMING_FIXME    -1
 205 /* this is intentionally same value as fixme */
 206 #define TIMING_IGNORED  -1
 207 #define TIMING_ZERO     -2
 208
 209 extern const struct flashchip flashchips[];
 210
 211 void chip_writeb(const struct flashctx *flash, uint8_t val, chipaddr addr);
 212 void chip_writew(const struct flashctx *flash, uint16_t val, chipaddr addr);
 213 void chip_writel(const struct flashctx *flash, uint32_t val, chipaddr addr);
 214 void chip_writen(const struct flashctx *flash, uint8_t *buf, chipaddr addr, size_t len);
 215 uint8_t chip_readb(const struct flashctx *flash, const chipaddr addr);
 216 uint16_t chip_readw(const struct flashctx *flash, const chipaddr addr);
 217 uint32_t chip_readl(const struct flashctx *flash, const chipaddr addr);
 218 void chip_readn(const struct flashctx *flash, uint8_t *buf, const chipaddr addr, size_t len);
 219
 220 /* print.c */
 221 char *flashbuses_to_text(enum chipbustype bustype);
 222 void print_supported(void);
 223 void print_supported_wiki(void);
 224
 225 /* flashrom.c */
 226 enum write_granularity {
 227         write_gran_1bit,
 228         write_gran_1byte,
 229         write_gran_256bytes,
 230 };
 231 extern int verbose_screen;
 232 extern int verbose_logfile;
 233 extern const char flashrom_version[];
 234 extern char *chip_to_probe;
 235 void map_flash_registers(struct flashctx *flash);
 236 int read_memmapped(struct flashctx *flash, uint8_t *buf, unsigned int start, unsigned int len);
 237 int erase_flash(struct flashctx *flash);
 238 int probe_flash(struct registered_programmer *pgm, int startchip, struct flashctx *fill_flash, int force);
 239 int read_flash_to_file(struct flashctx *flash, const char *filename);
 240 int min(int a, int b);
 241 int max(int a, int b);
 242 void tolower_string(char *str);
 243 char *extract_param(char **haystack, const char *needle, const char *delim);
 244 int verify_range(struct flashctx *flash, uint8_t *cmpbuf, unsigned int start, unsigned int len, const char *message);
 245 int need_erase(uint8_t *have, uint8_t *want, unsigned int len, enum write_granularity gran);
 246 char *strcat_realloc(char *dest, const char *src);
 247 void print_version(void);
 248 void print_buildinfo(void);
 249 void print_banner(void);
 250 void list_programmers_linebreak(int startcol, int cols, int paren);
 251 int selfcheck(void);
 252 int doit(struct flashctx *flash, int force, const char *filename, int read_it, int write_it, int erase_it, int verify_it);
 253 int read_buf_from_file(unsigned char *buf, unsigned long size, const char *filename);
 254 int write_buf_to_file(unsigned char *buf, unsigned long size, const char *filename);
 255
 256 enum test_state {
 257         OK = 0,
 258         NT = 1, /* Not tested */
 259         BAD
 260 };
 261
 262 /* Something happened that shouldn't happen, but we can go on. */
 263 #define ERROR_NONFATAL 0x100
 264
 265 /* Something happened that shouldn't happen, we'll abort. */
 266 #define ERROR_FATAL -0xee
 267 #define ERROR_FLASHROM_BUG -200
 268 /* We reached one of the hardcoded limits of flashrom. This can be fixed by
 269  * increasing the limit of a compile-time allocation or by switching to dynamic
 270  * allocation.
 271  * Note: If this warning is triggered, check first for runaway registrations.
 272  */
 273 #define ERROR_FLASHROM_LIMIT -201
 274
 275 /* cli_output.c */
 276 #ifndef STANDALONE
 277 int open_logfile(const char * const filename);
 278 int close_logfile(void);
 279 void start_logging(void);
 280 #endif
 281 enum msglevel {
 282         MSG_ERROR       = 0,
 283         MSG_INFO        = 1,
 284         MSG_DEBUG       = 2,
 285         MSG_DEBUG2      = 3,
 286         MSG_SPEW        = 4,
 287 };
 288 /* Let gcc and clang check for correct printf-style format strings. */
 289 int print(enum msglevel level, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 290 #define msg_gerr(...)   print(MSG_ERROR, __VA_ARGS__)   /* general errors */
 291 #define msg_perr(...)   print(MSG_ERROR, __VA_ARGS__)   /* programmer errors */
 292 #define msg_cerr(...)   print(MSG_ERROR, __VA_ARGS__)   /* chip errors */
 293 #define msg_ginfo(...)  print(MSG_INFO, __VA_ARGS__)    /* general info */
 294 #define msg_pinfo(...)  print(MSG_INFO, __VA_ARGS__)    /* programmer info */
 295 #define msg_cinfo(...)  print(MSG_INFO, __VA_ARGS__)    /* chip info */
 296 #define msg_gdbg(...)   print(MSG_DEBUG, __VA_ARGS__)   /* general debug */
 297 #define msg_pdbg(...)   print(MSG_DEBUG, __VA_ARGS__)   /* programmer debug */
 298 #define msg_cdbg(...)   print(MSG_DEBUG, __VA_ARGS__)   /* chip debug */
 299 #define msg_gdbg2(...)  print(MSG_DEBUG2, __VA_ARGS__)  /* general debug2 */
 300 #define msg_pdbg2(...)  print(MSG_DEBUG2, __VA_ARGS__)  /* programmer debug2 */
 301 #define msg_cdbg2(...)  print(MSG_DEBUG2, __VA_ARGS__)  /* chip debug2 */
 302 #define msg_gspew(...)  print(MSG_SPEW, __VA_ARGS__)    /* general debug spew  */
 303 #define msg_pspew(...)  print(MSG_SPEW, __VA_ARGS__)    /* programmer debug spew  */
 304 #define msg_cspew(...)  print(MSG_SPEW, __VA_ARGS__)    /* chip debug spew  */
 305
 306 /* layout.c */
 307 int register_include_arg(char *name);
 308 int process_include_args(void);
 309 int read_romlayout(char *name);
 310 int handle_romentries(struct flashctx *flash, uint8_t *oldcontents, uint8_t *newcontents);
 311
 312 /* spi.c */
 313 struct spi_command {
 314         unsigned int writecnt;
 315         unsigned int readcnt;
 316         const unsigned char *writearr;
 317         unsigned char *readarr;
 318 };
 319 int spi_send_command(struct flashctx *flash, unsigned int writecnt, unsigned int readcnt, const unsigned char *writearr, unsigned char *readarr);
 320 int spi_send_multicommand(struct flashctx *flash, struct spi_command *cmds);
 321 uint32_t spi_get_valid_read_addr(struct flashctx *flash);
 322
 323 enum chipbustype get_buses_supported(void);
 324 #endif                          /* !__FLASH_H__ */