libflashrom: Deprecate probing v1 API

flashrom_flash_probe marked as deprecated and existing tests are
updated to use probing v2 API

Change-Id: I88f78ac0c93ce99a555b42f87aa0a695089e0b3f
Signed-off-by: Anastasia Klimchuk <aklm@flashrom.org>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/88202
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Peter Marheine <pmarheine@chromium.org>

doc/release_notes/devel.rst

@@ -96,8 +96,17 @@ found (or 0 if none found) and the list of names of all matched entries.
 ``flashrom_flash_probe_v2`` continues to support an optional parameter ``chip_name``
 if the caller want to probe for only one specific chip with given name.
 
-Old API ``flashrom_flash_probe`` which stops probing if more than one chip entry matches
+Command line interface is now using ``flashrom_flash_probe_v2``.
-continues to work as before.
+
+Old API ``flashrom_flash_probe`` is deprecated. It stays available "as is" for now,
+however will be removed at some point in future. Users should switch to v2.
+
+The main reason for deprecation is that it was returning incomplete information in
+case when multiple matching chips were found during probing. Specifically, the only
+info returned was error code of "multiple chips match" with no details of which are
+the matches and how many. This left the caller unable to proceed further. Consequently,
+even flashrom's own command line interface was unable to use old libflashrom probing API,
+and had to maintain separate logic for probing.
 
 New API to get list of supported programmers
 --------------------------------------------

include/libflashrom.h

@@ -261,6 +261,8 @@ int flashrom_programmer_shutdown(struct flashrom_programmer *flashprog);
  */
 
 /**
+ * @deprecated Use flashrom_flash_probe_v2 instead
+ *
  * @brief Probe for a flash chip.
  *
  * Probes for a flash chip and returns a flash context, that can be used
@@ -278,7 +280,8 @@ int flashrom_programmer_shutdown(struct flashrom_programmer *flashprog);
  *         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);
+int flashrom_flash_probe(struct flashrom_flashctx **flashctx, const struct flashrom_programmer *flashprog, const char *chip_name)
+__attribute__((deprecated("Use flashrom_flash_probe_v2 instead")));
 
 /**
  * @brief Probe for a flash chip, v2

tests/ch341a_spi.c

@@ -129,7 +129,9 @@ void ch341a_spi_probe_lifecycle_test_success(void **state)
 		.fallback_open_state = &ch341a_spi_fallback_open_state,
 	};
 
-	run_probe_lifecycle(state, &ch341a_spi_io, &programmer_ch341a_spi, "", "W25Q128.V");
+	const char *expected_matched_names[1] = {"W25Q128.V"};
+	run_probe_v2_lifecycle(state, &ch341a_spi_io, &programmer_ch341a_spi, "", "W25Q128.V",
+				expected_matched_names, 1);
 }
 
 #else

tests/dummyflasher.c

@@ -39,7 +39,9 @@ void dummy_probe_lifecycle_test_success(void **state)
 		.fallback_open_state = &dummy_fallback_open_state,
 	};
 
-	run_probe_lifecycle(state, &dummy_io, &programmer_dummy, "bus=spi,emulate=W25Q128FV", "W25Q128.V");
+	const char *expected_matched_names[1] = {"W25Q128.V"};
+	run_probe_v2_lifecycle(state, &dummy_io, &programmer_dummy, "bus=spi,emulate=W25Q128FV", "W25Q128.V",
+				expected_matched_names, 1);
 }
 
 void dummy_probe_v2_one_match_for_W25Q128FV(void **state)
@@ -103,7 +105,9 @@ void dummy_probe_variable_size_test_success(void **state)
 		.fallback_open_state = &dummy_fallback_open_state,
 	};
 
-	run_probe_lifecycle(state, &dummy_io, &programmer_dummy, "size=8388608,emulate=VARIABLE_SIZE", "Opaque flash chip");
+	const char *expected_matched_names[1] = {"Opaque flash chip"};
+	run_probe_v2_lifecycle(state, &dummy_io, &programmer_dummy, "size=8388608,emulate=VARIABLE_SIZE", "Opaque flash chip",
+				expected_matched_names, 1);
 }
 
 void dummy_init_fails_unhandled_param_test_success(void **state)

tests/lifecycle.c

@@ -15,25 +15,6 @@
 
 #include "lifecycle.h"
 
-static void probe_chip(const struct programmer_entry *prog,
-			struct flashrom_programmer *flashprog,
-			const char *const chip_name,
-			const char **expected_matched_names, /* unused in probe v1 */
-			unsigned int expected_matched_count /* unused in probe v1 */)
-{
-	struct flashrom_flashctx *flashctx;
-
-	printf("Testing flashrom_flash_probe for programmer=%s, chip=%s ... \n", prog->name, chip_name);
-
-	assert_int_equal(0, flashrom_flash_probe(&flashctx, flashprog, chip_name));
-	if (chip_name)
-		assert_int_equal(0, strcmp(chip_name, flashctx->chip->name));
-
-	printf("... flashrom_flash_probe for programmer=%s successful\n", prog->name);
-
-	flashrom_flash_release(flashctx); /* cleanup */
-}
-
 static void probe_chip_v2(const struct programmer_entry *prog,
 			struct flashrom_programmer *flashprog,
 			const char *const chip_name,
@@ -103,16 +84,6 @@ void run_basic_lifecycle(void **state, const struct io_mock *io,
 			NULL /* action */);
 }
 
