diff options
| -rw-r--r-- | Doxyfile | 5 | ||||
| -rw-r--r-- | flashrom.c | 66 | ||||
| -rw-r--r-- | include/libflashrom.h | 477 | ||||
| -rw-r--r-- | layout.c | 51 | ||||
| -rw-r--r-- | libflashrom.c | 308 | ||||
| -rw-r--r-- | writeprotect.c | 2 |
6 files changed, 438 insertions, 471 deletions
@@ -780,10 +780,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = libflashrom.c \ - libflashrom.h \ - flashrom.c \ - layout.c \ +INPUT = include/libflashrom.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/flashrom.c b/flashrom.c index 173638165..9b136a03f 100644 --- a/flashrom.c +++ b/flashrom.c @@ -1901,20 +1901,6 @@ void finalize_flash_access(struct flashctx *const flash) unmap_flash(flash); } -/** - * @addtogroup flashrom-flash - * @{ - */ - -/** - * @brief Erase the specified ROM chip. - * - * If a layout is set in the given flash context, only included regions - * will be erased. - * - * @param flashctx The context of the flash chip to erase. - * @return 0 on success. - */ int flashrom_flash_erase(struct flashctx *const flashctx) { if (prepare_flash_access(flashctx, false, false, true, false)) @@ -1927,26 +1913,6 @@ int flashrom_flash_erase(struct flashctx *const flashctx) return ret; } -/** @} */ /* end flashrom-flash */ - -/** - * @defgroup flashrom-ops Operations - * @{ - */ - -/** - * @brief Read the current image from the specified ROM chip. - * - * If a layout is set in the specified flash context, only included regions - * will be read. - * - * @param flashctx The context of the flash chip. - * @param buffer Target buffer to write image to. - * @param buffer_len Size of target buffer in bytes. - * @return 0 on success, - * 2 if buffer_len is too short for the flash chip's contents, - * or 1 on any other failure. - */ int flashrom_image_read(struct flashctx *const flashctx, void *const buffer, const size_t buffer_len) { const size_t flash_size = flashctx->chip->total_size * 1024; @@ -1996,22 +1962,6 @@ static void combine_image_by_layout(const struct flashctx *const flashctx, memcpy(newcontents + start, oldcontents + start, copy_len); } -/** - * @brief Write the specified image to the ROM chip. - * - * If a layout is set in the specified flash context, only erase blocks - * containing included regions will be touched. - * - * @param flashctx The context of the flash chip. - * @param buffer Source buffer to read image from (may be altered for full verification). - * @param buffer_len Size of source buffer in bytes. - * @param refbuffer If given, assume flash chip contains same data as `refbuffer`. - * @return 0 on success, - * 4 if buffer_len doesn't match the size of the flash chip, - * 3 if write was tried but nothing has changed, - * 2 if write failed and flash contents changed, - * or 1 on any other failure. - */ int flashrom_image_write(struct flashctx *const flashctx, void *const buffer, const size_t buffer_len, const void *const refbuffer) { @@ -2135,20 +2085,6 @@ _free_ret: return ret; } -/** - * @brief Verify the ROM chip's contents with the specified image. - * - * If a layout is set in the specified flash context, only included regions - * will be verified. - * - * @param flashctx The context of the flash chip. - * @param buffer Source buffer to verify with. - * @param buffer_len Size of source buffer in bytes. - * @return 0 on success, - * 3 if the chip's contents don't match, - * 2 if buffer_len doesn't match the size of the flash chip, - * or 1 on any other failure. - */ int flashrom_image_verify(struct flashctx *const flashctx, const void *const buffer, const size_t buffer_len) { const struct flashrom_layout *const layout = get_layout(flashctx); @@ -2179,5 +2115,3 @@ _free_ret: free(curcontents); return ret; } - -/** @} */ /* end flashrom-ops */ diff --git a/include/libflashrom.h b/include/libflashrom.h index 936c9aeb7..cf1f46234 100644 --- a/include/libflashrom.h +++ b/include/libflashrom.h @@ -19,15 +19,35 @@ #ifndef __LIBFLASHROM_H__ #define __LIBFLASHROM_H__ 1 +/** + * @mainpage + * + * Have a look at the Modules section for a function reference. + */ + #include <sys/types.h> #include <stddef.h> #include <stdbool.h> #include <stdint.h> #include <stdarg.h> +/** + * @defgroup flashrom-general General + * @{ + */ + +/** + * @brief Initialize libflashrom. + * + * @param perform_selfcheck If not zero, perform a self check. + * @return 0 on success + */ int flashrom_init(int perform_selfcheck); +/** + * @brief Shut down libflashrom. + * @return 0 on success + */ int flashrom_shutdown(void); -/** @ingroup flashrom-general */ enum flashrom_log_level { FLASHROM_MSG_ERROR = 0, FLASHROM_MSG_WARN = 1, @@ -36,11 +56,26 @@ enum flashrom_log_level { FLASHROM_MSG_DEBUG2 = 4, FLASHROM_MSG_SPEW = 5, }; -/** @ingroup flashrom-general */ typedef int(flashrom_log_callback)(enum flashrom_log_level, const char *format, va_list); -void flashrom_set_log_callback(flashrom_log_callback *); +/** + * @brief Set the log callback function. + * + * Set a callback function which will be invoked whenever libflashrom wants + * to output messages. This allows frontends to do whatever they see fit with + * such messages, e.g. write them to syslog, or to a file, or print them in a + * GUI window, etc. + * + * @param log_callback Pointer to the new log callback function. + */ +void flashrom_set_log_callback(flashrom_log_callback *log_callback); + +/** @} */ /* end flashrom-general */ + +/** + * @defgroup flashrom-query Querying + * @{ + */ -/** @ingroup flashrom-query */ enum flashrom_test_state { FLASHROM_TESTED_OK = 0, FLASHROM_TESTED_NT = 1, @@ -75,52 +110,323 @@ struct flashrom_chipset_info { enum flashrom_test_state status; }; +/** + * @brief Returns flashrom version + * @return flashrom version + */ const char *flashrom_version_info(void); +/** + * @brief Returns list of supported flash chips + * @return List of supported flash chips, or NULL if an error occurred + */ struct flashrom_flashchip_info *flashrom_supported_flash_chips(void); +/** + * @brief Returns list of supported mainboards + * @return List of supported mainboards, or NULL if an error occurred + */ struct flashrom_board_info *flashrom_supported_boards(void); +/** + * @brief Returns list of supported chipsets + * @return List of supported chipsets, or NULL if an error occurred + */ struct flashrom_chipset_info *flashrom_supported_chipsets(void); +/** + * @brief Frees memory allocated by libflashrom API + * @param p Pointer to block of memory which should be freed + * @return 0 on success + */ int flashrom_data_free(void *const p); -/** @ingroup flashrom-prog */ +/** @} */ /* end flashrom-query */ + +/** + * @defgroup flashrom-prog Programmers + * @{ + */ struct flashrom_programmer; -int flashrom_programmer_init(struct flashrom_programmer **, const char *prog_name, const char *prog_params); -int flashrom_programmer_shutdown(struct flashrom_programmer *); + +/** + * @brief Initialize the specified programmer. + * + * Currently, only one programmer may be initialized at a time. + * + * @param[out] flashprog Points to a pointer of type struct flashrom_programmer + * that will be set if programmer initialization succeeds. + * *flashprog has to be shutdown by the caller with @ref + * flashrom_programmer_shutdown. + * @param[in] prog_name Name of the programmer to initialize. + * @param[in] prog_params Pointer to programmer specific parameters. + * @return 0 on success + */ +int flashrom_programmer_init(struct flashrom_programmer **flashprog, const char *prog_name, const char *prog_params); +/** + * @brief Shut down the initialized programmer. + * + * @param flashprog The programmer to shut down. + * @return 0 on success + */ +int flashrom_programmer_shutdown(struct flashrom_programmer *flashprog); + +/** @} */ /* end flashrom-prog */ + +/** + * @defgroup flashrom-flash Flash chips + * @{ + */ struct flashrom_flashctx; -int flashrom_flash_probe(struct flashrom_flashctx **, const struct flashrom_programmer *, const char *chip_name); -size_t flashrom_flash_getsize(const struct flashrom_flashctx *); -int flashrom_flash_erase(struct flashrom_flashctx *); -void flashrom_flash_release(struct flashrom_flashctx *); +/** + * @brief Probe for a flash chip. + * + * Probes for a flash chip and returns a flash context, that can be used + * later with flash chip and @ref flashrom-ops "image operations", if + * exactly one matching chip is found. + * + * @param[out] flashctx Points to a pointer of type struct flashrom_flashctx + * that will be set if exactly one chip is found. *flashctx + * has to be freed by the caller with @ref flashrom_flash_release. + * @param[in] flashprog The flash programmer used to access the chip. + * @param[in] chip_name Name of a chip to probe for, or NULL to probe for + * all known chips. + * @return 0 on success, + * 3 if multiple chips were found, + * 2 if no chip was found, + * or 1 on any other error. + */ +int flashrom_flash_probe(struct flashrom_flashctx **flashctx, const struct flashrom_programmer *flashprog, const char *chip_name); +/** + * @brief Returns the size of the specified flash chip in bytes. + * + * @param flashctx The queried flash context. + * @return Size of flash chip in bytes. + */ +size_t flashrom_flash_getsize(const struct flashrom_flashctx *flashctx); +/** + * @brief Erase the specified ROM chip. + * + * If a layout is set in the given flash context, only included regions + * will be erased. + * + * @param flashctx The context of the flash chip to erase. + * @return 0 on success. + */ +int flashrom_flash_erase(struct flashrom_flashctx *flashctx); +/** + * @brief Free a flash context. + * + * @param flashctx Flash context to free. + */ +void flashrom_flash_release(struct flashrom_flashctx *flashctx); -/** @ingroup flashrom-flash */ enum flashrom_flag { FLASHROM_FLAG_FORCE, FLASHROM_FLAG_FORCE_BOARDMISMATCH, FLASHROM_FLAG_VERIFY_AFTER_WRITE, FLASHROM_FLAG_VERIFY_WHOLE_CHIP, }; -void flashrom_flag_set(struct flashrom_flashctx *, enum flashrom_flag, bool value); -bool flashrom_flag_get(const struct flashrom_flashctx *, enum flashrom_flag); -int flashrom_image_read(struct flashrom_flashctx *, void *buffer, size_t buffer_len); -int flashrom_image_write(struct flashrom_flashctx *, void *buffer, size_t buffer_len, const void *refbuffer); -int flashrom_image_verify(struct flashrom_flashctx *, const void *buffer, size_t buffer_len); +/** + * @brief Set a flag in the given flash context. + * + * @param flashctx Flash context to alter. + * @param flag Flag that is to be set / cleared. + * @param value Value to set. + */ +void flashrom_flag_set(struct flashrom_flashctx *flashctx, enum flashrom_flag flag, bool value); +/** + * @brief Return the current value of a flag in the given flash context. + * + * @param flashctx Flash context to read from. + * @param flag Flag to be read. + * @return Current value of the flag. + */ +bool flashrom_flag_get(const struct flashrom_flashctx *flashctx, enum flashrom_flag flag); + +/** @} */ /* end flashrom-flash */ + +/** + * @defgroup flashrom-ops Operations + * @{ + */ + +/** + * @brief Read the current image from the specified ROM chip. + * + * If a layout is set in the specified flash context, only included regions + * will be read. + * + * @param flashctx The context of the flash chip. + * @param buffer Target buffer to write image to. + * @param buffer_len Size of target buffer in bytes. + * @return 0 on success, + * 2 if buffer_len is too small for the flash chip's contents, + * or 1 on any other failure. + */ +int flashrom_image_read(struct flashrom_flashctx *flashctx, void *buffer, size_t buffer_len); +/** + * @brief Write the specified image to the ROM chip. + * + * If a layout is set in the specified flash context, only erase blocks + * containing included regions will be touched. + * + * @param flashctx The context of the flash chip. + * @param buffer Source buffer to read image from (may be altered for full verification). + * @param buffer_len Size of source buffer in bytes. + * @param refbuffer If given, assume flash chip contains same data as `refbuffer`. + * @return 0 on success, + * 4 if buffer_len doesn't match the size of the flash chip, + * 3 if write was tried but nothing has changed, + * 2 if write failed and flash contents changed, + * or 1 on any other failure. + */ +int flashrom_image_write(struct flashrom_flashctx *flashctx, void *buffer, size_t buffer_len, const void *refbuffer); +/** + * @brief Verify the ROM chip's contents with the specified image. + * + * If a layout is set in the specified flash context, only included regions + * will be verified. + * + * @param flashctx The context of the flash chip. + * @param buffer Source buffer to verify with. + * @param buffer_len Size of source buffer in bytes. + * @return 0 on success, + * 3 if the chip's contents don't match, + * 2 if buffer_len doesn't match the size of the flash chip, + * or 1 on any other failure. + */ +int flashrom_image_verify(struct flashrom_flashctx *flashctx, const void *buffer, size_t buffer_len); + +/** @} */ /* end flashrom-ops */ + +/** + * @defgroup flashrom-layout Layout handling + * @{ + */ struct flashrom_layout; -int flashrom_layout_new(struct flashrom_layout **); -int flashrom_layout_read_from_ifd(struct flashrom_layout **, struct flashrom_flashctx *, const void *dump, size_t len); -int flashrom_layout_read_fmap_from_rom(struct flashrom_layout **, - struct flashrom_flashctx *, size_t offset, size_t length); +/** + * @brief Create a new, empty layout. + * + * @param layout Pointer to returned layout reference. + * + * @return 0 on success, + * 1 if out of memory. + */ +int flashrom_layout_new(struct flashrom_layout **layout); + +/** + * @brief Read a layout from the Intel ICH descriptor in the flash. + * + * Optionally verify that the layout matches the one in the given + * descriptor dump. + * + * @param[out] layout Points to a struct flashrom_layout pointer that + * gets set if the descriptor is read and parsed + * successfully. + * @param[in] flashctx Flash context to read the descriptor from flash. + * @param[in] dump The descriptor dump to compare to or NULL. + * @param[in] len The length of the descriptor dump. + * + * @return 0 on success, + * 6 if descriptor parsing isn't implemented for the host, + * 5 if the descriptors don't match, + * 4 if the descriptor dump couldn't be parsed, + * 3 if the descriptor on flash couldn't be parsed, + * 2 if the descriptor on flash couldn't be read, + * 1 on any other error. + */ +int flashrom_layout_read_from_ifd(struct flashrom_layout **layout, struct flashrom_flashctx *flashctx, const void *dump, size_t len); +/** + * @brief Read a layout by searching the flash chip for fmap. + * + * @param[out] layout Points to a struct flashrom_layout pointer that + * gets set if the fmap is read and parsed successfully. + * @param[in] flashctx Flash context + * @param[in] offset Offset to begin searching for fmap. + * @param[in] length Length of address space to search. + * + * @return 0 on success, + * 3 if fmap parsing isn't implemented for the host, + * 2 if the fmap couldn't be read, + * 1 on any other error. + */ +int flashrom_layout_read_fmap_from_rom(struct flashrom_layout **layout, + struct flashrom_flashctx *flashctx, size_t offset, size_t length); +/** + * @brief Read a layout by searching a buffer for fmap. + * + * @param[out] layout Points to a struct flashrom_layout pointer that + * gets set if the fmap is read and parsed successfully. + * @param[in] flashctx Flash context + * @param[in] buffer Buffer to search in + * @param[in] len Size of buffer to search + * + * @return 0 on success, + * 3 if fmap parsing isn't implemented for the host, + * 2 if the fmap couldn't be read, + * 1 on any other error. + */ int flashrom_layout_read_fmap_from_buffer(struct flashrom_layout **layout, - struct flashrom_flashctx *, const uint8_t *buf, size_t len); -int flashrom_layout_add_region(struct flashrom_layout *, size_t start, size_t end, const char *name); -int flashrom_layout_include_region(struct flashrom_layout *, const char *name); -int flashrom_layout_get_region_range(struct flashrom_layout *, const char *name, + struct flashrom_flashctx *flashctx, const uint8_t *buffer, size_t len); +/** + * @brief Add a region to an existing layout. + * + * @param layout The existing layout. + * @param start Start address of the region. + * @param end End address (inclusive) of the region. + * @param name Name of the region. + * + * @return 0 on success, + * 1 if out of memory. + */ +int flashrom_layout_add_region(struct flashrom_layout *layout, size_t start, size_t end, const char *name); +/** + * @brief Mark given region as included. + * + * @param layout The layout to alter. + * @param name The name of the region to include. + * + * @return 0 on success, + * 1 if the given name can't be found. + */ +int flashrom_layout_include_region(struct flashrom_layout *layout, const char *name); +/** + * @brief Get given region's offset and length. + * + * @param[in] layout The existing layout. + * @param[in] name The name of the region. + * @param[out] start The start address to be written. + * @param[out] len The length of the region to be written. + * + * @return 0 on success, + * 1 if the given name can't be found. + */ +int flashrom_layout_get_region_range(struct flashrom_layout *layout, const char *name, unsigned int *start, unsigned int *len); -void flashrom_layout_release(struct flashrom_layout *); -void flashrom_layout_set(struct flashrom_flashctx *, const struct flashrom_layout *); +/** + * @brief Free a layout. + * + * @param layout Layout to free. + */ +void flashrom_layout_release(struct flashrom_layout *layout); +/** + * @brief Set the active layout for a flash context. + * + * Note: The caller must not release the layout as long as it is used through + * the given flash context. + * + * @param flashctx Flash context whose layout will be set. + * @param layout Layout to bet set. + */ +void flashrom_layout_set(struct flashrom_flashctx *flashctx, const struct flashrom_layout *layout); + +/** @} */ /* end flashrom-layout */ + +/** + * @defgroup flashrom-wp Write Protect + * @{ + */ -/** @ingroup flashrom-wp */ enum flashrom_wp_result { FLASHROM_WP_OK = 0, FLASHROM_WP_ERR_CHIP_UNSUPPORTED = 1, @@ -141,20 +447,111 @@ enum flashrom_wp_mode { }; struct flashrom_wp_cfg; struct flashrom_wp_ranges; +/** + * @brief Create a new empty WP configuration. + * + * @param[out] cfg Points to a pointer of type struct flashrom_wp_cfg that will + * be set if creation succeeds. *cfg has to be freed by the + * caller with @ref flashrom_wp_cfg_release. + * @return 0 on success + * >0 on failure + */ +enum flashrom_wp_result flashrom_wp_cfg_new(struct flashrom_wp_cfg **cfg); +/** + * @brief Free a WP configuration. + * + * @param[in] cfg Pointer to the flashrom_wp_cfg to free. + */ +void flashrom_wp_cfg_release(struct flashrom_wp_cfg *cfg); +/** + * @brief Set the protection mode for a WP configuration. + * + * @param[in] mode The protection mode to set. + * @param[out] cfg Pointer to the flashrom_wp_cfg structure to modify. + */ +void flashrom_wp_set_mode(struct flashrom_wp_cfg *cfg, enum flashrom_wp_mode mode); +/** + * @brief Get the protection mode from a WP configuration. + * + * @param[in] cfg The WP configuration to get the protection mode from. + * @return The configuration's protection mode. + */ +enum flashrom_wp_mode flashrom_wp_get_mode(const struct flashrom_wp_cfg *cfg); +/** + * @brief Set the protection range for a WP configuration. + * + * @param[out] cfg Pointer to the flashrom_wp_cfg structure to modify. + * @param[in] start The range's start address. + * @param[in] len The range's length. + */ +void flashrom_wp_set_range(struct flashrom_wp_cfg *cfg, size_t start, size_t len); +/** + * @brief Get the protection range from a WP configuration. + * + * @param[out] start Points to a size_t to write the range start to. + * @param[out] len Points to a size_t to write the range length to. + * @param[in] cfg The WP configuration to get the range from. + */ +void flashrom_wp_get_range(size_t *start, size_t *len, const struct flashrom_wp_cfg *cfg); -enum flashrom_wp_result flashrom_wp_cfg_new(struct flashrom_wp_cfg **); -void flashrom_wp_cfg_release(struct flashrom_wp_cfg *); -void flashrom_wp_set_mode(struct flashrom_wp_cfg *, enum flashrom_wp_mode); -enum flashrom_wp_mode flashrom_wp_get_mode(const struct flashrom_wp_cfg *); -void flashrom_wp_set_range(struct flashrom_wp_cfg *, size_t start, size_t len); -void flashrom_wp_get_range(size_t *start, size_t *len, const struct flashrom_wp_cfg *); +/** + * @brief Read the current WP configuration from a flash chip. + * + * @param[out] cfg Pointer to a struct flashrom_wp_cfg to store the chip's + * configuration in. + * @param[in] flash The flash context used to access the chip. + * @return 0 on success + * >0 on failure + */ +enum flashrom_wp_result flashrom_wp_read_cfg(struct flashrom_wp_cfg *cfg, struct flashrom_flashctx *flash); +/** + * @brief Write a WP configuration to a flash chip. + * + * @param[in] flash The flash context used to access the chip. + * @param[in] cfg The WP configuration to write to the chip. + * @return 0 on success + * >0 on failure + */ +enum flashrom_wp_result flashrom_wp_write_cfg(struct flashrom_flashctx *flash, const struct flashrom_wp_cfg *cfg); -enum flashrom_wp_result flashrom_wp_read_cfg(struct flashrom_wp_cfg *, struct flashrom_flashctx *); -enum flashrom_wp_result flashrom_wp_write_cfg(struct flashrom_flashctx *, const struct flashrom_wp_cfg *); +/** + * @brief Get a list of protection ranges supported by the flash chip. + * + * @param[out] ranges Points to a pointer of type struct flashrom_wp_ranges + * that will be set if available ranges are found. Finding + * available ranges may not always be possible, even if the + * chip's protection range can be read or modified. *ranges + * must be freed using @ref flashrom_wp_ranges_release. + * @param[in] flash The flash context used to access the chip. + * @return 0 on success + * >0 on failure + */ +enum flashrom_wp_result flashrom_wp_get_available_ranges(struct flashrom_wp_ranges **ranges, struct flashrom_flashctx *flash); +/** + * @brief Get a number of protection ranges in a range list. + * + * @param[in] ranges The range list to get the count from. + * @return Number of ranges in the list. + */ +size_t flashrom_wp_ranges_get_count(const struct flashrom_wp_ranges *ranges); +/** + * @brief Get a protection range from a range list. + * + * @param[out] start Points to a size_t to write the range's start to. + * @param[out] len Points to a size_t to write the range's length to. + * @param[in] ranges The range list to get the range from. + * @param[in] index Index of the range to get. + * @return 0 on success + * >0 on failure + */ +enum flashrom_wp_result flashrom_wp_ranges_get_range(size_t *start, size_t *len, const struct flashrom_wp_ranges *ranges, unsigned int index); +/** + * @brief Free a WP range list. + * + * @param[out] ranges Pointer to the flashrom_wp_ranges to free. + */ +void flashrom_wp_ranges_release(struct flashrom_wp_ranges *ranges); -enum flashrom_wp_result flashrom_wp_get_available_ranges(struct flashrom_wp_ranges **, struct flashrom_flashctx *); -size_t flashrom_wp_ranges_get_count(const struct flashrom_wp_ranges *); -enum flashrom_wp_result flashrom_wp_ranges_get_range(size_t *start, size_t *len, const struct flashrom_wp_ranges *, unsigned int index); -void flashrom_wp_ranges_release(struct flashrom_wp_ranges *); +/** @} */ /* end flashrom-wp */ #endif /* !__LIBFLASHROM_H__ */ @@ -351,19 +351,6 @@ const struct romentry *layout_next( return iterator ? iterator->next : layout->head; } -/** - * @addtogroup flashrom-layout - * @{ - */ - -/** - * @brief Create a new, empty layout. - * - * @param layout Pointer to returned layout reference. - * - * @return 0 on success, - * 1 if out of memory. - */ int flashrom_layout_new(struct flashrom_layout **const layout) { *layout = malloc(sizeof(**layout)); @@ -377,17 +364,6 @@ int flashrom_layout_new(struct flashrom_layout **const layout) return 0; } -/** - * @brief Add another region to an existing layout. - * - * @param layout The existing layout. - * @param start Start address of the region. - * @param end End address (inclusive) of the region. - * @param name Name of the region. - * - * @return 0 on success, - * 1 if out of memory. - */ int flashrom_layout_add_region( struct flashrom_layout *const layout, const size_t start, const size_t end, const char *const name) @@ -418,31 +394,11 @@ _err_ret: return 1; } -/** - * @brief Mark given region as included. - * - * @param layout The layout to alter. - * @param name The name of the region to include. - * - * @return 0 on success, - * 1 if the given name can't be found. - */ int flashrom_layout_include_region(struct flashrom_layout *const layout, const char *name) { return include_region(layout, name, NULL); } -/** - * @brief Get given region's offset and length. - * - * @param layout The layout to alter. - * @param name The name of the region. - * @param start The start address to be written. - * @param len The length of the region to be written. - * - * @return 0 on success, - * 1 if the given name can't be found. - */ int flashrom_layout_get_region_range(struct flashrom_layout *const l, const char *name, unsigned int *start, unsigned int *len) { @@ -455,11 +411,6 @@ int flashrom_layout_get_region_range(struct flashrom_layout *const l, const char return 1; } -/** - * @brief Free a layout. - * - * @param layout Layout to free. - */ void flashrom_layout_release(struct flashrom_layout *const layout) { if (!layout) @@ -474,5 +425,3 @@ void flashrom_layout_release(struct flashrom_layout *const layout) } free(layout); } - -/** @} */ /* end flashrom-layout */ diff --git a/libflashrom.c b/libflashrom.c index 658d8122b..e70c1d1af 100644 --- a/libflashrom.c +++ b/libflashrom.c @@ -14,11 +14,6 @@ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. */ -/** - * @mainpage - * - * Have a look at the Modules section for a function reference. - */ #include <errno.h> #include <stdlib.h> @@ -33,20 +28,10 @@ #include "libflashrom.h" #include "writeprotect.h" -/** - * @defgroup flashrom-general General - * @{ - */ /** Pointer to log callback function. */ static flashrom_log_callback *global_log_callback = NULL; -/** - * @brief Initialize libflashrom. - * - * @param perform_selfcheck If not zero, perform a self check. - * @return 0 on success - */ int flashrom_init(const int perform_selfcheck) { if (perform_selfcheck && selfcheck()) @@ -55,10 +40,6 @@ int flashrom_init(const int perform_selfcheck) return 0; } -/** - * @brief Shut down libflashrom. - * @return 0 on success - */ int flashrom_shutdown(void) { return 0; /* TODO: nothing to do? */ @@ -66,17 +47,6 @@ int flashrom_shutdown(void) /* TODO: flashrom_set_loglevel()? do we need it? For now, let the user decide in their callback. */ - -/** - * @brief Set the log callback function. - * - * Set a callback function which will be invoked whenever libflashrom wants - * to output messages. This allows frontends to do whatever they see fit with - * such messages, e.g. write them to syslog, or to file, or print them in a - * GUI window, etc. - * - * @param log_callback Pointer to the new log callback function. - */ void flashrom_set_log_callback(flashrom_log_callback *const log_callback) { global_log_callback = log_callback; @@ -95,28 +65,11 @@ int print(const enum flashrom_log_level level, const char *const fmt, ...) return 0; } -/** @} */ /* end flashrom-general */ - - - -/** - * @defgroup flashrom-query Querying - * @{ - */ - -/** - * @brief Returns flashrom version - * @return flashrom version - */ const char *flashrom_version_info(void) { return flashrom_version; } -/** - * @brief Returns list of supported flash chips - * @return List of supported flash chips, or NULL if an error occurred - */ struct flashrom_flashchip_info *flashrom_supported_flash_chips(void) { unsigned int i = 0; @@ -144,10 +97,6 @@ struct flashrom_flashchip_info *flashrom_supported_flash_chips(void) return supported_flashchips; } -/** - * @brief Returns list of supported mainboards - * @return List of supported mainboards, or NULL if an error occurred - */ struct flashrom_board_info *flashrom_supported_boards(void) { #if CONFIG_INTERNAL == 1 @@ -181,10 +130,6 @@ struct flashrom_board_info *flashrom_supported_boards(void) #endif } -/** - * @brief Returns list of supported chipsets - * @return List of supported chipsets, or NULL if an error occurred - */ struct flashrom_chipset_info *flashrom_supported_chipsets(void) { #if CONFIG_INTERNAL == 1 @@ -220,39 +165,12 @@ struct flashrom_chipset_info *flashrom_supported_chipsets(void) #endif } -/** - * @brief Frees memory allocated by libflashrom API - * @param Pointer to block of memory which should be freed - * @return 0 on success - */ int flashrom_data_free(void *const p) { free(p); return 0; } -/** @} */ /* end flashrom-query */ - - - -/** - * @defgroup flashrom-prog Programmers - * @{ - */ - -/** - * @brief Initialize the specified programmer. - * - * Currently, only one programmer may be initialized at a time. - * - * @param[out] flashprog Points to a pointer of type struct flashrom_programmer - * that will be set if programmer initialization succeeds. - * *flashprog has to be shutdown by the caller with @ref - * flashrom_programmer_shutdown. - * @param[in] prog_name Name of the programmer to initialize. - * @param[in] prog_param Pointer to programmer specific parameters. - * @return 0 on success - */ int flashrom_programmer_init(struct flashrom_programmer **const flashprog, const char *const prog_name, const char *const prog_param) { @@ -270,12 +188,6 @@ int flashrom_programmer_init(struct flashrom_programmer **const flashprog, return programmer_init(programmer_table[prog], prog_param); } -/** - * @brief Shut down the initialized programmer. - * - * @param flashprog The programmer to shut down. - * @return 0 on success - */ int flashrom_programmer_shutdown(struct flashrom_programmer *const flashprog) { return programmer_shutdown(); @@ -283,33 +195,6 @@ int flashrom_programmer_shutdown(struct flashrom_programmer *const flashprog) /* TODO: flashrom_programmer_capabilities()? */ -/** @} */ /* end flashrom-prog */ - - - -/** - * @defgroup flashrom-flash Flash chips - * @{ - */ - -/** - * @brief Probe for a flash chip. - * - * Probes for a flash chip and returns a flash context, that can be used - * later with flash chip and @ref flashrom-ops "image operations", if - * exactly one matching chip is found. - * - * @param[out] flashctx Points to a pointer of type struct flashrom_flashctx - * that will be set if exactly one chip is found. *flashctx - * has to be freed by the caller with @ref flashrom_flash_release. - * @param[in] flashprog The flash programmer used to access the chip. - * @param[in] chip_name Name of a chip to probe for, or NULL to probe for - * all known chips. - * @return 0 on success, - * 3 if multiple chips were found, - * 2 if no chip was found, - * or 1 on any other error. - */ int flashrom_flash_probe(struct flashrom_flashctx **const flashctx, const struct flashrom_programmer *const flashprog, const char *const chip_name) @@ -344,22 +229,11 @@ int flashrom_flash_probe(struct flashrom_flashctx **const flashctx, return ret; } -/** - * @brief Returns the size of the specified flash chip in bytes. - * - * @param flashctx The queried flash context. - * @return Size of flash chip in bytes. - */ size_t flashrom_flash_getsize(const struct flashrom_flashctx *const flashctx) { return flashctx->chip->total_size * 1024; } -/** - * @brief Free a flash context. - * - * @param flashctx Flash context to free. - */ void flashrom_flash_release(struct flashrom_flashctx *const flashctx) { if (!flashctx) @@ -370,13 +244,6 @@ void flashrom_flash_release(struct flashrom_flashctx *const flashctx) free(flashctx); } -/** - * @brief Set a flag in the given flash context. - * - * @param flashctx Flash context to alter. - * @param flag Flag that is to be set / cleared. - * @param value Value to set. - */ void flashrom_flag_set(struct flashrom_flashctx *const flashctx, const enum flashrom_flag flag, const bool value) { @@ -388,13 +255,6 @@ void flashrom_flag_set(struct flashrom_flashctx *const flashctx, } } -/** - * @brief Return the current value of a flag in the given flash context. - * - * @param flashctx Flash context to read from. - * @param flag Flag to be read. - * @return Current value of the flag. - */ bool flashrom_flag_get(const struct flashrom_flashctx *const flashctx, const enum flashrom_flag flag) { switch (flag) { @@ -406,36 +266,6 @@ bool flashrom_flag_get(const struct flashrom_flashctx *const flashctx, const enu } } -/** @} */ /* end flashrom-flash */ - - - -/** - * @defgroup flashrom-layout Layout handling - * @{ - */ - -/** - * @brief Read a layout from the Intel ICH descriptor in the flash. - * - * Optionally verify that the layout matches the one in the given - * descriptor dump. - * - * @param[out] layout Points to a struct flashrom_layout pointer that - * gets set if the descriptor is read and parsed - * successfully. - * @param[in] flashctx Flash context to read the descriptor from flash. - * @param[in] dump The descriptor dump to compare to or NULL. - * @param[in] len The length of the descriptor dump. - * - * @return 0 on success, - * 6 if descriptor parsing isn't implemented for the host, - * 5 if the descriptors don't match, - * 4 if the descriptor dump couldn't be parsed, - * 3 if the descriptor on flash couldn't be parsed, - * 2 if the descriptor on flash couldn't be read, - * 1 on any other error. - */ int flashrom_layout_read_from_ifd(struct flashrom_layout **const layout, struct flashctx *const flashctx, const void *const dump, const size_t len) { @@ -523,20 +353,6 @@ static int flashrom_layout_parse_fmap(struct flashrom_layout **layout, } #endif /* __FLASHROM_LITTLE_ENDIAN__ */ -/** - * @brief Read a layout by searching the flash chip for fmap. - * - * @param[out] layout Points to a struct flashrom_layout pointer that - * gets set if the fmap is read and parsed successfully. - * @param[in] flashctx Flash context - * @param[in] offset Offset to begin searching for fmap. - * @param[in] offset Length of address space to search. - * - * @return 0 on success, - * 3 if fmap parsing isn't implemented for the host, - * 2 if the fmap couldn't be read, - * 1 on any other error. - */ int flashrom_layout_read_fmap_from_rom(struct flashrom_layout **const layout, struct flashctx *const flashctx, size_t offset, size_t len) { @@ -563,20 +379,6 @@ int flashrom_layout_read_fmap_from_rom(struct flashrom_layout **const layout, #endif } -/** - * @brief Read a layout by searching buffer for fmap. - * - * @param[out] layout Points to a struct flashrom_layout pointer that - * gets set if the fmap is read and parsed successfully. - * @param[in] flashctx Flash context - * @param[in] buffer Buffer to search in - * @param[in] size Size of buffer to search - * - * @return 0 on success, - * 3 if fmap parsing isn't implemented for the host, - * 2 if the fmap couldn't be read, - * 1 on any other error. - */ int flashrom_layout_read_fmap_from_buffer(struct flashrom_layout **const layout, struct flashctx *const flashctx, const uint8_t *const buf, size_t size) { @@ -609,109 +411,44 @@ _ret: #endif } -/** - * @brief Set the active layout for a flash context. - * - * Note: This just sets a pointer. The caller must not release the layout - * as long as he uses it through the given flash context. - * - * @param flashctx Flash context whose layout will be set. - * @param layout Layout to bet set. - */ void flashrom_layout_set(struct flashrom_flashctx *const flashctx, const struct flashrom_layout *const layout) { flashctx->layout = layout; } -/** @} */ /* end flashrom-layout */ - - -/** - * @defgroup flashrom-wp - * @{ - */ - -/** - * @brief Create a new empty WP configuration. - * - * @param[out] cfg Points to a pointer of type struct flashrom_wp_cfg that will - * be set if creation succeeds. *cfg has to be freed by the - * caller with @ref flashrom_wp_cfg_release. - * @return 0 on success - * >0 on failure - */ enum flashrom_wp_result flashrom_wp_cfg_new(struct flashrom_wp_cfg **cfg) { *cfg = calloc(1, sizeof(**cfg)); return *cfg ? 0 : FLASHROM_WP_ERR_OTHER; } -/** - * @brief Free a WP configuration. - * - * @param[out] cfg Pointer to the flashrom_wp_cfg to free. - */ void flashrom_wp_cfg_release(struct flashrom_wp_cfg *cfg) { free(cfg); } -/** - * @brief Set the protection mode for a WP configuration. - * - * @param[in] mode The protection mode to set. - * @param[out] cfg Pointer to the flashrom_wp_cfg structure to modify. - */ void flashrom_wp_set_mode(struct flashrom_wp_cfg *cfg, enum flashrom_wp_mode mode) { cfg->mode = mode; } -/** - * @brief Get the protection mode from a WP configuration. - * - * @param[in] cfg The WP configuration to get the protection mode from. - * @return The configuration's protection mode. - */ enum flashrom_wp_mode flashrom_wp_get_mode(const struct flashrom_wp_cfg *cfg) { return cfg->mode; } -/** - * @brief Set the protection range for a WP configuration. - * - * @param[out] cfg Pointer to the flashrom_wp_cfg structure to modify. - * @param[in] start The range's start address. - * @param[in] len The range's length. - */ void flashrom_wp_set_range(struct flashrom_wp_cfg *cfg, size_t start, size_t len) { cfg->range.start = start; cfg->range.len = len; } -/** - * @brief Get the protection range from a WP configuration. - * - * @param[out] start Points to a size_t to write the range start to. - * @param[out] len Points to a size_t to write the range length to. - * @param[in] cfg The WP configuration to get the range from. - */ void flashrom_wp_get_range(size_t *start, size_t *len, const struct flashrom_wp_cfg *cfg) { *start = cfg->range.start; *len = cfg->range.len; } -/** - * @brief Write a WP configuration to a flash chip. - * - * @param[in] flash The flash context used to access the chip. - * @param[in] cfg The WP configuration to write to the chip. - * @return 0 on success - * >0 on failure - */ enum flashrom_wp_result flashrom_wp_write_cfg(struct flashctx *flash, const struct flashrom_wp_cfg *cfg) { if (flash->mst->buses_supported & BUS_SPI) @@ -723,15 +460,6 @@ enum flashrom_wp_result flashrom_wp_write_cfg(struct flashctx *flash, const stru return FLASHROM_WP_ERR_OTHER; } -/** - * @brief Read the current WP configuration from a flash chip. - * - * @param[out] cfg Pointer to a struct flashrom_wp_cfg to store the chip's - * configuration in. - * @param[in] flash The flash context used to access the chip. - * @return 0 on success - * >0 on failure - */ enum flashrom_wp_result flashrom_wp_read_cfg(struct flashrom_wp_cfg *cfg, struct flashctx *flash) { if (flash->mst->buses_supported & BUS_SPI) @@ -743,18 +471,6 @@ enum flashrom_wp_result flashrom_wp_read_cfg(struct flashrom_wp_cfg *cfg, struct return FLASHROM_WP_ERR_OTHER; } -/** - * @brief Get a list of protection ranges supported by the flash chip. - * - * @param[out] ranges Points to a pointer of type struct flashrom_wp_ranges - * that will be set if available ranges are found. Finding - * available ranges may not always be possible, even if the - * chip's protection range can be read or modified. *ranges - * must be freed using @ref flashrom_wp_ranges_free. - * @param[in] flash The flash context used to access the chip. - * @return 0 on success - * >0 on failure - */ enum flashrom_wp_result flashrom_wp_get_available_ranges(struct flashrom_wp_ranges **list, struct flashrom_flashctx *flash) { if (flash->mst->buses_supported & BUS_SPI) @@ -766,27 +482,11 @@ enum flashrom_wp_result flashrom_wp_get_available_ranges(struct flashrom_wp_rang return FLASHROM_WP_ERR_OTHER; } -/** - * @brief Get a number of protection ranges in a range list. - * - * @param[in] ranges The range list to get the count from. - * @return Number of ranges in the list. - */ size_t flashrom_wp_ranges_get_count(const struct flashrom_wp_ranges *list) { return list->count; } -/** - * @brief Get a protection range from a range list. - * - * @param[out] start Points to a size_t to write the range's start to. - * @param[out] len Points to a size_t to write the range's length to. - * @param[in] ranges The range list to get the range from. - * @param[in] index Index of the range to get. - * @return 0 on success - * >0 on failure - */ enum flashrom_wp_result flashrom_wp_ranges_get_range(size_t *start, size_t *len, const struct flashrom_wp_ranges *list, unsigned int index) { if (index >= list->count) @@ -798,11 +498,6 @@ enum flashrom_wp_result flashrom_wp_ranges_get_range(size_t *start, size_t *len, return 0; } -/** - * @brief Free a WP range list. - * - * @param[out] cfg Pointer to the flashrom_wp_ranges to free. - */ void flashrom_wp_ranges_release(struct flashrom_wp_ranges *list) { if (!list) @@ -811,6 +506,3 @@ void flashrom_wp_ranges_release(struct flashrom_wp_ranges *list) free(list->ranges); free(list); } - - -/** @} */ /* end flashrom-wp */ diff --git a/writeprotect.c b/writeprotect.c index ab6b1761a..cfdd15b8b 100644 --- a/writeprotect.c +++ b/writeprotect.c @@ -489,5 +489,3 @@ out: free(range_pairs); return ret; } - -/** @} */ /* end flashrom-wp */ |