1 /* 2 * This file is part of the flashrom project. 3 * 4 * Copyright (C) 2010 Google Inc. 5 * Copyright (C) 2012 secunet Security Networks AG 6 * (Written by Nico Huber <[email protected]> for secunet) 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation; either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 */ 18 19 #ifndef __LIBFLASHROM_H__ 20 #define __LIBFLASHROM_H__ 1 21 22 /** 23 * @mainpage 24 * 25 * Have a look at the Modules section for a function reference. 26 */ 27 28 #include <sys/types.h> 29 #include <stddef.h> 30 #include <stdbool.h> 31 #include <stdint.h> 32 #include <stdarg.h> 33 34 /** 35 * @defgroup flashrom-general General 36 * @{ 37 */ 38 39 /** 40 * @brief Initialize libflashrom. 41 * 42 * @param perform_selfcheck If not zero, perform a self check. 43 * @return 0 on success 44 */ 45 int flashrom_init(int perform_selfcheck); 46 /** 47 * @brief Shut down libflashrom. 48 * @return 0 on success 49 */ 50 int flashrom_shutdown(void); 51 enum flashrom_log_level { 52 FLASHROM_MSG_ERROR = 0, 53 FLASHROM_MSG_WARN = 1, 54 FLASHROM_MSG_INFO = 2, 55 FLASHROM_MSG_DEBUG = 3, 56 FLASHROM_MSG_DEBUG2 = 4, 57 FLASHROM_MSG_SPEW = 5, 58 }; 59 typedef int(flashrom_log_callback)(enum flashrom_log_level, const char *format, va_list); 60 /** 61 * @brief Set the log callback function. 62 * 63 * Set a callback function which will be invoked whenever libflashrom wants 64 * to output messages. This allows frontends to do whatever they see fit with 65 * such messages, e.g. write them to syslog, or to a file, or print them in a 66 * GUI window, etc. 67 * 68 * @param log_callback Pointer to the new log callback function. 69 */ 70 void flashrom_set_log_callback(flashrom_log_callback *log_callback); 71 72 enum flashrom_progress_stage { 73 FLASHROM_PROGRESS_READ, 74 FLASHROM_PROGRESS_WRITE, 75 FLASHROM_PROGRESS_ERASE, 76 FLASHROM_PROGRESS_NR, 77 }; 78 struct flashrom_progress { 79 enum flashrom_progress_stage stage; 80 size_t current; 81 size_t total; 82 void *user_data; 83 }; 84 struct flashrom_flashctx; 85 typedef void(flashrom_progress_callback)(struct flashrom_flashctx *flashctx); 86 /** 87 * @brief Set the progress callback function. 88 * 89 * Set a callback function which will be invoked whenever libflashrom wants 90 * to indicate the progress has changed. This allows frontends to do whatever 91 * they see fit with such values, e.g. update a progress bar in a GUI tool. 92 * 93 * @param progress_callback Pointer to the new progress callback function. 94 * @param progress_state Pointer to progress state to include with the progress 95 * callback. 96 */ 97 void flashrom_set_progress_callback(struct flashrom_flashctx *const flashctx, 98 flashrom_progress_callback *progress_callback, struct flashrom_progress *progress_state); 99 100 /** @} */ /* end flashrom-general */ 101 102 /** 103 * @defgroup flashrom-query Querying 104 * @{ 105 */ 106 107 enum flashrom_test_state { 108 FLASHROM_TESTED_OK = 0, 109 FLASHROM_TESTED_NT = 1, 110 FLASHROM_TESTED_BAD = 2, 111 FLASHROM_TESTED_DEP = 3, 112 FLASHROM_TESTED_NA = 4, 113 }; 114 115 struct flashrom_flashchip_info { 116 const char *vendor; 117 const char *name; 118 uint32_t manufacture_id; 119 uint32_t model_id; 120 unsigned int total_size; 121 struct flashrom_tested { 122 enum flashrom_test_state probe; 123 enum flashrom_test_state read; 124 enum flashrom_test_state erase; 125 enum flashrom_test_state write; 126 enum flashrom_test_state wp; 127 } tested; 128 }; 129 130 struct flashrom_board_info { 131 const char *vendor; 132 const char *name; 133 enum flashrom_test_state working; 134 }; 135 136 struct flashrom_chipset_info { 137 const char *vendor; 138 const char *chipset; 139 uint16_t vendor_id; 140 uint16_t chipset_id; 141 enum flashrom_test_state status; 142 }; 143 144 /** 145 * @brief Returns flashrom version 146 * @return flashrom version 147 */ 148 const char *flashrom_version_info(void); 149 /** 150 * @brief Returns list of supported flash chips 151 * @return List of supported flash chips, or NULL if an error occurred 152 */ 153 struct flashrom_flashchip_info *flashrom_supported_flash_chips(void); 154 /** 155 * @brief Returns list of supported mainboards 156 * @return List of supported mainboards, or NULL if an error occurred 157 */ 158 struct flashrom_board_info *flashrom_supported_boards(void); 159 /** 160 * @brief Returns list of supported chipsets 161 * @return List of supported chipsets, or NULL if an error occurred 162 */ 163 struct flashrom_chipset_info *flashrom_supported_chipsets(void); 164 /** 165 * @brief Frees memory allocated by libflashrom API 166 * @param p Pointer to block of memory which should be freed 167 * @return 0 on success 168 */ 169 int flashrom_data_free(void *const p); 170 171 /** @} */ /* end flashrom-query */ 172 173 /** 174 * @defgroup flashrom-prog Programmers 175 * @{ 176 */ 177 struct flashrom_programmer; 178 179 /** 180 * @brief Initialize the specified programmer. 181 * 182 * Currently, only one programmer may be initialized at a time. 183 * 184 * @param[out] flashprog Points to a pointer of type struct flashrom_programmer 185 * that will be set if programmer initialization succeeds. 186 * *flashprog has to be shutdown by the caller with @ref 187 * flashrom_programmer_shutdown. 188 * @param[in] prog_name Name of the programmer to initialize. 189 * @param[in] prog_params Pointer to programmer specific parameters. 190 * @return 0 on success 191 */ 192 int flashrom_programmer_init(struct flashrom_programmer **flashprog, const char *prog_name, const char *prog_params); 193 /** 194 * @brief Shut down the initialized programmer. 195 * 196 * @param flashprog The programmer to shut down. 197 * @return 0 on success 198 */ 199 int flashrom_programmer_shutdown(struct flashrom_programmer *flashprog); 200 201 /** @} */ /* end flashrom-prog */ 202 203 /** 204 * @defgroup flashrom-flash Flash chips 205 * @{ 206 */ 207 208 /** 209 * @brief Probe for a flash chip. 210 * 211 * Probes for a flash chip and returns a flash context, that can be used 212 * later with flash chip and @ref flashrom-ops "image operations", if 213 * exactly one matching chip is found. 214 * 215 * @param[out] flashctx Points to a pointer of type struct flashrom_flashctx 216 * that will be set if exactly one chip is found. *flashctx 217 * has to be freed by the caller with @ref flashrom_flash_release. 218 * @param[in] flashprog The flash programmer used to access the chip. 219 * @param[in] chip_name Name of a chip to probe for, or NULL to probe for 220 * all known chips. 221 * @return 0 on success, 222 * 3 if multiple chips were found, 223 * 2 if no chip was found, 224 * or 1 on any other error. 225 */ 226 int flashrom_flash_probe(struct flashrom_flashctx **flashctx, const struct flashrom_programmer *flashprog, const char *chip_name); 227 /** 228 * @brief Returns the size of the specified flash chip in bytes. 229 * 230 * @param flashctx The queried flash context. 231 * @return Size of flash chip in bytes. 232 */ 233 size_t flashrom_flash_getsize(const struct flashrom_flashctx *flashctx); 234 /** 235 * @brief Returns the info of the specified flash chip within the flashctx. 236 * 237 * @param flashctx The queried flash context. 238 * @param[out] A reference of flashchip_info structure is provided to be filled. 239 */ 240 void flashrom_flash_getinfo(const struct flashrom_flashctx *const flashctx, struct flashrom_flashchip_info *info); 241 /** 242 * @brief Erase the specified ROM chip. 243 * 244 * If a layout is set in the given flash context, only included regions 245 * will be erased. 246 * 247 * @param flashctx The context of the flash chip to erase. 248 * @return 0 on success. 249 */ 250 int flashrom_flash_erase(struct flashrom_flashctx *flashctx); 251 /** 252 * @brief Free a flash context. 253 * 254 * @param flashctx Flash context to free. 255 */ 256 void flashrom_flash_release(struct flashrom_flashctx *flashctx); 257 258 enum flashrom_flag { 259 FLASHROM_FLAG_FORCE, 260 FLASHROM_FLAG_FORCE_BOARDMISMATCH, 261 FLASHROM_FLAG_VERIFY_AFTER_WRITE, 262 FLASHROM_FLAG_VERIFY_WHOLE_CHIP, 263 FLASHROM_FLAG_SKIP_UNREADABLE_REGIONS, 264 FLASHROM_FLAG_SKIP_UNWRITABLE_REGIONS, 265 }; 266 267 /** 268 * @brief Set a flag in the given flash context. 269 * 270 * @param flashctx Flash context to alter. 271 * @param flag Flag that is to be set / cleared. 272 * @param value Value to set. 273 */ 274 void flashrom_flag_set(struct flashrom_flashctx *flashctx, enum flashrom_flag flag, bool value); 275 /** 276 * @brief Return the current value of a flag in the given flash context. 277 * 278 * @param flashctx Flash context to read from. 279 * @param flag Flag to be read. 280 * @return Current value of the flag. 281 */ 282 bool flashrom_flag_get(const struct flashrom_flashctx *flashctx, enum flashrom_flag flag); 283 284 /** @} */ /* end flashrom-flash */ 285 286 /** 287 * @defgroup flashrom-ops Operations 288 * @{ 289 */ 290 291 /** 292 * @brief Read the current image from the specified ROM chip. 293 * 294 * If a layout is set in the specified flash context, only included regions 295 * will be read. 296 * 297 * @param flashctx The context of the flash chip. 298 * @param buffer Target buffer to write image to. 299 * @param buffer_len Size of target buffer in bytes. 300 * @return 0 on success, 301 * 2 if buffer_len is too small for the flash chip's contents, 302 * or 1 on any other failure. 303 */ 304 int flashrom_image_read(struct flashrom_flashctx *flashctx, void *buffer, size_t buffer_len); 305 /** 306 * @brief Write the specified image to the ROM chip. 307 * 308 * If a layout is set in the specified flash context, only erase blocks 309 * containing included regions will be touched. 310 * 311 * @param flashctx The context of the flash chip. 312 * @param buffer Source buffer to read image from (may be altered for full verification). 313 * @param buffer_len Size of source buffer in bytes. 314 * @param refbuffer If given, assume flash chip contains same data as `refbuffer`. 315 * @return 0 on success, 316 * 4 if buffer_len doesn't match the size of the flash chip, 317 * 3 if write was tried but nothing has changed, 318 * 2 if write failed and flash contents changed, 319 * or 1 on any other failure. 320 */ 321 int flashrom_image_write(struct flashrom_flashctx *flashctx, void *buffer, size_t buffer_len, const void *refbuffer); 322 /** 323 * @brief Verify the ROM chip's contents with the specified image. 324 * 325 * If a layout is set in the specified flash context, only included regions 326 * will be verified. 327 * 328 * @param flashctx The context of the flash chip. 329 * @param buffer Source buffer to verify with. 330 * @param buffer_len Size of source buffer in bytes. 331 * @return 0 on success, 332 * 3 if the chip's contents don't match, 333 * 2 if buffer_len doesn't match the size of the flash chip, 334 * or 1 on any other failure. 335 */ 336 int flashrom_image_verify(struct flashrom_flashctx *flashctx, const void *buffer, size_t buffer_len); 337 338 /** @} */ /* end flashrom-ops */ 339 340 /** 341 * @defgroup flashrom-layout Layout handling 342 * @{ 343 */ 344 345 struct flashrom_layout; 346 /** 347 * @brief Create a new, empty layout. 348 * 349 * @param layout Pointer to returned layout reference. 350 * 351 * @return 0 on success, 352 * 1 if out of memory. 353 */ 354 int flashrom_layout_new(struct flashrom_layout **layout); 355 356 /** 357 * @brief Read a layout from the Intel ICH descriptor in the flash. 358 * 359 * Optionally verify that the layout matches the one in the given 360 * descriptor dump. 361 * 362 * @param[out] layout Points to a struct flashrom_layout pointer that 363 * gets set if the descriptor is read and parsed 364 * successfully. 365 * @param[in] flashctx Flash context to read the descriptor from flash. 366 * @param[in] dump The descriptor dump to compare to or NULL. 367 * @param[in] len The length of the descriptor dump. 368 * 369 * @return 0 on success, 370 * 6 if descriptor parsing isn't implemented for the host, 371 * 5 if the descriptors don't match, 372 * 4 if the descriptor dump couldn't be parsed, 373 * 3 if the descriptor on flash couldn't be parsed, 374 * 2 if the descriptor on flash couldn't be read, 375 * 1 on any other error. 376 */ 377 int flashrom_layout_read_from_ifd(struct flashrom_layout **layout, struct flashrom_flashctx *flashctx, const void *dump, size_t len); 378 /** 379 * @brief Read a layout by searching the flash chip for fmap. 380 * 381 * @param[out] layout Points to a struct flashrom_layout pointer that 382 * gets set if the fmap is read and parsed successfully. 383 * @param[in] flashctx Flash context 384 * @param[in] offset Offset to begin searching for fmap. 385 * @param[in] length Length of address space to search. 386 * 387 * @return 0 on success, 388 * 3 if fmap parsing isn't implemented for the host, 389 * 2 if the fmap couldn't be read, 390 * 1 on any other error. 391 */ 392 int flashrom_layout_read_fmap_from_rom(struct flashrom_layout **layout, 393 struct flashrom_flashctx *flashctx, size_t offset, size_t length); 394 /** 395 * @brief Read a layout by searching a buffer for fmap. 396 * 397 * @param[out] layout Points to a struct flashrom_layout pointer that 398 * gets set if the fmap is read and parsed successfully. 399 * @param[in] flashctx Flash context 400 * @param[in] buffer Buffer to search in 401 * @param[in] len Size of buffer to search 402 * 403 * @return 0 on success, 404 * 3 if fmap parsing isn't implemented for the host, 405 * 2 if the fmap couldn't be read, 406 * 1 on any other error. 407 */ 408 int flashrom_layout_read_fmap_from_buffer(struct flashrom_layout **layout, 409 struct flashrom_flashctx *flashctx, const uint8_t *buffer, size_t len); 410 /** 411 * @brief Add a region to an existing layout. 412 * 413 * @param layout The existing layout. 414 * @param start Start address of the region. 415 * @param end End address (inclusive) of the region. 416 * @param name Name of the region. 417 * 418 * @return 0 on success, 419 * 1 if out of memory. 420 */ 421 int flashrom_layout_add_region(struct flashrom_layout *layout, size_t start, size_t end, const char *name); 422 /** 423 * @brief Mark given region as included. 424 * 425 * @param layout The layout to alter. 426 * @param name The name of the region to include. 427 * 428 * @return 0 on success, 429 * 1 if the given name can't be found. 430 */ 431 int flashrom_layout_include_region(struct flashrom_layout *layout, const char *name); 432 /** 433 * @brief Mark given region as not included. 434 * 435 * @param layout The layout to alter. 436 * @param name The name of the region to exclude. 437 * 438 * @return 0 on success, 439 * 1 if the given name can't be found. 440 */ 441 int flashrom_layout_exclude_region(struct flashrom_layout *layout, const char *name); 442 /** 443 * @brief Get given region's offset and length. 444 * 445 * @param[in] layout The existing layout. 446 * @param[in] name The name of the region. 447 * @param[out] start The start address to be written. 448 * @param[out] len The length of the region to be written. 449 * 450 * @return 0 on success, 451 * 1 if the given name can't be found. 452 */ 453 int flashrom_layout_get_region_range(struct flashrom_layout *layout, const char *name, 454 unsigned int *start, unsigned int *len); 455 /** 456 * @brief Free a layout. 457 * 458 * @param layout Layout to free. 459 */ 460 void flashrom_layout_release(struct flashrom_layout *layout); 461 /** 462 * @brief Set the active layout for a flash context. 463 * 464 * Note: The caller must not release the layout as long as it is used through 465 * the given flash context. 466 * 467 * @param flashctx Flash context whose layout will be set. 468 * @param layout Layout to bet set. 469 */ 470 void flashrom_layout_set(struct flashrom_flashctx *flashctx, const struct flashrom_layout *layout); 471 472 /** @} */ /* end flashrom-layout */ 473 474 /** 475 * @defgroup flashrom-wp Write Protect 476 * @{ 477 */ 478 479 enum flashrom_wp_result { 480 FLASHROM_WP_OK = 0, 481 FLASHROM_WP_ERR_CHIP_UNSUPPORTED = 1, 482 FLASHROM_WP_ERR_OTHER = 2, 483 FLASHROM_WP_ERR_READ_FAILED = 3, 484 FLASHROM_WP_ERR_WRITE_FAILED = 4, 485 FLASHROM_WP_ERR_VERIFY_FAILED = 5, 486 FLASHROM_WP_ERR_RANGE_UNSUPPORTED = 6, 487 FLASHROM_WP_ERR_MODE_UNSUPPORTED = 7, 488 FLASHROM_WP_ERR_RANGE_LIST_UNAVAILABLE = 8, 489 FLASHROM_WP_ERR_UNSUPPORTED_STATE = 9 490 }; 491 492 enum flashrom_wp_mode { 493 FLASHROM_WP_MODE_DISABLED, 494 FLASHROM_WP_MODE_HARDWARE, 495 FLASHROM_WP_MODE_POWER_CYCLE, 496 FLASHROM_WP_MODE_PERMANENT 497 }; 498 struct flashrom_wp_cfg; 499 struct flashrom_wp_ranges; 500 /** 501 * @brief Create a new empty WP configuration. 502 * 503 * @param[out] cfg Points to a pointer of type struct flashrom_wp_cfg that will 504 * be set if creation succeeds. *cfg has to be freed by the 505 * caller with @ref flashrom_wp_cfg_release. 506 * @return 0 on success 507 * >0 on failure 508 */ 509 enum flashrom_wp_result flashrom_wp_cfg_new(struct flashrom_wp_cfg **cfg); 510 /** 511 * @brief Free a WP configuration. 512 * 513 * @param[in] cfg Pointer to the flashrom_wp_cfg to free. 514 */ 515 void flashrom_wp_cfg_release(struct flashrom_wp_cfg *cfg); 516 /** 517 * @brief Set the protection mode for a WP configuration. 518 * 519 * @param[in] mode The protection mode to set. 520 * @param[out] cfg Pointer to the flashrom_wp_cfg structure to modify. 521 */ 522 void flashrom_wp_set_mode(struct flashrom_wp_cfg *cfg, enum flashrom_wp_mode mode); 523 /** 524 * @brief Get the protection mode from a WP configuration. 525 * 526 * @param[in] cfg The WP configuration to get the protection mode from. 527 * @return The configuration's protection mode. 528 */ 529 enum flashrom_wp_mode flashrom_wp_get_mode(const struct flashrom_wp_cfg *cfg); 530 /** 531 * @brief Set the protection range for a WP configuration. 532 * 533 * @param[out] cfg Pointer to the flashrom_wp_cfg structure to modify. 534 * @param[in] start The range's start address. 535 * @param[in] len The range's length. 536 */ 537 void flashrom_wp_set_range(struct flashrom_wp_cfg *cfg, size_t start, size_t len); 538 /** 539 * @brief Get the protection range from a WP configuration. 540 * 541 * @param[out] start Points to a size_t to write the range start to. 542 * @param[out] len Points to a size_t to write the range length to. 543 * @param[in] cfg The WP configuration to get the range from. 544 */ 545 void flashrom_wp_get_range(size_t *start, size_t *len, const struct flashrom_wp_cfg *cfg); 546 547 /** 548 * @brief Read the current WP configuration from a flash chip. 549 * 550 * @param[out] cfg Pointer to a struct flashrom_wp_cfg to store the chip's 551 * configuration in. 552 * @param[in] flash The flash context used to access the chip. 553 * @return 0 on success 554 * >0 on failure 555 */ 556 enum flashrom_wp_result flashrom_wp_read_cfg(struct flashrom_wp_cfg *cfg, struct flashrom_flashctx *flash); 557 /** 558 * @brief Write a WP configuration to a flash chip. 559 * 560 * @param[in] flash The flash context used to access the chip. 561 * @param[in] cfg The WP configuration to write to the chip. 562 * @return 0 on success 563 * >0 on failure 564 */ 565 enum flashrom_wp_result flashrom_wp_write_cfg(struct flashrom_flashctx *flash, const struct flashrom_wp_cfg *cfg); 566 567 /** 568 * @brief Get a list of protection ranges supported by the flash chip. 569 * 570 * @param[out] ranges Points to a pointer of type struct flashrom_wp_ranges 571 * that will be set if available ranges are found. Finding 572 * available ranges may not always be possible, even if the 573 * chip's protection range can be read or modified. *ranges 574 * must be freed using @ref flashrom_wp_ranges_release. 575 * @param[in] flash The flash context used to access the chip. 576 * @return 0 on success 577 * >0 on failure 578 */ 579 enum flashrom_wp_result flashrom_wp_get_available_ranges(struct flashrom_wp_ranges **ranges, struct flashrom_flashctx *flash); 580 /** 581 * @brief Get a number of protection ranges in a range list. 582 * 583 * @param[in] ranges The range list to get the count from. 584 * @return Number of ranges in the list. 585 */ 586 size_t flashrom_wp_ranges_get_count(const struct flashrom_wp_ranges *ranges); 587 /** 588 * @brief Get a protection range from a range list. 589 * 590 * @param[out] start Points to a size_t to write the range's start to. 591 * @param[out] len Points to a size_t to write the range's length to. 592 * @param[in] ranges The range list to get the range from. 593 * @param[in] index Index of the range to get. 594 * @return 0 on success 595 * >0 on failure 596 */ 597 enum flashrom_wp_result flashrom_wp_ranges_get_range(size_t *start, size_t *len, const struct flashrom_wp_ranges *ranges, unsigned int index); 598 /** 599 * @brief Free a WP range list. 600 * 601 * @param[out] ranges Pointer to the flashrom_wp_ranges to free. 602 */ 603 void flashrom_wp_ranges_release(struct flashrom_wp_ranges *ranges); 604 605 /** @} */ /* end flashrom-wp */ 606 607 #endif /* !__LIBFLASHROM_H__ */ 608