aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Doxyfile5
-rw-r--r--flashrom.c66
-rw-r--r--include/libflashrom.h477
-rw-r--r--layout.c51
-rw-r--r--libflashrom.c308
-rw-r--r--writeprotect.c2
6 files changed, 438 insertions, 471 deletions
diff --git a/Doxyfile b/Doxyfile
index 6906cc82..a13c06f6 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -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 17363816..9b136a03 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 936c9aeb..cf1f4623 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__ */
diff --git a/layout.c b/layout.c
index 05bee19c..39f504ac 100644
--- a/layout.c
+++ b/layout.c
@@ -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 658d8122..e70c1d1a 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 ab6b1761..cfdd15b8 100644
--- a/writeprotect.c
+++ b/writeprotect.c
@@ -489,5 +489,3 @@ out:
free(range_pairs);
return ret;
}
-
-/** @} */ /* end flashrom-wp */