drivers/spi: reduce confusion in the API

Julius brought up confusion about the current spi api in [1]. In order
alleviate the confusion stemming from supporting x86 spi flash
controllers:

- Remove spi_xfer_two_vectors() which was fusing transactions to
  accomodate the limitations of the spi controllers themselves.
- Add spi_flash_vector_helper() for the x86 spi flash controllers to
  utilize in validating driver/controller current assumptions.
- Remove the xfer() callback in the x86 spi flash drivers which
  will trigger an error as these controllers can't support the api.

[1] https://mail.coreboot.org/pipermail/coreboot/2018-April/086561.html

Change-Id: Id88adc6ad5234c29a739d43521c5f344bb7d3217
Signed-off-by: Aaron Durbin <adurbin@chromium.org>
Reviewed-on: https://review.coreboot.org/25745
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Julius Werner <jwerner@chromium.org>

1 files changed, 8 insertions, 20 deletions

diff --git a/src/include/spi-generic.h b/src/include/spi-generic.h
index 20c7cc72c7..e3e7f829f7 100644
--- a/src/include/spi-generic.h
+++ b/src/include/spi-generic.h
@@ -109,7 +109,10 @@ enum {
 };
 
 /*-----------------------------------------------------------------------
- * Representation of a SPI controller.
+ * Representation of a SPI controller. Note the xfer() and xfer_vector()
+ * callbacks are meant to process full duplex transactions. If the
+ * controller cannot handle these transactions then return an error when
+ * din and dout are both set. See spi_xfer() below for more details.
  *
  * claim_bus:		Claim SPI bus and prepare for communication.
  * release_bus:	Release SPI bus.
@@ -232,6 +235,10 @@ void spi_release_bus(const struct spi_slave *slave);
  *   din:	Pointer to a string of bytes that will be filled in.
  *   bytesin:	How many bytes to read.
  *
+ * Note that din and dout are transferred simulataneously in a full duplex
+ * transaction. The number of clocks within one transaction is calculated
+ * as: MAX(bytesout*8, bytesin*8).
+ *
  *   Returns: 0 on success, not 0 on failure
  */
 int spi_xfer(const struct spi_slave *slave, const void *dout, size_t bytesout,
@@ -281,23 +288,4 @@ static inline int spi_w8r8(const struct spi_slave *slave, unsigned char byte)
 	return ret < 0 ? ret : din[1];
 }
 
-/*
- * Helper function to allow chipsets to combine two vectors if possible. It can
- * only handle upto 2 vectors.
- *
- * This function is provided to support command-response kind of transactions
- * expected by users like flash. Some special SPI flash controllers can handle
- * such command-response operations in a single transaction. For these special
- * controllers, separate command and response vectors can be combined into a
- * single operation.
- *
- * Two vectors are combined if first vector has a non-NULL dout and NULL din and
- * second vector has a non-NULL din and NULL dout. Otherwise, each vector is
- * operated upon one at a time.
- *
- * Returns 0 on success and non-zero on failure.
- */
-int spi_xfer_two_vectors(const struct spi_slave *slave,
-			struct spi_op vectors[], size_t count);
-
 #endif	/* _SPI_GENERIC_H_ */