-void run_probe_lifecycle(void **state, const struct io_mock *io,
-		const struct programmer_entry *prog, const char *param, const char *const chip_name)
-{
-	/* Each probe lifecycle should run independently, without cache. */
-	clear_spi_id_cache();
-	run_lifecycle(state, io, prog, param, chip_name,
-			NULL /* expected_matched_names, */, 0 /* expected_matched_count, */,
-			&probe_chip);
-}
-
 void run_probe_v2_lifecycle(void **state, const struct io_mock *io,
 		const struct programmer_entry *prog, const char *param,
 		const char *const chip_name,

tests/lifecycle.h

@@ -31,9 +31,6 @@
 void run_basic_lifecycle(void **state, const struct io_mock *io,
 		const struct programmer_entry *prog, const char *param);
 
-void run_probe_lifecycle(void **state, const struct io_mock *io,
-		const struct programmer_entry *prog, const char *param, const char *const chip_name);
-
 void run_probe_v2_lifecycle(void **state, const struct io_mock *io,
 		const struct programmer_entry *prog, const char *param,
 		const char *const chip_name,

tests/linux_mtd.c

@@ -89,7 +89,9 @@ void linux_mtd_probe_lifecycle_test_success(void **state)
 		.fallback_open_state = &linux_mtd_fallback_open_state,
 	};
 
-	run_probe_lifecycle(state, &linux_mtd_io, &programmer_linux_mtd, "", "Opaque flash chip");
+	const char *expected_matched_names[1] = {"Opaque flash chip"};
+	run_probe_v2_lifecycle(state, &linux_mtd_io, &programmer_linux_mtd, "", "Opaque flash chip",
+				expected_matched_names, 1);
 }
 #else
 	SKIP_TEST(linux_mtd_probe_lifecycle_test_success)

tests/linux_spi.c

@@ -65,7 +65,9 @@ void linux_spi_probe_lifecycle_test_success(void **state)
 		.fallback_open_state = &linux_spi_fallback_open_state,
 	};
 
-	run_probe_lifecycle(state, &linux_spi_io, &programmer_linux_spi, "dev=/dev/null", "W25Q128.V");
+	const char *expected_matched_names[1] = {"W25Q128.V"};
+	run_probe_v2_lifecycle(state, &linux_spi_io, &programmer_linux_spi, "dev=/dev/null", "W25Q128.V",
+				expected_matched_names, 1);
 }
 #else
 	SKIP_TEST(linux_spi_probe_lifecycle_test_success)

tests/spidriver.c

@@ -212,7 +212,9 @@ void spidriver_probe_lifecycle_test_success(void **state)
 		.fallback_open_state = &spidriver_fallback_open_state,
 	};
 
-	run_probe_lifecycle(state, &spidriver_io, &programmer_spidriver, "dev=/dev/null", "W25Q128.V");
+	const char *expected_matched_names[1] = {"W25Q128.V"};
+	run_probe_v2_lifecycle(state, &spidriver_io, &programmer_spidriver, "dev=/dev/null", "W25Q128.V",
+				expected_matched_names, 1);
 }
 #else
 	SKIP_TEST(spidriver_probe_lifecycle_test_success)