libflashprog: Allow to query bus types, voltage, and test status
This is mostly an export of the long stable internal structures. We do
some renames, though, and provide the voltage range as floating point
numbers. While we are at it, also rename:
* flashprog_test_status.wp => .block_protection,
* BUS_PROG => BUS_OPAQUE,
* BUS_NONSPI => BUS_PRESPI.
The last one is a pseudonym for the older, memory-mapped buses, and
doesn't include BUS_OPAQUE.
Also try to name the captured test state consistently, either `tested`
or `status`.
Change-Id: Ibefb923fa5f566daa804651aa1a9bfe5602ca364
Signed-off-by: Nico Huber <nico.h@gmx.de>
Reviewed-on: https://review.sourcearcade.org/c/flashprog/+/482
diff --git a/include/flash.h b/include/flash.h
index 75c0250..3ad9d1f 100644
--- a/include/flash.h
+++ b/include/flash.h
@@ -61,15 +61,14 @@
#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
-enum chipbustype {
- BUS_NONE = 0,
- BUS_PARALLEL = 1 << 0,
- BUS_LPC = 1 << 1,
- BUS_FWH = 1 << 2,
- BUS_SPI = 1 << 3,
- BUS_PROG = 1 << 4,
- BUS_NONSPI = BUS_PARALLEL | BUS_LPC | BUS_FWH,
-};
+#define chipbustype flashprog_bus_type
+#define BUS_NONE 0
+#define BUS_PARALLEL FLASHPROG_BUS_PARALLEL
+#define BUS_LPC FLASHPROG_BUS_LPC
+#define BUS_FWH FLASHPROG_BUS_FWH
+#define BUS_SPI FLASHPROG_BUS_SPI
+#define BUS_OPAQUE FLASHPROG_BUS_OPAQUE
+#define BUS_PRESPI (BUS_PARALLEL | BUS_LPC | BUS_FWH)
/*
* The following enum defines possible write granularities of flash chips. These tend to reflect the properties
@@ -181,27 +180,36 @@
#define ERASED_VALUE(flash) (((flash)->chip->feature_bits & FEATURE_ERASED_ZERO) ? 0x00 : 0xff)
-enum test_state {
- OK = 0,
- NT = 1, /* Not tested */
- BAD, /* Known to not work */
- DEP, /* Support depends on configuration (e.g. Intel flash descriptor) */
- NA, /* Not applicable (e.g. write support on ROM chips) */
-};
+#define OK FLASHPROG_TEST_OK
+#define NT FLASHPROG_TEST_NT
+#define BAD FLASHPROG_TEST_BAD
+#define DEP FLASHPROG_TEST_DEP
+#define NA FLASHPROG_TEST_NA
-#define TEST_UNTESTED (struct tested){ .probe = NT, .read = NT, .erase = NT, .write = NT, .wp = NT }
+#define TEST_UNTESTED (struct flashprog_test_status) \
+ { .probe = NT, .read = NT, .erase = NT, .write = NT, .block_protection = NT }
-#define TEST_OK_PROBE (struct tested){ .probe = OK, .read = NT, .erase = NT, .write = NT, .wp = NT }
-#define TEST_OK_PR (struct tested){ .probe = OK, .read = OK, .erase = NT, .write = NT, .wp = NT }
-#define TEST_OK_PRE (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = NT, .wp = NT }
-#define TEST_OK_PREW (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = OK, .wp = NT }
-#define TEST_OK_PREWB (struct tested){ .probe = OK, .read = OK, .erase = OK, .write = OK, .wp = OK }
+#define TEST_OK_PROBE (struct flashprog_test_status) \
+ { .probe = OK, .read = NT, .erase = NT, .write = NT, .block_protection = NT }
+#define TEST_OK_PR (struct flashprog_test_status) \
+ { .probe = OK, .read = OK, .erase = NT, .write = NT, .block_protection = NT }
+#define TEST_OK_PRE (struct flashprog_test_status) \
+ { .probe = OK, .read = OK, .erase = OK, .write = NT, .block_protection = NT }
+#define TEST_OK_PREW (struct flashprog_test_status) \
+ { .probe = OK, .read = OK, .erase = OK, .write = OK, .block_protection = NT }
+#define TEST_OK_PREWB (struct flashprog_test_status) \
+ { .probe = OK, .read = OK, .erase = OK, .write = OK, .block_protection = OK }
-#define TEST_BAD_PROBE (struct tested){ .probe = BAD, .read = NT, .erase = NT, .write = NT, .wp = NT }
-#define TEST_BAD_PR (struct tested){ .probe = BAD, .read = BAD, .erase = NT, .write = NT, .wp = NT }
-#define TEST_BAD_PRE (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = NT, .wp = NT }
-#define TEST_BAD_PREW (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .wp = NT }
-#define TEST_BAD_PREWB (struct tested){ .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .wp = BAD }
+#define TEST_BAD_PROBE (struct flashprog_test_status) \
+ { .probe = BAD, .read = NT, .erase = NT, .write = NT, .block_protection = NT }
+#define TEST_BAD_PR (struct flashprog_test_status) \
+ { .probe = BAD, .read = BAD, .erase = NT, .write = NT, .block_protection = NT }
+#define TEST_BAD_PRE (struct flashprog_test_status) \
+ { .probe = BAD, .read = BAD, .erase = BAD, .write = NT, .block_protection = NT }
+#define TEST_BAD_PREW (struct flashprog_test_status) \
+ { .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .block_protection = NT }
+#define TEST_BAD_PREWB (struct flashprog_test_status) \
+ { .probe = BAD, .read = BAD, .erase = BAD, .write = BAD, .block_protection = BAD }
struct flashprog_flashctx;
#define flashctx flashprog_flashctx /* TODO: Agree on a name and convert all occurrences. */
@@ -258,13 +266,7 @@
feature_bits_t feature_bits;
/* Indicate how well flashprog supports different operations of this flash chip. */
- struct tested {
- enum test_state probe;
- enum test_state read;
- enum test_state erase;
- enum test_state write;
- enum test_state wp;
- } tested;
+ struct flashprog_test_status tested;
/*
* Group chips that have common command sets. This should ensure that
diff --git a/include/libflashprog.h b/include/libflashprog.h
index 1f46be1..eec69ee 100644
--- a/include/libflashprog.h
+++ b/include/libflashprog.h
@@ -64,6 +64,60 @@
__attribute__((nonnull))
size_t flashprog_chip_size(const struct flashprog_chip *);
+/**
+ * @brief Bit masks that represent supported bus types.
+ * @ingroup flashprog-chip
+ */
+enum flashprog_bus_type {
+ FLASHPROG_BUS_PARALLEL = 1 << 0, /**< Parallel flash chip */
+ FLASHPROG_BUS_LPC = 1 << 1, /**< Low Pin Count (LPC) flash */
+ FLASHPROG_BUS_FWH = 1 << 2, /**< Firmware Hub (FWH) flash */
+ FLASHPROG_BUS_SPI = 1 << 3, /**< Serial Peripheral Interface (SPI) flash */
+ FLASHPROG_BUS_OPAQUE = 1 << 4, /**< Chip behind an opaque bus interface */
+};
+__attribute__((nonnull))
+enum flashprog_bus_type flashprog_chip_buses(const struct flashprog_chip *);
+__attribute__((nonnull))
+char *flashprog_chip_bus_names(const struct flashprog_chip *);
+
+/**
+ * @brief Documents the minimal and maximal operating voltage for a chip.
+ * @ingroup flashprog-chip
+ */
+struct flashprog_voltage_range {
+ float min; /**< Lowest operating voltage */
+ float max; /**< Highest operating voltage */
+};
+__attribute__((nonnull))
+struct flashprog_voltage_range flashprog_chip_voltage_range(const struct flashprog_chip *);
+
+/**
+ * @brief Documents the test status of a chip operation.
+ * @ingroup flashprog-chip
+ */
+enum flashprog_test_state {
+ FLASHPROG_TEST_OK = 0, /**< Tested positively */
+ FLASHPROG_TEST_NT = 1, /**< Not tested */
+ FLASHPROG_TEST_BAD, /**< Known to not work */
+ FLASHPROG_TEST_DEP, /**< Support depends on configuration (e.g. Intel flash descriptor) */
+ FLASHPROG_TEST_NA, /**< Not applicable (e.g. write support on ROM chips) */
+};
+/**
+ * @brief Documents the test status of various chip operations.
+ * @ingroup flashprog-chip
+ */
+struct flashprog_test_status {
+ enum flashprog_test_state probe:3; /**< Test status for probing. */
+ enum flashprog_test_state read:3; /**< Test status for reading. */
+ enum flashprog_test_state erase:3; /**< Test status for erasing. */
+ enum flashprog_test_state write:3; /**< Test status for writing. */
+ enum flashprog_test_state block_protection:3; /**< Test status for block-protection configuration. */
+ enum flashprog_test_state :3, :3, :3, :3, :3, :3, :3, :3, :3, :3, reserved:3;
+ /* XXX: Used as return value. Consider ABI compatibility when extending. */
+};
+__attribute__((nonnull))
+struct flashprog_test_status flashprog_chip_test_status(const struct flashprog_chip *);
+
struct flashprog_flashctx;
int flashprog_flash_probe(struct flashprog_flashctx **, const struct flashprog_programmer *, const char *chip_name);
size_t flashprog_flash_getsize(const struct flashprog_flashctx *);
diff --git a/include/programmer.h b/include/programmer.h
index 88a7047..31c95f7 100644
--- a/include/programmer.h
+++ b/include/programmer.h
@@ -36,7 +36,7 @@
struct dev_entry {
uint16_t vendor_id;
uint16_t device_id;
- const enum test_state status;
+ const enum flashprog_test_state status;
const char *vendor_name;
const char *device_name;
};
@@ -142,7 +142,7 @@
bool match_revision;
uint8_t revision_id;
enum chipbustype buses;
- const enum test_state status;
+ const enum flashprog_test_state status;
const char *vendor_name;
const char *device_name;
int (*doit) (struct flashprog_programmer *, struct pci_dev *, const char *name);
@@ -184,7 +184,7 @@
const char *board_name;
int max_rom_decode_parallel;
- const enum test_state status;
+ const enum flashprog_test_state status;
int (*enable) (struct flashprog_programmer *); /* May be NULL. */
};
@@ -193,7 +193,7 @@
struct board_info {
const char *vendor;
const char *name;
- const enum test_state working;
+ const enum flashprog_test_state working;
#ifdef CONFIG_PRINT_WIKI
const char *url;
const char *note;